view README @ 24:7d28bed0864e

* Rearrange Python plugin construction.

  Formerly, the PyPluginAdapter has retained a single plugin instance pointer
  for each plugin found, and its createPlugin method has simply returned a new
  PyPlugin object wrapping the same instance pointer.  This has a couple of
  negative consequences:
   - Because construction of the actual Python instance occurred before the
     wrapper was constructed, it was not possible to pass arguments (i.e.
     the sample rate) from the wrapper constructor to the Python plugin
     instance constructor -- they had to be passed later, to initialise,
     disadvantaging those plugins that would like to use the sample rate
     for parameter & step/block size calculations etc
   - Because there was only a single Python plugin instance, it was not
     possible to run more than one instance at once with any isolation

  This rework instead stores the Python class pointer (rather than instance
  pointer) in the PyPluginAdapter, and each PyPlugin wrapper instance creates
  its own Python plugin instance.  What could possibly go wrong?

 * VamPy is a Vamp plugin wrapper for Python Scripts.

WHAT IS IT FOR?
	
	This wrapper is for writing Vamp plugins in Python which can do the same as a native C++ plugin,
	plus a lot more if you're using advanced Python modules.

	This may be an easier way to get into Vamp development.
	You can use it for prototyping your plugin before writing it in C++	 


WHY PYTHON?

	Python is a general purpose high level scripting language.
	It is interpreted, so you don't need to compile your plugins.
	It has very high level libraries. e.g. you can stream audio from your VamPy plugin (it works for me...)
	Supports functional programming. 


HOW DOES IT WORK:

	(1) Make sure you have Python installed.
	(2) Compile the C++ source or ask me for a binary (MacOS).
	(3) Copy the library in your Vamp plugin directory like any other Vamp plugins: 
		eg. /Library/Audio/Plug-Ins/Vamp
	(4) Write some python plugins and copy them to the same place.
	(5) Each plugin must contain a single class with the same name as your script file.
		e.g. PyZeroCrossing.py -> calss PyZeroCrossing
		-Scripts with syntax errors in them are ignored.
		-Scripts not having the same class as the filename are ignored. (Python is case sensitive!)
		-Other unknown scripts are likely to cause a crash.  (Don't put other python scripts in your Vamp directory.)

	
COMPILING AND LINKING:

	(1) make sure Python.h is included wherever it is on your machine 
	(2) the plugin needs to be linked against the Python binary: e.g.: ld -lpython2.5

	example on on MacOSX:
	g++ -I../vamp-plugin-sdk -O2 -Wall -I/usr/include/python2.5   -c -o PyPlugin.o PyPlugin.cpp
	g++ -I../vamp-plugin-sdk -O2 -Wall -I/usr/include/python2.5   -c -o PyPlugScanner.o PyPlugScanner.cpp
	g++ -I../vamp-plugin-sdk -O2 -Wall -I/usr/include/python2.5   -c -o pyvamp-main.o pyvamp-main.cpp
	g++ -I../vamp-plugin-sdk -O2 -Wall -I/usr/include/python2.5   -c -o Mutex.o Mutex.cpp
	g++ -shared PyPlugin.o PyPlugScanner.o pyvamp-main.o Mutex.o -o vampy.dylib -L../vamp-plugin-sdk/vamp-sdk -lvamp-sdk -dynamiclib -lpython2.5 -lpthread

	
	(3) There is a Makefile that compiles this plugin by default.


LIMITATIONS:

	This is mainly a proof of concept. The implementation is not the most efficient, but using NumPy it's very reasonable.	
	Only tested on MacOSX and Linux (by Chris), but in theory should work on other platforms with small fixes.	

	Error checking is not yet fully complete.
	You better not make a mistake in your Python script, although in most cases you can see what the problem is 
	if you start the host (e.g. Sonic Visualiser) from a command line interface.
	The wrapper plugin is quite verbose and outputs error messages.


TODO:	* needs more complete error checking (almost done)
	* needs correct implementation of Python threading (done)
	* more efficient data conversion using the buffering interface or ctypes (done)
	* Vamp 'programs' not implemented
	* support multiple classes per script in scanner
	* ensure proper cleanup, (host does a good job though)

HISTORY:
	added support for NumPy arrays in processN()
	framecount is now passed also to legacy process() and fixed resulting bugs in the PyZeroCrossing plugin
	added two examples which use Frequency Domain input in processN()