cannam@14: cannam@14: Vamp cannam@14: ==== cannam@35: http://www.sonicvisualiser.org/vamp.html cannam@14: cannam@14: An API for audio analysis and feature extraction plugins. cannam@14: 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@31: Vamp reuses some ideas from several existing systems, notably DSSI cannam@31: (http://dssi.sourceforge.net) and FEAPI (http://feapi.sourceforge.net). cannam@31: 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@18: vamp-sdk/PluginBase.h and Plugin.h for code documentation. cannam@18: cannam@14: Hosts may use the Vamp::PluginHostAdapter to convert the loaded cannam@14: plugin's C API back into a Vamp::Plugin object. cannam@14: 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@16: Requires libsndfile. 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@14: Building the SDK cannam@14: ================ cannam@14: cannam@18: Edit the Makefile to suit your platform according to the comments in cannam@18: it. Type "make". 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@18: licence. See the file COPYING for more details. In short, you are cannam@18: permitted to reuse the SDK and example plugins in any commercial or cannam@18: non-commercial, proprietary or open-source application or plugin under cannam@18: almost any conditions 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@14: Chris Cannam cannam@14: Centre for Digital Music cannam@14: Queen Mary, University of London