1 /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*- vi:set ts=8 sts=4 sw=4: */
6 An API for audio analysis and feature extraction plugins.
8 Centre for Digital Music, Queen Mary, University of London.
9 Copyright 2006 Chris Cannam.
11 Permission is hereby granted, free of charge, to any person
12 obtaining a copy of this software and associated documentation
13 files (the "Software"), to deal in the Software without
14 restriction, including without limitation the rights to use, copy,
15 modify, merge, publish, distribute, sublicense, and/or sell copies
16 of the Software, and to permit persons to whom the Software is
17 furnished to do so, subject to the following conditions:
19 The above copyright notice and this permission notice shall be
20 included in all copies or substantial portions of the Software.
22 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
23 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
24 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
25 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
26 ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
27 CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
28 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
30 Except as contained in this notice, the names of the Centre for
31 Digital Music; Queen Mary, University of London; and Chris Cannam
32 shall not be used in advertising or otherwise to promote the sale,
33 use or other dealings in this Software without prior written
37 #ifndef VAMP_HEADER_INCLUDED
38 #define VAMP_HEADER_INCLUDED
45 * Plugin API version. This is incremented when a change is made that
46 * changes the binary layout of the descriptor records. When this
47 * happens, there should be a mechanism for retaining compatibility
48 * with older hosts and/or plugins.
50 * See also the vampApiVersion field in the plugin descriptor, and the
51 * hostApiVersion argument to the vampGetPluginDescriptor function.
53 #define VAMP_API_VERSION 1
56 * C language API for Vamp plugins.
58 * This is the formal plugin API for Vamp. Plugin authors may prefer
59 * to use the C++ classes provided in the Vamp plugin SDK, instead of
60 * using this API directly. There is an adapter class provided that
61 * makes C++ plugins available using this C API with relatively little
62 * work, and the C++ headers are more thoroughly documented.
64 * IMPORTANT: The comments in this file summarise the purpose of each
65 * of the declared fields and functions, but do not provide a complete
66 * guide to their permitted values and expected usage. Please refer
67 * to the C++ headers in the Vamp plugin SDK for further details and
68 * plugin lifecycle documentation.
71 typedef struct _VampParameterDescriptor
73 /** Computer-usable name of the parameter. Must not change. [a-zA-Z0-9_] */
74 const char *identifier;
76 /** Human-readable name of the parameter. May be translatable. */
79 /** Human-readable short text about the parameter. May be translatable. */
80 const char *description;
82 /** Human-readable unit of the parameter. */
91 /** Default value. Plugin is responsible for setting this on initialise. */
94 /** 1 if parameter values are quantized to a particular resolution. */
97 /** Quantization resolution, if isQuantized. */
100 /** Human-readable names of the values, if isQuantized. May be NULL. */
101 const char **valueNames;
103 } VampParameterDescriptor;
107 /** Each process call returns results aligned with call's block start. */
108 vampOneSamplePerStep,
110 /** Returned results are evenly spaced at samplerate specified below. */
113 /** Returned results have their own individual timestamps. */
114 vampVariableSampleRate
118 typedef struct _VampOutputDescriptor
120 /** Computer-usable name of the output. Must not change. [a-zA-Z0-9_] */
121 const char *identifier;
123 /** Human-readable name of the output. May be translatable. */
126 /** Human-readable short text about the output. May be translatable. */
127 const char *description;
129 /** Human-readable name of the unit of the output. */
132 /** 1 if output has equal number of values for each returned result. */
133 int hasFixedBinCount;
135 /** Number of values per result, if hasFixedBinCount. */
136 unsigned int binCount;
138 /** Names of returned value bins, if hasFixedBinCount. May be NULL. */
139 const char **binNames;
141 /** 1 if each returned value falls within the same fixed min/max range. */
144 /** Minimum value for a returned result in any bin, if hasKnownExtents. */
147 /** Maximum value for a returned result in any bin, if hasKnownExtents. */
150 /** 1 if returned results are quantized to a particular resolution. */
153 /** Quantization resolution for returned results, if isQuantized. */
156 /** Time positioning method for returned results (see VampSampleType). */
157 VampSampleType sampleType;
159 /** Sample rate of returned results, if sampleType is vampFixedSampleRate.
160 "Resolution" of result, if sampleType is vampVariableSampleRate. */
163 } VampOutputDescriptor;
165 typedef struct _VampFeature
167 /** 1 if the feature has a timestamp (i.e. if vampVariableSampleRate). */
170 /** Seconds component of timestamp. */
173 /** Nanoseconds component of timestamp. */
176 /** Number of values. Must be binCount if hasFixedBinCount. */
177 unsigned int valueCount;
179 /** Values for this returned sample. */
182 /** Label for this returned sample. May be NULL. */
187 typedef struct _VampFeatureList
189 /** Number of features in this feature list. */
190 unsigned int featureCount;
192 /** Features in this feature list. May be NULL if featureCount is zero. */
193 VampFeature *features;
204 typedef void *VampPluginHandle;
206 typedef struct _VampPluginDescriptor
208 /** API version with which this descriptor is compatible. */
209 unsigned int vampApiVersion;
211 /** Computer-usable name of the plugin. Must not change. [a-zA-Z0-9_] */
212 const char *identifier;
214 /** Human-readable name of the plugin. May be translatable. */
217 /** Human-readable short text about the plugin. May be translatable. */
218 const char *description;
220 /** Human-readable name of plugin's author or vendor. */
223 /** Version number of the plugin. */
226 /** Human-readable summary of copyright or licensing for plugin. */
227 const char *copyright;
229 /** Number of parameter inputs. */
230 unsigned int parameterCount;
232 /** Fixed descriptors for parameter inputs. */
233 const VampParameterDescriptor **parameters;
235 /** Number of programs. */
236 unsigned int programCount;
238 /** Fixed names for programs. */
239 const char **programs;
241 /** Preferred input domain for audio input (time or frequency). */
242 VampInputDomain inputDomain;
244 /** Create and return a new instance of this plugin. */
245 VampPluginHandle (*instantiate)(const struct _VampPluginDescriptor *,
246 float inputSampleRate);
248 /** Destroy an instance of this plugin. */
249 void (*cleanup)(VampPluginHandle);
251 /** Initialise an instance following parameter configuration. */
252 int (*initialise)(VampPluginHandle,
253 unsigned int inputChannels,
254 unsigned int stepSize,
255 unsigned int blockSize);
257 /** Reset an instance, ready to use again on new input data. */
258 void (*reset)(VampPluginHandle);
260 /** Get a parameter value. */
261 float (*getParameter)(VampPluginHandle, int);
263 /** Set a parameter value. May only be called before initialise. */
264 void (*setParameter)(VampPluginHandle, int, float);
266 /** Get the current program (if programCount > 0). */
267 unsigned int (*getCurrentProgram)(VampPluginHandle);
269 /** Set the current program. May only be called before initialise. */
270 void (*selectProgram)(VampPluginHandle, unsigned int);
272 /** Get the plugin's preferred processing window increment in samples. */
273 unsigned int (*getPreferredStepSize)(VampPluginHandle);
275 /** Get the plugin's preferred processing window size in samples. */
276 unsigned int (*getPreferredBlockSize)(VampPluginHandle);
278 /** Get the minimum number of input channels this plugin can handle. */
279 unsigned int (*getMinChannelCount)(VampPluginHandle);
281 /** Get the maximum number of input channels this plugin can handle. */
282 unsigned int (*getMaxChannelCount)(VampPluginHandle);
284 /** Get the number of feature outputs (distinct sets of results). */
285 unsigned int (*getOutputCount)(VampPluginHandle);
287 /** Get a descriptor for a given feature output. Returned pointer
288 is valid only until next call to getOutputDescriptor for this
289 handle, or releaseOutputDescriptor for this descriptor. Host
290 must call releaseOutputDescriptor after use. */
291 VampOutputDescriptor *(*getOutputDescriptor)(VampPluginHandle,
294 /** Destroy a descriptor for a feature output. */
295 void (*releaseOutputDescriptor)(VampOutputDescriptor *);
297 /** Process an input block and return a set of features. Returned
298 pointer is valid only until next call to process,
299 getRemainingFeatures, or cleanup for this handle, or
300 releaseFeatureSet for this feature set. Host must call
301 releaseFeatureSet after use. */
302 VampFeatureList *(*process)(VampPluginHandle,
303 const float *const *inputBuffers,
307 /** Return any remaining features at the end of processing. */
308 VampFeatureList *(*getRemainingFeatures)(VampPluginHandle);
310 /** Release a feature set returned from process or getRemainingFeatures. */
311 void (*releaseFeatureSet)(VampFeatureList *);
313 } VampPluginDescriptor;
315 /** Get the descriptor for a given plugin index in this library.
316 Return NULL if the index is outside the range of valid indices for
319 The hostApiVersion argument tells the library code the highest
320 Vamp API version supported by the host. The function should
321 return a plugin descriptor compatible with the highest API version
322 supported by the library that is no higher than that supported by
323 the host. Provided the descriptor has the correct vampApiVersion
324 field for its actual compatibility level, the host should be able
325 to do the right thing with it: use it if possible, discard it
328 const VampPluginDescriptor *vampGetPluginDescriptor
329 (unsigned int hostApiVersion, unsigned int index);
331 /** Function pointer type for vampGetPluginDescriptor. */
332 typedef const VampPluginDescriptor *(*VampGetPluginDescriptorFunction)
333 (unsigned int, unsigned int);