annotate README @ 115:1b0bcb8b6f91

...
author cannam
date Tue, 19 Feb 2008 16:34:09 +0000
parents 70bcd0b62cba
children 24859c958732
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@90 52 This is version 1.1b 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@86 79 should link with -lvampsdk. [*NOTE: this has changed from vamp-sdk in
cannam@86 80 previous versions, to avoid conflict with the use of hyphens for
cannam@86 81 library versioning schemes on some platforms.]
cannam@18 82
cannam@14 83 Hosts may use the Vamp::PluginHostAdapter to convert the loaded
cannam@78 84 plugin's C API back into a Vamp::Plugin object. Host authors should
cannam@78 85 refer to the example host code in the host directory. Hosts should
cannam@86 86 link with -lvamphostsdk. [*NOTE: this has changed from vamp-hostsdk
cannam@86 87 in previous versions, to avoid conflict with the use of hyphens for
cannam@86 88 library versioning schemes on some platforms.]
cannam@14 89
cannam@64 90 * vamp-sdk/hostext
cannam@64 91
cannam@75 92 Additional C++ classes to make a host's life easier (introduced in
cannam@75 93 version 1.1 of the Vamp SDK).
cannam@64 94
cannam@78 95 Vamp::HostExt::PluginLoader provides a very easy interface for a host
cannam@78 96 to discover, load, and find out category information about the
cannam@64 97 available plugins. Most "casual" Vamp hosts will probably want to use
cannam@64 98 this class.
cannam@64 99
cannam@78 100 Vamp::HostExt::PluginInputDomainAdapter provides a means for hosts to
cannam@78 101 handle plugins that expect frequency-domain input, without having to
cannam@78 102 convert the input themselves.
cannam@64 103
cannam@78 104 Vamp::HostExt::PluginChannelAdapter provides a means for hosts to use
cannam@78 105 plugins that do not necessarily support the same number of audio
cannam@78 106 channels as they have available, without having to worry about
cannam@78 107 applying a channel management / mixdown policy themselves.
cannam@64 108
cannam@75 109 The PluginLoader class can also use the input domain and channel
cannam@75 110 adapters automatically to make the entire conversion process
cannam@75 111 transparent to the host if required.
cannam@64 112
cannam@14 113 * examples
cannam@14 114
cannam@14 115 Example plugins implemented using the C++ classes. ZeroCrossing
cannam@14 116 calculates the positions and density of zero-crossing points in an
cannam@35 117 audio waveform. SpectralCentroid calculates the centre of gravity of
cannam@14 118 the frequency domain representation of each block of audio.
cannam@78 119 AmplitudeFollower tracks the amplitude of a signal based on a method
cannam@78 120 from the SuperCollider real-time audio system.
cannam@35 121 PercussionOnsetDetector estimates the locations of percussive onsets
cannam@35 122 using a simple method described in "Drum Source Separation using
cannam@35 123 Percussive Feature Detection and Spectral Modulation" by Dan Barry,
cannam@35 124 Derry Fitzgerald, Eugene Coyle and Bob Lawlor, ISSC 2005.
cannam@14 125
cannam@14 126 * host
cannam@14 127
cannam@16 128 A simple command-line Vamp host, capable of loading a plugin and using
cannam@16 129 it to process a complete audio file, with its default parameters.
cannam@64 130 Requires libsndfile (http://www.mega-nerd.com/libsndfile/).
cannam@64 131
cannam@64 132 If you don't have libsndfile, you may want to edit the Makefile to
cannam@75 133 change the default build target from "all" to "sdk", so as to compile
cannam@75 134 only the SDK and not the host.
cannam@14 135
cannam@40 136
cannam@40 137 Plugin Lookup and Categorisation
cannam@40 138 ================================
cannam@40 139
cannam@40 140 The Vamp API does not officially specify how to load plugin libraries
cannam@40 141 or where to find them. However, the SDK does include a function
cannam@40 142 (Vamp::PluginHostAdapter::getPluginPath()) that returns a recommended
cannam@75 143 directory search path that hosts may use for plugin libraries, and a
cannam@75 144 class (Vamp::HostExt::PluginLoader) that implements a sensible
cannam@75 145 cross-platform lookup policy using this path. We recommend using this
cannam@75 146 class in your host unless you have a good reason not to want to. This
cannam@75 147 implementation also permits the user to set the environment variable
cannam@75 148 VAMP_PATH to override the default path if desired.
cannam@40 149
cannam@75 150 The policy used by Vamp::HostExt::PluginLoader -- and our
cannam@75 151 recommendation for any host -- is to search each directory in the path
cannam@75 152 returned by getPluginPath for .DLL (on Windows), .so (on Linux,
cannam@75 153 Solaris, BSD etc) or .dylib (on OS/X) files, then to load each one and
cannam@75 154 perform a dynamic name lookup on the vampGetPluginDescriptor function
cannam@75 155 to enumerate the plugins in the library. This operation will
cannam@75 156 necessarily be system-dependent.
cannam@40 157
cannam@40 158 Vamp also has an informal convention for sorting plugins into
cannam@40 159 functional categories. In addition to the library file itself, a
cannam@40 160 plugin library may install a category file with the same name as the
cannam@40 161 library but .cat extension. The existence and format of this file are
cannam@40 162 not specified by the Vamp API, but by convention the file may contain
cannam@40 163 lines of the format
cannam@40 164
cannam@40 165 vamp:pluginlibrary:pluginname::General Category > Specific Category
cannam@40 166
cannam@40 167 which a host may read and use to assign plugins a location within a
cannam@40 168 category tree for display to the user. The expectation is that
cannam@40 169 advanced users may also choose to set up their own preferred category
cannam@40 170 trees, which is why this information is not queried as part of the
cannam@75 171 Vamp plugin's API itself. The Vamp::HostExt::PluginLoader class also
cannam@75 172 provides support for plugin category lookup using this scheme.
cannam@32 173
cannam@14 174
cannam@42 175 Building and Installing the SDK and Examples
cannam@42 176 ============================================
cannam@14 177
cannam@42 178 To build the SDK, the simple host, and the example plugins, edit the
cannam@42 179 Makefile to suit your platform according to the comments in it, then
cannam@42 180 run "make".
cannam@42 181
cannam@94 182 There is a ready-tweaked Makefile for use on OS/X; to use it, run
cannam@94 183 "make -f Makefile.osx".
cannam@94 184
cannam@85 185 To use an IDE to build a plugin or host using the Vamp SDK, simply add
cannam@85 186 the .cpp files in the vamp-sdk directory to your project.
cannam@85 187
cannam@42 188 Installing the example plugins so that they can be found by other Vamp
cannam@42 189 hosts depends on your platform:
cannam@42 190
cannam@44 191 * Windows: copy the files
cannam@44 192 examples/vamp-example-plugins.dll
cannam@44 193 examples/vamp-example-plugins.cat
cannam@44 194 to
cannam@44 195 C:\Program Files\Vamp Plugins
cannam@42 196
cannam@44 197 * Linux: copy the files
cannam@44 198 examples/vamp-example-plugins.so
cannam@44 199 examples/vamp-example-plugins.cat
cannam@44 200 to
cannam@44 201 /usr/local/lib/vamp/
cannam@42 202
cannam@44 203 * OS/X: copy the files
cannam@44 204 examples/vamp-example-plugins.dylib
cannam@44 205 examples/vamp-example-plugins.cat
cannam@44 206 to
cannam@44 207 /Library/Audio/Plug-Ins/Vamp
cannam@42 208
cannam@14 209
cannam@14 210 Licensing
cannam@14 211 =========
cannam@14 212
cannam@18 213 This plugin SDK is freely redistributable under a "new-style BSD"
cannam@42 214 licence. See the file COPYING for more details. In short, you may
cannam@42 215 modify and redistribute the SDK and example plugins within any
cannam@42 216 commercial or non-commercial, proprietary or open-source plugin or
cannam@42 217 application under almost any conditions, with no obligation to provide
cannam@42 218 source code, provided you retain the original copyright note.
cannam@14 219
cannam@14 220
cannam@14 221 See Also
cannam@14 222 ========
cannam@14 223
cannam@14 224 Sonic Visualiser, an interactive open-source graphical audio
cannam@14 225 inspection, analysis and visualisation tool supporting Vamp plugins.
cannam@35 226 http://www.sonicvisualiser.org/
cannam@14 227
cannam@14 228
cannam@44 229 Authors
cannam@44 230 =======
cannam@44 231
cannam@44 232 Vamp and the Vamp SDK were designed and made at the Centre for Digital
cannam@64 233 Music at Queen Mary, University of London.
cannam@44 234
cannam@64 235 The SDK was written by Chris Cannam, copyright (c) 2005-2007
cannam@64 236 Chris Cannam and QMUL.
cannam@64 237
cannam@64 238 Mark Sandler and Christian Landone provided ideas and direction, and
cannam@64 239 Mark Levy, Dan Stowell, Martin Gasser and Craig Sapp provided testing
cannam@64 240 and other input for the 1.0 API and SDK. The API also uses some ideas
cannam@64 241 from prior plugin systems, notably DSSI (http://dssi.sourceforge.net)
cannam@64 242 and FEAPI (http://feapi.sourceforge.net).
cannam@64 243