cannam@14: cannam@14: Vamp cannam@14: ==== cannam@14: cannam@14: An API for audio analysis and feature extraction plugins. cannam@14: cannam@44: http://www.vamp-plugins.org/ cannam@44: cannam@14: Vamp is an API for C and C++ plugins that process sampled audio data cannam@18: to produce descriptive output (measurements or semantic observations). cannam@14: cannam@14: The principal differences between Vamp and a real-time audio cannam@14: processing plugin system such as VST are: cannam@14: cannam@14: * Vamp plugins may output complex multidimensional data with labels. cannam@14: As a consequence, they are likely to work best when the output cannam@14: data has a much lower sampling rate than the input. (This also cannam@14: means it is usually desirable to implement them in C++ using the cannam@14: high-level base class provided rather than use the raw C API.) cannam@14: cannam@14: * While Vamp plugins receive data block-by-block, they are not cannam@14: required to return output immediately on receiving the input. cannam@14: A Vamp plugin may be non-causal, preferring to store up data cannam@14: based on its input until the end of a processing run and then cannam@14: return all results at once. cannam@14: cannam@14: * Vamp plugins have more control over their inputs than a typical cannam@14: real-time processing plugin. For example, they can indicate to cannam@18: the host their preferred processing block and step sizes, and these cannam@18: may differ. cannam@18: cannam@18: * Vamp plugins may ask to receive data in the frequency domain cannam@18: instead of the time domain. The host takes the responsibility cannam@18: for converting the input data using an FFT of windowed frames. cannam@18: This simplifies plugins that do straightforward frequency-domain cannam@18: processing and permits the host to cache frequency-domain data cannam@18: when possible. cannam@14: cannam@14: * A Vamp plugin is configured once before each processing run, and cannam@78: receives no further parameter changes during use -- unlike real- cannam@14: time plugin APIs in which the input parameters may change at any cannam@14: time. This also means that fundamental properties such as the cannam@14: number of values per output or the preferred processing block cannam@18: size may depend on the input parameters. cannam@14: cannam@38: * Vamp plugins do not have to be able to run in real time. cannam@38: cannam@14: cannam@14: About this SDK cannam@14: ============== cannam@14: cannam@162: This is version 1.3 of the Vamp plugin Software Development Kit. cannam@78: Plugins and hosts built with this SDK are binary compatible with those cannam@78: built using version 1.0 of the SDK. cannam@78: cannam@78: This SDK contains the following: cannam@14: cannam@14: * vamp/vamp.h cannam@14: cannam@14: The formal C language plugin API for Vamp plugins. cannam@14: cannam@14: A Vamp plugin is a dynamic library (.so, .dll or .dylib depending on cannam@14: platform) exposing one C-linkage entry point (vampGetPluginDescriptor) cannam@14: which returns data defined in the rest of this C header. cannam@14: cannam@78: Although the C API is the official API for Vamp, we don't recommend cannam@78: that you program directly to it. The C++ abstraction found in the cannam@78: vamp-sdk directory (below) is preferable for most purposes and is cannam@78: more thoroughly documented. cannam@14: cannam@14: * vamp-sdk cannam@14: cannam@14: C++ classes for straightforwardly implementing Vamp plugins and hosts. cannam@18: cannam@78: Plugins should subclass Vamp::Plugin and then use Vamp::PluginAdapter cannam@78: to expose the correct C API for the plugin. Plugin authors should cannam@78: read vamp-sdk/PluginBase.h and Plugin.h for code documentation, and cannam@78: refer to the example plugin code in the examples directory. Plugins cannam@162: should link with -lvamp-sdk. cannam@18: cannam@14: Hosts may use the Vamp::PluginHostAdapter to convert the loaded cannam@78: plugin's C API back into a Vamp::Plugin object. Host authors should cannam@78: refer to the example host code in the host directory. Hosts should cannam@162: link with -lvamp-hostsdk. cannam@14: cannam@64: * vamp-sdk/hostext cannam@64: cannam@75: Additional C++ classes to make a host's life easier (introduced in cannam@125: versions 1.1 and 1.2 of the Vamp SDK). cannam@64: cannam@78: Vamp::HostExt::PluginLoader provides a very easy interface for a host cannam@78: to discover, load, and find out category information about the cannam@64: available plugins. Most "casual" Vamp hosts will probably want to use cannam@64: this class. cannam@64: cannam@78: Vamp::HostExt::PluginInputDomainAdapter provides a means for hosts to cannam@78: handle plugins that expect frequency-domain input, without having to cannam@78: convert the input themselves. cannam@64: cannam@78: Vamp::HostExt::PluginChannelAdapter provides a means for hosts to use cannam@78: plugins that do not necessarily support the same number of audio cannam@78: channels as they have available, without having to worry about cannam@78: applying a channel management / mixdown policy themselves. cannam@64: cannam@125: Vamp::HostExt::PluginBufferingAdapter provides a means for hosts to cannam@125: avoid having to negotiate the input step and block size, instead cannam@125: permitting the host to use any block size they desire (and a step size cannam@125: equal to it). This is particularly useful for "streaming" hosts that cannam@125: cannot seek backwards in the input audio stream and so would otherwise cannam@125: need to implement an additional buffer to support step sizes smaller cannam@125: than the block size. cannam@125: cannam@75: The PluginLoader class can also use the input domain and channel cannam@75: adapters automatically to make the entire conversion process cannam@75: transparent to the host if required. cannam@64: cannam@14: * examples cannam@14: cannam@14: Example plugins implemented using the C++ classes. ZeroCrossing cannam@14: calculates the positions and density of zero-crossing points in an cannam@35: audio waveform. SpectralCentroid calculates the centre of gravity of cannam@14: the frequency domain representation of each block of audio. cannam@78: AmplitudeFollower tracks the amplitude of a signal based on a method cannam@78: from the SuperCollider real-time audio system. cannam@35: PercussionOnsetDetector estimates the locations of percussive onsets cannam@35: using a simple method described in "Drum Source Separation using cannam@35: Percussive Feature Detection and Spectral Modulation" by Dan Barry, cannam@35: Derry Fitzgerald, Eugene Coyle and Bob Lawlor, ISSC 2005. cannam@14: cannam@14: * host cannam@14: cannam@16: A simple command-line Vamp host, capable of loading a plugin and using cannam@16: it to process a complete audio file, with its default parameters. cannam@64: Requires libsndfile (http://www.mega-nerd.com/libsndfile/). cannam@64: cannam@64: If you don't have libsndfile, you may want to edit the Makefile to cannam@75: change the default build target from "all" to "sdk", so as to compile cannam@75: only the SDK and not the host. cannam@14: cannam@40: cannam@40: Plugin Lookup and Categorisation cannam@40: ================================ cannam@40: cannam@40: The Vamp API does not officially specify how to load plugin libraries cannam@40: or where to find them. However, the SDK does include a function cannam@40: (Vamp::PluginHostAdapter::getPluginPath()) that returns a recommended cannam@75: directory search path that hosts may use for plugin libraries, and a cannam@75: class (Vamp::HostExt::PluginLoader) that implements a sensible cannam@75: cross-platform lookup policy using this path. We recommend using this cannam@75: class in your host unless you have a good reason not to want to. This cannam@75: implementation also permits the user to set the environment variable cannam@75: VAMP_PATH to override the default path if desired. cannam@40: cannam@75: The policy used by Vamp::HostExt::PluginLoader -- and our cannam@75: recommendation for any host -- is to search each directory in the path cannam@75: returned by getPluginPath for .DLL (on Windows), .so (on Linux, cannam@75: Solaris, BSD etc) or .dylib (on OS/X) files, then to load each one and cannam@75: perform a dynamic name lookup on the vampGetPluginDescriptor function cannam@75: to enumerate the plugins in the library. This operation will cannam@75: necessarily be system-dependent. cannam@40: cannam@40: Vamp also has an informal convention for sorting plugins into cannam@40: functional categories. In addition to the library file itself, a cannam@40: plugin library may install a category file with the same name as the cannam@40: library but .cat extension. The existence and format of this file are cannam@40: not specified by the Vamp API, but by convention the file may contain cannam@40: lines of the format cannam@40: cannam@40: vamp:pluginlibrary:pluginname::General Category > Specific Category cannam@40: cannam@40: which a host may read and use to assign plugins a location within a cannam@40: category tree for display to the user. The expectation is that cannam@40: advanced users may also choose to set up their own preferred category cannam@40: trees, which is why this information is not queried as part of the cannam@75: Vamp plugin's API itself. The Vamp::HostExt::PluginLoader class also cannam@75: provides support for plugin category lookup using this scheme. cannam@32: cannam@14: cannam@162: Compiling the SDK and Examples cannam@162: ============================== cannam@14: cannam@162: This SDK is intended for use on Windows, OS/X, Linux, and other POSIX cannam@162: platforms. cannam@162: cannam@162: * Windows cannam@162: cannam@162: A project file for Visual Studio is included (VampPluginSDK.vcproj). cannam@162: This builds the SDK library, but does not build the example plugins or cannam@162: command-line host. cannam@162: cannam@162: Alternatively, when using Visual Studio or another IDE to build a cannam@162: plugin or host using the SDK, you can simply add the .cpp files in the cannam@162: vamp-sdk and vamp-sdk/hostext directories to your existing project. cannam@162: cannam@162: If you are using a Cygwin or MinGW GNU toolchain, use the included cannam@162: Makefile (see Linux and other POSIX platforms below). cannam@162: cannam@162: * OS/X cannam@162: cannam@162: Run "make -f Makefile.osx" to build the SDK, example plugins, and cannam@162: command-line host. cannam@162: cannam@162: Note that the host requires that you have libsndfile cannam@162: (http://www.mega-nerd.com/libsndfile/) installed. To build only the cannam@162: SDK and examples, "make -f Makefile.osx sdk examples". cannam@162: cannam@162: If you are using an IDE, you may prefer to simply add the .cpp files cannam@162: in the vamp-sdk and vamp-sdk/hostext directories to your existing cannam@162: project. cannam@162: cannam@162: * Linux and other POSIX platforms cannam@162: cannam@162: To build the SDK, example plugins, and command-line host, edit the cannam@42: Makefile to suit your platform according to the comments in it, then cannam@42: run "make". cannam@42: cannam@162: Note that the host requires that you have libsndfile cannam@162: (http://www.mega-nerd.com/libsndfile/) installed. To build only the cannam@162: SDK and examples, edit the Makefile then run "make sdk examples". cannam@94: cannam@162: cannam@162: Installing the Example Plugins cannam@162: ============================== cannam@85: cannam@42: Installing the example plugins so that they can be found by other Vamp cannam@42: hosts depends on your platform: cannam@42: cannam@44: * Windows: copy the files cannam@44: examples/vamp-example-plugins.dll cannam@44: examples/vamp-example-plugins.cat cannam@44: to cannam@44: C:\Program Files\Vamp Plugins cannam@42: cannam@44: * Linux: copy the files cannam@44: examples/vamp-example-plugins.so cannam@44: examples/vamp-example-plugins.cat cannam@44: to cannam@44: /usr/local/lib/vamp/ cannam@42: cannam@44: * OS/X: copy the files cannam@44: examples/vamp-example-plugins.dylib cannam@44: examples/vamp-example-plugins.cat cannam@44: to cannam@44: /Library/Audio/Plug-Ins/Vamp cannam@42: cannam@14: cannam@14: Licensing cannam@14: ========= cannam@14: cannam@18: This plugin SDK is freely redistributable under a "new-style BSD" cannam@42: licence. See the file COPYING for more details. In short, you may cannam@42: modify and redistribute the SDK and example plugins within any cannam@42: commercial or non-commercial, proprietary or open-source plugin or cannam@42: application under almost any conditions, with no obligation to provide cannam@42: source code, provided you retain the original copyright note. cannam@14: cannam@14: cannam@14: See Also cannam@14: ======== cannam@14: cannam@14: Sonic Visualiser, an interactive open-source graphical audio cannam@14: inspection, analysis and visualisation tool supporting Vamp plugins. cannam@35: http://www.sonicvisualiser.org/ cannam@14: cannam@14: cannam@44: Authors cannam@44: ======= cannam@44: cannam@44: Vamp and the Vamp SDK were designed and made at the Centre for Digital cannam@64: Music at Queen Mary, University of London. cannam@44: cannam@127: The SDK was written by Chris Cannam, copyright (c) 2005-2008 cannam@64: Chris Cannam and QMUL. cannam@64: cannam@64: Mark Sandler and Christian Landone provided ideas and direction, and cannam@64: Mark Levy, Dan Stowell, Martin Gasser and Craig Sapp provided testing cannam@64: and other input for the 1.0 API and SDK. The API also uses some ideas cannam@64: from prior plugin systems, notably DSSI (http://dssi.sourceforge.net) cannam@64: and FEAPI (http://feapi.sourceforge.net). cannam@64: