VampPluginSDK  2.10
vamp.h
Go to the documentation of this file.
1 /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*- vi:set ts=8 sts=4 sw=4: */
2 
3 /*
4  Vamp
5 
6  An API for audio analysis and feature extraction plugins.
7 
8  Centre for Digital Music, Queen Mary, University of London.
9  Copyright 2006 Chris Cannam.
10 
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:
18 
19  The above copyright notice and this permission notice shall be
20  included in all copies or substantial portions of the Software.
21 
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.
29 
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
34  authorization.
35 */
36 
37 #ifndef VAMP_HEADER_INCLUDED
38 #define VAMP_HEADER_INCLUDED
39 
40 #ifdef __cplusplus
41 extern "C" {
42 #endif
43 
53 #define VAMP_API_VERSION 2
54 
72 {
74  const char *identifier;
75 
77  const char *name;
78 
80  const char *description;
81 
83  const char *unit;
84 
86  float minValue;
87 
89  float maxValue;
90 
92  float defaultValue;
93 
96 
98  float quantizeStep;
99 
101  const char **valueNames;
102 
104 
105 typedef enum
106 {
109 
112 
115 
117 
118 typedef struct _VampOutputDescriptor
119 {
121  const char *identifier;
122 
124  const char *name;
125 
127  const char *description;
128 
130  const char *unit;
131 
134 
136  unsigned int binCount;
137 
139  const char **binNames;
140 
143 
145  float minValue;
146 
148  float maxValue;
149 
152 
155 
158 
161  float sampleRate;
162 
171 
173 
174 typedef struct _VampFeature
175 {
178 
180  int sec;
181 
183  int nsec;
184 
186  unsigned int valueCount;
187 
189  float *values;
190 
192  char *label;
193 
194 } VampFeature;
195 
196 typedef struct _VampFeatureV2
197 {
200 
203 
206 
207 } VampFeatureV2;
208 
209 typedef union _VampFeatureUnion
210 {
211  // sizeof(featureV1) >= sizeof(featureV2) for backward compatibility
214 
216 
217 typedef struct _VampFeatureList
218 {
220  unsigned int featureCount;
221 
236 
238 
239 typedef enum
240 {
243 
245 
246 typedef void *VampPluginHandle;
247 
248 typedef struct _VampPluginDescriptor
249 {
251  unsigned int vampApiVersion;
252 
254  const char *identifier;
255 
257  const char *name;
258 
260  const char *description;
261 
263  const char *maker;
264 
267 
269  const char *copyright;
270 
272  unsigned int parameterCount;
273 
276 
278  unsigned int programCount;
279 
281  const char **programs;
282 
285 
288  float inputSampleRate);
289 
292 
295  unsigned int inputChannels,
296  unsigned int stepSize,
297  unsigned int blockSize);
298 
301 
304 
306  void (*setParameter)(VampPluginHandle, int, float);
307 
310 
312  void (*selectProgram)(VampPluginHandle, unsigned int);
313 
316 
319 
322 
325 
328 
333  VampOutputDescriptor *(*getOutputDescriptor)(VampPluginHandle,
334  unsigned int);
335 
338 
345  const float *const *inputBuffers,
346  int sec,
347  int nsec);
348 
350  VampFeatureList *(*getRemainingFeatures)(VampPluginHandle);
351 
354 
356 
357 
377  (unsigned int hostApiVersion, unsigned int index);
378 
379 
381 typedef const VampPluginDescriptor *(*VampGetPluginDescriptorFunction)
382  (unsigned int, unsigned int);
383 
384 #ifdef __cplusplus
385 }
386 #endif
387 
388 #endif
vampFrequencyDomain
@ vampFrequencyDomain
Definition: vamp.h:242
_VampFeatureUnion::v2
VampFeatureV2 v2
Definition: vamp.h:213
_VampPluginDescriptor::getMaxChannelCount
unsigned int(* getMaxChannelCount)(VampPluginHandle)
Get the maximum number of input channels this plugin can handle.
Definition: vamp.h:324
_VampParameterDescriptor::unit
const char * unit
Human-readable unit of the parameter.
Definition: vamp.h:83
_VampPluginDescriptor::copyright
const char * copyright
Human-readable summary of copyright or licensing for plugin.
Definition: vamp.h:269
_VampOutputDescriptor::sampleType
VampSampleType sampleType
Time positioning method for returned results (see VampSampleType).
Definition: vamp.h:157
_VampFeatureV2
Definition: vamp.h:196
_VampOutputDescriptor::binCount
unsigned int binCount
Number of values per result, if hasFixedBinCount.
Definition: vamp.h:136
_VampOutputDescriptor::identifier
const char * identifier
Computer-usable name of the output.
Definition: vamp.h:121
_VampOutputDescriptor::quantizeStep
float quantizeStep
Quantization resolution for returned results, if isQuantized.
Definition: vamp.h:154
_VampFeature::sec
int sec
Seconds component of timestamp.
Definition: vamp.h:180
_VampPluginDescriptor::instantiate
VampPluginHandle(* instantiate)(const struct _VampPluginDescriptor *, float inputSampleRate)
Create and return a new instance of this plugin.
Definition: vamp.h:287
_VampOutputDescriptor::binNames
const char ** binNames
Names of returned value bins, if hasFixedBinCount.
Definition: vamp.h:139
_VampPluginDescriptor::releaseFeatureSet
void(* releaseFeatureSet)(VampFeatureList *)
Release a feature set returned from process or getRemainingFeatures.
Definition: vamp.h:353
_VampPluginDescriptor::programs
const char ** programs
Fixed names for programs.
Definition: vamp.h:281
VampOutputDescriptor
struct _VampOutputDescriptor VampOutputDescriptor
_VampParameterDescriptor::quantizeStep
float quantizeStep
Quantization resolution, if isQuantized.
Definition: vamp.h:98
_VampPluginDescriptor::parameterCount
unsigned int parameterCount
Number of parameter inputs.
Definition: vamp.h:272
_VampFeatureV2::hasDuration
int hasDuration
1 if the feature has a duration.
Definition: vamp.h:199
_VampPluginDescriptor::identifier
const char * identifier
Computer-usable name of the plugin.
Definition: vamp.h:254
_VampPluginDescriptor
Definition: vamp.h:248
_VampParameterDescriptor::isQuantized
int isQuantized
1 if parameter values are quantized to a particular resolution.
Definition: vamp.h:95
_VampFeatureUnion::v1
VampFeature v1
Definition: vamp.h:212
_VampFeature::hasTimestamp
int hasTimestamp
1 if the feature has a timestamp (i.e.
Definition: vamp.h:177
_VampPluginDescriptor::getCurrentProgram
unsigned int(* getCurrentProgram)(VampPluginHandle)
Get the current program (if programCount > 0).
Definition: vamp.h:309
_VampOutputDescriptor::unit
const char * unit
Human-readable name of the unit of the output.
Definition: vamp.h:130
_VampFeature
Definition: vamp.h:174
_VampPluginDescriptor::parameters
const VampParameterDescriptor ** parameters
Fixed descriptors for parameter inputs.
Definition: vamp.h:275
_VampFeatureV2::durationNsec
int durationNsec
Nanoseconds component of duration.
Definition: vamp.h:205
_VampFeature::valueCount
unsigned int valueCount
Number of values.
Definition: vamp.h:186
_VampPluginDescriptor::inputDomain
VampInputDomain inputDomain
Preferred input domain for audio input (time or frequency).
Definition: vamp.h:284
vampTimeDomain
@ vampTimeDomain
Definition: vamp.h:241
vampGetPluginDescriptor
const VampPluginDescriptor * vampGetPluginDescriptor(unsigned int hostApiVersion, unsigned int index)
Get the descriptor for a given plugin index in this library.
Definition: plugins.cpp:54
_VampParameterDescriptor::valueNames
const char ** valueNames
Human-readable names of the values, if isQuantized.
Definition: vamp.h:101
_VampPluginDescriptor::selectProgram
void(* selectProgram)(VampPluginHandle, unsigned int)
Set the current program.
Definition: vamp.h:312
_VampPluginDescriptor::getOutputCount
unsigned int(* getOutputCount)(VampPluginHandle)
Get the number of feature outputs (distinct sets of results).
Definition: vamp.h:327
_VampPluginDescriptor::cleanup
void(* cleanup)(VampPluginHandle)
Destroy an instance of this plugin.
Definition: vamp.h:291
VampFeature
struct _VampFeature VampFeature
VampPluginHandle
void * VampPluginHandle
Definition: vamp.h:246
_VampFeature::values
float * values
Values for this returned sample.
Definition: vamp.h:189
_VampFeatureList::features
VampFeatureUnion * features
Features in this feature list.
Definition: vamp.h:235
_VampParameterDescriptor::defaultValue
float defaultValue
Default value.
Definition: vamp.h:92
_VampParameterDescriptor
C language API for Vamp plugins.
Definition: vamp.h:71
vampVariableSampleRate
@ vampVariableSampleRate
Returned results have their own individual timestamps.
Definition: vamp.h:114
_VampOutputDescriptor::hasDuration
int hasDuration
1 if the returned results for this output are known to have a duration field.
Definition: vamp.h:170
_VampOutputDescriptor::isQuantized
int isQuantized
1 if returned results are quantized to a particular resolution.
Definition: vamp.h:151
_VampPluginDescriptor::initialise
int(* initialise)(VampPluginHandle, unsigned int inputChannels, unsigned int stepSize, unsigned int blockSize)
Initialise an instance following parameter configuration.
Definition: vamp.h:294
_VampOutputDescriptor::hasKnownExtents
int hasKnownExtents
1 if each returned value falls within the same fixed min/max range.
Definition: vamp.h:142
_VampFeatureList::featureCount
unsigned int featureCount
Number of features in this feature list.
Definition: vamp.h:220
_VampOutputDescriptor::name
const char * name
Human-readable name of the output.
Definition: vamp.h:124
_VampPluginDescriptor::vampApiVersion
unsigned int vampApiVersion
API version with which this descriptor is compatible.
Definition: vamp.h:251
_VampPluginDescriptor::setParameter
void(* setParameter)(VampPluginHandle, int, float)
Set a parameter value.
Definition: vamp.h:306
_VampOutputDescriptor
Definition: vamp.h:118
_VampFeatureList
Definition: vamp.h:217
vampFixedSampleRate
@ vampFixedSampleRate
Returned results are evenly spaced at samplerate specified below.
Definition: vamp.h:111
VampFeatureV2
struct _VampFeatureV2 VampFeatureV2
_VampPluginDescriptor::getPreferredStepSize
unsigned int(* getPreferredStepSize)(VampPluginHandle)
Get the plugin's preferred processing window increment in samples.
Definition: vamp.h:315
_VampPluginDescriptor::description
const char * description
Human-readable short text about the plugin.
Definition: vamp.h:260
_VampPluginDescriptor::name
const char * name
Human-readable name of the plugin.
Definition: vamp.h:257
_VampFeature::label
char * label
Label for this returned sample.
Definition: vamp.h:192
_VampPluginDescriptor::releaseOutputDescriptor
void(* releaseOutputDescriptor)(VampOutputDescriptor *)
Destroy a descriptor for a feature output.
Definition: vamp.h:337
VampFeatureList
struct _VampFeatureList VampFeatureList
_VampPluginDescriptor::getMinChannelCount
unsigned int(* getMinChannelCount)(VampPluginHandle)
Get the minimum number of input channels this plugin can handle.
Definition: vamp.h:321
VampPluginDescriptor
struct _VampPluginDescriptor VampPluginDescriptor
_VampParameterDescriptor::identifier
const char * identifier
Computer-usable name of the parameter.
Definition: vamp.h:74
VampInputDomain
VampInputDomain
Definition: vamp.h:239
_VampOutputDescriptor::description
const char * description
Human-readable short text about the output.
Definition: vamp.h:127
_VampOutputDescriptor::hasFixedBinCount
int hasFixedBinCount
1 if output has equal number of values for each returned result.
Definition: vamp.h:133
_VampPluginDescriptor::getParameter
float(* getParameter)(VampPluginHandle, int)
Get a parameter value.
Definition: vamp.h:303
_VampParameterDescriptor::maxValue
float maxValue
Maximum value.
Definition: vamp.h:89
_VampFeatureV2::durationSec
int durationSec
Seconds component of duratiion.
Definition: vamp.h:202
_VampPluginDescriptor::programCount
unsigned int programCount
Number of programs.
Definition: vamp.h:278
vampOneSamplePerStep
@ vampOneSamplePerStep
Each process call returns results aligned with call's block start.
Definition: vamp.h:108
_VampPluginDescriptor::reset
void(* reset)(VampPluginHandle)
Reset an instance, ready to use again on new input data.
Definition: vamp.h:300
VampFeatureUnion
union _VampFeatureUnion VampFeatureUnion
_VampParameterDescriptor::description
const char * description
Human-readable short text about the parameter.
Definition: vamp.h:80
_VampFeature::nsec
int nsec
Nanoseconds component of timestamp.
Definition: vamp.h:183
_VampPluginDescriptor::pluginVersion
int pluginVersion
Version number of the plugin.
Definition: vamp.h:266
_VampParameterDescriptor::name
const char * name
Human-readable name of the parameter.
Definition: vamp.h:77
VampParameterDescriptor
struct _VampParameterDescriptor VampParameterDescriptor
C language API for Vamp plugins.
_VampPluginDescriptor::maker
const char * maker
Human-readable name of plugin's author or vendor.
Definition: vamp.h:263
_VampOutputDescriptor::sampleRate
float sampleRate
Sample rate of returned results, if sampleType is vampFixedSampleRate.
Definition: vamp.h:161
_VampPluginDescriptor::getPreferredBlockSize
unsigned int(* getPreferredBlockSize)(VampPluginHandle)
Get the plugin's preferred processing window size in samples.
Definition: vamp.h:318
VampSampleType
VampSampleType
Definition: vamp.h:105
_VampParameterDescriptor::minValue
float minValue
Minimum value.
Definition: vamp.h:86
_VampOutputDescriptor::minValue
float minValue
Minimum value for a returned result in any bin, if hasKnownExtents.
Definition: vamp.h:145
_VampOutputDescriptor::maxValue
float maxValue
Maximum value for a returned result in any bin, if hasKnownExtents.
Definition: vamp.h:148
_VampFeatureUnion
Definition: vamp.h:209