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