cannam@14: cannam@14: Vamp cannam@14: ==== 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@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@14: audio waveform; SpectralCentroid calculates the centre of gravity of cannam@14: the frequency domain representation of each block of audio. 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@32: The Vamp API doesn't officially specify how to load plugin libraries cannam@32: or where to find them. However, good practice for a host is to use cannam@32: the Vamp path returned by Vamp::PluginHostAdapter::getPluginPath() and cannam@32: search each directory in this path for .so, .dll or .dylib files cannam@32: (depending on platform), loading each one and testing for the cannam@32: vampGetPluginDescriptor function to enumerate the plugins in this cannam@32: object. The example host has some code that may help. 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@14: cannam@14: cannam@14: Chris Cannam cannam@14: Centre for Digital Music cannam@14: Queen Mary, University of London