annotate README @ 354:e85513153c71

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