163 lines
7.2 KiB
Plaintext
163 lines
7.2 KiB
Plaintext
|
|
/** \mainpage Vamp Plugin SDK
|
|
|
|
\section about About Vamp
|
|
|
|
Vamp is an API for C and C++ plugins that process sampled audio data
|
|
to produce descriptive output (measurements or semantic observations).
|
|
Find more information at http://www.vamp-plugins.org/ .
|
|
|
|
Although the official API for Vamp plugins is defined in C for maximum
|
|
binary compatibility, we strongly recommend using the provided C++
|
|
classes in the SDK to implement your own plugins and hosts.
|
|
|
|
\section plugins For Plugins
|
|
|
|
Plugins should subclass Vamp::Plugin, and then use a
|
|
Vamp::PluginAdapter to expose the correct C API for the plugin. Read
|
|
the documentation for Vamp::PluginBase and Vamp::Plugin before
|
|
starting.
|
|
|
|
Plugins should be compiled and linked into dynamic libraries using the
|
|
usual convention for your platform, and should link (preferably
|
|
statically) with -lvamp-sdk. Any number of plugins can reside in a
|
|
single dynamic library. See plugins.cpp in the example plugins
|
|
directory for the sort of code that will need to accompany your plugin
|
|
class or classes, to make it possible for a host to look up your
|
|
plugins properly.
|
|
|
|
Please read the relevant README file for your platform found in the
|
|
Vamp SDK build/ directory, for details about how to ensure the
|
|
resulting dynamic library exports the correct linker symbols.
|
|
|
|
The following example plugins are provided. You may legally reuse any
|
|
amount of the code from these examples in any plugins you write,
|
|
whether proprietary or open-source.
|
|
|
|
- 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.
|
|
|
|
Plugin authors should also read the Programmer's Guide at
|
|
http://vamp-plugins.org/guide.pdf .
|
|
|
|
\section hosts For 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.
|
|
|
|
(The following notes in this section are mostly relevant for
|
|
developers that are not using the HostExt classes, or that wish to
|
|
know more about the policy they implement.)
|
|
|
|
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 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
|
|
|
|
\code
|
|
vamp:pluginlibrary:pluginname::General Category > Specific Category
|
|
\endcode
|
|
|
|
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.
|
|
|
|
\section license License
|
|
|
|
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.
|
|
|
|
|
|
*/
|