annotate README @ 214:930b51de9c28

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