comparison README @ 38:d2ff6e7be4a1 vampy2final

updated vampy2final readme
author fazekasgy
date Mon, 05 Oct 2009 12:05:26 +0000
parents 27bab3a16c9a
children 66dafe6a7377
comparison
equal deleted inserted replaced
37:27bab3a16c9a 38:d2ff6e7be4a1
1 1
2 * VamPy is an API wrapper for Vamp. It allows for writing Vamp 2 * VamPy is an API wrapper for Vamp. It allows for writing Vamp
3 plugins in Python with or without Numpy support. 3 plugins in Python with or without Numpy support.
4
4 5
5 WHAT IS IT FOR? 6 WHAT IS IT FOR?
6 7
7 This wrapper is for writing Vamp plugins in Python which 8 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 can do the same as a native C++ plugin, plus a lot more if
9 you're using advanced Python modules. 10 you're using advanced Python modules such as Numpy and Scipy.
10 11
11 This may be an easier way to get into Vamp development. 12 This may be an easier way to get into Vamp development.
12 You can use it for prototyping your plugin before writing 13 You can use it for prototyping your plugin before writing
13 it in C++. 14 it in C++.
14 15
15 16
16 WHY PYTHON? 17 WHY PYTHON?
17 18
18 Python is a general purpose high level scripting language. 19 Python is a general purpose high level scripting language.
19 It is interpreted, so you don't need to compile your plugins. 20 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 It has very high level libraries. e.g. you can stream audio
22 from a Vampy plugin if you want to.
21 Supports functional programming. 23 Supports functional programming.
22 24
23 UPDATE IN THIS VERSION: 25
26 UPDATES IN THIS VERSION (Vampy 2.0):
24 27
25 * Two-way Numpy Support 28 * Two-way Numpy Support
26 * Embedded extension module exposing Vamp defined names 29 * Embedded extension module exposing Vamp defined names
27 e.g. ParameterDescriptor. This allows easier porting to C++. 30 e.g. ParameterDescriptor. This allows easier porting to C++.
28 * Support RealTime time stamps 31 * Support RealTime time stamps
30 * Environment variables: VAMPY_COMPILED, VAMPY_EXTPATH 33 * Environment variables: VAMPY_COMPILED, VAMPY_EXTPATH
31 * Flags to control type conversion and error reporting for development 34 * Flags to control type conversion and error reporting for development
32 * Flexible type inference to take advantage of Python's loose typing 35 * Flexible type inference to take advantage of Python's loose typing
33 * Full error checking for all Python/C API calls 36 * Full error checking for all Python/C API calls
34 * Various optimisations and speed-ups 37 * Various optimisations and speed-ups
38
39 Vampy now supports two main use cases:
40 1) Prototyping C++ Vamp plugins in Python.
41 2) Develop Vampy plugins in Python to allow the use of a vamp
42 hosts for e.g. batch processing or visualisation.
43
44 Vampy provides an extension module which allows the use of
45 Vamp data types such as FeatureSet() or RealTime() in Vampy plugins.
35 46
36 PREVIOUS VAMPY README:
37 47
38 HOW DOES IT WORK: 48 HOW DOES IT WORK:
39 49
40 (1) Make sure you have Python installed. 50 (1) Make sure you have Python (and Numpy) installed.
41 (2) Compile the C++ source or ask me for a binary (MacOS). 51 (2) Download and install vampy into your vamp plugin path.
42 (3) Copy the library in your Vamp plugin directory like any other Vamp plugins:
43 eg. /Library/Audio/Plug-Ins/Vamp 52 eg. /Library/Audio/Plug-Ins/Vamp
44 (4) Write some python plugins and copy them to the same place. 53 (3) 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. 54 (4) Each plugin must contain a single class with the same name as your script file.
46 e.g. PyZeroCrossing.py -> calss PyZeroCrossing 55 e.g. PyZeroCrossing.py -> calss PyZeroCrossing
47 -Scripts with syntax errors in them are ignored. 56 -Scripts with syntax errors in them are ignored.
48 -Scripts not having the same class as the filename are ignored. (Python is case sensitive!) 57 -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.) 58 -Other unknown scripts may cause a crash.
59 (Don't put other python scripts in your Vamp directory.)
60
61 FLAGS :
62
63 You can use some flags to control Vampy. They are:
64
65 vf_NULL : zero value, default for vampy version 1 behaviour
66 vf_DEBUG : print debug messages to standard error
67 vf_STRICT : more strict type conversion (follows the C++ API more closely)
68 vf_QUIT : quit the host process on hard errors
69 vf_REALTIME : use RealTime time stamps
70 vf_BUFFER : use the Numpy buffer interface to
71 pass time/frequency domain samples to the python process
72
73 vf_ARRAY : use the numpy Array interface directly
74
75 vf_DEFAULT_V2 : default Vampy version 2 behaviour
76 (= vf_ARRAY | vf_REALTIME)
77
78 The use of these flags is optional. The default behaviour is
79 that of Vampy version 1.
80
81 To set the flags, place a variable called 'vampy_flags' in
82 your plugin class's __init__() function.
83
84 Example:
85
86 class PyMFCC(melScaling):
87 def __init__(self,inputSampleRate):
88 self.vampy_flags = vf_DEBUG | vf_ARRAY | vf_REALTIME
89
90
91 ENVIRONMENT VARIABLES:
92
93 Vampy recognises two optional environment variables:
94
95 VAMPY_COMPILED=1 recognise byte compiled python plugins (default)
96 VAMPY_COMPILED=0 ignore them
97 VAMPY_EXTPATH: if given, searches this path for vampy plugins.
98 (This is useful if you want to keep your python plugins separate.)
99 Only a single fully qualified path name is recognised.
100
101 Example:
102 export VAMPY_EXTPATH="/Users/Shared/Development/vampy-path"
50 103
51 104
52 COMPILING AND LINKING: 105 COMPILING AND LINKING:
53 106
54 (1) make sure Python.h is included wherever it is on your machine 107 Please use the make files provided.
55 (2) the plugin needs to be linked against the Python binary: e.g.: ld -lpython2.5 108 Make sure the correct include locations are provided for
56 109 Python, Numpy, and the Vamp plugin SDK.
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 110
64 111
65 (3) There is a Makefile that compiles this plugin by default. 112 COMPILER OPTIONS:
113
114 HAVE_NUMPY : compile with Numpy array interface support
115
116 for developers:
117 _DEBUG : print very detailed messages and logs while Vampy is in use
118 _DEBUG_VALUES : print all converted values to stderr
66 119
67 120
68 LIMITATIONS: 121 TODO:
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 122 * Vamp 'programs' not implemented
83 * support multiple classes per script in scanner 123 * support multiple classes per script in scanner
84 * ensure proper cleanup, (host does a good job though)
85 124
86 HISTORY: 125 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 126
127 v1:
128 * added support for NumPy arrays in processN()
129 * framecount is now passed also to legacy process() and fixed resulting bugs in the PyZeroCrossing plugin
130 * added two examples which use Frequency Domain input in processN()
131
132 v2.0:
133 * complete rewrite (using generic functions implementing full error checking)
134 * added extension module : support RealTime and other Vamp type wrappers
135 * added numpy Array interface
136 * added falgs
137 * added environment variables
138 * recognise byte compiled python scripts
139
140
141