annotate README @ 66:80803674a695

* removed empty directory (from a prior ill-considered reshuffle)
author cannam
date Mon, 04 Jun 2007 10:45:25 +0000
parents 9d3272c7db60
children 0f8524203677
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@14 12 The principal differences between Vamp and a real-time audio
cannam@14 13 processing plugin system such as VST are:
cannam@14 14
cannam@14 15 * Vamp plugins may output complex multidimensional data with labels.
cannam@14 16 As a consequence, they are likely to work best when the output
cannam@14 17 data has a much lower sampling rate than the input. (This also
cannam@14 18 means it is usually desirable to implement them in C++ using the
cannam@14 19 high-level base class provided rather than use the raw C API.)
cannam@14 20
cannam@14 21 * While Vamp plugins receive data block-by-block, they are not
cannam@14 22 required to return output immediately on receiving the input.
cannam@14 23 A Vamp plugin may be non-causal, preferring to store up data
cannam@14 24 based on its input until the end of a processing run and then
cannam@14 25 return all results at once.
cannam@14 26
cannam@14 27 * Vamp plugins have more control over their inputs than a typical
cannam@14 28 real-time processing plugin. For example, they can indicate to
cannam@18 29 the host their preferred processing block and step sizes, and these
cannam@18 30 may differ.
cannam@18 31
cannam@18 32 * Vamp plugins may ask to receive data in the frequency domain
cannam@18 33 instead of the time domain. The host takes the responsibility
cannam@18 34 for converting the input data using an FFT of windowed frames.
cannam@18 35 This simplifies plugins that do straightforward frequency-domain
cannam@18 36 processing and permits the host to cache frequency-domain data
cannam@18 37 when possible.
cannam@14 38
cannam@14 39 * A Vamp plugin is configured once before each processing run, and
cannam@14 40 receives no further parameter changes during use -- unlike real
cannam@14 41 time plugin APIs in which the input parameters may change at any
cannam@14 42 time. This also means that fundamental properties such as the
cannam@14 43 number of values per output or the preferred processing block
cannam@18 44 size may depend on the input parameters.
cannam@14 45
cannam@38 46 * Vamp plugins do not have to be able to run in real time.
cannam@38 47
cannam@14 48
cannam@14 49 About this SDK
cannam@14 50 ==============
cannam@14 51
cannam@14 52 This Software Development Kit contains the following:
cannam@14 53
cannam@14 54 * vamp/vamp.h
cannam@14 55
cannam@14 56 The formal C language plugin API for Vamp plugins.
cannam@14 57
cannam@14 58 A Vamp plugin is a dynamic library (.so, .dll or .dylib depending on
cannam@14 59 platform) exposing one C-linkage entry point (vampGetPluginDescriptor)
cannam@14 60 which returns data defined in the rest of this C header.
cannam@14 61
cannam@14 62 Although this is the official API for Vamp, we don't recommend that
cannam@14 63 you program directly to it. The C++ abstraction in the SDK directory
cannam@18 64 (below) is likely to be preferable for most purposes, and is better
cannam@14 65 documented.
cannam@14 66
cannam@14 67 * vamp-sdk
cannam@14 68
cannam@14 69 C++ classes for straightforwardly implementing Vamp plugins and hosts.
cannam@18 70
cannam@18 71 Plugins should subclass Vamp::Plugin and then use a
cannam@18 72 Vamp::PluginAdapter to expose the correct C API for the plugin. Read
cannam@51 73 vamp-sdk/PluginBase.h and Plugin.h for code documentation. Plugins
cannam@51 74 should link with -lvamp-sdk.
cannam@18 75
cannam@14 76 Hosts may use the Vamp::PluginHostAdapter to convert the loaded
cannam@51 77 plugin's C API back into a Vamp::Plugin object. Hosts should link
cannam@51 78 with -lvamp-hostsdk.
cannam@14 79
cannam@64 80 * vamp-sdk/hostext
cannam@64 81
cannam@64 82 Additional C++ classes to make a host's life easier.
cannam@64 83
cannam@64 84 Vamp::HostExt::PluginLoader provides a very simple interface for a
cannam@64 85 host to discover, load, and find out category information about the
cannam@64 86 available plugins. Most "casual" Vamp hosts will probably want to use
cannam@64 87 this class.
cannam@64 88
cannam@64 89 Vamp::HostExt::PluginInputDomainAdapter provides a simple means for
cannam@64 90 hosts to handle plugins that expect frequency-domain input, without
cannam@64 91 having to convert the input themselves.
cannam@64 92
cannam@64 93 Vamp::HostExt::PluginChannelAdapter provides a simple means for hosts
cannam@64 94 to use plugins that do not necessarily support the same number of
cannam@64 95 audio channels as they have available, without having to apply a
cannam@64 96 channel management / mixdown policy themselves.
cannam@64 97
cannam@64 98 The PluginLoader can use the input domain and channel adapters
cannam@64 99 automatically to make the entire conversion process transparent to the
cannam@64 100 host if required.
cannam@64 101
cannam@14 102 * examples
cannam@14 103
cannam@14 104 Example plugins implemented using the C++ classes. ZeroCrossing
cannam@14 105 calculates the positions and density of zero-crossing points in an
cannam@35 106 audio waveform. SpectralCentroid calculates the centre of gravity of
cannam@14 107 the frequency domain representation of each block of audio.
cannam@35 108 PercussionOnsetDetector estimates the locations of percussive onsets
cannam@35 109 using a simple method described in "Drum Source Separation using
cannam@35 110 Percussive Feature Detection and Spectral Modulation" by Dan Barry,
cannam@35 111 Derry Fitzgerald, Eugene Coyle and Bob Lawlor, ISSC 2005.
cannam@14 112
cannam@14 113 * host
cannam@14 114
cannam@16 115 A simple command-line Vamp host, capable of loading a plugin and using
cannam@16 116 it to process a complete audio file, with its default parameters.
cannam@64 117 Requires libsndfile (http://www.mega-nerd.com/libsndfile/).
cannam@64 118
cannam@64 119 If you don't have libsndfile, you may want to edit the Makefile to
cannam@64 120 change the default build target from "all" to "sdk" so as to compile
cannam@64 121 only the SDK.
cannam@14 122
cannam@40 123
cannam@40 124 Plugin Lookup and Categorisation
cannam@40 125 ================================
cannam@40 126
cannam@40 127 The Vamp API does not officially specify how to load plugin libraries
cannam@40 128 or where to find them. However, the SDK does include a function
cannam@40 129 (Vamp::PluginHostAdapter::getPluginPath()) that returns a recommended
cannam@40 130 directory search path that hosts may use for plugin libraries.
cannam@40 131
cannam@40 132 Our suggestion for a host is to search each directory in this path for
cannam@40 133 .DLL (on Windows), .so (on Linux, Solaris, BSD etc) or .dylib (on
cannam@40 134 OS/X) files, then to load each one and perform a dynamic name lookup
cannam@40 135 on the vampGetPluginDescriptor function to enumerate the plugins in
cannam@40 136 the library. The example host has some code that may help, but this
cannam@40 137 operation will necessarily be system-dependent.
cannam@40 138
cannam@40 139 Vamp also has an informal convention for sorting plugins into
cannam@40 140 functional categories. In addition to the library file itself, a
cannam@40 141 plugin library may install a category file with the same name as the
cannam@40 142 library but .cat extension. The existence and format of this file are
cannam@40 143 not specified by the Vamp API, but by convention the file may contain
cannam@40 144 lines of the format
cannam@40 145
cannam@40 146 vamp:pluginlibrary:pluginname::General Category > Specific Category
cannam@40 147
cannam@40 148 which a host may read and use to assign plugins a location within a
cannam@40 149 category tree for display to the user. The expectation is that
cannam@40 150 advanced users may also choose to set up their own preferred category
cannam@40 151 trees, which is why this information is not queried as part of the
cannam@40 152 Vamp API itself.
cannam@32 153
cannam@14 154
cannam@42 155 Building and Installing the SDK and Examples
cannam@42 156 ============================================
cannam@14 157
cannam@42 158 To build the SDK, the simple host, and the example plugins, edit the
cannam@42 159 Makefile to suit your platform according to the comments in it, then
cannam@42 160 run "make".
cannam@42 161
cannam@42 162 Installing the example plugins so that they can be found by other Vamp
cannam@42 163 hosts depends on your platform:
cannam@42 164
cannam@44 165 * Windows: copy the files
cannam@44 166 examples/vamp-example-plugins.dll
cannam@44 167 examples/vamp-example-plugins.cat
cannam@44 168 to
cannam@44 169 C:\Program Files\Vamp Plugins
cannam@42 170
cannam@44 171 * Linux: copy the files
cannam@44 172 examples/vamp-example-plugins.so
cannam@44 173 examples/vamp-example-plugins.cat
cannam@44 174 to
cannam@44 175 /usr/local/lib/vamp/
cannam@42 176
cannam@44 177 * OS/X: copy the files
cannam@44 178 examples/vamp-example-plugins.dylib
cannam@44 179 examples/vamp-example-plugins.cat
cannam@44 180 to
cannam@44 181 /Library/Audio/Plug-Ins/Vamp
cannam@42 182
cannam@42 183 When building a plugin or host of your own using the SDK, you will
cannam@44 184 need to include the headers from the vamp-sdk directory; then when
cannam@44 185 linking your plugin or host, we suggest statically linking the SDK
cannam@44 186 code (in preference to distributing it alongside your program in DLL
cannam@44 187 form). An easy way to do this, if using a project-based build tool
cannam@42 188 such as Visual Studio or XCode, is simply to add the .cpp files in the
cannam@42 189 vamp-sdk directory to your project.
cannam@14 190
cannam@14 191
cannam@14 192 Licensing
cannam@14 193 =========
cannam@14 194
cannam@18 195 This plugin SDK is freely redistributable under a "new-style BSD"
cannam@42 196 licence. See the file COPYING for more details. In short, you may
cannam@42 197 modify and redistribute the SDK and example plugins within any
cannam@42 198 commercial or non-commercial, proprietary or open-source plugin or
cannam@42 199 application under almost any conditions, with no obligation to provide
cannam@42 200 source code, provided you retain the original copyright note.
cannam@14 201
cannam@14 202
cannam@14 203 See Also
cannam@14 204 ========
cannam@14 205
cannam@14 206 Sonic Visualiser, an interactive open-source graphical audio
cannam@14 207 inspection, analysis and visualisation tool supporting Vamp plugins.
cannam@35 208 http://www.sonicvisualiser.org/
cannam@14 209
cannam@14 210
cannam@44 211 Authors
cannam@44 212 =======
cannam@44 213
cannam@44 214 Vamp and the Vamp SDK were designed and made at the Centre for Digital
cannam@64 215 Music at Queen Mary, University of London.
cannam@44 216
cannam@64 217 The SDK was written by Chris Cannam, copyright (c) 2005-2007
cannam@64 218 Chris Cannam and QMUL.
cannam@64 219
cannam@64 220 Mark Sandler and Christian Landone provided ideas and direction, and
cannam@64 221 Mark Levy, Dan Stowell, Martin Gasser and Craig Sapp provided testing
cannam@64 222 and other input for the 1.0 API and SDK. The API also uses some ideas
cannam@64 223 from prior plugin systems, notably DSSI (http://dssi.sourceforge.net)
cannam@64 224 and FEAPI (http://feapi.sourceforge.net).
cannam@64 225