libs/vamp-sdk/README

   1
   2 Vamp
   3 ====
   4
   5 An API for audio analysis and feature extraction plugins.
   6
   7    http://www.vamp-plugins.org/
   8
   9 Vamp is an API for C and C++ plugins that process sampled audio data
  10 to produce descriptive output (measurements or semantic observations).
  11
  12 The principal differences between Vamp and a real-time audio
  13 processing plugin system such as VST are:
  14
  15  * Vamp plugins may output complex multidimensional data with labels.
  16    As a consequence, they are likely to work best when the output
  17    data has a much lower sampling rate than the input.  (This also
  18    means it is usually desirable to implement them in C++ using the
  19    high-level base class provided rather than use the raw C API.)
  20
  21  * While Vamp plugins receive data block-by-block, they are not
  22    required to return output immediately on receiving the input.
  23    A Vamp plugin may be non-causal, preferring to store up data
  24    based on its input until the end of a processing run and then
  25    return all results at once.
  26
  27  * Vamp plugins have more control over their inputs than a typical
  28    real-time processing plugin.  For example, they can indicate to
  29    the host their preferred processing block and step sizes, and these
  30    may differ.
  31
  32  * Vamp plugins may ask to receive data in the frequency domain
  33    instead of the time domain.  The host takes the responsibility
  34    for converting the input data using an FFT of windowed frames.
  35    This simplifies plugins that do straightforward frequency-domain
  36    processing and permits the host to cache frequency-domain data
  37    when possible.
  38
  39  * A Vamp plugin is configured once before each processing run, and
  40    receives no further parameter changes during use -- unlike real-
  41    time plugin APIs in which the input parameters may change at any
  42    time.  This also means that fundamental properties such as the
  43    number of values per output or the preferred processing block
  44    size may depend on the input parameters.
  45
  46  * Vamp plugins do not have to be able to run in real time.
  47
  48
  49 About this SDK
  50 ==============
  51
  52 This is version 1.1b of the Vamp plugin Software Development Kit.
  53 Plugins and hosts built with this SDK are binary compatible with those
  54 built using version 1.0 of the SDK.
  55
  56 This SDK contains the following:
  57
  58  * vamp/vamp.h
  59
  60 The formal C language plugin API for Vamp plugins.
  61
  62 A Vamp plugin is a dynamic library (.so, .dll or .dylib depending on
  63 platform) exposing one C-linkage entry point (vampGetPluginDescriptor)
  64 which returns data defined in the rest of this C header.
  65
  66 Although the C API is the official API for Vamp, we don't recommend
  67 that you program directly to it.  The C++ abstraction found in the
  68 vamp-sdk directory (below) is preferable for most purposes and is
  69 more thoroughly documented.
  70
  71  * vamp-sdk
  72
  73 C++ classes for straightforwardly implementing Vamp plugins and hosts.
  74
  75 Plugins should subclass Vamp::Plugin and then use Vamp::PluginAdapter
  76 to expose the correct C API for the plugin.  Plugin authors should
  77 read vamp-sdk/PluginBase.h and Plugin.h for code documentation, and
  78 refer to the example plugin code in the examples directory.  Plugins
  79 should link with -lvampsdk.  [*NOTE: this has changed from vamp-sdk in
  80 previous versions, to avoid conflict with the use of hyphens for
  81 library versioning schemes on some platforms.]
  82
  83 Hosts may use the Vamp::PluginHostAdapter to convert the loaded
  84 plugin's C API back into a Vamp::Plugin object.  Host authors should
  85 refer to the example host code in the host directory.  Hosts should
  86 link with -lvamphostsdk.  [*NOTE: this has changed from vamp-hostsdk
  87 in previous versions, to avoid conflict with the use of hyphens for
  88 library versioning schemes on some platforms.]
  89
  90  * vamp-sdk/hostext
  91
  92 Additional C++ classes to make a host's life easier (introduced in
  93 version 1.1 of the Vamp SDK).
  94
  95 Vamp::HostExt::PluginLoader provides a very easy interface for a host
  96 to discover, load, and find out category information about the
  97 available plugins.  Most "casual" Vamp hosts will probably want to use
  98 this class.
  99
 100 Vamp::HostExt::PluginInputDomainAdapter provides a means for hosts to
 101 handle plugins that expect frequency-domain input, without having to
 102 convert the input themselves.
 103
 104 Vamp::HostExt::PluginChannelAdapter provides a means for hosts to use
 105 plugins that do not necessarily support the same number of audio
 106 channels as they have available, without having to worry about
 107 applying a channel management / mixdown policy themselves.
 108
 109 The PluginLoader class can also use the input domain and channel
 110 adapters automatically to make the entire conversion process
 111 transparent to the host if required.
 112
 113  * examples
 114
 115 Example plugins implemented using the C++ classes.  ZeroCrossing
 116 calculates the positions and density of zero-crossing points in an
 117 audio waveform.  SpectralCentroid calculates the centre of gravity of
 118 the frequency domain representation of each block of audio.
 119 AmplitudeFollower tracks the amplitude of a signal based on a method
 120 from the SuperCollider real-time audio system.
 121 PercussionOnsetDetector estimates the locations of percussive onsets
 122 using a simple method described in "Drum Source Separation using
 123 Percussive Feature Detection and Spectral Modulation" by Dan Barry,
 124 Derry Fitzgerald, Eugene Coyle and Bob Lawlor, ISSC 2005.
 125
 126  * host
 127
 128 A simple command-line Vamp host, capable of loading a plugin and using
 129 it to process a complete audio file, with its default parameters.
 130 Requires libsndfile (http://www.mega-nerd.com/libsndfile/).
 131
 132 If you don't have libsndfile, you may want to edit the Makefile to
 133 change the default build target from "all" to "sdk", so as to compile
 134 only the SDK and not the host.
 135
 136
 137 Plugin Lookup and Categorisation
 138 ================================
 139
 140 The Vamp API does not officially specify how to load plugin libraries
 141 or where to find them.  However, the SDK does include a function
 142 (Vamp::PluginHostAdapter::getPluginPath()) that returns a recommended
 143 directory search path that hosts may use for plugin libraries, and a
 144 class (Vamp::HostExt::PluginLoader) that implements a sensible
 145 cross-platform lookup policy using this path.  We recommend using this
 146 class in your host unless you have a good reason not to want to.  This
 147 implementation also permits the user to set the environment variable
 148 VAMP_PATH to override the default path if desired.
 149
 150 The policy used by Vamp::HostExt::PluginLoader -- and our
 151 recommendation for any host -- is to search each directory in the path
 152 returned by getPluginPath for .DLL (on Windows), .so (on Linux,
 153 Solaris, BSD etc) or .dylib (on OS/X) files, then to load each one and
 154 perform a dynamic name lookup on the vampGetPluginDescriptor function
 155 to enumerate the plugins in the library.  This operation will
 156 necessarily be system-dependent.
 157
 158 Vamp also has an informal convention for sorting plugins into
 159 functional categories.  In addition to the library file itself, a
 160 plugin library may install a category file with the same name as the
 161 library but .cat extension.  The existence and format of this file are
 162 not specified by the Vamp API, but by convention the file may contain
 163 lines of the format
 164
 165 vamp:pluginlibrary:pluginname::General Category > Specific Category
 166
 167 which a host may read and use to assign plugins a location within a
 168 category tree for display to the user.  The expectation is that
 169 advanced users may also choose to set up their own preferred category
 170 trees, which is why this information is not queried as part of the
 171 Vamp plugin's API itself.  The Vamp::HostExt::PluginLoader class also
 172 provides support for plugin category lookup using this scheme.
 173
 174
 175 Building and Installing the SDK and Examples
 176 ============================================
 177
 178 To build the SDK, the simple host, and the example plugins, edit the
 179 Makefile to suit your platform according to the comments in it, then
 180 run "make".
 181
 182 To use an IDE to build a plugin or host using the Vamp SDK, simply add
 183 the .cpp files in the vamp-sdk directory to your project.
 184
 185 Installing the example plugins so that they can be found by other Vamp
 186 hosts depends on your platform:
 187
 188  * Windows: copy the files
 189       examples/vamp-example-plugins.dll
 190       examples/vamp-example-plugins.cat
 191    to
 192       C:\Program Files\Vamp Plugins
 193
 194  * Linux: copy the files
 195       examples/vamp-example-plugins.so
 196       examples/vamp-example-plugins.cat
 197    to
 198       /usr/local/lib/vamp/
 199
 200  * OS/X: copy the files
 201       examples/vamp-example-plugins.dylib
 202       examples/vamp-example-plugins.cat
 203    to
 204       /Library/Audio/Plug-Ins/Vamp
 205
 206
 207 Licensing
 208 =========
 209
 210 This plugin SDK is freely redistributable under a "new-style BSD"
 211 licence.  See the file COPYING for more details.  In short, you may
 212 modify and redistribute the SDK and example plugins within any
 213 commercial or non-commercial, proprietary or open-source plugin or
 214 application under almost any conditions, with no obligation to provide
 215 source code, provided you retain the original copyright note.
 216
 217
 218 See Also
 219 ========
 220
 221 Sonic Visualiser, an interactive open-source graphical audio
 222 inspection, analysis and visualisation tool supporting Vamp plugins.
 223 http://www.sonicvisualiser.org/
 224
 225
 226 Authors
 227 =======
 228
 229 Vamp and the Vamp SDK were designed and made at the Centre for Digital
 230 Music at Queen Mary, University of London.
 231
 232 The SDK was written by Chris Cannam, copyright (c) 2005-2007
 233 Chris Cannam and QMUL.
 234
 235 Mark Sandler and Christian Landone provided ideas and direction, and
 236 Mark Levy, Dan Stowell, Martin Gasser and Craig Sapp provided testing
 237 and other input for the 1.0 API and SDK.  The API also uses some ideas
 238 from prior plugin systems, notably DSSI (http://dssi.sourceforge.net)
 239 and FEAPI (http://feapi.sourceforge.net).
 240