Chris@23: Chris@23: Vamp Chris@23: ==== Chris@23: Chris@23: An API for audio analysis and feature extraction plugins. Chris@23: Chris@23: http://www.vamp-plugins.org/ Chris@23: Chris@23: Vamp is an API for C and C++ plugins that process sampled audio data Chris@23: to produce descriptive output (measurements or semantic observations). Chris@23: Chris@23: This is version 2.5 of the Vamp plugin Software Development Kit. Chris@23: Chris@23: Plugins and hosts built with this SDK are binary compatible with those Chris@23: built using version 1.0 of the SDK, with certain restrictions. See Chris@23: the file README.compat for more details. Chris@23: Chris@23: See the file CHANGELOG for a list of the changes in this release. Chris@23: Chris@23: A documentation guide to writing plugins using the Vamp SDK can be Chris@23: found at http://www.vamp-plugins.org/guide.pdf . Chris@23: Chris@23: Chris@23: Compiling and Installing the SDK and Examples Chris@23: ============================================= Chris@23: Chris@23: This SDK is intended for use on Windows, OS/X, Linux, and other POSIX Chris@23: and GNU platforms. Chris@23: Chris@23: Please see the platform-specific README file (README.msvc, README.osx, Chris@23: README.linux) in the build/ directory for details about how to compile Chris@23: and install the SDK, how to build plugin libraries using it, and how Chris@23: to install the example plugins so you can use them in a host. Chris@23: Chris@23: Chris@23: What's In This SDK Chris@23: ================== Chris@23: Chris@23: This SDK contains the following: Chris@23: Chris@23: Chris@23: vamp/vamp.h Chris@23: ----------- Chris@23: Chris@23: The formal C language plugin API for Vamp plugins. Chris@23: Chris@23: A Vamp plugin is a dynamic library (.so, .dll or .dylib depending on Chris@23: platform) exposing one C-linkage entry point (vampGetPluginDescriptor) Chris@23: which returns data defined in the rest of this C header. Chris@23: Chris@23: Although the C API is the official API for Vamp, we don't recommend Chris@23: that you program directly to it. The C++ abstractions found in the Chris@23: vamp-sdk and vamp-hostsdk directories (below) are preferable for most Chris@23: purposes and are more thoroughly documented. Chris@23: Chris@23: Chris@23: vamp-sdk Chris@23: -------- Chris@23: Chris@23: C++ classes for implementing Vamp plugins. Chris@23: Chris@23: Plugins should subclass Vamp::Plugin and then use Vamp::PluginAdapter Chris@23: to expose the correct C API for the plugin. Plugin authors should Chris@23: read vamp-sdk/PluginBase.h and Plugin.h for code documentation. Chris@23: Chris@23: See "examples" below for details of the example plugins in the SDK, Chris@23: from which you are welcome to take code and inspiration. Chris@23: Chris@23: Plugins should link with -lvamp-sdk. Chris@23: Chris@23: Chris@23: vamp-hostsdk Chris@23: ------------ Chris@23: Chris@23: C++ classes for implementing Vamp hosts. Chris@23: Chris@23: Hosts will normally use a Vamp::PluginHostAdapter to convert each Chris@23: plugin's exposed C API back into a useful Vamp::Plugin C++ object. Chris@23: Chris@23: The Vamp::HostExt namespace contains several additional C++ classes to Chris@23: do this work for them, and make the host's life easier: Chris@23: Chris@23: - Vamp::HostExt::PluginLoader provides a very easy interface for a Chris@23: host to discover, load, and find out category information about the Chris@23: available plugins. Most Vamp hosts will probably want to use this Chris@23: class. Chris@23: Chris@23: - Vamp::HostExt::PluginInputDomainAdapter provides a simple means for Chris@23: hosts to handle plugins that want frequency-domain input, without Chris@23: having to convert the input themselves. Chris@23: Chris@23: - Vamp::HostExt::PluginChannelAdapter provides a simple means for Chris@23: hosts to use plugins that do not necessarily support the same number Chris@23: of audio channels as they have available, without having to apply a Chris@23: channel management / mixdown policy themselves. Chris@23: Chris@23: - Vamp::HostExt::PluginBufferingAdapter provides a means for hosts to Chris@23: avoid having to negotiate the input step and block size, instead Chris@23: permitting the host to use any block size they desire (and a step Chris@23: size equal to it). This is particularly useful for "streaming" hosts Chris@23: that cannot seek backwards in the input audio stream and so would Chris@23: otherwise need to implement an additional buffer to support step Chris@23: sizes smaller than the block size. Chris@23: Chris@23: - Vamp::HostExt::PluginSummarisingAdapter provides summarisation Chris@23: methods such as mean and median averages of output features, for use Chris@23: in any context where an available plugin produces individual values Chris@23: but the result that is actually needed is some sort of aggregate. Chris@23: Chris@23: The PluginLoader class can also use the input domain, channel, and Chris@23: buffering adapters automatically to make these conversions transparent Chris@23: to the host if required. Chris@23: Chris@23: Host authors should also refer to the example host code in the host Chris@23: directory of the SDK. Chris@23: Chris@23: Hosts should link with -lvamp-hostsdk. Chris@23: Chris@23: Chris@23: examples Chris@23: -------- Chris@23: Chris@23: Example plugins implemented using the C++ classes. Chris@23: Chris@23: These plugins are intended to be useful examples you can draw code Chris@23: from in order to provide the basic shape and structure of a Vamp Chris@23: plugin. They are also intended to be correct and useful, if simple. Chris@23: Chris@23: - ZeroCrossing calculates the positions and density of zero-crossing Chris@23: points in an audio waveform. Chris@23: Chris@23: - SpectralCentroid calculates the centre of gravity of the frequency Chris@23: domain representation of each block of audio. Chris@23: Chris@23: - PowerSpectrum calculates a power spectrum from the input audio. Chris@23: Actually, it doesn't do any work except calculating power from a Chris@23: cartesian complex FFT output. The work of calculating this frequency Chris@23: domain output is done for it by the host or host SDK; the plugin just Chris@23: needs to declare that it wants frequency domain input. This is the Chris@23: simplest of the example plugins. Chris@23: Chris@23: - AmplitudeFollower is a simple implementation of SuperCollider's Chris@23: amplitude-follower algorithm. Chris@23: Chris@23: - PercussionOnsetDetector estimates the locations of percussive Chris@23: onsets using a simple method described in "Drum Source Separation Chris@23: using Percussive Feature Detection and Spectral Modulation" by Dan Chris@23: Barry, Derry Fitzgerald, Eugene Coyle and Bob Lawlor, ISSC 2005. Chris@23: Chris@23: - FixedTempoEstimator calculates a single beats-per-minute value Chris@23: which is an estimate of the tempo of a piece of music that is assumed Chris@23: to be of fixed tempo, using autocorrelation of a frequency domain Chris@23: energy rise metric. It has several outputs that return intermediate Chris@23: results used in the calculation, and may be a useful example of a Chris@23: plugin having several outputs with varying feature structures. Chris@23: Chris@23: Chris@23: skeleton Chris@23: -------- Chris@23: Chris@23: Skeleton code that could be used as a template for your new plugin Chris@23: implementation. Chris@23: Chris@23: Chris@23: host Chris@23: ---- Chris@23: Chris@23: A simple command-line Vamp host, capable of loading a plugin and using Chris@23: it to process a complete audio file, with its default parameters. Chris@23: Chris@23: This host also contains a number of options for listing the installed Chris@23: plugins and their properties in various formats. For that reason, it Chris@23: isn't really as simple as one might hope. The core of the code is Chris@23: still reasonably straightforward, however. Chris@23: Chris@23: Chris@23: Plugin Lookup and Categorisation Chris@23: ================================ Chris@23: Chris@23: The Vamp API does not officially specify how to load plugin libraries Chris@23: or where to find them. However, the SDK does include a function Chris@23: (Vamp::PluginHostAdapter::getPluginPath()) that returns a recommended Chris@23: directory search path that hosts may use for plugin libraries, and a Chris@23: class (Vamp::HostExt::PluginLoader) that implements a sensible Chris@23: cross-platform lookup policy using this path. We recommend using this Chris@23: class in your host unless you have a good reason not to want to. This Chris@23: implementation also permits the user to set the environment variable Chris@23: VAMP_PATH to override the default path if desired. Chris@23: Chris@23: The policy used by Vamp::HostExt::PluginLoader -- and our Chris@23: recommendation for any host -- is to search each directory in the path Chris@23: returned by getPluginPath for .DLL (on Windows), .so (on Linux, Chris@23: Solaris, BSD etc) or .dylib (on OS/X) files, then to load each one and Chris@23: perform a dynamic name lookup on the vampGetPluginDescriptor function Chris@23: to enumerate the plugins in the library. This operation will Chris@23: necessarily be system-dependent. Chris@23: Chris@23: Vamp also has an informal convention for sorting plugins into Chris@23: functional categories. In addition to the library file itself, a Chris@23: plugin library may install a category file with the same name as the Chris@23: library but .cat extension. The existence and format of this file are Chris@23: not specified by the Vamp API, but by convention the file may contain Chris@23: lines of the format Chris@23: Chris@23: vamp:pluginlibrary:pluginname::General Category > Specific Category Chris@23: Chris@23: which a host may read and use to assign plugins a location within a Chris@23: category tree for display to the user. The expectation is that Chris@23: advanced users may also choose to set up their own preferred category Chris@23: trees, which is why this information is not queried as part of the Chris@23: Vamp plugin's API itself. The Vamp::HostExt::PluginLoader class also Chris@23: provides support for plugin category lookup using this scheme. Chris@23: Chris@23: Chris@23: Licensing Chris@23: ========= Chris@23: Chris@23: This plugin SDK is freely redistributable under a "new-style BSD" Chris@23: licence. See the file COPYING for more details. In short, you may Chris@23: modify and redistribute the SDK and example plugins within any Chris@23: commercial or non-commercial, proprietary or open-source plugin or Chris@23: application under almost any conditions, with no obligation to provide Chris@23: source code, provided you retain the original copyright note. Chris@23: Chris@23: Chris@23: See Also Chris@23: ======== Chris@23: Chris@23: Sonic Visualiser, an interactive open-source graphical audio Chris@23: inspection, analysis and visualisation tool supporting Vamp plugins. Chris@23: http://www.sonicvisualiser.org/ Chris@23: Chris@23: Chris@23: Authors Chris@23: ======= Chris@23: Chris@23: Vamp and the Vamp SDK were designed and made at the Centre for Digital Chris@23: Music at Queen Mary, University of London. Chris@23: Chris@23: The SDK was written by Chris Cannam, copyright (c) 2005-2009 Chris@23: Chris Cannam and QMUL. Chris@23: Chris@23: Mark Sandler and Christian Landone provided ideas and direction, and Chris@23: Mark Levy, Dan Stowell, Martin Gasser and Craig Sapp provided testing Chris@23: and other input for the 1.0 API and SDK. The API also uses some ideas Chris@23: from prior plugin systems, notably DSSI (http://dssi.sourceforge.net) Chris@23: and FEAPI (http://feapi.sourceforge.net). Chris@23: