annotate README @ 53:7e59caea821b

* Make a better job of preloading Python, especially when it's in a
  framework.  Go for the Python file in the frameworks directory in
  preference to any libpythonX.Y.dylib.  Particularly, don't try to
  preload any library without an absolute path until we've exhausted
  all our framework possibilities (so as to avoid picking up an
  ancient system library).

 * VamPy is an API wrapper for Vamp. It allows for writing Vamp 
	plugins in Python with or without Numpy support.


WHAT IS IT FOR?
	
	This wrapper is for writing Vamp plugins in Python which 
	can do the same as a native C++ plugin, plus a lot more if 
	you're using advanced Python modules such as Numpy and Scipy.

	This may be an easier way to get into Vamp development.
	You can use it for prototyping your plugin before writing 
	it in C++.
	

WHY PYTHON?

	Python is a general purpose high level scripting language.
	It is interpreted, so you don't need to compile your plugins.
	It has very high level libraries. e.g. you can stream audio 
	from a Vampy plugin if you want to.
	Supports functional programming. 


UPDATES IN THIS VERSION (Vampy 2.0):

	* Two-way Numpy Support
	* Embedded extension module exposing Vamp defined names 
		e.g. ParameterDescriptor. This allows easier porting to C++.
	* Support RealTime time stamps
	* Support byte compiled Python scripts (.pyc)
	* Environment variables: VAMPY_COMPILED, VAMPY_EXTPATH
	* Flags to control type conversion and error reporting for development
	* Flexible type inference to take advantage of Python's loose typing
	* Full error checking for all Python/C API calls
	* Various optimisations and speed-ups
	
	Vampy now supports two main use cases: 
	1) Prototyping C++ Vamp plugins in Python.
	2) Develop Vampy plugins in Python to allow the use of a vamp
	hosts for e.g. batch processing or visualisation.
	
	Vampy provides an extension module which allows the use of
	Vamp data types such as FeatureSet() or RealTime() in Vampy plugins. 


HOW DOES IT WORK:

	(1) Make sure you have Python (and Numpy) installed.
	(2) Download Vampy and install it to your Vamp plugin path.
		eg. /Library/Audio/Plug-Ins/Vamp
	(3) Write some python plugins and copy them to the same place.
	(4) Each plugin must contain a single class with the same name as your script file.
		e.g. PyZeroCrossing.py -> calss PyZeroCrossing
		-Scripts with syntax errors in them are ignored.
		-Scripts not having the same class as the filename are ignored. (Python is case sensitive!)
		-Other unknown scripts may cause a crash.  
		(Don't put other python scripts in your Vamp directory.)
	    Some example plugin scripts are provided in "Example VamPy plugins".

FLAGS :

	You can use some flags to control Vampy. They are:

	vf_NULL : zero value, default for vampy version 1 behaviour
	vf_DEBUG : print debug messages to standard error
	vf_STRICT : more strict type conversion (follows the C++ API more closely)
	vf_QUIT : quit the host process on hard errors
	vf_REALTIME : use RealTime time stamps
	vf_BUFFER : use the Numpy buffer interface to 
				pass time/frequency domain samples to the python process

	vf_ARRAY : use the numpy Array interface directly

	vf_DEFAULT_V2 : default Vampy version 2 behaviour 
					(= vf_ARRAY | vf_REALTIME)
					
	The use of these flags is optional. The default behaviour is
	that of Vampy version 1.
	
	To set the flags, place a variable called 'vampy_flags' in
	your plugin class's __init__() function.
	
	Example:
	
	class PyMFCC(melScaling): 
		def __init__(self,inputSampleRate):
			self.vampy_flags = vf_DEBUG | vf_ARRAY | vf_REALTIME
	

ENVIRONMENT VARIABLES:

	Vampy recognises two optional environment variables:
	
	VAMPY_COMPILED=1 recognise byte compiled python plugins (default)
	VAMPY_COMPILED=0 ignore them 
	VAMPY_EXTPATH: if given, searches this path for vampy plugins.
	(This is useful if you want to keep your python plugins separate.)
	Only a single fully qualified path name is recognised.
	
	Example:
	export VAMPY_EXTPATH="/Users/Shared/Development/vampy-path"

	
COMPILING AND LINKING:
	
	Please use the make files provided.
	Make sure the correct include locations are provided for
	Python, Numpy, and the Vamp plugin SDK.

	
COMPILER OPTIONS: 

	HAVE_NUMPY : compile with Numpy array interface support

	for developers:
	_DEBUG : print very detailed messages and logs while Vampy is in use
	_DEBUG_VALUES : print all converted values to stderr


TODO:	
	* Vamp 'programs' not implemented
	* support multiple classes per script in scanner


HISTORY:

	v1:
	* added support for Numpy arrays in processN()
	* framecount is now passed also to legacy process() and fixed resulting bugs in the PyZeroCrossing plugin
	* added two examples which use Frequency Domain input in processN()

	v2.0:
	* complete rewrite (using generic functions implementing full error checking)
	* added extension module : support RealTime and other Vamp type wrappers
	* added Numpy Array interface
	* added flags
	* added environment variables
	* recognise byte compiled python scripts
	
LICENCE:

	VamPy is distributed under a "new-style BSD" license; see the
	file COPYING for details.  You may modify and redistribute it
	within any commercial or non-commercial, proprietary or
	open-source context.  VamPy imposes no limitation on how you
	may choose to license your own plugin scripts.  Note that
	these happen to be the same terms as the Vamp SDK itself.

	VamPy was written by Gyorgy Fazekas at the Centre for Digital
	  Music, Queen Mary University of London.
	Copyright 2008-2009 Gyorgy Fazekas.