Vamp Plugin SDK

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).

This is version 2.10 of the Vamp plugin Software Development Kit.

Plugins and hosts built with this SDK are binary compatible with those

built using any version 2.0 or newer of the SDK.

Plugins and hosts built with this SDK are binary compatible with those

built using version 1.0 of the SDK, with certain restrictions.  See

the file README.compat for more details.

See the file CHANGELOG for a list of the changes in this release.

A documentation guide to writing plugins using the Vamp SDK can be

found at http://www.vamp-plugins.org/guide.pdf .

Compiling and Installing the SDK and Examples

=============================================

This SDK is intended for use on Windows, OS/X, Linux, and other POSIX

and GNU platforms.

Please see the platform-specific README file (README.msvc, README.osx,

README.linux) in the build/ directory for details about how to compile

and install the SDK, how to build plugin libraries using it, and how

to install the example plugins so you can use them in a host.

What's In This SDK

==================

This SDK 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 the C API is the official API for Vamp, we don't recommend

that you program directly to it.  The C++ abstractions found in the

vamp-sdk and vamp-hostsdk directories (below) are preferable for most

purposes and are more thoroughly documented.

vamp-sdk

--------

C++ classes for implementing Vamp plugins.

Plugins should subclass Vamp::Plugin and then use Vamp::PluginAdapter

to expose the correct C API for the plugin.  Plugin authors should

read vamp-sdk/PluginBase.h and Plugin.h for code documentation.

See "examples" below for details of the example plugins in the SDK,

from which you are welcome to take code and inspiration.

Plugins should link with -lvamp-sdk.

vamp-hostsdk

------------

C++ classes for implementing Vamp hosts.

Hosts will normally use a Vamp::PluginHostAdapter to convert each

plugin's exposed C API back into a useful Vamp::Plugin C++ object.

The Vamp::HostExt namespace contains several additional C++ classes to

do this work for them, and make the host's life easier:

 - Vamp::HostExt::PluginLoader provides a very easy interface for a

 host to discover, load, and find out category information about the

 available plugins.  Most Vamp hosts will probably want to use this

 class.

 - Vamp::HostExt::PluginInputDomainAdapter provides a simple means for

 hosts to handle plugins that want 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.

 - Vamp::HostExt::PluginBufferingAdapter provides a means for hosts to

 avoid having to negotiate the input step and block size, instead

 permitting the host to use any block size they desire (and a step

 size equal to it).  This is particularly useful for "streaming" hosts

 that cannot seek backwards in the input audio stream and so would

 otherwise need to implement an additional buffer to support step

 sizes smaller than the block size.

 - Vamp::HostExt::PluginSummarisingAdapter provides summarisation

 methods such as mean and median averages of output features, for use

 in any context where an available plugin produces individual values

 but the result that is actually needed is some sort of aggregate.

The PluginLoader class can also use the input domain, channel, and

buffering adapters automatically to make these conversions transparent

to the host if required.

Host authors should also refer to the example host code in the host

directory of the SDK.

Hosts should link with -lvamp-hostsdk.

vamp-hostsdk/host-c.h

---------------------

A C-linkage header wrapping the part of the C++ SDK code that handles

plugin discovery and library loading. Host programs written in C or in

a language with a C-linkage foreign function interface may choose to

use this header to discover and load plugin libraries, together with

the vamp/vamp.h formal API to interact with plugins themselves. See

the header for more documentation.

examples

--------

Example plugins implemented using the C++ classes.

These plugins are intended to be useful examples you can draw code

from in order to provide the basic shape and structure of a Vamp

plugin.  They are also intended to be correct and useful, if simple.

 - 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.

 - PowerSpectrum calculates a power spectrum from the input audio.

 Actually, it doesn't do any work except calculating power from a

 cartesian complex FFT output.  The work of calculating this frequency

 domain output is done for it by the host or host SDK; the plugin just

 needs to declare that it wants frequency domain input.  This is the

 simplest of the example plugins.

 - AmplitudeFollower is a simple implementation of SuperCollider's

 amplitude-follower algorithm.

 - 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.

 - FixedTempoEstimator calculates a single beats-per-minute value

 which is an estimate of the tempo of a piece of music that is assumed

 to be of fixed tempo, using autocorrelation of a frequency domain

 energy rise metric.  It has several outputs that return intermediate

 results used in the calculation, and may be a useful example of a

 plugin having several outputs with varying feature structures.

skeleton

--------

Skeleton code that could be used as a template for your new plugin

implementation.

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.

This host also contains a number of options for listing the installed

plugins and their properties in various formats.  For that reason, it

isn't really as simple as one might hope.  The core of the code is

still reasonably straightforward, however.

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, and a

class (Vamp::HostExt::PluginLoader) that implements a sensible

cross-platform lookup policy using this path.  We recommend using this

class in your host unless you have a good reason not to want to.  This

implementation also permits the user to set the environment variable

VAMP_PATH to override the default path if desired.

The policy used by Vamp::HostExt::PluginLoader -- and our

recommendation for any host -- is to search each directory in the path

returned by getPluginPath 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.  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 plugin's API itself.  The Vamp::HostExt::PluginLoader class also

provides support for plugin category lookup using this scheme.

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-2017

Chris Cannam and QMUL.

The SDK incorporates KissFFT code, copyright (c) 2003-2010 Mark

Borgerding.

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).