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@14: 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@14: This Software Development Kit 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@14: Although this is the official API for Vamp, we don't recommend that cannam@14: you program directly to it. The C++ abstraction in the SDK directory cannam@18: (below) is likely to be preferable for most purposes, and is better cannam@14: documented. cannam@14: cannam@14: * vamp-sdk cannam@14: cannam@14: C++ classes for straightforwardly implementing Vamp plugins and hosts. cannam@18: cannam@18: Plugins should subclass Vamp::Plugin and then use a cannam@18: Vamp::PluginAdapter to expose the correct C API for the plugin. Read cannam@51: vamp-sdk/PluginBase.h and Plugin.h for code documentation. Plugins cannam@51: should link with -lvamp-sdk. cannam@18: cannam@14: Hosts may use the Vamp::PluginHostAdapter to convert the loaded cannam@51: plugin's C API back into a Vamp::Plugin object. Hosts should link cannam@51: with -lvamp-hostsdk. cannam@14: cannam@64: * vamp-sdk/hostext cannam@64: cannam@64: Additional C++ classes to make a host's life easier. cannam@64: cannam@64: Vamp::HostExt::PluginLoader provides a very simple interface for a cannam@64: host 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@64: Vamp::HostExt::PluginInputDomainAdapter provides a simple means for cannam@64: hosts to handle plugins that expect frequency-domain input, without cannam@64: having to convert the input themselves. cannam@64: cannam@64: Vamp::HostExt::PluginChannelAdapter provides a simple means for hosts cannam@64: to use plugins that do not necessarily support the same number of cannam@64: audio channels as they have available, without having to apply a cannam@64: channel management / mixdown policy themselves. cannam@64: cannam@64: The PluginLoader can use the input domain and channel adapters cannam@64: automatically to make the entire conversion process transparent to the cannam@64: 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@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@64: change the default build target from "all" to "sdk" so as to compile cannam@64: only the SDK. 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@40: directory search path that hosts may use for plugin libraries. cannam@40: cannam@40: Our suggestion for a host is to search each directory in this path for cannam@40: .DLL (on Windows), .so (on Linux, Solaris, BSD etc) or .dylib (on cannam@40: OS/X) files, then to load each one and perform a dynamic name lookup cannam@40: on the vampGetPluginDescriptor function to enumerate the plugins in cannam@40: the library. The example host has some code that may help, but this cannam@40: operation will 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@40: Vamp API itself. cannam@32: cannam@14: cannam@42: Building and Installing the SDK and Examples cannam@42: ============================================ cannam@14: cannam@42: To build the SDK, the simple host, and the example plugins, edit the cannam@42: Makefile to suit your platform according to the comments in it, then cannam@42: run "make". cannam@42: 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@42: When building a plugin or host of your own using the SDK, you will cannam@44: need to include the headers from the vamp-sdk directory; then when cannam@44: linking your plugin or host, we suggest statically linking the SDK cannam@44: code (in preference to distributing it alongside your program in DLL cannam@44: form). An easy way to do this, if using a project-based build tool cannam@42: such as Visual Studio or XCode, is simply to add the .cpp files in the cannam@42: vamp-sdk directory to your project. cannam@14: 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@64: The SDK was written by Chris Cannam, copyright (c) 2005-2007 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: