cannam@14: 
cannam@14: Vamp
cannam@14: ====
cannam@14: 
cannam@14: An API for audio analysis and feature extraction plugins.
cannam@14: 
cannam@14: Vamp is an API for C and C++ plugins that process sampled audio data
cannam@14: to produce descriptive output, such as measurements of particular
cannam@14: features of the audio or semantic output based on them.
cannam@14: 
cannam@14: The principal differences between Vamp and a real-time audio
cannam@14: processing plugin system such as VST are:
cannam@14: 
cannam@14:  * Vamp plugins may output complex multidimensional data with labels.
cannam@14:    As a consequence, they are likely to work best when the output
cannam@14:    data has a much lower sampling rate than the input.  (This also
cannam@14:    means it is usually desirable to implement them in C++ using the
cannam@14:    high-level base class provided rather than use the raw C API.)
cannam@14: 
cannam@14:  * While Vamp plugins receive data block-by-block, they are not
cannam@14:    required to return output immediately on receiving the input.
cannam@14:    A Vamp plugin may be non-causal, preferring to store up data
cannam@14:    based on its input until the end of a processing run and then
cannam@14:    return all results at once.
cannam@14: 
cannam@14:  * Vamp plugins have more control over their inputs than a typical
cannam@14:    real-time processing plugin.  For example, they can indicate to
cannam@14:    the host the permitted range of processing block sizes, and can
cannam@14:    request input data in the frequency domain instead of the time
cannam@14:    domain.
cannam@14: 
cannam@14:  * A Vamp plugin is configured once before each processing run, and
cannam@14:    receives no further parameter changes during use -- unlike real
cannam@14:    time plugin APIs in which the input parameters may change at any
cannam@14:    time.  This also means that fundamental properties such as the
cannam@14:    number of values per output or the preferred processing block
cannam@14:    size can depend on the input parameters.
cannam@14: 
cannam@14: 
cannam@14: About this SDK
cannam@14: ==============
cannam@14: 
cannam@14: This Software Development Kit contains the following:
cannam@14: 
cannam@14:  * vamp/vamp.h
cannam@14: 
cannam@14: The formal C language plugin API for Vamp plugins.
cannam@14: 
cannam@14: A Vamp plugin is a dynamic library (.so, .dll or .dylib depending on
cannam@14: platform) exposing one C-linkage entry point (vampGetPluginDescriptor)
cannam@14: which returns data defined in the rest of this C header.
cannam@14: 
cannam@14: Although this is the official API for Vamp, we don't recommend that
cannam@14: you program directly to it.  The C++ abstraction in the SDK directory
cannam@14: (below) is likely to be preferable for most purposes and also better
cannam@14: documented.
cannam@14: 
cannam@14:  * vamp-sdk
cannam@14: 
cannam@14: C++ classes for straightforwardly implementing Vamp plugins and hosts.
cannam@14: Plugins should subclass Vamp::Plugin (in vamp-sdk/Plugin.h) and then
cannam@14: use a Vamp::PluginAdapter to expose the correct C API for the plugin.
cannam@14: Hosts may use the Vamp::PluginHostAdapter to convert the loaded
cannam@14: plugin's C API back into a Vamp::Plugin object.
cannam@14: 
cannam@14:  * examples
cannam@14: 
cannam@14: Example plugins implemented using the C++ classes.  ZeroCrossing
cannam@14: calculates the positions and density of zero-crossing points in an
cannam@14: audio waveform; SpectralCentroid calculates the centre of gravity of
cannam@14: the frequency domain representation of each block of audio.
cannam@14: 
cannam@14:  * host
cannam@14: 
cannam@14: The simplest possible Vamp host -- this doesn't even process anything
cannam@14: yet, just loads the plugins and prints out their names.
cannam@14: 
cannam@14: 
cannam@14: Building the SDK
cannam@14: ================
cannam@14: 
cannam@14: Edit the Makefile for your platform according to the comments in it.
cannam@14: Type "make".
cannam@14: 
cannam@14: 
cannam@14: Licensing
cannam@14: =========
cannam@14: 
cannam@14: This plugin SDK is freely redistributable under the "new BSD" licence.
cannam@14: See the file COPYING for more details.  In short, you are permitted to
cannam@14: reuse the SDK and example plugins in any commercial or non-commercial,
cannam@14: proprietary or open-source application under almost any conditions.
cannam@14: 
cannam@14: 
cannam@14: See Also
cannam@14: ========
cannam@14: 
cannam@14: Sonic Visualiser, an interactive open-source graphical audio
cannam@14: inspection, analysis and visualisation tool supporting Vamp plugins.
cannam@14: 
cannam@14: 
cannam@14: Chris Cannam
cannam@14: Centre for Digital Music
cannam@14: Queen Mary, University of London