annotate src/doc-overview @ 541:0e32c328b02a tip

Added tag vamp-plugin-sdk-v2.10 for changeset fa74c473e48c
author Chris Cannam
date Mon, 18 May 2020 11:53:49 +0100
parents d5c5a52e6c9f
children
rev   line source
cannam@229 1
cannam@229 2 /** \mainpage Vamp Plugin SDK
cannam@229 3
cannam@229 4 \section about About Vamp
cannam@229 5
cannam@229 6 Vamp is an API for C and C++ plugins that process sampled audio data
cannam@229 7 to produce descriptive output (measurements or semantic observations).
cannam@229 8 Find more information at http://www.vamp-plugins.org/ .
cannam@229 9
cannam@229 10 Although the official API for Vamp plugins is defined in C for maximum
cannam@229 11 binary compatibility, we strongly recommend using the provided C++
cannam@229 12 classes in the SDK to implement your own plugins and hosts.
cannam@229 13
cannam@229 14 \section plugins For Plugins
cannam@229 15
cannam@229 16 Plugins should subclass Vamp::Plugin, and then use a
cannam@229 17 Vamp::PluginAdapter to expose the correct C API for the plugin. Read
cannam@229 18 the documentation for Vamp::PluginBase and Vamp::Plugin before
cannam@229 19 starting.
cannam@229 20
cannam@229 21 Plugins should be compiled and linked into dynamic libraries using the
cannam@229 22 usual convention for your platform, and should link (preferably
cannam@229 23 statically) with -lvamp-sdk. Any number of plugins can reside in a
cannam@229 24 single dynamic library. See plugins.cpp in the example plugins
cannam@229 25 directory for the sort of code that will need to accompany your plugin
cannam@229 26 class or classes, to make it possible for a host to look up your
cannam@229 27 plugins properly.
cannam@229 28
cannam@239 29 Please read the relevant README file for your platform found in the
cannam@239 30 Vamp SDK build/ directory, for details about how to ensure the
cannam@239 31 resulting dynamic library exports the correct linker symbols.
cannam@229 32
cannam@229 33 The following example plugins are provided. You may legally reuse any
cannam@229 34 amount of the code from these examples in any plugins you write,
cannam@229 35 whether proprietary or open-source.
cannam@229 36
cannam@229 37 - ZeroCrossing calculates the positions and density of zero-crossing
cannam@229 38 points in an audio waveform.
cannam@229 39
cannam@229 40 - SpectralCentroid calculates the centre of gravity of the frequency
cannam@229 41 domain representation of each block of audio.
cannam@229 42
cannam@242 43 - PowerSpectrum calculates a power spectrum from the input audio.
cannam@245 44 Actually, it doesn't do any work except calculating power from a
cannam@245 45 cartesian complex FFT output. The work of calculating this frequency
cannam@245 46 domain output is done for it by the host or host SDK; the plugin just
cannam@245 47 needs to declare that it wants frequency domain input. This is the
cannam@245 48 simplest of the example plugins.
cannam@242 49
cannam@229 50 - AmplitudeFollower is a simple implementation of SuperCollider's
cannam@229 51 amplitude-follower algorithm.
cannam@229 52
cannam@229 53 - PercussionOnsetDetector estimates the locations of percussive
cannam@229 54 onsets using a simple method described in "Drum Source Separation
cannam@229 55 using Percussive Feature Detection and Spectral Modulation" by Dan
cannam@229 56 Barry, Derry Fitzgerald, Eugene Coyle and Bob Lawlor, ISSC 2005.
cannam@229 57
cannam@239 58 - FixedTempoEstimator calculates a single beats-per-minute value
cannam@239 59 which is an estimate of the tempo of a piece of music that is assumed
cannam@239 60 to be of fixed tempo, using autocorrelation of a frequency domain
cannam@239 61 energy rise metric. It has several outputs that return intermediate
cannam@239 62 results used in the calculation, and may be a useful example of a
cannam@239 63 plugin having several outputs with varying feature structures.
cannam@229 64
Chris@337 65 Plugin authors should also read the Programmer's Guide at
Chris@337 66 http://vamp-plugins.org/guide.pdf .
Chris@337 67
cannam@229 68 \section hosts For Hosts
cannam@229 69
cannam@229 70 Hosts will normally use a Vamp::PluginHostAdapter to convert each
cannam@229 71 plugin's exposed C API back into a useful Vamp::Plugin C++ object.
cannam@229 72
cannam@239 73 The Vamp::HostExt namespace contains several additional C++ classes to
cannam@239 74 do this work for them, and make the host's life easier:
cannam@229 75
cannam@239 76 - Vamp::HostExt::PluginLoader provides a very easy interface for a
cannam@229 77 host to discover, load, and find out category information about the
cannam@239 78 available plugins. Most Vamp hosts will probably want to use this
cannam@239 79 class.
cannam@229 80
cannam@229 81 - Vamp::HostExt::PluginInputDomainAdapter provides a simple means for
cannam@239 82 hosts to handle plugins that want frequency-domain input, without
cannam@229 83 having to convert the input themselves.
cannam@229 84
cannam@229 85 - Vamp::HostExt::PluginChannelAdapter provides a simple means for
cannam@229 86 hosts to use plugins that do not necessarily support the same number
cannam@229 87 of audio channels as they have available, without having to apply a
cannam@229 88 channel management / mixdown policy themselves.
cannam@229 89
cannam@239 90 - Vamp::HostExt::PluginBufferingAdapter provides a means for hosts to
cannam@239 91 avoid having to negotiate the input step and block size, instead
cannam@239 92 permitting the host to use any block size they desire (and a step
cannam@239 93 size equal to it). This is particularly useful for "streaming" hosts
cannam@239 94 that cannot seek backwards in the input audio stream and so would
cannam@239 95 otherwise need to implement an additional buffer to support step
cannam@239 96 sizes smaller than the block size.
cannam@229 97
cannam@239 98 - Vamp::HostExt::PluginSummarisingAdapter provides summarisation
cannam@239 99 methods such as mean and median averages of output features, for use
cannam@239 100 in any context where an available plugin produces individual values
cannam@239 101 but the result that is actually needed is some sort of aggregate.
cannam@229 102
cannam@229 103 The PluginLoader class can also use the input domain, channel, and
cannam@229 104 buffering adapters automatically to make these conversions transparent
cannam@229 105 to the host if required.
cannam@229 106
cannam@239 107 Host authors should also refer to the example host code in the host
cannam@239 108 directory of the SDK.
cannam@239 109
cannam@229 110 Hosts should link with -lvamp-hostsdk.
cannam@229 111
cannam@229 112 (The following notes in this section are mostly relevant for
cannam@229 113 developers that are not using the HostExt classes, or that wish to
cannam@229 114 know more about the policy they implement.)
cannam@229 115
cannam@229 116 The Vamp API does not officially specify how to load plugin libraries
cannam@229 117 or where to find them. However, the SDK does include a function
cannam@229 118 (Vamp::PluginHostAdapter::getPluginPath()) that returns a recommended
cannam@239 119 directory search path that hosts may use for plugin libraries, and a
cannam@239 120 class (Vamp::HostExt::PluginLoader) that implements a sensible
cannam@239 121 cross-platform lookup policy using this path. We recommend using this
cannam@239 122 class in your host unless you have a good reason not to want to. This
cannam@239 123 implementation also permits the user to set the environment variable
cannam@239 124 VAMP_PATH to override the default path if desired.
cannam@229 125
cannam@239 126 The policy used by Vamp::HostExt::PluginLoader -- and our
cannam@239 127 recommendation for any host -- is to search each directory in this
cannam@239 128 path for .DLL (on Windows), .so (on Linux, Solaris, BSD etc) or .dylib
cannam@239 129 (on OS/X) files, then to load each one and perform a dynamic name
cannam@239 130 lookup on the vampGetPluginDescriptor function to enumerate the
cannam@239 131 plugins in the library. The example host has some code that may help,
cannam@239 132 but this operation will necessarily be system-dependent.
cannam@229 133
cannam@229 134 Vamp also has an informal convention for sorting plugins into
cannam@229 135 functional categories. In addition to the library file itself, a
cannam@229 136 plugin library may install a category file with the same name as the
cannam@229 137 library but .cat extension. The existence and format of this file are
cannam@229 138 not specified by the Vamp API, but by convention the file may contain
cannam@229 139 lines of the format
cannam@229 140
cannam@229 141 \code
cannam@229 142 vamp:pluginlibrary:pluginname::General Category > Specific Category
cannam@229 143 \endcode
cannam@229 144
cannam@229 145 which a host may read and use to assign plugins a location within a
cannam@229 146 category tree for display to the user. The expectation is that
cannam@229 147 advanced users may also choose to set up their own preferred category
cannam@229 148 trees, which is why this information is not queried as part of the
cannam@239 149 Vamp plugin's API itself. The Vamp::HostExt::PluginLoader class also
cannam@239 150 provides support for plugin category lookup using this scheme.
cannam@229 151
cannam@229 152 \section license License
cannam@229 153
cannam@229 154 This plugin SDK is freely redistributable under a "new-style BSD"
cannam@229 155 licence. See the file COPYING for more details. In short, you may
cannam@229 156 modify and redistribute the SDK and example plugins within any
cannam@229 157 commercial or non-commercial, proprietary or open-source plugin or
cannam@229 158 application under almost any conditions, with no obligation to provide
cannam@229 159 source code, provided you retain the original copyright note.
cannam@229 160
cannam@229 161
cannam@229 162 */