fazekasgy@37
|
1
|
fazekasgy@37
|
2 * VamPy is an API wrapper for Vamp. It allows for writing Vamp
|
fazekasgy@37
|
3 plugins in Python with or without Numpy support.
|
fazekasgy@37
|
4
|
fazekasgy@38
|
5
|
fazekasgy@37
|
6 WHAT IS IT FOR?
|
fazekasgy@37
|
7
|
fazekasgy@37
|
8 This wrapper is for writing Vamp plugins in Python which
|
fazekasgy@37
|
9 can do the same as a native C++ plugin, plus a lot more if
|
fazekasgy@38
|
10 you're using advanced Python modules such as Numpy and Scipy.
|
fazekasgy@37
|
11
|
fazekasgy@37
|
12 This may be an easier way to get into Vamp development.
|
fazekasgy@37
|
13 You can use it for prototyping your plugin before writing
|
fazekasgy@37
|
14 it in C++.
|
fazekasgy@38
|
15
|
fazekasgy@37
|
16
|
fazekasgy@37
|
17 WHY PYTHON?
|
fazekasgy@37
|
18
|
fazekasgy@37
|
19 Python is a general purpose high level scripting language.
|
fazekasgy@37
|
20 It is interpreted, so you don't need to compile your plugins.
|
fazekasgy@38
|
21 It has very high level libraries. e.g. you can stream audio
|
fazekasgy@38
|
22 from a Vampy plugin if you want to.
|
fazekasgy@37
|
23 Supports functional programming.
|
fazekasgy@37
|
24
|
fazekasgy@38
|
25
|
fazekasgy@38
|
26 UPDATES IN THIS VERSION (Vampy 2.0):
|
fazekasgy@37
|
27
|
fazekasgy@37
|
28 * Two-way Numpy Support
|
fazekasgy@37
|
29 * Embedded extension module exposing Vamp defined names
|
fazekasgy@37
|
30 e.g. ParameterDescriptor. This allows easier porting to C++.
|
fazekasgy@37
|
31 * Support RealTime time stamps
|
fazekasgy@37
|
32 * Support byte compiled Python scripts (.pyc)
|
fazekasgy@37
|
33 * Environment variables: VAMPY_COMPILED, VAMPY_EXTPATH
|
fazekasgy@37
|
34 * Flags to control type conversion and error reporting for development
|
fazekasgy@37
|
35 * Flexible type inference to take advantage of Python's loose typing
|
fazekasgy@37
|
36 * Full error checking for all Python/C API calls
|
fazekasgy@37
|
37 * Various optimisations and speed-ups
|
fazekasgy@38
|
38
|
fazekasgy@38
|
39 Vampy now supports two main use cases:
|
fazekasgy@38
|
40 1) Prototyping C++ Vamp plugins in Python.
|
fazekasgy@38
|
41 2) Develop Vampy plugins in Python to allow the use of a vamp
|
fazekasgy@38
|
42 hosts for e.g. batch processing or visualisation.
|
fazekasgy@38
|
43
|
fazekasgy@38
|
44 Vampy provides an extension module which allows the use of
|
fazekasgy@38
|
45 Vamp data types such as FeatureSet() or RealTime() in Vampy plugins.
|
fazekasgy@37
|
46
|
fazekasgy@37
|
47
|
fazekasgy@37
|
48 HOW DOES IT WORK:
|
fazekasgy@37
|
49
|
fazekasgy@38
|
50 (1) Make sure you have Python (and Numpy) installed.
|
fazekasgy@38
|
51 (2) Download and install vampy into your vamp plugin path.
|
fazekasgy@37
|
52 eg. /Library/Audio/Plug-Ins/Vamp
|
fazekasgy@38
|
53 (3) Write some python plugins and copy them to the same place.
|
fazekasgy@38
|
54 (4) Each plugin must contain a single class with the same name as your script file.
|
fazekasgy@37
|
55 e.g. PyZeroCrossing.py -> calss PyZeroCrossing
|
fazekasgy@37
|
56 -Scripts with syntax errors in them are ignored.
|
fazekasgy@37
|
57 -Scripts not having the same class as the filename are ignored. (Python is case sensitive!)
|
fazekasgy@38
|
58 -Other unknown scripts may cause a crash.
|
fazekasgy@38
|
59 (Don't put other python scripts in your Vamp directory.)
|
fazekasgy@38
|
60
|
fazekasgy@38
|
61 FLAGS :
|
fazekasgy@38
|
62
|
fazekasgy@38
|
63 You can use some flags to control Vampy. They are:
|
fazekasgy@38
|
64
|
fazekasgy@38
|
65 vf_NULL : zero value, default for vampy version 1 behaviour
|
fazekasgy@38
|
66 vf_DEBUG : print debug messages to standard error
|
fazekasgy@38
|
67 vf_STRICT : more strict type conversion (follows the C++ API more closely)
|
fazekasgy@38
|
68 vf_QUIT : quit the host process on hard errors
|
fazekasgy@38
|
69 vf_REALTIME : use RealTime time stamps
|
fazekasgy@38
|
70 vf_BUFFER : use the Numpy buffer interface to
|
fazekasgy@38
|
71 pass time/frequency domain samples to the python process
|
fazekasgy@38
|
72
|
fazekasgy@38
|
73 vf_ARRAY : use the numpy Array interface directly
|
fazekasgy@38
|
74
|
fazekasgy@38
|
75 vf_DEFAULT_V2 : default Vampy version 2 behaviour
|
fazekasgy@38
|
76 (= vf_ARRAY | vf_REALTIME)
|
fazekasgy@38
|
77
|
fazekasgy@38
|
78 The use of these flags is optional. The default behaviour is
|
fazekasgy@38
|
79 that of Vampy version 1.
|
fazekasgy@38
|
80
|
fazekasgy@38
|
81 To set the flags, place a variable called 'vampy_flags' in
|
fazekasgy@38
|
82 your plugin class's __init__() function.
|
fazekasgy@38
|
83
|
fazekasgy@38
|
84 Example:
|
fazekasgy@38
|
85
|
fazekasgy@38
|
86 class PyMFCC(melScaling):
|
fazekasgy@38
|
87 def __init__(self,inputSampleRate):
|
fazekasgy@38
|
88 self.vampy_flags = vf_DEBUG | vf_ARRAY | vf_REALTIME
|
fazekasgy@38
|
89
|
fazekasgy@38
|
90
|
fazekasgy@38
|
91 ENVIRONMENT VARIABLES:
|
fazekasgy@38
|
92
|
fazekasgy@38
|
93 Vampy recognises two optional environment variables:
|
fazekasgy@38
|
94
|
fazekasgy@38
|
95 VAMPY_COMPILED=1 recognise byte compiled python plugins (default)
|
fazekasgy@38
|
96 VAMPY_COMPILED=0 ignore them
|
fazekasgy@38
|
97 VAMPY_EXTPATH: if given, searches this path for vampy plugins.
|
fazekasgy@38
|
98 (This is useful if you want to keep your python plugins separate.)
|
fazekasgy@38
|
99 Only a single fully qualified path name is recognised.
|
fazekasgy@38
|
100
|
fazekasgy@38
|
101 Example:
|
fazekasgy@38
|
102 export VAMPY_EXTPATH="/Users/Shared/Development/vampy-path"
|
fazekasgy@37
|
103
|
fazekasgy@37
|
104
|
fazekasgy@37
|
105 COMPILING AND LINKING:
|
fazekasgy@38
|
106
|
fazekasgy@38
|
107 Please use the make files provided.
|
fazekasgy@38
|
108 Make sure the correct include locations are provided for
|
fazekasgy@38
|
109 Python, Numpy, and the Vamp plugin SDK.
|
fazekasgy@37
|
110
|
fazekasgy@37
|
111
|
fazekasgy@38
|
112 COMPILER OPTIONS:
|
fazekasgy@37
|
113
|
fazekasgy@38
|
114 HAVE_NUMPY : compile with Numpy array interface support
|
fazekasgy@37
|
115
|
fazekasgy@38
|
116 for developers:
|
fazekasgy@38
|
117 _DEBUG : print very detailed messages and logs while Vampy is in use
|
fazekasgy@38
|
118 _DEBUG_VALUES : print all converted values to stderr
|
fazekasgy@37
|
119
|
fazekasgy@37
|
120
|
fazekasgy@38
|
121 TODO:
|
fazekasgy@37
|
122 * Vamp 'programs' not implemented
|
fazekasgy@37
|
123 * support multiple classes per script in scanner
|
fazekasgy@37
|
124
|
fazekasgy@37
|
125 HISTORY:
|
fazekasgy@37
|
126
|
fazekasgy@38
|
127 v1:
|
fazekasgy@38
|
128 * added support for NumPy arrays in processN()
|
fazekasgy@38
|
129 * framecount is now passed also to legacy process() and fixed resulting bugs in the PyZeroCrossing plugin
|
fazekasgy@38
|
130 * added two examples which use Frequency Domain input in processN()
|
fazekasgy@38
|
131
|
fazekasgy@38
|
132 v2.0:
|
fazekasgy@38
|
133 * complete rewrite (using generic functions implementing full error checking)
|
fazekasgy@38
|
134 * added extension module : support RealTime and other Vamp type wrappers
|
fazekasgy@38
|
135 * added numpy Array interface
|
fazekasgy@38
|
136 * added falgs
|
fazekasgy@38
|
137 * added environment variables
|
fazekasgy@38
|
138 * recognise byte compiled python scripts
|
fazekasgy@38
|
139
|
fazekasgy@38
|
140
|
fazekasgy@38
|
141
|