comparison README @ 10:8e9fbe4dc94d

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.
+	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.
 
-	you might get into Vamp development more easily this way.
-	you can use it for prototyping your plugin before writing in C++	 
+	This may be an easier way to get into Vamp development.
+	You can use it for prototyping your plugin before writing it in C++	 
 
 
-LIMITATIONS:
+WHY PYTHON?
 
-	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.
+	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 your python plugins and copy them to the same place.
+	(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.
-		-Other unknown scripts are likely to cause a nasty crash. 
-		(Don't put other python scripts in your Vamp directory.)
+		-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.)
 
 	
-WHY PYTHON?
+COMPILING AND LINKING:
 
-	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 
+	(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.
 
 
-COMPILING AND LINKING:
+LIMITATIONS:
 
-	(1) include Python.h wherever it is on your machine 
-	(2) this plugin needs to be linked against the Python binary:
+	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.	
 
-	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.
+	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 
-	  	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)
+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()