1 2Vamp 3==== 4 5An API for audio analysis and feature extraction plugins. 6 7 http://www.vamp-plugins.org/ 8 9Vamp is an API for C and C++ plugins that process sampled audio data 10to produce descriptive output (measurements or semantic observations). 11 12This is version 2.5 of the Vamp plugin Software Development Kit. 13 14Plugins and hosts built with this SDK are binary compatible with those 15built using version 1.0 of the SDK, with certain restrictions. See 16the file README.compat for more details. 17 18See the file CHANGELOG for a list of the changes in this release. 19 20A documentation guide to writing plugins using the Vamp SDK can be 21found at http://www.vamp-plugins.org/guide.pdf . 22 23 24Compiling and Installing the SDK and Examples 25============================================= 26 27This SDK is intended for use on Windows, OS/X, Linux, and other POSIX 28and GNU platforms. 29 30Please see the platform-specific README file (README.msvc, README.osx, 31README.linux) in the build/ directory for details about how to compile 32and install the SDK, how to build plugin libraries using it, and how 33to install the example plugins so you can use them in a host. 34 35 36What's In This SDK 37================== 38 39This SDK contains the following: 40 41 42vamp/vamp.h 43----------- 44 45The formal C language plugin API for Vamp plugins. 46 47A Vamp plugin is a dynamic library (.so, .dll or .dylib depending on 48platform) exposing one C-linkage entry point (vampGetPluginDescriptor) 49which returns data defined in the rest of this C header. 50 51Although the C API is the official API for Vamp, we don't recommend 52that you program directly to it. The C++ abstractions found in the 53vamp-sdk and vamp-hostsdk directories (below) are preferable for most 54purposes and are more thoroughly documented. 55 56 57vamp-sdk 58-------- 59 60C++ classes for implementing Vamp plugins. 61 62Plugins should subclass Vamp::Plugin and then use Vamp::PluginAdapter 63to expose the correct C API for the plugin. Plugin authors should 64read vamp-sdk/PluginBase.h and Plugin.h for code documentation. 65 66See "examples" below for details of the example plugins in the SDK, 67from which you are welcome to take code and inspiration. 68 69Plugins should link with -lvamp-sdk. 70 71 72vamp-hostsdk 73------------ 74 75C++ classes for implementing Vamp hosts. 76 77Hosts will normally use a Vamp::PluginHostAdapter to convert each 78plugin's exposed C API back into a useful Vamp::Plugin C++ object. 79 80The Vamp::HostExt namespace contains several additional C++ classes to 81do this work for them, and make the host's life easier: 82 83 - Vamp::HostExt::PluginLoader provides a very easy interface for a 84 host to discover, load, and find out category information about the 85 available plugins. Most Vamp hosts will probably want to use this 86 class. 87 88 - Vamp::HostExt::PluginInputDomainAdapter provides a simple means for 89 hosts to handle plugins that want frequency-domain input, without 90 having to convert the input themselves. 91 92 - Vamp::HostExt::PluginChannelAdapter provides a simple means for 93 hosts to use plugins that do not necessarily support the same number 94 of audio channels as they have available, without having to apply a 95 channel management / mixdown policy themselves. 96 97 - Vamp::HostExt::PluginBufferingAdapter provides a means for hosts to 98 avoid having to negotiate the input step and block size, instead 99 permitting the host to use any block size they desire (and a step 100 size equal to it). This is particularly useful for "streaming" hosts 101 that cannot seek backwards in the input audio stream and so would 102 otherwise need to implement an additional buffer to support step 103 sizes smaller than the block size. 104 105 - Vamp::HostExt::PluginSummarisingAdapter provides summarisation 106 methods such as mean and median averages of output features, for use 107 in any context where an available plugin produces individual values 108 but the result that is actually needed is some sort of aggregate. 109 110The PluginLoader class can also use the input domain, channel, and 111buffering adapters automatically to make these conversions transparent 112to the host if required. 113 114Host authors should also refer to the example host code in the host 115directory of the SDK. 116 117Hosts should link with -lvamp-hostsdk. 118 119 120examples 121-------- 122 123Example plugins implemented using the C++ classes. 124 125These plugins are intended to be useful examples you can draw code 126from in order to provide the basic shape and structure of a Vamp 127plugin. They are also intended to be correct and useful, if simple. 128 129 - ZeroCrossing calculates the positions and density of zero-crossing 130 points in an audio waveform. 131 132 - SpectralCentroid calculates the centre of gravity of the frequency 133 domain representation of each block of audio. 134 135 - PowerSpectrum calculates a power spectrum from the input audio. 136 Actually, it doesn't do any work except calculating power from a 137 cartesian complex FFT output. The work of calculating this frequency 138 domain output is done for it by the host or host SDK; the plugin just 139 needs to declare that it wants frequency domain input. This is the 140 simplest of the example plugins. 141 142 - AmplitudeFollower is a simple implementation of SuperCollider's 143 amplitude-follower algorithm. 144 145 - PercussionOnsetDetector estimates the locations of percussive 146 onsets using a simple method described in "Drum Source Separation 147 using Percussive Feature Detection and Spectral Modulation" by Dan 148 Barry, Derry Fitzgerald, Eugene Coyle and Bob Lawlor, ISSC 2005. 149 150 - FixedTempoEstimator calculates a single beats-per-minute value 151 which is an estimate of the tempo of a piece of music that is assumed 152 to be of fixed tempo, using autocorrelation of a frequency domain 153 energy rise metric. It has several outputs that return intermediate 154 results used in the calculation, and may be a useful example of a 155 plugin having several outputs with varying feature structures. 156 157 158skeleton 159-------- 160 161Skeleton code that could be used as a template for your new plugin 162implementation. 163 164 165host 166---- 167 168A simple command-line Vamp host, capable of loading a plugin and using 169it to process a complete audio file, with its default parameters. 170 171This host also contains a number of options for listing the installed 172plugins and their properties in various formats. For that reason, it 173isn't really as simple as one might hope. The core of the code is 174still reasonably straightforward, however. 175 176 177Plugin Lookup and Categorisation 178================================ 179 180The Vamp API does not officially specify how to load plugin libraries 181or where to find them. However, the SDK does include a function 182(Vamp::PluginHostAdapter::getPluginPath()) that returns a recommended 183directory search path that hosts may use for plugin libraries, and a 184class (Vamp::HostExt::PluginLoader) that implements a sensible 185cross-platform lookup policy using this path. We recommend using this 186class in your host unless you have a good reason not to want to. This 187implementation also permits the user to set the environment variable 188VAMP_PATH to override the default path if desired. 189 190The policy used by Vamp::HostExt::PluginLoader -- and our 191recommendation for any host -- is to search each directory in the path 192returned by getPluginPath for .DLL (on Windows), .so (on Linux, 193Solaris, BSD etc) or .dylib (on OS/X) files, then to load each one and 194perform a dynamic name lookup on the vampGetPluginDescriptor function 195to enumerate the plugins in the library. This operation will 196necessarily be system-dependent. 197 198Vamp also has an informal convention for sorting plugins into 199functional categories. In addition to the library file itself, a 200plugin library may install a category file with the same name as the 201library but .cat extension. The existence and format of this file are 202not specified by the Vamp API, but by convention the file may contain 203lines of the format 204 205vamp:pluginlibrary:pluginname::General Category > Specific Category 206 207which a host may read and use to assign plugins a location within a 208category tree for display to the user. The expectation is that 209advanced users may also choose to set up their own preferred category 210trees, which is why this information is not queried as part of the 211Vamp plugin's API itself. The Vamp::HostExt::PluginLoader class also 212provides support for plugin category lookup using this scheme. 213 214 215Licensing 216========= 217 218This plugin SDK is freely redistributable under a "new-style BSD" 219licence. See the file COPYING for more details. In short, you may 220modify and redistribute the SDK and example plugins within any 221commercial or non-commercial, proprietary or open-source plugin or 222application under almost any conditions, with no obligation to provide 223source code, provided you retain the original copyright note. 224 225 226See Also 227======== 228 229Sonic Visualiser, an interactive open-source graphical audio 230inspection, analysis and visualisation tool supporting Vamp plugins. 231http://www.sonicvisualiser.org/ 232 233 234Authors 235======= 236 237Vamp and the Vamp SDK were designed and made at the Centre for Digital 238Music at Queen Mary, University of London. 239 240The SDK was written by Chris Cannam, copyright (c) 2005-2009 241Chris Cannam and QMUL. 242 243Mark Sandler and Christian Landone provided ideas and direction, and 244Mark Levy, Dan Stowell, Martin Gasser and Craig Sapp provided testing 245and other input for the 1.0 API and SDK. The API also uses some ideas 246from prior plugin systems, notably DSSI (http://dssi.sourceforge.net) 247and FEAPI (http://feapi.sourceforge.net). 248 249