241 lines
9.4 KiB
Plaintext
241 lines
9.4 KiB
Plaintext
|
|
||
|
|
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 is version 1.1b of the Vamp plugin Software Development Kit.
|
||
|
|
Plugins and hosts built with this SDK are binary compatible with those
|
||
|
|
built using version 1.0 of the 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++ abstraction found in the
|
||
|
|
vamp-sdk directory (below) is preferable for most purposes and is
|
||
|
|
more thoroughly documented.
|
||
|
|
|
||
|
|
* vamp-sdk
|
||
|
|
|
||
|
|
C++ classes for straightforwardly implementing Vamp plugins and hosts.
|
||
|
|
|
||
|
|
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, and
|
||
|
|
refer to the example plugin code in the examples directory. Plugins
|
||
|
|
should link with -lvampsdk. [*NOTE: this has changed from vamp-sdk in
|
||
|
|
previous versions, to avoid conflict with the use of hyphens for
|
||
|
|
library versioning schemes on some platforms.]
|
||
|
|
|
||
|
|
Hosts may use the Vamp::PluginHostAdapter to convert the loaded
|
||
|
|
plugin's C API back into a Vamp::Plugin object. Host authors should
|
||
|
|
refer to the example host code in the host directory. Hosts should
|
||
|
|
link with -lvamphostsdk. [*NOTE: this has changed from vamp-hostsdk
|
||
|
|
in previous versions, to avoid conflict with the use of hyphens for
|
||
|
|
library versioning schemes on some platforms.]
|
||
|
|
|
||
|
|
* vamp-sdk/hostext
|
||
|
|
|
||
|
|
Additional C++ classes to make a host's life easier (introduced in
|
||
|
|
version 1.1 of the Vamp SDK).
|
||
|
|
|
||
|
|
Vamp::HostExt::PluginLoader provides a very easy 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 means for hosts to
|
||
|
|
handle plugins that expect frequency-domain input, without having to
|
||
|
|
convert the input themselves.
|
||
|
|
|
||
|
|
Vamp::HostExt::PluginChannelAdapter provides a means for hosts to use
|
||
|
|
plugins that do not necessarily support the same number of audio
|
||
|
|
channels as they have available, without having to worry about
|
||
|
|
applying a channel management / mixdown policy themselves.
|
||
|
|
|
||
|
|
The PluginLoader class can also 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.
|
||
|
|
AmplitudeFollower tracks the amplitude of a signal based on a method
|
||
|
|
from the SuperCollider real-time audio system.
|
||
|
|
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 and not the host.
|
||
|
|
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
|
||
|
|
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".
|
||
|
|
|
||
|
|
To use an IDE to build a plugin or host using the Vamp SDK, simply add
|
||
|
|
the .cpp files in the vamp-sdk directory to your project.
|
||
|
|
|
||
|
|
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
|
||
|
|
|
||
|
|
|
||
|
|
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).
|
||
|
|
|