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