annotate README @ 38:7d237da42772

...

Vamp
====
http://www.sonicvisualiser.org/vamp.html

An API for audio analysis and feature extraction plugins.

Vamp is an API for C and C++ plugins that process sampled audio data
to produce descriptive output (measurements or semantic observations).

The principal differences between Vamp and a real-time audio
processing plugin system such as VST are:

 * Vamp plugins may output complex multidimensional data with labels.
   As a consequence, they are likely to work best when the output
   data has a much lower sampling rate than the input.  (This also
   means it is usually desirable to implement them in C++ using the
   high-level base class provided rather than use the raw C API.)

 * While Vamp plugins receive data block-by-block, they are not
   required to return output immediately on receiving the input.
   A Vamp plugin may be non-causal, preferring to store up data
   based on its input until the end of a processing run and then
   return all results at once.

 * Vamp plugins have more control over their inputs than a typical
   real-time processing plugin.  For example, they can indicate to
   the host their preferred processing block and step sizes, and these
   may differ.

 * Vamp plugins may ask to receive data in the frequency domain
   instead of the time domain.  The host takes the responsibility
   for converting the input data using an FFT of windowed frames.
   This simplifies plugins that do straightforward frequency-domain
   processing and permits the host to cache frequency-domain data
   when possible.

 * A Vamp plugin is configured once before each processing run, and
   receives no further parameter changes during use -- unlike real
   time plugin APIs in which the input parameters may change at any
   time.  This also means that fundamental properties such as the
   number of values per output or the preferred processing block
   size may depend on the input parameters.

 * Vamp plugins do not have to be able to run in real time.

Vamp reuses some ideas from several existing systems, notably DSSI
(http://dssi.sourceforge.net) and FEAPI (http://feapi.sourceforge.net).


About this SDK
==============

This Software Development Kit contains the following:

 * vamp/vamp.h

The formal C language plugin API for Vamp plugins.

A Vamp plugin is a dynamic library (.so, .dll or .dylib depending on
platform) exposing one C-linkage entry point (vampGetPluginDescriptor)
which returns data defined in the rest of this C header.

Although this is the official API for Vamp, we don't recommend that
you program directly to it.  The C++ abstraction in the SDK directory
(below) is likely to be preferable for most purposes, and is better
documented.

 * vamp-sdk

C++ classes for straightforwardly implementing Vamp plugins and hosts.

Plugins should subclass Vamp::Plugin and then use a
Vamp::PluginAdapter to expose the correct C API for the plugin.  Read
vamp-sdk/PluginBase.h and Plugin.h for code documentation.

Hosts may use the Vamp::PluginHostAdapter to convert the loaded
plugin's C API back into a Vamp::Plugin object.

 * examples

Example plugins implemented using the C++ classes.  ZeroCrossing
calculates the positions and density of zero-crossing points in an
audio waveform.  SpectralCentroid calculates the centre of gravity of
the frequency domain representation of each block of audio.
PercussionOnsetDetector estimates the locations of percussive onsets
using a simple method described in "Drum Source Separation using
Percussive Feature Detection and Spectral Modulation" by Dan Barry,
Derry Fitzgerald, Eugene Coyle and Bob Lawlor, ISSC 2005.

 * host

A simple command-line Vamp host, capable of loading a plugin and using
it to process a complete audio file, with its default parameters.
Requires libsndfile.

The Vamp API doesn't officially specify how to load plugin libraries
or where to find them.  However, good practice for a host is to use
the Vamp path returned by Vamp::PluginHostAdapter::getPluginPath() and
search each directory in this path for .so, .dll or .dylib files
(depending on platform), loading each one and testing for the
vampGetPluginDescriptor function to enumerate the plugins in this
object.  The example host has some code that may help.


Building the SDK
================

Edit the Makefile to suit your platform according to the comments in
it.  Type "make".


Licensing
=========

This plugin SDK is freely redistributable under a "new-style BSD"
licence.  See the file COPYING for more details.  In short, you are
permitted to reuse the SDK and example plugins in any commercial or
non-commercial, proprietary or open-source application or plugin under
almost any conditions provided you retain the original copyright note.


See Also
========

Sonic Visualiser, an interactive open-source graphical audio
inspection, analysis and visualisation tool supporting Vamp plugins.
http://www.sonicvisualiser.org/


Chris Cannam
Centre for Digital Music
Queen Mary, University of London