annotate README @ 239:cc467e52da4c

* Add platform README files
author cannam
date Mon, 10 Nov 2008 12:39:19 +0000
parents 3ad28b1e2150
children 7f3a806ed1df
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@239 132 - AmplitudeFollower is a simple implementation of SuperCollider's
cannam@239 133 amplitude-follower algorithm.
cannam@239 134
cannam@239 135 - PercussionOnsetDetector estimates the locations of percussive
cannam@239 136 onsets using a simple method described in "Drum Source Separation
cannam@239 137 using Percussive Feature Detection and Spectral Modulation" by Dan
cannam@239 138 Barry, Derry Fitzgerald, Eugene Coyle and Bob Lawlor, ISSC 2005.
cannam@239 139
cannam@239 140 - FixedTempoEstimator calculates a single beats-per-minute value
cannam@239 141 which is an estimate of the tempo of a piece of music that is assumed
cannam@239 142 to be of fixed tempo, using autocorrelation of a frequency domain
cannam@239 143 energy rise metric. It has several outputs that return intermediate
cannam@239 144 results used in the calculation, and may be a useful example of a
cannam@239 145 plugin having several outputs with varying feature structures.
cannam@239 146
cannam@239 147
cannam@239 148 host
cannam@239 149 ----
cannam@14 150
cannam@16 151 A simple command-line Vamp host, capable of loading a plugin and using
cannam@16 152 it to process a complete audio file, with its default parameters.
cannam@14 153
cannam@40 154
cannam@40 155 Plugin Lookup and Categorisation
cannam@40 156 ================================
cannam@40 157
cannam@40 158 The Vamp API does not officially specify how to load plugin libraries
cannam@40 159 or where to find them. However, the SDK does include a function
cannam@40 160 (Vamp::PluginHostAdapter::getPluginPath()) that returns a recommended
cannam@75 161 directory search path that hosts may use for plugin libraries, and a
cannam@75 162 class (Vamp::HostExt::PluginLoader) that implements a sensible
cannam@75 163 cross-platform lookup policy using this path. We recommend using this
cannam@75 164 class in your host unless you have a good reason not to want to. This
cannam@75 165 implementation also permits the user to set the environment variable
cannam@75 166 VAMP_PATH to override the default path if desired.
cannam@40 167
cannam@75 168 The policy used by Vamp::HostExt::PluginLoader -- and our
cannam@75 169 recommendation for any host -- is to search each directory in the path
cannam@75 170 returned by getPluginPath for .DLL (on Windows), .so (on Linux,
cannam@75 171 Solaris, BSD etc) or .dylib (on OS/X) files, then to load each one and
cannam@75 172 perform a dynamic name lookup on the vampGetPluginDescriptor function
cannam@75 173 to enumerate the plugins in the library. This operation will
cannam@75 174 necessarily be system-dependent.
cannam@40 175
cannam@40 176 Vamp also has an informal convention for sorting plugins into
cannam@40 177 functional categories. In addition to the library file itself, a
cannam@40 178 plugin library may install a category file with the same name as the
cannam@40 179 library but .cat extension. The existence and format of this file are
cannam@40 180 not specified by the Vamp API, but by convention the file may contain
cannam@40 181 lines of the format
cannam@40 182
cannam@40 183 vamp:pluginlibrary:pluginname::General Category > Specific Category
cannam@40 184
cannam@40 185 which a host may read and use to assign plugins a location within a
cannam@40 186 category tree for display to the user. The expectation is that
cannam@40 187 advanced users may also choose to set up their own preferred category
cannam@40 188 trees, which is why this information is not queried as part of the
cannam@75 189 Vamp plugin's API itself. The Vamp::HostExt::PluginLoader class also
cannam@75 190 provides support for plugin category lookup using this scheme.
cannam@32 191
cannam@14 192
cannam@14 193 Licensing
cannam@14 194 =========
cannam@14 195
cannam@18 196 This plugin SDK is freely redistributable under a "new-style BSD"
cannam@42 197 licence. See the file COPYING for more details. In short, you may
cannam@42 198 modify and redistribute the SDK and example plugins within any
cannam@42 199 commercial or non-commercial, proprietary or open-source plugin or
cannam@42 200 application under almost any conditions, with no obligation to provide
cannam@42 201 source code, provided you retain the original copyright note.
cannam@14 202
cannam@14 203
cannam@14 204 See Also
cannam@14 205 ========
cannam@14 206
cannam@14 207 Sonic Visualiser, an interactive open-source graphical audio
cannam@14 208 inspection, analysis and visualisation tool supporting Vamp plugins.
cannam@35 209 http://www.sonicvisualiser.org/
cannam@14 210
cannam@14 211
cannam@44 212 Authors
cannam@44 213 =======
cannam@44 214
cannam@44 215 Vamp and the Vamp SDK were designed and made at the Centre for Digital
cannam@64 216 Music at Queen Mary, University of London.
cannam@44 217
cannam@127 218 The SDK was written by Chris Cannam, copyright (c) 2005-2008
cannam@64 219 Chris Cannam and QMUL.
cannam@64 220
cannam@64 221 Mark Sandler and Christian Landone provided ideas and direction, and
cannam@64 222 Mark Levy, Dan Stowell, Martin Gasser and Craig Sapp provided testing
cannam@64 223 and other input for the 1.0 API and SDK. The API also uses some ideas
cannam@64 224 from prior plugin systems, notably DSSI (http://dssi.sourceforge.net)
cannam@64 225 and FEAPI (http://feapi.sourceforge.net).
cannam@64 226