annotate README @ 228:e58242c9ff85 distinct-libraries

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