view README @ 9:d2d36e7d2276

more examples and some bug fixes

 * VamPy is a Vamp plugin wrapper for Python Scripts.

WHAT IS IT FOR?
	
	you can write Vamp plugins in Python which can do the same as the native C++ plugins
	plus more if you're using advanced Python modules.

	you might get into Vamp development more easily this way.
	you can use it for prototyping your plugin before writing in C++	 


LIMITATIONS:

	this is really just a proof of concept. The implementation is not the most efficient.	
	only tested on MacOSX, but in theory should work on other platforms with small fixes	
	The Python C/API is not fully thread safe and correct threading is not yet implemented.
	(This can cause problems resulting in nasty crashes.)

	Error checking is incomplete.
	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 (Sonic Visualiser) from the command line.


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 your 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.
		-Other unknown scripts are likely to cause a nasty crash. 
		(Don't put other python scripts in your Vamp directory.)

	
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 


COMPILING AND LINKING:

	(1) include Python.h wherever it is on your machine 
	(2) this plugin needs to be linked against the Python binary:

	example on on MacOSX:
	g++  -O2 -Wall -I. -fPIC -c -o pyvamp-main.o pyvamp-main.cpp
	g++  -dynamiclib   -o vamp-pyvamp-plugin.dylib ./PyPlugScanner.o ./PyPlugin.o ./pyvamp-main.o sdk/vamp-sdk/libvamp-sdk.a 
	-u _PyMac_Error /Library/Frameworks/Python.framework/Versions/2.5/Python
	
	(3) There is a modified Makefile from the Vamp SDK that compiles this plugin by default.


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