annotate README @ 255:88ef5ffdbe8d

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