Mercurial > hg > vampy

annotate README @ 37:27bab3a16c9a vampy2final

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
new branch Vampy2final
author fazekasgy
date Mon, 05 Oct 2009 11:28:00 +0000
parents
children d2ff6e7be4a1
rev   line source
fazekasgy@37 1
fazekasgy@37 2 * VamPy is an API wrapper for Vamp. It allows for writing Vamp
fazekasgy@37 3 plugins in Python with or without Numpy support.
fazekasgy@37 4
fazekasgy@37 5 WHAT IS IT FOR?
fazekasgy@37 6
fazekasgy@37 7 This wrapper is for writing Vamp plugins in Python which
fazekasgy@37 8 can do the same as a native C++ plugin, plus a lot more if
fazekasgy@37 9 you're using advanced Python modules.
fazekasgy@37 10
fazekasgy@37 11 This may be an easier way to get into Vamp development.
fazekasgy@37 12 You can use it for prototyping your plugin before writing
fazekasgy@37 13 it in C++.
fazekasgy@37 14
fazekasgy@37 15
fazekasgy@37 16 WHY PYTHON?
fazekasgy@37 17
fazekasgy@37 18 Python is a general purpose high level scripting language.
fazekasgy@37 19 It is interpreted, so you don't need to compile your plugins.
fazekasgy@37 20 It has very high level libraries. e.g. you can stream audio from your VamPy plugin (it works for me...)
fazekasgy@37 21 Supports functional programming.
fazekasgy@37 22
fazekasgy@37 23 UPDATE IN THIS VERSION:
fazekasgy@37 24
fazekasgy@37 25 * Two-way Numpy Support
fazekasgy@37 26 * Embedded extension module exposing Vamp defined names
fazekasgy@37 27 e.g. ParameterDescriptor. This allows easier porting to C++.
fazekasgy@37 28 * Support RealTime time stamps
fazekasgy@37 29 * Support byte compiled Python scripts (.pyc)
fazekasgy@37 30 * Environment variables: VAMPY_COMPILED, VAMPY_EXTPATH
fazekasgy@37 31 * Flags to control type conversion and error reporting for development
fazekasgy@37 32 * Flexible type inference to take advantage of Python's loose typing
fazekasgy@37 33 * Full error checking for all Python/C API calls
fazekasgy@37 34 * Various optimisations and speed-ups
fazekasgy@37 35
fazekasgy@37 36 PREVIOUS VAMPY README:
fazekasgy@37 37
fazekasgy@37 38 HOW DOES IT WORK:
fazekasgy@37 39
fazekasgy@37 40 (1) Make sure you have Python installed.
fazekasgy@37 41 (2) Compile the C++ source or ask me for a binary (MacOS).
fazekasgy@37 42 (3) Copy the library in your Vamp plugin directory like any other Vamp plugins:
fazekasgy@37 43 eg. /Library/Audio/Plug-Ins/Vamp
fazekasgy@37 44 (4) Write some python plugins and copy them to the same place.
fazekasgy@37 45 (5) Each plugin must contain a single class with the same name as your script file.
fazekasgy@37 46 e.g. PyZeroCrossing.py -> calss PyZeroCrossing
fazekasgy@37 47 -Scripts with syntax errors in them are ignored.
fazekasgy@37 48 -Scripts not having the same class as the filename are ignored. (Python is case sensitive!)
fazekasgy@37 49 -Other unknown scripts are likely to cause a crash. (Don't put other python scripts in your Vamp directory.)
fazekasgy@37 50
fazekasgy@37 51
fazekasgy@37 52 COMPILING AND LINKING:
fazekasgy@37 53
fazekasgy@37 54 (1) make sure Python.h is included wherever it is on your machine
fazekasgy@37 55 (2) the plugin needs to be linked against the Python binary: e.g.: ld -lpython2.5
fazekasgy@37 56
fazekasgy@37 57 example on on MacOSX:
fazekasgy@37 58 g++ -I../vamp-plugin-sdk -O2 -Wall -I/usr/include/python2.5 -c -o PyPlugin.o PyPlugin.cpp
fazekasgy@37 59 g++ -I../vamp-plugin-sdk -O2 -Wall -I/usr/include/python2.5 -c -o PyPlugScanner.o PyPlugScanner.cpp
fazekasgy@37 60 g++ -I../vamp-plugin-sdk -O2 -Wall -I/usr/include/python2.5 -c -o pyvamp-main.o pyvamp-main.cpp
fazekasgy@37 61 g++ -I../vamp-plugin-sdk -O2 -Wall -I/usr/include/python2.5 -c -o Mutex.o Mutex.cpp
fazekasgy@37 62 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@37 63
fazekasgy@37 64
fazekasgy@37 65 (3) There is a Makefile that compiles this plugin by default.
fazekasgy@37 66
fazekasgy@37 67
fazekasgy@37 68 LIMITATIONS:
fazekasgy@37 69
fazekasgy@37 70 This is mainly a proof of concept. The implementation is not the most efficient, but using NumPy it's very reasonable.
fazekasgy@37 71 Only tested on MacOSX and Linux (by Chris), but in theory should work on other platforms with small fixes.
fazekasgy@37 72
fazekasgy@37 73 Error checking is not yet fully complete.
fazekasgy@37 74 You better not make a mistake in your Python script, although in most cases you can see what the problem is
fazekasgy@37 75 if you start the host (e.g. Sonic Visualiser) from a command line interface.
fazekasgy@37 76 The wrapper plugin is quite verbose and outputs error messages.
fazekasgy@37 77
fazekasgy@37 78
fazekasgy@37 79 TODO: * needs more complete error checking (almost done)
fazekasgy@37 80 * needs correct implementation of Python threading (done)
fazekasgy@37 81 * more efficient data conversion using the buffering interface or ctypes (done)
fazekasgy@37 82 * Vamp 'programs' not implemented
fazekasgy@37 83 * support multiple classes per script in scanner
fazekasgy@37 84 * ensure proper cleanup, (host does a good job though)
fazekasgy@37 85
fazekasgy@37 86 HISTORY:
fazekasgy@37 87 added support for NumPy arrays in processN()
fazekasgy@37 88 framecount is now passed also to legacy process() and fixed resulting bugs in the PyZeroCrossing plugin
fazekasgy@37 89 added two examples which use Frequency Domain input in processN()
fazekasgy@37 90