annotate README @ 10:8e9fbe4dc94d

more examples and some bug fixes
author fazekasgy
date Fri, 13 Jun 2008 17:28:22 +0000
parents a4c955e9a70b
children
rev   line source
fazekasgy@0 1
cannam@7 2 * VamPy is a Vamp plugin wrapper for Python Scripts.
fazekasgy@0 3
fazekasgy@0 4 WHAT IS IT FOR?
fazekasgy@0 5
fazekasgy@10 6 This wrapper is for writing Vamp plugins in Python which can do the same as a native C++ plugin,
fazekasgy@10 7 plus a lot more if you're using advanced Python modules.
fazekasgy@0 8
fazekasgy@10 9 This may be an easier way to get into Vamp development.
fazekasgy@10 10 You can use it for prototyping your plugin before writing it in C++
fazekasgy@0 11
fazekasgy@0 12
fazekasgy@10 13 WHY PYTHON?
fazekasgy@0 14
fazekasgy@10 15 Python is a general purpose high level scripting language.
fazekasgy@10 16 It is interpreted, so you don't need to compile your plugins.
fazekasgy@10 17 It has very high level libraries. e.g. you can stream audio from your VamPy plugin (it works for me...)
fazekasgy@10 18 Supports functional programming.
fazekasgy@0 19
fazekasgy@0 20
fazekasgy@0 21 HOW DOES IT WORK:
fazekasgy@0 22
fazekasgy@0 23 (1) Make sure you have Python installed.
fazekasgy@0 24 (2) Compile the C++ source or ask me for a binary (MacOS).
cannam@7 25 (3) Copy the library in your Vamp plugin directory like any other Vamp plugins:
cannam@7 26 eg. /Library/Audio/Plug-Ins/Vamp
fazekasgy@10 27 (4) Write some python plugins and copy them to the same place.
fazekasgy@0 28 (5) Each plugin must contain a single class with the same name as your script file.
fazekasgy@0 29 e.g. PyZeroCrossing.py -> calss PyZeroCrossing
fazekasgy@0 30 -Scripts with syntax errors in them are ignored.
fazekasgy@10 31 -Scripts not having the same class as the filename are ignored. (Python is case sensitive!)
fazekasgy@10 32 -Other unknown scripts are likely to cause a crash. (Don't put other python scripts in your Vamp directory.)
fazekasgy@0 33
fazekasgy@0 34
fazekasgy@0 35 COMPILING AND LINKING:
fazekasgy@1 36
fazekasgy@10 37 (1) make sure Python.h is included wherever it is on your machine
fazekasgy@10 38 (2) the plugin needs to be linked against the Python binary: e.g.: ld -lpython2.5
fazekasgy@0 39
fazekasgy@0 40 example on on MacOSX:
fazekasgy@10 41 g++ -I../vamp-plugin-sdk -O2 -Wall -I/usr/include/python2.5 -c -o PyPlugin.o PyPlugin.cpp
fazekasgy@10 42 g++ -I../vamp-plugin-sdk -O2 -Wall -I/usr/include/python2.5 -c -o PyPlugScanner.o PyPlugScanner.cpp
fazekasgy@10 43 g++ -I../vamp-plugin-sdk -O2 -Wall -I/usr/include/python2.5 -c -o pyvamp-main.o pyvamp-main.cpp
fazekasgy@10 44 g++ -I../vamp-plugin-sdk -O2 -Wall -I/usr/include/python2.5 -c -o Mutex.o Mutex.cpp
fazekasgy@10 45 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
fazekasgy@10 46
fazekasgy@0 47
fazekasgy@10 48 (3) There is a Makefile that compiles this plugin by default.
fazekasgy@0 49
fazekasgy@0 50
fazekasgy@10 51 LIMITATIONS:
fazekasgy@0 52
fazekasgy@10 53 This is mainly a proof of concept. The implementation is not the most efficient, but using NumPy it's very reasonable.
fazekasgy@10 54 Only tested on MacOSX and Linux (by Chris), but in theory should work on other platforms with small fixes.
fazekasgy@0 55
fazekasgy@10 56 Error checking is not yet fully complete.
fazekasgy@10 57 You better not make a mistake in your Python script, although in most cases you can see what the problem is
fazekasgy@10 58 if you start the host (e.g. Sonic Visualiser) from a command line interface.
fazekasgy@10 59 The wrapper plugin is quite verbose and outputs error messages.
fazekasgy@10 60
fazekasgy@10 61
fazekasgy@10 62 TODO: * needs more complete error checking (almost done)
fazekasgy@10 63 * needs correct implementation of Python threading (done)
fazekasgy@10 64 * more efficient data conversion using the buffering interface or ctypes (done)
fazekasgy@10 65 * Vamp 'programs' not implemented
fazekasgy@10 66 * support multiple classes per script in scanner
fazekasgy@10 67 * ensure proper cleanup, (host does a good job though)
fazekasgy@10 68
fazekasgy@10 69 HISTORY:
fazekasgy@10 70 added support for NumPy arrays in processN()
fazekasgy@10 71 framecount is now passed also to legacy process() and fixed resulting bugs in the PyZeroCrossing plugin
fazekasgy@10 72 added two examples which use Frequency Domain input in processN()
fazekasgy@10 73