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