|
cannam@0
|
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
cannam@0
|
2 <html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
|
|
cannam@0
|
3 <title>VampPluginSDK: Vamp Plugin SDK</title>
|
|
cannam@35
|
4 <link href="tabs.css" rel="stylesheet" type="text/css">
|
|
cannam@0
|
5 <link href="doxygen.css" rel="stylesheet" type="text/css">
|
|
cannam@0
|
6 </head><body>
|
|
cannam@35
|
7 <!-- Generated by Doxygen 1.5.8 -->
|
|
cannam@0
|
8 <div class="navigation" id="top">
|
|
cannam@0
|
9 <div class="tabs">
|
|
cannam@0
|
10 <ul>
|
|
cannam@0
|
11 <li class="current"><a href="main.html"><span>Main Page</span></a></li>
|
|
cannam@0
|
12 <li><a href="namespaces.html"><span>Namespaces</span></a></li>
|
|
cannam@0
|
13 <li><a href="annotated.html"><span>Classes</span></a></li>
|
|
cannam@0
|
14 <li><a href="files.html"><span>Files</span></a></li>
|
|
cannam@0
|
15 <li><a href="dirs.html"><span>Directories</span></a></li>
|
|
cannam@0
|
16 </ul>
|
|
cannam@0
|
17 </div>
|
|
cannam@0
|
18 </div>
|
|
cannam@0
|
19 <div class="contents">
|
|
cannam@0
|
20 <h1>Vamp Plugin SDK</h1>
|
|
cannam@0
|
21 <p>
|
|
cannam@35
|
22 <h3 align="center">2.1 </h3><h2><a class="anchor" name="about">
|
|
cannam@0
|
23 About Vamp</a></h2>
|
|
cannam@21
|
24 <a class="el" href="namespaceVamp.html">Vamp</a> is an API for C and C++ plugins that process sampled audio data to produce descriptive output (measurements or semantic observations). Find more information at <a href="http://www.vamp-plugins.org/">http://www.vamp-plugins.org/</a> .<p>
|
|
cannam@21
|
25 Although the official API for <a class="el" href="namespaceVamp.html">Vamp</a> plugins is defined in C for maximum binary compatibility, we strongly recommend using the provided C++ classes in the SDK to implement your own plugins and hosts.<h2><a class="anchor" name="plugins">
|
|
cannam@0
|
26 For Plugins</a></h2>
|
|
cannam@0
|
27 Plugins should subclass <a class="el" href="classVamp_1_1Plugin.html" title="Vamp::Plugin is a base class for plugin instance classes that provide feature extraction...">Vamp::Plugin</a>, and then use a <a class="el" href="classVamp_1_1PluginAdapter.html" title="PluginAdapter turns a PluginAdapterBase into a specific wrapper for a particular...">Vamp::PluginAdapter</a> to expose the correct C API for the plugin. Read the documentation for <a class="el" href="classVamp_1_1PluginBase.html" title="A base class for plugins with optional configurable parameters, programs, etc.">Vamp::PluginBase</a> and <a class="el" href="classVamp_1_1Plugin.html" title="Vamp::Plugin is a base class for plugin instance classes that provide feature extraction...">Vamp::Plugin</a> before starting.<p>
|
|
cannam@0
|
28 Plugins should be compiled and linked into dynamic libraries using the usual convention for your platform, and should link (preferably statically) with -lvamp-sdk. Any number of plugins can reside in a single dynamic library. See <a class="el" href="plugins_8cpp.html">plugins.cpp</a> in the example plugins directory for the sort of code that will need to accompany your plugin class or classes, to make it possible for a host to look up your plugins properly.<p>
|
|
cannam@21
|
29 Please read the relevant README file for your platform found in the <a class="el" href="namespaceVamp.html">Vamp</a> SDK build/ directory, for details about how to ensure the resulting dynamic library exports the correct linker symbols.<p>
|
|
cannam@21
|
30 The following example plugins are provided. You may legally reuse any amount of the code from these examples in any plugins you write, whether proprietary or open-source.<p>
|
|
cannam@0
|
31 <ul>
|
|
cannam@0
|
32 <li><a class="el" href="classZeroCrossing.html" title="Example plugin that calculates the positions and density of zero-crossing points...">ZeroCrossing</a> calculates the positions and density of zero-crossing points in an audio waveform.</li></ul>
|
|
cannam@0
|
33 <p>
|
|
cannam@0
|
34 <ul>
|
|
cannam@0
|
35 <li><a class="el" href="classSpectralCentroid.html" title="Example plugin that calculates the centre of gravity of the frequency domain representation...">SpectralCentroid</a> calculates the centre of gravity of the frequency domain representation of each block of audio.</li></ul>
|
|
cannam@0
|
36 <p>
|
|
cannam@0
|
37 <ul>
|
|
cannam@21
|
38 <li><a class="el" href="classPowerSpectrum.html" title="Example plugin that returns a power spectrum calculated (trivially) from the frequency...">PowerSpectrum</a> calculates a power spectrum from the input audio. Actually, it doesn't do any work except calculating power from a cartesian complex FFT output. The work of calculating this frequency domain output is done for it by the host or host SDK; the plugin just needs to declare that it wants frequency domain input. This is the simplest of the example plugins.</li></ul>
|
|
cannam@21
|
39 <p>
|
|
cannam@21
|
40 <ul>
|
|
cannam@21
|
41 <li><a class="el" href="classAmplitudeFollower.html" title="Example plugin implementing the SuperCollider amplitude follower function.">AmplitudeFollower</a> is a simple implementation of SuperCollider's amplitude-follower algorithm.</li></ul>
|
|
cannam@0
|
42 <p>
|
|
cannam@0
|
43 <ul>
|
|
cannam@0
|
44 <li><a class="el" href="classPercussionOnsetDetector.html" title="Example plugin that detects percussive events.">PercussionOnsetDetector</a> estimates the locations of percussive onsets using a simple method described in "Drum Source Separation using Percussive Feature Detection and Spectral Modulation" by Dan Barry, Derry Fitzgerald, Eugene Coyle and Bob Lawlor, ISSC 2005.</li></ul>
|
|
cannam@21
|
45 <p>
|
|
cannam@21
|
46 <ul>
|
|
cannam@21
|
47 <li><a class="el" href="classFixedTempoEstimator.html" title="Example plugin that estimates the tempo of a short fixed-tempo sample.">FixedTempoEstimator</a> calculates a single beats-per-minute value which is an estimate of the tempo of a piece of music that is assumed to be of fixed tempo, using autocorrelation of a frequency domain energy rise metric. It has several outputs that return intermediate results used in the calculation, and may be a useful example of a plugin having several outputs with varying feature structures.</li></ul>
|
|
cannam@0
|
48 <h2><a class="anchor" name="hosts">
|
|
cannam@0
|
49 For Hosts</a></h2>
|
|
cannam@0
|
50 Hosts will normally use a <a class="el" href="classVamp_1_1PluginHostAdapter.html" title="PluginHostAdapter is a wrapper class that a Vamp host can use to make the C-language...">Vamp::PluginHostAdapter</a> to convert each plugin's exposed C API back into a useful <a class="el" href="classVamp_1_1Plugin.html" title="Vamp::Plugin is a base class for plugin instance classes that provide feature extraction...">Vamp::Plugin</a> C++ object.<p>
|
|
cannam@21
|
51 The <a class="el" href="namespaceVamp_1_1HostExt.html">Vamp::HostExt</a> namespace contains several additional C++ classes to do this work for them, and make the host's life easier:<p>
|
|
cannam@0
|
52 <ul>
|
|
cannam@21
|
53 <li><a class="el" href="classVamp_1_1HostExt_1_1PluginLoader.html" title="Vamp::HostExt::PluginLoader is a convenience class for discovering and loading Vamp...">Vamp::HostExt::PluginLoader</a> provides a very easy interface for a host to discover, load, and find out category information about the available plugins. Most <a class="el" href="namespaceVamp.html">Vamp</a> hosts will probably want to use this class.</li></ul>
|
|
cannam@0
|
54 <p>
|
|
cannam@0
|
55 <ul>
|
|
cannam@21
|
56 <li><a class="el" href="classVamp_1_1HostExt_1_1PluginInputDomainAdapter.html" title="PluginInputDomainAdapter is a Vamp plugin adapter that converts time-domain input...">Vamp::HostExt::PluginInputDomainAdapter</a> provides a simple means for hosts to handle plugins that want frequency-domain input, without having to convert the input themselves.</li></ul>
|
|
cannam@0
|
57 <p>
|
|
cannam@0
|
58 <ul>
|
|
cannam@0
|
59 <li><a class="el" href="classVamp_1_1HostExt_1_1PluginChannelAdapter.html" title="PluginChannelAdapter is a Vamp plugin adapter that implements a policy for management...">Vamp::HostExt::PluginChannelAdapter</a> provides a simple means for hosts to use plugins that do not necessarily support the same number of audio channels as they have available, without having to apply a channel management / mixdown policy themselves.</li></ul>
|
|
cannam@0
|
60 <p>
|
|
cannam@0
|
61 <ul>
|
|
cannam@21
|
62 <li><a class="el" href="classVamp_1_1HostExt_1_1PluginBufferingAdapter.html" title="PluginBufferingAdapter is a Vamp plugin adapter that allows plugins to be used by...">Vamp::HostExt::PluginBufferingAdapter</a> provides a means for hosts to avoid having to negotiate the input step and block size, instead permitting the host to use any block size they desire (and a step size equal to it). This is particularly useful for "streaming" hosts that cannot seek backwards in the input audio stream and so would otherwise need to implement an additional buffer to support step sizes smaller than the block size.</li></ul>
|
|
cannam@0
|
63 <p>
|
|
cannam@21
|
64 <ul>
|
|
cannam@21
|
65 <li><a class="el" href="classVamp_1_1HostExt_1_1PluginSummarisingAdapter.html" title="PluginSummarisingAdapter is a Vamp plugin adapter that provides summarisation methods...">Vamp::HostExt::PluginSummarisingAdapter</a> provides summarisation methods such as mean and median averages of output features, for use in any context where an available plugin produces individual values but the result that is actually needed is some sort of aggregate.</li></ul>
|
|
cannam@21
|
66 <p>
|
|
cannam@21
|
67 The PluginLoader class can also use the input domain, channel, and buffering adapters automatically to make these conversions transparent to the host if required.<p>
|
|
cannam@21
|
68 Host authors should also refer to the example host code in the host directory of the SDK.<p>
|
|
cannam@0
|
69 Hosts should link with -lvamp-hostsdk.<p>
|
|
cannam@0
|
70 (The following notes in this section are mostly relevant for developers that are not using the HostExt classes, or that wish to know more about the policy they implement.)<p>
|
|
cannam@21
|
71 The <a class="el" href="namespaceVamp.html">Vamp</a> API does not officially specify how to load plugin libraries or where to find them. However, the SDK does include a function (<a class="el" href="classVamp_1_1PluginHostAdapter.html#09cbfb7903d28f10d6d556c6cb81c5f6">Vamp::PluginHostAdapter::getPluginPath()</a>) that returns a recommended directory search path that hosts may use for plugin libraries, and a class (<a class="el" href="classVamp_1_1HostExt_1_1PluginLoader.html" title="Vamp::HostExt::PluginLoader is a convenience class for discovering and loading Vamp...">Vamp::HostExt::PluginLoader</a>) that implements a sensible cross-platform lookup policy using this path. We recommend using this class in your host unless you have a good reason not to want to. This implementation also permits the user to set the environment variable VAMP_PATH to override the default path if desired.<p>
|
|
cannam@21
|
72 The policy used by <a class="el" href="classVamp_1_1HostExt_1_1PluginLoader.html" title="Vamp::HostExt::PluginLoader is a convenience class for discovering and loading Vamp...">Vamp::HostExt::PluginLoader</a> -- and our recommendation for any host -- is to search each directory in this path for .DLL (on Windows), .so (on Linux, Solaris, BSD etc) or .dylib (on OS/X) files, then to load each one and perform a dynamic name lookup on the vampGetPluginDescriptor function to enumerate the plugins in the library. The example host has some code that may help, but this operation will necessarily be system-dependent.<p>
|
|
cannam@21
|
73 <a class="el" href="namespaceVamp.html">Vamp</a> also has an informal convention for sorting plugins into functional categories. In addition to the library file itself, a plugin library may install a category file with the same name as the library but .cat extension. The existence and format of this file are not specified by the <a class="el" href="namespaceVamp.html">Vamp</a> API, but by convention the file may contain lines of the format<p>
|
|
cannam@0
|
74 <div class="fragment"><pre class="fragment">vamp:pluginlibrary:pluginname::General Category > Specific Category
|
|
cannam@0
|
75 </pre></div><p>
|
|
cannam@21
|
76 which a host may read and use to assign plugins a location within a category tree for display to the user. The expectation is that advanced users may also choose to set up their own preferred category trees, which is why this information is not queried as part of the <a class="el" href="namespaceVamp.html">Vamp</a> plugin's API itself. The <a class="el" href="classVamp_1_1HostExt_1_1PluginLoader.html" title="Vamp::HostExt::PluginLoader is a convenience class for discovering and loading Vamp...">Vamp::HostExt::PluginLoader</a> class also provides support for plugin category lookup using this scheme.<h2><a class="anchor" name="license">
|
|
cannam@0
|
77 License</a></h2>
|
|
cannam@0
|
78 This plugin SDK is freely redistributable under a "new-style BSD" licence. See the file COPYING for more details. In short, you may modify and redistribute the SDK and example plugins within any commercial or non-commercial, proprietary or open-source plugin or application under almost any conditions, with no obligation to provide source code, provided you retain the original copyright note. </div>
|
|
cannam@35
|
79 <hr size="1"><address style="text-align: right;"><small>Generated on Thu Sep 24 13:40:13 2009 for VampPluginSDK by
|
|
cannam@0
|
80 <a href="http://www.doxygen.org/index.html">
|
|
cannam@35
|
81 <img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.8 </small></address>
|
|
cannam@0
|
82 </body>
|
|
cannam@0
|
83 </html>
|
