fazekasgy@37
|
1
|
Chris@79
|
2 Vampy is a wrapper for the Vamp audio analysis plugin API.
|
fazekasgy@58
|
3 (http://www.vamp-plugins.org/) It allows for writing Vamp
|
fazekasgy@58
|
4 plugins in Python.
|
fazekasgy@37
|
5
|
fazekasgy@38
|
6
|
fazekasgy@37
|
7 WHAT IS IT FOR?
|
fazekasgy@58
|
8
|
fazekasgy@58
|
9 Vamp is an audio analysis and feature extraction plugin system
|
fazekasgy@58
|
10 with a C/C++ Application Programming Interface (API).
|
fazekasgy@58
|
11
|
fazekasgy@58
|
12 Typical applications of Vamp plugins include visualisation, using
|
cannam@101
|
13 a host such as Sonic Visualiser (https://www.sonicvisualiser.org/),
|
fazekasgy@58
|
14 or batch feature extraction from audio, using Sonic Annotator
|
cannam@101
|
15 (https://vamp-plugins.org/sonic-annotator).
|
fazekasgy@58
|
16
|
fazekasgy@58
|
17 Vamp plugins are typically written in C++. Although currently
|
fazekasgy@58
|
18 available plugin hosts are valuable tools in audio research,
|
Chris@66
|
19 the long and tedious development cycle of plugins does not
|
fazekasgy@58
|
20 support quick prototyping of feature extraction algorithms.
|
fazekasgy@58
|
21 Learning the extra skills needed for plugin development or using
|
fazekasgy@58
|
22 scientific libraries available for C and C++ is often outside
|
fazekasgy@58
|
23 the interest of audio researches typically using MATLAB or other
|
fazekasgy@58
|
24 high-level development environments.
|
fazekasgy@37
|
25
|
fazekasgy@58
|
26 This package aims at easing Vamp plugin development, prototyping
|
fazekasgy@58
|
27 or deployment by using the high-level Python scripting language.
|
fazekasgy@37
|
28
|
fazekasgy@37
|
29
|
fazekasgy@37
|
30 WHY PYTHON?
|
fazekasgy@58
|
31
|
Chris@93
|
32 The Python programming language is extremely popular in the
|
Chris@93
|
33 scientific community. Besides being a high-productivity
|
Chris@93
|
34 interpreted language, it has extensions for scientific
|
Chris@93
|
35 computing such as Numpy, an efficient numerical library and
|
Chris@93
|
36 SciPy, a collection of Python modules for signal processing,
|
Chris@93
|
37 linear algebra, statistics and machine learning ...
|
Chris@93
|
38 (www.SciPy.org). These packages together with matplotlib
|
Chris@93
|
39 (http://matplotlib.sourceforge.net/) provide similar
|
Chris@93
|
40 capabilities to most commercial modelling environments. As a
|
Chris@93
|
41 further advantage, Python is a general purpose language which
|
Chris@93
|
42 also supports the functional programming style.
|
fazekasgy@37
|
43
|
fazekasgy@58
|
44
|
fazekasgy@58
|
45 HOW DOES IT WORK?
|
fazekasgy@58
|
46
|
fazekasgy@58
|
47 Vampy acts like a bridge between a Vamp plugin host application
|
fazekasgy@58
|
48 and Python scripts. It translates host function calls to Python
|
fazekasgy@58
|
49 interpreter calls and converts Python data types to C++ and Vamp
|
fazekasgy@58
|
50 defined data structures.
|
fazekasgy@58
|
51
|
fazekasgy@58
|
52 Vampy is distributed and can be installed like any other ordinary
|
fazekasgy@58
|
53 Vamp plugin. When it is installed, any appropriately structured
|
fazekasgy@58
|
54 Python script in its script directory will be presented to
|
fazekasgy@58
|
55 host programs as if they were native Vamp plugins written in C++.
|
fazekasgy@58
|
56
|
fazekasgy@58
|
57 Vampy embeds the Python interpreter dynamically, and also extends
|
fazekasgy@58
|
58 it with data types defined by the Vamp C++ API, all within a
|
fazekasgy@58
|
59 single shared library.
|
fazekasgy@58
|
60
|
fazekasgy@58
|
61
|
fazekasgy@58
|
62 OBTAINING VAMPY:
|
fazekasgy@58
|
63
|
Chris@93
|
64 Vampy is a free, cross platform, open source package. The
|
Chris@93
|
65 source code is available from its repository at
|
Chris@93
|
66 https://code.soundsoftware.ac.uk/projects/vampy.
|
fazekasgy@58
|
67
|
Chris@93
|
68 * Binary distributions are available for Windows, macOS, and
|
Chris@93
|
69 Linux.
|
fazekasgy@58
|
70
|
Chris@93
|
71 * The source code can be obtained using the Mercurial command:
|
Chris@93
|
72 hg clone https://code.soundsoftware.ac.uk/hg/vampy
|
fazekasgy@58
|
73
|
fazekasgy@58
|
74
|
fazekasgy@58
|
75 DEPENDENCIES:
|
fazekasgy@58
|
76
|
Chris@66
|
77 * Vampy requires Python 2.7.
|
fazekasgy@58
|
78
|
Chris@93
|
79 Note that Vampy does not support Python 3 at all at this
|
Chris@93
|
80 point. Note also that on a Mac in normal circumstances Vampy
|
cannam@101
|
81 expects to use the system installation of Python, so plugins
|
cannam@101
|
82 that you write should be tested using the system Python.
|
fazekasgy@58
|
83
|
Chris@93
|
84 * Vampy supports Numpy 1.1 or greater.
|
fazekasgy@58
|
85
|
Chris@93
|
86 Using Numpy is optional, however writing plugins in pure
|
Chris@93
|
87 Python typically results in significantly slower processing.
|
fazekasgy@58
|
88
|
fazekasgy@58
|
89
|
fazekasgy@58
|
90 BUILDING VAMPY:
|
fazekasgy@58
|
91
|
fazekasgy@58
|
92 It is advised to use a binary distribution if available for
|
fazekasgy@58
|
93 your platform and Python/Numpy versions before attempting to
|
fazekasgy@58
|
94 compile it from source. If you decide to do so, please use the
|
fazekasgy@58
|
95 make files provided. Make sure the correct include locations
|
fazekasgy@58
|
96 are set for Python, Numpy, and the Vamp plugin SDK.
|
fazekasgy@58
|
97
|
fazekasgy@58
|
98
|
fazekasgy@58
|
99 COMPILER OPTIONS:
|
fazekasgy@58
|
100
|
fazekasgy@58
|
101 HAVE_NUMPY : compile with Numpy array interface support
|
fazekasgy@58
|
102
|
fazekasgy@58
|
103 NUMPY_SHORTVERSION : set to the minimum version of Numpy you have,
|
fazekasgy@58
|
104 as a floating-point value; the default is 1.1, which should be
|
fazekasgy@58
|
105 OK for using the plugin with Numpy 1.1, 1.2 and 1.3
|
fazekasgy@58
|
106
|
fazekasgy@58
|
107 simple debugging (for developers):
|
fazekasgy@58
|
108 _DEBUG : print more detailed messages while Vampy is in use
|
fazekasgy@58
|
109 _DEBUG_VALUES : print all converted values to stderr
|
Chris@67
|
110
|
Chris@67
|
111 (But note that basic debug messages are compiled in already, and
|
Chris@67
|
112 will be displayed if the environment variable VAMPY_VERBOSE is set.)
|
fazekasgy@37
|
113
|
fazekasgy@38
|
114
|
fazekasgy@38
|
115 UPDATES IN THIS VERSION (Vampy 2.0):
|
fazekasgy@37
|
116
|
fazekasgy@58
|
117 * More complete, two-way Numpy support
|
fazekasgy@37
|
118 * Embedded extension module exposing Vamp defined names
|
fazekasgy@37
|
119 e.g. ParameterDescriptor. This allows easier porting to C++.
|
fazekasgy@37
|
120 * Support RealTime time stamps
|
fazekasgy@37
|
121 * Support byte compiled Python scripts (.pyc)
|
fazekasgy@58
|
122 * Environment variables
|
fazekasgy@58
|
123 * Flags to control how Vampy works with each plugin
|
fazekasgy@58
|
124 * Flexible type inference to take advantage of dynamic typing
|
fazekasgy@58
|
125 * More complete error checking for all Python/C API calls
|
fazekasgy@37
|
126 * Various optimisations and speed-ups
|
fazekasgy@38
|
127
|
fazekasgy@38
|
128 Vampy now supports two main use cases:
|
fazekasgy@38
|
129 1) Prototyping C++ Vamp plugins in Python.
|
fazekasgy@38
|
130 2) Develop Vampy plugins in Python to allow the use of a vamp
|
fazekasgy@38
|
131 hosts for e.g. batch processing or visualisation.
|
fazekasgy@38
|
132
|
fazekasgy@38
|
133 Vampy provides an extension module which allows the use of
|
fazekasgy@58
|
134 data types defined in the Vamp API; such as FeatureSet() or
|
fazekasgy@58
|
135 RealTime() in Vampy plugins.
|
fazekasgy@37
|
136
|
fazekasgy@37
|
137
|
fazekasgy@58
|
138 BACKWARD COMPATIBILITY (Read this if you used Vampy 1):
|
fazekasgy@58
|
139
|
fazekasgy@58
|
140 This is the second version of Vampy. It is largely compatible
|
fazekasgy@58
|
141 with the previous version and it is able to run plugins
|
fazekasgy@58
|
142 written for it. However, due to some bug fixes in this release,
|
fazekasgy@58
|
143 it may be required to modify old plugins to work correctly
|
fazekasgy@58
|
144 with Vampy 2.0:
|
fazekasgy@58
|
145
|
fazekasgy@58
|
146 * The size of the input buffers of frequency domain plugins
|
fazekasgy@58
|
147 are now longer by one element corresponding to the Nyquist
|
fazekasgy@58
|
148 frequency output of the FFT.
|
fazekasgy@58
|
149
|
fazekasgy@58
|
150 * The legacy interface now uses complex numbers to pass the
|
fazekasgy@58
|
151 FFT output to frequency domain plugins in Vampy 2.0 instead
|
fazekasgy@58
|
152 of floating point values.
|
fazekasgy@58
|
153
|
fazekasgy@58
|
154 * Consequently, the size of the input buffer for each
|
fazekasgy@58
|
155 audio channel is blockSize/2 + 1 if the legacy interface
|
fazekasgy@58
|
156 is used and blockSize+2 if the buffer interface is used
|
fazekasgy@58
|
157 in frequency domain plugins. Time domain plugins however
|
fazekasgy@58
|
158 do not require any change.
|
fazekasgy@58
|
159
|
fazekasgy@58
|
160 * Vampy 1 had two types of process interfaces; the legacy
|
fazekasgy@58
|
161 and the buffer interface (for Numpy support). They were
|
fazekasgy@58
|
162 selected based on the name of the process method.
|
fazekasgy@58
|
163 A process() implementation used the legacy interface,
|
fazekasgy@58
|
164 a processN() implementation used the Numpy buffer interface.
|
fazekasgy@58
|
165 This behaviour is retained for backward compatibility but
|
fazekasgy@58
|
166 only if no flags are set. The use of processN() is now
|
fazekasgy@58
|
167 obsolete, since the standard process() implementation can
|
fazekasgy@58
|
168 be configured to use any of the available interfaces by
|
fazekasgy@58
|
169 setting the flags appropriately.
|
fazekasgy@37
|
170
|
fazekasgy@38
|
171
|
fazekasgy@58
|
172 USING VAMPY:
|
fazekasgy@38
|
173
|
Chris@66
|
174 (1) Make sure you have Python 2.7 installed and you
|
fazekasgy@58
|
175 have a recent Vamp plugin host application.
|
fazekasgy@58
|
176 (e.g. Sonic Visualier)
|
fazekasgy@38
|
177
|
fazekasgy@58
|
178 (2) Download a version of Vampy compatible with your
|
fazekasgy@58
|
179 operating system and Python distribution.
|
fazekasgy@58
|
180
|
fazekasgy@58
|
181 (3) Unzip the package and copy the shared library
|
fazekasgy@58
|
182 (Windows: vampy.dll, Linux: vampy.so, MacOS: vampy.dylib)
|
fazekasgy@58
|
183 to your Vamp plugin path.
|
fazekasgy@58
|
184
|
fazekasgy@58
|
185 (4) Copy the example plugins (.py files) from the
|
fazekasgy@58
|
186 'Example VamPy plugins' directory to the same place.
|
fazekasgy@58
|
187 (without the example directory itself)
|
fazekasgy@58
|
188
|
fazekasgy@58
|
189 (5) If you are familiar with Python, it is straightforward
|
fazekasgy@58
|
190 to start writing your own plugins by following these examples.
|
fazekasgy@58
|
191
|
fazekasgy@58
|
192 Note: The interpreter automatically generates a compiled version
|
fazekasgy@58
|
193 of each plugin when their source file is first imported. This
|
fazekasgy@58
|
194 file can be distributed alone is so desired. Compiled or compiled
|
fazekasgy@58
|
195 and optimised versions of a plugin can also be obtained using the
|
fazekasgy@58
|
196 'py_compile' standard library module. (Note that Python byte
|
fazekasgy@58
|
197 compiled binaries are easier to reverse than C++ binaries.)
|
fazekasgy@58
|
198
|
fazekasgy@58
|
199 Some familiarity with the Vamp plugin SDK and Vamp Plugin
|
fazekasgy@58
|
200 documentation is assumed before one would start writing a plugin
|
fazekasgy@58
|
201 using Vampy. Only the particularities of Vampy plugins are
|
fazekasgy@58
|
202 covered here. The Vamp plugin documentation is available at:
|
fazekasgy@58
|
203 * http://www.vamp-plugins.org/code-doc/index.html
|
fazekasgy@58
|
204 * http://www.vamp-plugins.org/guide.pdf
|
fazekasgy@58
|
205
|
fazekasgy@58
|
206
|
fazekasgy@58
|
207 BASIC RULES:
|
fazekasgy@58
|
208
|
fazekasgy@58
|
209 Only the Python scripts that follow some basic rules qualify as
|
fazekasgy@58
|
210 Vampy plugins:
|
fazekasgy@58
|
211
|
fazekasgy@58
|
212 (1) Each plugin must contain a single class with the
|
fazekasgy@58
|
213 same name as the script file name.
|
fazekasgy@58
|
214
|
fazekasgy@58
|
215 e.g. PyZeroCrossing.py -> class PyZeroCrossing
|
fazekasgy@58
|
216
|
fazekasgy@58
|
217 (2) Vampy plugins have to be in a specific directory designated
|
fazekasgy@58
|
218 to Vamp plugins. The exact location is platform specific.
|
fazekasgy@58
|
219 Additionally, you can use the VAMPY_EXTPATH environment
|
fazekasgy@58
|
220 variable to specify a separate path for Vampy plugins.
|
fazekasgy@58
|
221
|
fazekasgy@58
|
222 (3) Vampy plugins can be used and distributed as Python scripts
|
fazekasgy@58
|
223 (.py) or byte compiled Python binaries (.pyc / .pyo).
|
fazekasgy@58
|
224
|
fazekasgy@58
|
225 When a script is present with the same name as a compiled
|
fazekasgy@58
|
226 file on any of the valid paths, the script will be preferred.
|
fazekasgy@58
|
227
|
fazekasgy@58
|
228 (4) Vampy may decide to reject some scripts after some basic
|
fazekasgy@58
|
229 validation is performed:
|
fazekasgy@58
|
230
|
fazekasgy@58
|
231 * Scripts with syntax errors in them are ignored.
|
fazekasgy@58
|
232
|
fazekasgy@58
|
233 * Scripts not containing a class with the exact same name
|
fazekasgy@58
|
234 as the file name are ignored. (Python is case sensitive!)
|
fazekasgy@58
|
235
|
fazekasgy@58
|
236 * Scripts with the wrong number of arguments to the plugin
|
fazekasgy@58
|
237 class's __init__() function will be avoided.
|
Chris@93
|
238
|
Chris@93
|
239 * Scripts that redefine any of Vampy's standard type names
|
Chris@93
|
240 will be avoided.
|
fazekasgy@58
|
241
|
Chris@93
|
242 (5) Unknown scripts may cause undesired behaviour.
|
fazekasgy@58
|
243 Don't put arbitrary Python scripts in your Vamp directory,
|
fazekasgy@58
|
244 you may use a subdirectory for that.
|
fazekasgy@58
|
245
|
fazekasgy@58
|
246
|
fazekasgy@58
|
247 PLUGIN ERRORS:
|
fazekasgy@58
|
248
|
fazekasgy@58
|
249 Script validation is performed by the interpreter itself
|
fazekasgy@58
|
250 using the same rules as module compilation. This means that
|
fazekasgy@58
|
251 while most syntax errors will be noted when Vampy is first
|
fazekasgy@58
|
252 used by a host, runtime errors can still occur during
|
fazekasgy@58
|
253 execution. For example, a plugin calculating the dot product
|
fazekasgy@58
|
254 of two vectors with different sizes will produce a runtime error.
|
fazekasgy@58
|
255
|
Chris@93
|
256 Error messages from Vampy are printed on the standard error
|
Chris@93
|
257 channel.
|
fazekasgy@58
|
258 If you're using a graphical host (such as Sonic Visualiser)
|
fazekasgy@58
|
259 you may start the application from a command line terminal
|
Chris@93
|
260 in order to see these messages, or they may be forwarded by
|
Chris@93
|
261 the host to its own debug log file.
|
fazekasgy@58
|
262
|
fazekasgy@58
|
263 Exceptions:
|
fazekasgy@58
|
264
|
fazekasgy@58
|
265 * Runtime errors occurring in the plugin's __init__() function
|
fazekasgy@58
|
266 will prevent the host from loading the plugin.
|
fazekasgy@58
|
267
|
fazekasgy@58
|
268 * Runtime errors in the plugin's initialise() function will
|
fazekasgy@58
|
269 prevent the host from using the plugin.
|
fazekasgy@58
|
270
|
fazekasgy@58
|
271 * Module level errors resulting from importing a non-existent
|
fazekasgy@58
|
272 module or source file or an error occurring on an imported
|
fazekasgy@58
|
273 module's source tree will prevent the plugin from loading.
|
fazekasgy@58
|
274
|
fazekasgy@58
|
275 Any other error, including those during the process will
|
fazekasgy@58
|
276 only be noted on the terminal output. Processing errors will
|
fazekasgy@58
|
277 generally result in a blank screen or no results displayed by
|
fazekasgy@58
|
278 graphical hosts.
|
fazekasgy@58
|
279
|
fazekasgy@58
|
280
|
fazekasgy@58
|
281 EXTENSION MODULE:
|
fazekasgy@58
|
282
|
fazekasgy@58
|
283 Vampy extends Python with some useful data types defined
|
fazekasgy@58
|
284 by the Vamp plugin API. This extension module is embedded
|
fazekasgy@58
|
285 into the Vampy shared library, therefore it doesn't need
|
fazekasgy@58
|
286 to be installed separately. However, it works very similarly
|
fazekasgy@58
|
287 to any third party Python extension within a Vampy plugin.
|
fazekasgy@58
|
288
|
fazekasgy@58
|
289 You may import the extension in the usual manner using
|
fazekasgy@58
|
290 " import vampy " and " from vampy import * ". (Note that
|
fazekasgy@58
|
291 currently the extension module is not available as a
|
fazekasgy@58
|
292 separate package, therefore this will only work if the
|
fazekasgy@58
|
293 plugin is executed by Vampy within a usual host context.)
|
fazekasgy@58
|
294
|
fazekasgy@58
|
295 You can use any standard Python statement involving
|
fazekasgy@58
|
296 modules such as " dir(vampy) " to print the names exported
|
fazekasgy@58
|
297 by the module. The use of the extension in entirely optional,
|
fazekasgy@58
|
298 however its use is strongly advised for the following reasons:
|
fazekasgy@58
|
299
|
fazekasgy@58
|
300 * Using the module hides the mapping between Python and
|
fazekasgy@58
|
301 C++ data types and provides improved plugin portability.
|
fazekasgy@58
|
302
|
fazekasgy@58
|
303 * Returning types exported by the module is often faster.
|
fazekasgy@58
|
304
|
fazekasgy@58
|
305 * In future releases its use may become mandatory.
|
fazekasgy@58
|
306
|
fazekasgy@58
|
307
|
fazekasgy@58
|
308 PROCESS INTERFACES:
|
fazekasgy@58
|
309
|
fazekasgy@58
|
310 Most computationally intensive processing takes place in
|
fazekasgy@58
|
311 the plugin's process() method. This method has two arguments,
|
fazekasgy@58
|
312 (besides the 'self' argument mandatory in all Python class methods).
|
fazekasgy@58
|
313
|
fazekasgy@58
|
314 * The fist argument is used to pass audio samples (in time
|
fazekasgy@58
|
315 domain plugins) or frequency samples (complex FFT output)
|
fazekasgy@58
|
316 in frequency domain plugins. This argument is always a
|
fazekasgy@58
|
317 Python list object where each element of the list corresponds
|
fazekasgy@58
|
318 to an audio channel. (The length of this list can not be zero.)
|
fazekasgy@58
|
319 The actual element types contained in this list depends
|
fazekasgy@58
|
320 on the domain type of the plugin (time/frequency domain) and
|
fazekasgy@58
|
321 the selected process interface. (explained below)
|
fazekasgy@58
|
322
|
fazekasgy@58
|
323 * The second argument is the time stamp of the processing
|
fazekasgy@58
|
324 block passed to the plugin. This time stamp is either
|
fazekasgy@58
|
325 a long integer corresponding to a sample number, or a
|
fazekasgy@58
|
326 RealTime data type exposed by the vampy module.
|
fazekasgy@58
|
327 The use of the time stamp is different in time and frequency
|
fazekasgy@58
|
328 domain plugins. Please refer to the Vamp plugin documentation
|
fazekasgy@58
|
329 for more details.
|
fazekasgy@58
|
330
|
fazekasgy@58
|
331 Vampy supports three interfaces to process() function.
|
fazekasgy@58
|
332 The interface type can be selected using the flags indicated
|
fazekasgy@58
|
333 next to the process name below. The detailed use of these
|
fazekasgy@58
|
334 flags will be explained later.
|
fazekasgy@58
|
335
|
fazekasgy@58
|
336 INTERFACE TYPES:
|
fazekasgy@58
|
337
|
fazekasgy@58
|
338 (1) Legacy interface (default, slowest):
|
fazekasgy@58
|
339
|
fazekasgy@58
|
340 Vampy passes a Python List of List of values to the
|
fazekasgy@58
|
341 plugin corresponding to each audio channel, and the
|
fazekasgy@58
|
342 time or frequency domain samples of each channel:
|
fazekasgy@58
|
343
|
fazekasgy@58
|
344 * Audio samples are passed as an N element list
|
fazekasgy@58
|
345 of floating point values in time domain plugins,
|
fazekasgy@58
|
346 (where N equals to the block size parameter of the plugin).
|
fazekasgy@58
|
347
|
fazekasgy@58
|
348 * Frequency Domain plugins are passed an N element list
|
fazekasgy@58
|
349 of complex numbers, where N = (blockSize/2) + 1. This list
|
fazekasgy@58
|
350 includes the DC and the Nyquist frequency FFT oputputs.
|
fazekasgy@58
|
351
|
fazekasgy@58
|
352 Note: This is the only available interface which can be used
|
fazekasgy@58
|
353 without Numpy or a compatible numerical library.
|
fazekasgy@58
|
354
|
fazekasgy@58
|
355 (2) Buffer interface (vf_BUFFER, fast):
|
fazekasgy@58
|
356
|
fazekasgy@58
|
357 * Both time and frequency domain plugins are passed a list
|
fazekasgy@58
|
358 of shared memory buffer objects where each buffer corresponds
|
fazekasgy@58
|
359 to an audio channel. The length of these buffers is blockSize
|
fazekasgy@58
|
360 in time domain plugins and blockSize+2 in frequency domain
|
fazekasgy@58
|
361 plugins. The easiest way to access the data in the buffers
|
fazekasgy@58
|
362 is the use of Numpy's frombuffer() command. See the Numpy
|
fazekasgy@58
|
363 documentation or the Vampy example plugins for more details.
|
fazekasgy@58
|
364
|
fazekasgy@58
|
365 Note that this interface is very similar to how the data is
|
fazekasgy@58
|
366 passed to Vamp plugins in C++.
|
fazekasgy@58
|
367
|
fazekasgy@58
|
368 (3) Numpy Array interface (vf_ARRAY, fast):
|
fazekasgy@58
|
369
|
fazekasgy@58
|
370 Vampy passes a list of Numpy arrays to the process()
|
fazekasgy@58
|
371 corresponding to each audio channel.
|
fazekasgy@58
|
372
|
fazekasgy@58
|
373 * Time Domain plugins are passed an array of numpy.float32
|
fazekasgy@58
|
374 values where the array size is N = blockSize.
|
fazekasgy@58
|
375
|
fazekasgy@58
|
376 * Frequency Domain plugins are passed an array of
|
fazekasgy@58
|
377 numpy.complex64 values where the size N = (blockSize/2) + 1.
|
fazekasgy@58
|
378
|
fazekasgy@58
|
379
|
fazekasgy@58
|
380 RETURNING VALUES:
|
fazekasgy@58
|
381
|
fazekasgy@58
|
382 Python is a dynamically typed language, which means
|
fazekasgy@58
|
383 that the programmer is not forced to declare variable
|
fazekasgy@58
|
384 types strictly and specifically, they can be decided
|
fazekasgy@58
|
385 or changed at runtime. This leads to different programming
|
fazekasgy@58
|
386 styles compared to using statically typed languages such
|
fazekasgy@58
|
387 as C++. The Vamp API is declared using C++ and expects
|
fazekasgy@58
|
388 statically declared types returned by the plugin.
|
fazekasgy@58
|
389 This leads to difficulties to the Python programmer, and
|
fazekasgy@58
|
390 requires a detailed knowledge of the API which otherwise
|
fazekasgy@58
|
391 would be unnecessary. Vampy relaxes this requirement by
|
fazekasgy@58
|
392 using a runtime type inference mechanism.
|
fazekasgy@58
|
393
|
fazekasgy@58
|
394 Vampy can convert just about any suitable Python data
|
fazekasgy@58
|
395 object to the appropriate C++ data type expected by a
|
fazekasgy@58
|
396 Vamp plugin host. This includes Numpy data types such as
|
fazekasgy@58
|
397 numpy.float32 or a Numpy array. The type conversion is
|
fazekasgy@58
|
398 dynamic and it is decided based on the plugin context and
|
fazekasgy@58
|
399 the expected data type defined by the Vamp plugin API
|
fazekasgy@58
|
400 in that context. This mechanism also takes advantage of the
|
fazekasgy@58
|
401 higher level Python number, sequence and mapping protocols.
|
fazekasgy@58
|
402
|
fazekasgy@58
|
403 For example if the Vamp API expects a floating point value,
|
fazekasgy@58
|
404 any returned Python object will be attempted to cast
|
fazekasgy@58
|
405 to a floating point value first and returned to the host.
|
fazekasgy@58
|
406 If the value can not be converted, an error message is
|
fazekasgy@58
|
407 displayed.
|
fazekasgy@58
|
408
|
fazekasgy@58
|
409 Similarly, any returned value will be converted to a vector of
|
fazekasgy@58
|
410 the appropriate element type when the expected return type is
|
fazekasgy@58
|
411 a sequence of values. This allows the programmer to omit
|
fazekasgy@58
|
412 unnecessary conversions, when, for example, a one element
|
fazekasgy@58
|
413 list (vector) would be returned.
|
fazekasgy@58
|
414
|
fazekasgy@58
|
415 The type conversion can be controlled specifically for
|
fazekasgy@58
|
416 each plugin. Vampy supports the use case of prototyping
|
fazekasgy@58
|
417 C++ Vamp plugins in Python by using a more strict type
|
fazekasgy@58
|
418 conversion mechanism which would issue an error message
|
fazekasgy@58
|
419 if the Python object does not correspond to a C++ type
|
fazekasgy@58
|
420 according to a strict one-to-one mapping. This mapping
|
fazekasgy@58
|
421 can be briefly outlined as follows:
|
fazekasgy@58
|
422
|
fazekasgy@58
|
423 * numerical types require direct correspondence
|
fazekasgy@58
|
424 between Python and C++ types when available
|
fazekasgy@58
|
425 e.g. C++ float -> Python float
|
fazekasgy@58
|
426
|
fazekasgy@58
|
427 * Data structures defined in the Vamp Plugin API require
|
fazekasgy@58
|
428 a type exported be the vampy extension module.
|
fazekasgy@58
|
429 Vamp::FeatureSet() -> vampy.FeatureSet()
|
fazekasgy@58
|
430 Vamp::RealTime() -> vampy.RealTime()
|
fazekasgy@58
|
431
|
fazekasgy@58
|
432 The strict type conversion method can be selected using
|
fazekasgy@58
|
433 the Vampy flag: vf_STRICT (explained in the FLAGS section).
|
fazekasgy@58
|
434
|
fazekasgy@58
|
435
|
fazekasgy@58
|
436 TIME STAMPS :
|
fazekasgy@58
|
437
|
fazekasgy@58
|
438 Vamp uses RealTime time stamps to indicate the position of
|
fazekasgy@58
|
439 a processing block passed to the plugin, or the position of
|
fazekasgy@58
|
440 any returned features relative to the start of the audio.
|
fazekasgy@58
|
441 RealTime uses two integer values to represent time values
|
fazekasgy@58
|
442 to nanosecond precision. Vampy provides a Python compatible
|
fazekasgy@58
|
443 representation of this this type which can be imported and
|
fazekasgy@58
|
444 used in any Vampy plugin.
|
fazekasgy@58
|
445
|
fazekasgy@58
|
446 * Vampy RealTime objects can be initialised using integers
|
fazekasgy@58
|
447 corresponding to second and nanosecond values, or seconds (floats).
|
fazekasgy@58
|
448 e.g.:
|
fazekasgy@58
|
449 timestamp1 = RealTime(2,0)
|
fazekasgy@58
|
450 timestamp2 = RealTime('seconds',2.123)
|
fazekasgy@58
|
451
|
fazekasgy@58
|
452 Please note that only the following methods are available:
|
fazekasgy@58
|
453
|
fazekasgy@58
|
454 * values() : returns a tuple of integers (sec,nsec)
|
fazekasgy@58
|
455 * toFloat() : return a floating point representation (in seconds)
|
fazekasgy@58
|
456 * toFrame(samplerate) : convert to frame
|
fazekasgy@58
|
457 (sample number) given the audio sample rate
|
fazekasgy@58
|
458 * toString() : human readable string representation
|
fazekasgy@58
|
459 * a limited set of arithmetic operators (+,-)
|
fazekasgy@58
|
460
|
fazekasgy@58
|
461 Additionally Vampy provides a function to convert frame
|
fazekasgy@58
|
462 counts (in audio samples) to RealTime:
|
fazekasgy@58
|
463
|
fazekasgy@58
|
464 timestamp = frame2RealTime(frameCount,inputSampleRate)
|
fazekasgy@58
|
465
|
fazekasgy@58
|
466 For the detailed use of time stamps, refer to the Vamp plugin
|
fazekasgy@58
|
467 documentation. i.e. Section 5, "Sample Types and Timestamps"
|
fazekasgy@58
|
468 in the Vamp plugin guide, and the Vamp SDK documentation:
|
fazekasgy@58
|
469 http://vamp-plugins.org/code-doc/classVamp_1_1Plugin.html
|
fazekasgy@58
|
470 on how time stamps are used in process calls.
|
fazekasgy@58
|
471
|
fazekasgy@58
|
472 Note: The support for RealTime time stamps is new in this
|
fazekasgy@58
|
473 version of Vampy. Vampy 1 used long integer sample counts
|
fazekasgy@58
|
474 instead. This is still accepted for backward compatibility,
|
fazekasgy@58
|
475 but the use of RealTime is encouraged whenever possible.
|
fazekasgy@58
|
476 By default sample counts are used, please set the falg:
|
fazekasgy@58
|
477 vf_REALTIME to obtain RealTime time stamps in process calls.
|
fazekasgy@58
|
478
|
fazekasgy@58
|
479
|
fazekasgy@58
|
480 VAMPY FLAGS :
|
fazekasgy@58
|
481
|
fazekasgy@58
|
482 The execution of Vampy plugins can be controlled using a set
|
fazekasgy@58
|
483 of flags. (Each control flag is prefixed by vf_)
|
fazekasgy@58
|
484
|
fazekasgy@58
|
485 vf_NULL : zero value, default for Vampy version 1 behaviour
|
fazekasgy@38
|
486 vf_DEBUG : print debug messages to standard error
|
fazekasgy@58
|
487 vf_STRICT : strict type conversion (follows the C++ API more closely)
|
fazekasgy@38
|
488 vf_QUIT : quit the host process on hard errors
|
fazekasgy@38
|
489 vf_REALTIME : use RealTime time stamps
|
fazekasgy@58
|
490 vf_BUFFER : use the Numpy Buffer interface
|
fazekasgy@58
|
491 vf_ARRAY : use the numpy Array interface
|
fazekasgy@38
|
492 vf_DEFAULT_V2 : default Vampy version 2 behaviour
|
fazekasgy@58
|
493 (equals to setting: vf_ARRAY | vf_REALTIME)
|
fazekasgy@38
|
494
|
fazekasgy@58
|
495 The use of flags is optional. The default behaviour is that
|
fazekasgy@58
|
496 of Vampy version 1.
|
fazekasgy@38
|
497
|
fazekasgy@38
|
498 To set the flags, place a variable called 'vampy_flags' in
|
fazekasgy@38
|
499 your plugin class's __init__() function.
|
fazekasgy@38
|
500
|
fazekasgy@38
|
501 Example:
|
fazekasgy@38
|
502
|
fazekasgy@38
|
503 class PyMFCC(melScaling):
|
fazekasgy@38
|
504 def __init__(self,inputSampleRate):
|
fazekasgy@38
|
505 self.vampy_flags = vf_DEBUG | vf_ARRAY | vf_REALTIME
|
fazekasgy@38
|
506
|
fazekasgy@38
|
507
|
fazekasgy@38
|
508 ENVIRONMENT VARIABLES:
|
fazekasgy@38
|
509
|
Chris@67
|
510 Vampy recognises these optional environment variables:
|
Chris@67
|
511
|
Chris@67
|
512 VAMPY_VERBOSE if set at all, print out debug info to stderr
|
Chris@67
|
513
|
fazekasgy@38
|
514 VAMPY_COMPILED=1 recognise byte compiled python plugins (default)
|
fazekasgy@38
|
515 VAMPY_COMPILED=0 ignore them
|
cannam@57
|
516
|
fazekasgy@38
|
517 VAMPY_EXTPATH: if given, searches this path for vampy plugins.
|
fazekasgy@58
|
518 This is useful if you want to keep your python plugins
|
fazekasgy@58
|
519 separate. Only a single absolute path name is recognised.
|
fazekasgy@58
|
520
|
fazekasgy@58
|
521 Example:
|
fazekasgy@58
|
522 export VAMPY_EXTPATH="/Users/Shared/Development/vampy-path"
|
cannam@57
|
523
|
cannam@57
|
524 VAMPY_PYLIB: path to the Python shared library to be preloaded
|
cannam@57
|
525 before scripts are run. The preload is necessary on some
|
cannam@57
|
526 systems to support plugins that load additional Python modules.
|
cannam@57
|
527 Vampy will attempt to preload the right library by default, but
|
cannam@57
|
528 it sometimes fails; if so, set this variable to override it.
|
fazekasgy@37
|
529
|
cannam@50
|
530
|
fazekasgy@37
|
531 HISTORY:
|
fazekasgy@37
|
532
|
fazekasgy@38
|
533 v1:
|
fazekasgy@51
|
534 * added support for Numpy arrays in processN()
|
fazekasgy@58
|
535 * framecount is now passed also to legacy process()
|
fazekasgy@58
|
536 and fixed resulting bugs in the PyZeroCrossing plugin
|
fazekasgy@38
|
537 * added two examples which use Frequency Domain input in processN()
|
fazekasgy@38
|
538
|
fazekasgy@38
|
539 v2.0:
|
fazekasgy@58
|
540 * complete rewrite using generic functions for
|
fazekasgy@58
|
541 implementing full error checking on Python/C API calls
|
fazekasgy@58
|
542 * added extension module;
|
fazekasgy@58
|
543 supports RealTime and other Vamp type wrappers
|
fazekasgy@58
|
544 enables a much more readable syntax
|
fazekasgy@51
|
545 * added Numpy Array interface
|
fazekasgy@51
|
546 * added flags
|
fazekasgy@38
|
547 * added environment variables
|
fazekasgy@58
|
548 * recognise byte compiled python scripts
|
fazekasgy@58
|
549 * new example plugin PyMFCC
|
fazekasgy@58
|
550 * modified all examples for the new syntax
|
fazekasgy@58
|
551 * bug fix: Nyquist frequency FFT output is now passed correctly
|
fazekasgy@58
|
552
|
fazekasgy@58
|
553
|
fazekasgy@58
|
554 TODO:
|
fazekasgy@58
|
555 * Vamp 'programs' not implemented
|
fazekasgy@58
|
556 * support multiple classes per script in scanner
|
fazekasgy@58
|
557 * implement missing methods of vampy.RealTime type
|
fazekasgy@58
|
558
|
fazekasgy@38
|
559
|
cannam@50
|
560 LICENCE:
|
cannam@50
|
561
|
cannam@50
|
562 VamPy is distributed under a "new-style BSD" license; see the
|
cannam@50
|
563 file COPYING for details. You may modify and redistribute it
|
cannam@50
|
564 within any commercial or non-commercial, proprietary or
|
cannam@50
|
565 open-source context. VamPy imposes no limitation on how you
|
cannam@50
|
566 may choose to license your own plugin scripts. Note that
|
cannam@50
|
567 these happen to be the same terms as the Vamp SDK itself.
|
cannam@50
|
568
|
cannam@50
|
569 VamPy was written by Gyorgy Fazekas at the Centre for Digital
|
cannam@50
|
570 Music, Queen Mary University of London.
|
cannam@50
|
571 Copyright 2008-2009 Gyorgy Fazekas.
|
Chris@93
|
572 Copyright 2008-2019 Queen Mary University of London.
|
fazekasgy@38
|
573
|
fazekasgy@38
|
574
|