comparison README @ 37:27bab3a16c9a vampy2final

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