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