annotate README @ 92:a6718f9fe942

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