Vampy

Vampy is a wrapper for the Vamp audio analysis plugin API.
(http://www.vamp-plugins.org/) It allows for writing Vamp 
plugins in Python.

WHAT IS IT FOR?

Vamp is an audio analysis and feature extraction plugin system 
with a C/C++ Application Programming Interface (API).

Typical applications of Vamp plugins include visualisation, using 
a host such as Sonic Visualiser (https://www.sonicvisualiser.org/),
or batch feature extraction from audio, using Sonic Annotator 
(https://vamp-plugins.org/sonic-annotator).

Vamp plugins are typically written in C++. Although currently
available plugin hosts are valuable tools in audio research,
the long and tedious development cycle of plugins does not 
support quick prototyping of feature extraction algorithms.
Learning the extra skills needed for plugin development or using 
scientific libraries available for C and C++ is often outside 
the interest of audio researches typically using MATLAB or other
high-level development environments.

This package aims at easing Vamp plugin development, prototyping 
or deployment by using the high-level Python scripting language.

WHY PYTHON?

The Python programming language is extremely popular in the
scientific community. Besides being a high-productivity
interpreted language, it has extensions for scientific
computing such as Numpy, an efficient numerical library and
SciPy, a collection of Python modules for signal processing,
linear algebra, statistics and machine learning ...
(www.SciPy.org). These packages together with matplotlib
(http://matplotlib.sourceforge.net/) provide similar
capabilities to most commercial modelling environments. As a
further advantage, Python is a general purpose language which
also supports the functional programming style.

HOW DOES IT WORK?

Vampy acts like a bridge between a Vamp plugin host application
and Python scripts. It translates host function calls to Python
interpreter calls and converts Python data types to C++ and Vamp
defined data structures. 

Vampy is distributed and can be installed like any other ordinary 
Vamp plugin. When it is installed, any appropriately structured 
Python script in its script directory will be presented to 
host programs as if they were native Vamp plugins written in C++.

Vampy embeds the Python interpreter dynamically, and also extends 
it with data types defined by the Vamp C++ API, all within a 
single shared library.

WHAT'S NEW IN THIS RELEASE?

    See the file CHANGELOG for details of changes in this release
    (and previous releases) of Vampy.

OBTAINING VAMPY:

Vampy is a free, cross platform, open source package. The
source code is available from its repository at
https://code.soundsoftware.ac.uk/projects/vampy.

* Binary distributions are available for Windows, macOS, and
Linux.

* The source code can be obtained using the Mercurial command:
hg clone https://code.soundsoftware.ac.uk/hg/vampy

DEPENDENCIES:

* Vampy requires Python 2.7.

Note that Vampy does not support Python 3 at all at this
point.  Note also that on a Mac in normal circumstances Vampy
expects to use the system installation of Python, so plugins
that you write should be tested using the system Python.

* Vampy supports Numpy 1.1 or greater. 

Using Numpy is optional, however writing plugins in pure
Python typically results in significantly slower processing.

BUILDING VAMPY:

It is advised to use a binary distribution if available for
your platform and Python/Numpy versions before attempting to 
compile it from source. If you decide to do so, please use the 
make files provided. Make sure the correct include locations 
are set for Python, Numpy, and the Vamp plugin SDK.

COMPILER OPTIONS:

HAVE_NUMPY : compile with Numpy array interface support

NUMPY_SHORTVERSION : set to the minimum version of Numpy you have, 
	as a floating-point value; the default is 1.1, which should be 
	OK for using the plugin with Numpy 1.1, 1.2 and 1.3

simple debugging (for developers):
	_DEBUG : print more detailed messages while Vampy is in use
	_DEBUG_VALUES : print all converted values to stderr
	
(But note that basic debug messages are compiled in already, and
will be displayed if the environment variable VAMPY_VERBOSE is set.)

USING VAMPY:

(1) Make sure you have Python 2.7 installed and you
	have a recent Vamp plugin host application. 
	(e.g. Sonic Visualier)

(2) Download a version of Vampy compatible with your
	operating system and Python distribution.

(3) Unzip the package and copy the shared library 
	(Windows: vampy.dll, Linux: vampy.so, MacOS: vampy.dylib)
	to your Vamp plugin path.
	
(4) Copy the example plugins (.py files) from the 
	'Example VamPy plugins' directory to the same place.
	(without the example directory itself)

(5) If you are familiar with Python, it is straightforward 
	to start writing your own plugins by following these examples.
	
Note: The interpreter automatically generates a compiled version
of each plugin when their source file is first imported. This 
file can be distributed alone is so desired. Compiled or compiled 
and optimised versions of a plugin can also be obtained using the 
'py_compile' standard library module. (Note that Python byte 
compiled binaries are easier to reverse than C++ binaries.)

Some familiarity with the Vamp plugin SDK and Vamp Plugin 
documentation is assumed before one would start writing a plugin
using Vampy. Only the particularities of Vampy plugins are 
covered here. The Vamp plugin documentation is available at:
* http://www.vamp-plugins.org/code-doc/index.html
* http://www.vamp-plugins.org/guide.pdf

BASIC RULES:

Only the Python scripts that follow some basic rules qualify as
Vampy plugins:

(1) Each plugin must contain a single class with the 
	same name as the script file name.
	
	e.g. PyZeroCrossing.py -> class PyZeroCrossing
	
(2) Vampy plugins have to be in a specific directory designated
	to Vamp plugins. The exact location is platform specific.
	Additionally, you can use the VAMPY_EXTPATH environment
	variable to specify a separate path for Vampy plugins.
	
(3) Vampy plugins can be used and distributed as Python scripts 
	(.py) or byte compiled Python binaries (.pyc / .pyo).
	
	When a script is present with the same name as a compiled
	file on any of the valid paths, the script will be preferred.
	
(4) Vampy may decide to reject some scripts after some basic
	validation is performed:

	* Scripts with syntax errors in them are ignored.
	
	* Scripts not containing a class with the exact same name 
	as the file name are ignored. (Python is case sensitive!)
	
	* Scripts with the wrong number of arguments to the plugin 
	class's __init__() function will be avoided.

	* Scripts that redefine any of Vampy's standard type names
	will be avoided.
	
(5) Unknown scripts may cause undesired behaviour.
	Don't put arbitrary Python scripts in your Vamp directory,
	you may use a subdirectory for that.

PLUGIN ERRORS:

Script validation is performed by the interpreter itself
using the same rules as module compilation. This means that
while most syntax errors will be noted when Vampy is first
used by a host, runtime errors can still occur during
execution. For example, a plugin calculating the dot product
of two vectors with different sizes will produce a runtime error.

Error messages from Vampy are printed on the standard error
channel.
If you're using a graphical host (such as Sonic Visualiser)
you may start the application from a command line terminal
in order to see these messages, or they may be forwarded by
the host to its own debug log file.
	
Exceptions:
	
* Runtime errors occurring in the plugin's __init__() function
will prevent the host from loading the plugin.  

* Runtime errors in the plugin's initialise() function will
prevent the host from using the plugin.
	
* Module level errors resulting from importing a non-existent
module or source file or an error occurring on an imported
module's source tree will prevent the plugin from loading.

Any other error, including those during the process will
only be noted on the terminal output. Processing errors will
generally result in a blank screen or no results displayed by
graphical hosts.

EXTENSION MODULE:

Vampy extends Python with some useful data types defined
by the Vamp plugin API. This extension module is embedded
into the Vampy shared library, therefore it doesn't need 
to be installed separately. However, it works very similarly 
to any third party Python extension within a Vampy plugin.

You may import the extension in the usual manner using
" import vampy " and " from vampy import * ". (Note that
currently the extension module is not available as a 
separate package, therefore this will only work if the 
plugin is executed by Vampy within a usual host context.)

You can use any standard Python statement involving 
modules such as " dir(vampy) " to print the names exported
by the module. The use of the extension in entirely optional,
however its use is strongly advised for the following reasons:

* Using the module hides the mapping between Python and
C++ data types and provides improved plugin portability.
	
* Returning types exported by the module is often faster.
	
* In future releases its use may become mandatory.

PROCESS INTERFACES:

Most computationally intensive processing takes place in
the plugin's process() method. This method has two arguments,
(besides the 'self' argument mandatory in all Python class methods).

* The fist argument is used to pass audio samples (in time 
domain plugins) or frequency samples (complex FFT output)
in frequency domain plugins. This argument is always a
Python list object where each element of the list corresponds
to an audio channel. (The length of this list can not be zero.)
The actual element types con