annotate src/doc-overview @ 415:1522e2f6d700

Fix handling of output sample rate in buffering adapter in case where SampleType is Fixed but no sample rate provided (which is invalid behaviour from the plugin, but we might as well do the right thing with it)
author Chris Cannam
date Fri, 04 Sep 2015 13:48:28 +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 */