annotate README @ 462:6ac615fd02a3

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