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);
added
removed
lib-src/libvamp/vamp/vamp.h
