annotate README @ 412:6c38ae0a25e5

Minor tweak to guard
author Chris Cannam
date Fri, 04 Sep 2015 12:37:47 +0100
parents 14b34e85523b
children 8c45dee08a95
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@397 12 This is version 2.6 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
Chris@397 120 vamp-hostsdk/host-c.h
Chris@397 121 ---------------------
Chris@397 122
Chris@397 123 A C-linkage header wrapping the part of the C++ SDK code that handles
Chris@397 124 plugin discovery and library loading. Host programs written in C or in
Chris@397 125 a language with a C-linkage foreign function interface may choose to
Chris@397 126 use this header to discover and load plugin libraries, together with
Chris@397 127 the vamp/vamp.h formal API to interact with plugins themselves. See
Chris@397 128 the header for more documentation.
Chris@397 129
Chris@397 130
cannam@239 131 examples
cannam@239 132 --------
cannam@239 133
cannam@239 134 Example plugins implemented using the C++ classes.
cannam@239 135
cannam@239 136 These plugins are intended to be useful examples you can draw code
cannam@239 137 from in order to provide the basic shape and structure of a Vamp
cannam@239 138 plugin. They are also intended to be correct and useful, if simple.
cannam@239 139
cannam@239 140 - ZeroCrossing calculates the positions and density of zero-crossing
cannam@239 141 points in an audio waveform.
cannam@239 142
cannam@239 143 - SpectralCentroid calculates the centre of gravity of the frequency
cannam@239 144 domain representation of each block of audio.
cannam@239 145
cannam@242 146 - PowerSpectrum calculates a power spectrum from the input audio.
cannam@244 147 Actually, it doesn't do any work except calculating power from a
cannam@244 148 cartesian complex FFT output. The work of calculating this frequency
cannam@244 149 domain output is done for it by the host or host SDK; the plugin just
cannam@244 150 needs to declare that it wants frequency domain input. This is the
cannam@244 151 simplest of the example plugins.
cannam@242 152
cannam@239 153 - AmplitudeFollower is a simple implementation of SuperCollider's
cannam@239 154 amplitude-follower algorithm.
cannam@239 155
cannam@239 156 - PercussionOnsetDetector estimates the locations of percussive
cannam@239 157 onsets using a simple method described in "Drum Source Separation
cannam@239 158 using Percussive Feature Detection and Spectral Modulation" by Dan
cannam@239 159 Barry, Derry Fitzgerald, Eugene Coyle and Bob Lawlor, ISSC 2005.
cannam@239 160
cannam@239 161 - FixedTempoEstimator calculates a single beats-per-minute value
cannam@239 162 which is an estimate of the tempo of a piece of music that is assumed
cannam@239 163 to be of fixed tempo, using autocorrelation of a frequency domain
cannam@239 164 energy rise metric. It has several outputs that return intermediate
cannam@239 165 results used in the calculation, and may be a useful example of a
cannam@239 166 plugin having several outputs with varying feature structures.
cannam@239 167
cannam@239 168
cannam@290 169 skeleton
cannam@290 170 --------
cannam@290 171
cannam@290 172 Skeleton code that could be used as a template for your new plugin
cannam@290 173 implementation.
cannam@290 174
cannam@290 175
cannam@239 176 host
cannam@239 177 ----
cannam@14 178
cannam@16 179 A simple command-line Vamp host, capable of loading a plugin and using
cannam@16 180 it to process a complete audio file, with its default parameters.
cannam@14 181
cannam@250 182 This host also contains a number of options for listing the installed
cannam@250 183 plugins and their properties in various formats. For that reason, it
cannam@250 184 isn't really as simple as one might hope. The core of the code is
cannam@250 185 still reasonably straightforward, however.
cannam@250 186
cannam@40 187
cannam@40 188 Plugin Lookup and Categorisation
cannam@40 189 ================================
cannam@40 190
cannam@40 191 The Vamp API does not officially specify how to load plugin libraries
cannam@40 192 or where to find them. However, the SDK does include a function
cannam@40 193 (Vamp::PluginHostAdapter::getPluginPath()) that returns a recommended
cannam@75 194 directory search path that hosts may use for plugin libraries, and a
cannam@75 195 class (Vamp::HostExt::PluginLoader) that implements a sensible
cannam@75 196 cross-platform lookup policy using this path. We recommend using this
cannam@75 197 class in your host unless you have a good reason not to want to. This
cannam@75 198 implementation also permits the user to set the environment variable
cannam@75 199 VAMP_PATH to override the default path if desired.
cannam@40 200
cannam@75 201 The policy used by Vamp::HostExt::PluginLoader -- and our
cannam@75 202 recommendation for any host -- is to search each directory in the path
cannam@75 203 returned by getPluginPath for .DLL (on Windows), .so (on Linux,
cannam@75 204 Solaris, BSD etc) or .dylib (on OS/X) files, then to load each one and
cannam@75 205 perform a dynamic name lookup on the vampGetPluginDescriptor function
cannam@75 206 to enumerate the plugins in the library. This operation will
cannam@75 207 necessarily be system-dependent.
cannam@40 208
cannam@40 209 Vamp also has an informal convention for sorting plugins into
cannam@40 210 functional categories. In addition to the library file itself, a
cannam@40 211 plugin library may install a category file with the same name as the
cannam@40 212 library but .cat extension. The existence and format of this file are
cannam@40 213 not specified by the Vamp API, but by convention the file may contain
cannam@40 214 lines of the format
cannam@40 215
cannam@40 216 vamp:pluginlibrary:pluginname::General Category > Specific Category
cannam@40 217
cannam@40 218 which a host may read and use to assign plugins a location within a
cannam@40 219 category tree for display to the user. The expectation is that
cannam@40 220 advanced users may also choose to set up their own preferred category
cannam@40 221 trees, which is why this information is not queried as part of the
cannam@75 222 Vamp plugin's API itself. The Vamp::HostExt::PluginLoader class also
cannam@75 223 provides support for plugin category lookup using this scheme.
cannam@32 224
cannam@14 225
cannam@14 226 Licensing
cannam@14 227 =========
cannam@14 228
cannam@18 229 This plugin SDK is freely redistributable under a "new-style BSD"
cannam@42 230 licence. See the file COPYING for more details. In short, you may
cannam@42 231 modify and redistribute the SDK and example plugins within any
cannam@42 232 commercial or non-commercial, proprietary or open-source plugin or
cannam@42 233 application under almost any conditions, with no obligation to provide
cannam@42 234 source code, provided you retain the original copyright note.
cannam@14 235
cannam@14 236
cannam@14 237 See Also
cannam@14 238 ========
cannam@14 239
cannam@14 240 Sonic Visualiser, an interactive open-source graphical audio
cannam@14 241 inspection, analysis and visualisation tool supporting Vamp plugins.
cannam@35 242 http://www.sonicvisualiser.org/
cannam@14 243
cannam@14 244
cannam@44 245 Authors
cannam@44 246 =======
cannam@44 247
cannam@44 248 Vamp and the Vamp SDK were designed and made at the Centre for Digital
cannam@64 249 Music at Queen Mary, University of London.
cannam@44 250
Chris@397 251 The SDK was written by Chris Cannam, copyright (c) 2005-2015
cannam@64 252 Chris Cannam and QMUL.
cannam@64 253
cannam@64 254 Mark Sandler and Christian Landone provided ideas and direction, and
cannam@64 255 Mark Levy, Dan Stowell, Martin Gasser and Craig Sapp provided testing
cannam@64 256 and other input for the 1.0 API and SDK. The API also uses some ideas
cannam@64 257 from prior plugin systems, notably DSSI (http://dssi.sourceforge.net)
cannam@64 258 and FEAPI (http://feapi.sourceforge.net).
cannam@64 259