fazekasgy@37: fazekasgy@37: * VamPy is an API wrapper for Vamp. It allows for writing Vamp fazekasgy@37: plugins in Python with or without Numpy support. fazekasgy@37: fazekasgy@38: fazekasgy@37: WHAT IS IT FOR? fazekasgy@37: fazekasgy@37: This wrapper is for writing Vamp plugins in Python which fazekasgy@37: can do the same as a native C++ plugin, plus a lot more if fazekasgy@38: you're using advanced Python modules such as Numpy and Scipy. fazekasgy@37: fazekasgy@37: This may be an easier way to get into Vamp development. fazekasgy@37: You can use it for prototyping your plugin before writing fazekasgy@37: it in C++. fazekasgy@38: fazekasgy@37: fazekasgy@37: WHY PYTHON? fazekasgy@37: fazekasgy@37: Python is a general purpose high level scripting language. fazekasgy@37: It is interpreted, so you don't need to compile your plugins. fazekasgy@38: It has very high level libraries. e.g. you can stream audio fazekasgy@38: from a Vampy plugin if you want to. fazekasgy@37: Supports functional programming. fazekasgy@37: fazekasgy@38: fazekasgy@38: UPDATES IN THIS VERSION (Vampy 2.0): fazekasgy@37: fazekasgy@37: * Two-way Numpy Support fazekasgy@37: * Embedded extension module exposing Vamp defined names fazekasgy@37: e.g. ParameterDescriptor. This allows easier porting to C++. fazekasgy@37: * Support RealTime time stamps fazekasgy@37: * Support byte compiled Python scripts (.pyc) fazekasgy@37: * Environment variables: VAMPY_COMPILED, VAMPY_EXTPATH fazekasgy@37: * Flags to control type conversion and error reporting for development fazekasgy@37: * Flexible type inference to take advantage of Python's loose typing fazekasgy@37: * Full error checking for all Python/C API calls fazekasgy@37: * Various optimisations and speed-ups fazekasgy@38: fazekasgy@38: Vampy now supports two main use cases: fazekasgy@38: 1) Prototyping C++ Vamp plugins in Python. fazekasgy@38: 2) Develop Vampy plugins in Python to allow the use of a vamp fazekasgy@38: hosts for e.g. batch processing or visualisation. fazekasgy@38: fazekasgy@38: Vampy provides an extension module which allows the use of fazekasgy@38: Vamp data types such as FeatureSet() or RealTime() in Vampy plugins. fazekasgy@37: fazekasgy@37: fazekasgy@37: HOW DOES IT WORK: fazekasgy@37: fazekasgy@38: (1) Make sure you have Python (and Numpy) installed. fazekasgy@39: (2) Download Vampy and install it to your Vamp plugin path. fazekasgy@37: eg. /Library/Audio/Plug-Ins/Vamp fazekasgy@38: (3) Write some python plugins and copy them to the same place. fazekasgy@38: (4) Each plugin must contain a single class with the same name as your script file. fazekasgy@37: e.g. PyZeroCrossing.py -> calss PyZeroCrossing fazekasgy@37: -Scripts with syntax errors in them are ignored. fazekasgy@37: -Scripts not having the same class as the filename are ignored. (Python is case sensitive!) fazekasgy@38: -Other unknown scripts may cause a crash. fazekasgy@38: (Don't put other python scripts in your Vamp directory.) cannam@48: Some example plugin scripts are provided in "Example VamPy plugins". fazekasgy@38: fazekasgy@38: FLAGS : fazekasgy@38: fazekasgy@38: You can use some flags to control Vampy. They are: fazekasgy@38: fazekasgy@38: vf_NULL : zero value, default for vampy version 1 behaviour fazekasgy@38: vf_DEBUG : print debug messages to standard error fazekasgy@38: vf_STRICT : more strict type conversion (follows the C++ API more closely) fazekasgy@38: vf_QUIT : quit the host process on hard errors fazekasgy@38: vf_REALTIME : use RealTime time stamps fazekasgy@38: vf_BUFFER : use the Numpy buffer interface to fazekasgy@38: pass time/frequency domain samples to the python process fazekasgy@38: fazekasgy@38: vf_ARRAY : use the numpy Array interface directly fazekasgy@38: fazekasgy@38: vf_DEFAULT_V2 : default Vampy version 2 behaviour fazekasgy@38: (= vf_ARRAY | vf_REALTIME) fazekasgy@38: fazekasgy@38: The use of these flags is optional. The default behaviour is fazekasgy@38: that of Vampy version 1. fazekasgy@38: fazekasgy@38: To set the flags, place a variable called 'vampy_flags' in fazekasgy@38: your plugin class's __init__() function. fazekasgy@38: fazekasgy@38: Example: fazekasgy@38: fazekasgy@38: class PyMFCC(melScaling): fazekasgy@38: def __init__(self,inputSampleRate): fazekasgy@38: self.vampy_flags = vf_DEBUG | vf_ARRAY | vf_REALTIME fazekasgy@38: fazekasgy@38: fazekasgy@38: ENVIRONMENT VARIABLES: fazekasgy@38: fazekasgy@38: Vampy recognises two optional environment variables: fazekasgy@38: fazekasgy@38: VAMPY_COMPILED=1 recognise byte compiled python plugins (default) fazekasgy@38: VAMPY_COMPILED=0 ignore them fazekasgy@38: VAMPY_EXTPATH: if given, searches this path for vampy plugins. fazekasgy@38: (This is useful if you want to keep your python plugins separate.) fazekasgy@38: Only a single fully qualified path name is recognised. fazekasgy@38: fazekasgy@38: Example: fazekasgy@38: export VAMPY_EXTPATH="/Users/Shared/Development/vampy-path" fazekasgy@37: fazekasgy@37: fazekasgy@37: COMPILING AND LINKING: fazekasgy@38: fazekasgy@38: Please use the make files provided. fazekasgy@38: Make sure the correct include locations are provided for fazekasgy@38: Python, Numpy, and the Vamp plugin SDK. fazekasgy@37: fazekasgy@37: fazekasgy@38: COMPILER OPTIONS: fazekasgy@37: fazekasgy@38: HAVE_NUMPY : compile with Numpy array interface support fazekasgy@37: fazekasgy@38: for developers: fazekasgy@38: _DEBUG : print very detailed messages and logs while Vampy is in use fazekasgy@38: _DEBUG_VALUES : print all converted values to stderr fazekasgy@37: fazekasgy@37: fazekasgy@38: TODO: fazekasgy@37: * Vamp 'programs' not implemented fazekasgy@37: * support multiple classes per script in scanner fazekasgy@37: cannam@50: fazekasgy@37: HISTORY: fazekasgy@37: fazekasgy@38: v1: fazekasgy@38: * added support for NumPy arrays in processN() fazekasgy@38: * framecount is now passed also to legacy process() and fixed resulting bugs in the PyZeroCrossing plugin fazekasgy@38: * added two examples which use Frequency Domain input in processN() fazekasgy@38: fazekasgy@38: v2.0: fazekasgy@38: * complete rewrite (using generic functions implementing full error checking) fazekasgy@38: * added extension module : support RealTime and other Vamp type wrappers fazekasgy@38: * added numpy Array interface fazekasgy@38: * added falgs fazekasgy@38: * added environment variables fazekasgy@38: * recognise byte compiled python scripts fazekasgy@38: cannam@50: LICENCE: cannam@50: cannam@50: VamPy is distributed under a "new-style BSD" license; see the cannam@50: file COPYING for details. You may modify and redistribute it cannam@50: within any commercial or non-commercial, proprietary or cannam@50: open-source context. VamPy imposes no limitation on how you cannam@50: may choose to license your own plugin scripts. Note that cannam@50: these happen to be the same terms as the Vamp SDK itself. cannam@50: cannam@50: VamPy was written by Gyorgy Fazekas at the Centre for Digital cannam@50: Music, Queen Mary University of London. cannam@50: Copyright 2008-2009 Gyorgy Fazekas. fazekasgy@38: fazekasgy@38: