Mercurial > hg > vampy
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 |