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