annotate README @ 39:66dafe6a7377 vampy2final

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