annotate README @ 42:1eb2419fc326

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