annotate vamp-sdk/doc-overview @ 218:81ffb843c8cc

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