annotate README @ 72:65add4f460e9

* make PluginLoader quicker to load a single named plugin (don't always
  have to bother enumerating them all first)

Vamp
====

An API for audio analysis and feature extraction plugins.

   http://www.vamp-plugins.org/

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.


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.  Plugins
should link with -lvamp-sdk.

Hosts may use the Vamp::PluginHostAdapter to convert the loaded
plugin's C API back into a Vamp::Plugin object.  Hosts should link
with -lvamp-hostsdk.

 * vamp-sdk/hostext

Additional C++ classes to make a host's life easier.

Vamp::HostExt::PluginLoader provides a very simple interface for a
host to discover, load, and find out category information about the
available plugins.  Most "casual" Vamp hosts will probably want to use
this class.

Vamp::HostExt::PluginInputDomainAdapter provides a simple means for
hosts to handle plugins that expect frequency-domain input, without
having to convert the input themselves.

Vamp::HostExt::PluginChannelAdapter provides a simple means for hosts
to use plugins that do not necessarily support the same number of
audio channels as they have available, without having to apply a
channel management / mixdown policy themselves.

The PluginLoader can use the input domain and channel adapters
automatically to make the entire conversion process transparent to the
host if required.

 * 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 (http://www.mega-nerd.com/libsndfile/).

If you don't have libsndfile, you may want to edit the Makefile to
change the default build target from "all" to "sdk" so as to compile
only the SDK.


Plugin Lookup and Categorisation
================================

The Vamp API does not officially specify how to load plugin libraries
or where to find them.  However, the SDK does include a function
(Vamp::PluginHostAdapter::getPluginPath()) that returns a recommended
directory search path that hosts may use for plugin libraries.

Our suggestion for a host is to search each directory in this path for
.DLL (on Windows), .so (on Linux, Solaris, BSD etc) or .dylib (on
OS/X) files, then to load each one and perform a dynamic name lookup
on the vampGetPluginDescriptor function to enumerate the plugins in
the library.  The example host has some code that may help, but this
operation will necessarily be system-dependent.

Vamp also has an informal convention for sorting plugins into
functional categories.  In addition to the library file itself, a
plugin library may install a category file with the same name as the
library but .cat extension.  The existence and format of this file are
not specified by the Vamp API, but by convention the file may contain
lines of the format

vamp:pluginlibrary:pluginname::General Category > Specific Category

which a host may read and use to assign plugins a location within a
category tree for display to the user.  The expectation is that
advanced users may also choose to set up their own preferred category
trees, which is why this information is not queried as part of the
Vamp API itself.


Building and Installing the SDK and Examples
============================================

To build the SDK, the simple host, and the example plugins, edit the
Makefile to suit your platform according to the comments in it, then
run "make".

Installing the example plugins so that they can be found by other Vamp
hosts depends on your platform:

 * Windows: copy the files
      examples/vamp-example-plugins.dll
      examples/vamp-example-plugins.cat
   to
      C:\Program Files\Vamp Plugins

 * Linux: copy the files
      examples/vamp-example-plugins.so
      examples/vamp-example-plugins.cat
   to
      /usr/local/lib/vamp/

 * OS/X: copy the files
      examples/vamp-example-plugins.dylib
      examples/vamp-example-plugins.cat
   to
      /Library/Audio/Plug-Ins/Vamp

When building a plugin or host of your own using the SDK, you will
need to include the headers from the vamp-sdk directory; then when
linking your plugin or host, we suggest statically linking the SDK
code (in preference to distributing it alongside your program in DLL
form).  An easy way to do this, if using a project-based build tool
such as Visual Studio or XCode, is simply to add the .cpp files in the
vamp-sdk directory to your project.


Licensing
=========

This plugin SDK is freely redistributable under a "new-style BSD"
licence.  See the file COPYING for more details.  In short, you may
modify and redistribute the SDK and example plugins within any
commercial or non-commercial, proprietary or open-source plugin or
application under almost any conditions, with no obligation to provide
source code, 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/


Authors
=======

Vamp and the Vamp SDK were designed and made at the Centre for Digital
Music at Queen Mary, University of London.

The SDK was written by Chris Cannam, copyright (c) 2005-2007
Chris Cannam and QMUL.

Mark Sandler and Christian Landone provided ideas and direction, and
Mark Levy, Dan Stowell, Martin Gasser and Craig Sapp provided testing
and other input for the 1.0 API and SDK.  The API also uses some ideas
from prior plugin systems, notably DSSI (http://dssi.sourceforge.net)
and FEAPI (http://feapi.sourceforge.net).