cannam@0
|
1 /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*- vi:set ts=8 sts=4 sw=4: */
|
cannam@0
|
2
|
cannam@0
|
3 /*
|
cannam@0
|
4 Vamp
|
cannam@0
|
5
|
cannam@0
|
6 An API for audio analysis and feature extraction plugins.
|
cannam@0
|
7
|
cannam@0
|
8 Centre for Digital Music, Queen Mary, University of London.
|
cannam@0
|
9 Copyright 2006 Chris Cannam.
|
cannam@0
|
10
|
cannam@0
|
11 Permission is hereby granted, free of charge, to any person
|
cannam@0
|
12 obtaining a copy of this software and associated documentation
|
cannam@0
|
13 files (the "Software"), to deal in the Software without
|
cannam@0
|
14 restriction, including without limitation the rights to use, copy,
|
cannam@0
|
15 modify, merge, publish, distribute, sublicense, and/or sell copies
|
cannam@0
|
16 of the Software, and to permit persons to whom the Software is
|
cannam@0
|
17 furnished to do so, subject to the following conditions:
|
cannam@0
|
18
|
cannam@0
|
19 The above copyright notice and this permission notice shall be
|
cannam@0
|
20 included in all copies or substantial portions of the Software.
|
cannam@0
|
21
|
cannam@0
|
22 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
cannam@0
|
23 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
cannam@0
|
24 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
cannam@6
|
25 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
|
cannam@0
|
26 ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
|
cannam@0
|
27 CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
cannam@0
|
28 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
cannam@0
|
29
|
cannam@0
|
30 Except as contained in this notice, the names of the Centre for
|
cannam@0
|
31 Digital Music; Queen Mary, University of London; and Chris Cannam
|
cannam@0
|
32 shall not be used in advertising or otherwise to promote the sale,
|
cannam@0
|
33 use or other dealings in this Software without prior written
|
cannam@0
|
34 authorization.
|
cannam@0
|
35 */
|
cannam@0
|
36
|
cannam@0
|
37 #ifndef VAMP_HEADER_INCLUDED
|
cannam@0
|
38 #define VAMP_HEADER_INCLUDED
|
cannam@0
|
39
|
cannam@0
|
40 /*
|
cannam@0
|
41 * C language API for Vamp plugins.
|
cannam@0
|
42 *
|
cannam@0
|
43 * This is the formal plugin API for Vamp. Plugin authors may prefer
|
cannam@18
|
44 * to use the C++ classes provided in the Vamp plugin SDK, instead of
|
cannam@0
|
45 * using this API directly. There is an adapter class provided that
|
cannam@0
|
46 * makes C++ plugins available using this C API with relatively little
|
cannam@24
|
47 * work, and the C++ headers are more thoroughly documented.
|
cannam@24
|
48 *
|
cannam@24
|
49 * IMPORTANT: The comments in this file summarise the purpose of each
|
cannam@24
|
50 * of the declared fields and functions, but do not provide a complete
|
cannam@24
|
51 * guide to their permitted values and expected usage. Please refer
|
cannam@24
|
52 * to the C++ headers in the Vamp plugin SDK for further details and
|
cannam@24
|
53 * plugin lifecycle documentation.
|
cannam@0
|
54 */
|
cannam@0
|
55
|
cannam@0
|
56 #ifdef __cplusplus
|
cannam@0
|
57 extern "C" {
|
cannam@0
|
58 #endif
|
cannam@0
|
59
|
cannam@18
|
60 /**
|
cannam@18
|
61 * Plugin API version. Incompatible changes to the API may be expected
|
cannam@18
|
62 * prior to version 1.0.
|
cannam@18
|
63 */
|
cannam@43
|
64 #define VAMP_API_VERSION "1.0"
|
cannam@43
|
65 #define VAMP_API_VERSION_MAJOR 1
|
cannam@43
|
66 #define VAMP_API_VERSION_MINOR 0
|
cannam@18
|
67
|
cannam@0
|
68 typedef struct _VampParameterDescriptor
|
cannam@0
|
69 {
|
cannam@24
|
70 /** Computer-usable name of the parameter. Must not change. [a-zA-Z0-9_] */
|
cannam@49
|
71 const char *identifier;
|
cannam@49
|
72
|
cannam@49
|
73 /** Human-readable name of the parameter. May be translatable. */
|
cannam@0
|
74 const char *name;
|
cannam@24
|
75
|
cannam@49
|
76 /** Human-readable short text about the parameter. May be translatable. */
|
cannam@0
|
77 const char *description;
|
cannam@24
|
78
|
cannam@24
|
79 /** Human-readable unit of the parameter. */
|
cannam@0
|
80 const char *unit;
|
cannam@24
|
81
|
cannam@24
|
82 /** Minimum value. */
|
cannam@0
|
83 float minValue;
|
cannam@24
|
84
|
cannam@24
|
85 /** Maximum value. */
|
cannam@0
|
86 float maxValue;
|
cannam@24
|
87
|
cannam@24
|
88 /** Default value. Plugin is responsible for setting this on initialise. */
|
cannam@0
|
89 float defaultValue;
|
cannam@24
|
90
|
cannam@24
|
91 /** 1 if parameter values are quantized to a particular resolution. */
|
cannam@0
|
92 int isQuantized;
|
cannam@24
|
93
|
cannam@24
|
94 /** Quantization resolution, if isQuantized. */
|
cannam@0
|
95 float quantizeStep;
|
cannam@24
|
96
|
cannam@24
|
97 /** Human-readable names of the values, if isQuantized. May be NULL. */
|
cannam@9
|
98 const char **valueNames;
|
cannam@0
|
99
|
cannam@0
|
100 } VampParameterDescriptor;
|
cannam@0
|
101
|
cannam@0
|
102 typedef enum
|
cannam@0
|
103 {
|
cannam@24
|
104 /** Each process call returns results aligned with call's block start. */
|
cannam@0
|
105 vampOneSamplePerStep,
|
cannam@24
|
106
|
cannam@24
|
107 /** Returned results are evenly spaced at samplerate specified below. */
|
cannam@0
|
108 vampFixedSampleRate,
|
cannam@24
|
109
|
cannam@24
|
110 /** Returned results have their own individual timestamps. */
|
cannam@0
|
111 vampVariableSampleRate
|
cannam@0
|
112
|
cannam@0
|
113 } VampSampleType;
|
cannam@0
|
114
|
cannam@0
|
115 typedef struct _VampOutputDescriptor
|
cannam@0
|
116 {
|
cannam@24
|
117 /** Computer-usable name of the output. Must not change. [a-zA-Z0-9_] */
|
cannam@49
|
118 const char *identifier;
|
cannam@49
|
119
|
cannam@49
|
120 /** Human-readable name of the output. May be translatable. */
|
cannam@0
|
121 const char *name;
|
cannam@24
|
122
|
cannam@49
|
123 /** Human-readable short text about the output. May be translatable. */
|
cannam@0
|
124 const char *description;
|
cannam@24
|
125
|
cannam@24
|
126 /** Human-readable name of the unit of the output. */
|
cannam@0
|
127 const char *unit;
|
cannam@24
|
128
|
cannam@24
|
129 /** 1 if output has equal number of values for each returned result. */
|
cannam@9
|
130 int hasFixedBinCount;
|
cannam@24
|
131
|
cannam@24
|
132 /** Number of values per result, if hasFixedBinCount. */
|
cannam@9
|
133 unsigned int binCount;
|
cannam@24
|
134
|
cannam@24
|
135 /** Names of returned value bins, if hasFixedBinCount. May be NULL. */
|
cannam@9
|
136 const char **binNames;
|
cannam@24
|
137
|
cannam@24
|
138 /** 1 if each returned value falls within the same fixed min/max range. */
|
cannam@0
|
139 int hasKnownExtents;
|
cannam@24
|
140
|
cannam@24
|
141 /** Minimum value for a returned result in any bin, if hasKnownExtents. */
|
cannam@0
|
142 float minValue;
|
cannam@24
|
143
|
cannam@24
|
144 /** Maximum value for a returned result in any bin, if hasKnownExtents. */
|
cannam@0
|
145 float maxValue;
|
cannam@24
|
146
|
cannam@24
|
147 /** 1 if returned results are quantized to a particular resolution. */
|
cannam@0
|
148 int isQuantized;
|
cannam@24
|
149
|
cannam@24
|
150 /** Quantization resolution for returned results, if isQuantized. */
|
cannam@0
|
151 float quantizeStep;
|
cannam@24
|
152
|
cannam@24
|
153 /** Time positioning method for returned results (see VampSampleType). */
|
cannam@0
|
154 VampSampleType sampleType;
|
cannam@24
|
155
|
cannam@24
|
156 /** Sample rate of returned results, if sampleType is vampFixedSampleRate.
|
cannam@24
|
157 "Resolution" of result, if sampleType is vampVariableSampleRate. */
|
cannam@0
|
158 float sampleRate;
|
cannam@0
|
159
|
cannam@0
|
160 } VampOutputDescriptor;
|
cannam@0
|
161
|
cannam@0
|
162 typedef struct _VampFeature
|
cannam@0
|
163 {
|
cannam@24
|
164 /** 1 if the feature has a timestamp (i.e. if vampVariableSampleRate). */
|
cannam@0
|
165 int hasTimestamp;
|
cannam@24
|
166
|
cannam@24
|
167 /** Seconds component of timestamp. */
|
cannam@0
|
168 int sec;
|
cannam@24
|
169
|
cannam@24
|
170 /** Nanoseconds component of timestamp. */
|
cannam@0
|
171 int nsec;
|
cannam@24
|
172
|
cannam@24
|
173 /** Number of values. Must be binCount if hasFixedBinCount. */
|
cannam@0
|
174 unsigned int valueCount;
|
cannam@24
|
175
|
cannam@24
|
176 /** Values for this returned sample. */
|
cannam@0
|
177 float *values;
|
cannam@24
|
178
|
cannam@24
|
179 /** Label for this returned sample. May be NULL. */
|
cannam@0
|
180 char *label;
|
cannam@0
|
181
|
cannam@0
|
182 } VampFeature;
|
cannam@0
|
183
|
cannam@0
|
184 typedef struct _VampFeatureList
|
cannam@0
|
185 {
|
cannam@24
|
186 /** Number of features in this feature list. */
|
cannam@0
|
187 unsigned int featureCount;
|
cannam@24
|
188
|
cannam@24
|
189 /** Features in this feature list. May be NULL if featureCount is zero. */
|
cannam@0
|
190 VampFeature *features;
|
cannam@0
|
191
|
cannam@0
|
192 } VampFeatureList;
|
cannam@0
|
193
|
cannam@0
|
194 typedef enum
|
cannam@0
|
195 {
|
cannam@0
|
196 vampTimeDomain,
|
cannam@0
|
197 vampFrequencyDomain
|
cannam@0
|
198
|
cannam@0
|
199 } VampInputDomain;
|
cannam@0
|
200
|
cannam@0
|
201 typedef void *VampPluginHandle;
|
cannam@0
|
202
|
cannam@0
|
203 typedef struct _VampPluginDescriptor
|
cannam@0
|
204 {
|
cannam@24
|
205 /** Computer-usable name of the plugin. Must not change. [a-zA-Z0-9_] */
|
cannam@49
|
206 const char *identifier;
|
cannam@49
|
207
|
cannam@49
|
208 /** Human-readable name of the plugin. May be translatable. */
|
cannam@0
|
209 const char *name;
|
cannam@24
|
210
|
cannam@49
|
211 /** Human-readable short text about the plugin. May be translatable. */
|
cannam@0
|
212 const char *description;
|
cannam@24
|
213
|
cannam@24
|
214 /** Human-readable name of plugin's author or vendor. */
|
cannam@0
|
215 const char *maker;
|
cannam@24
|
216
|
cannam@24
|
217 /** Version number of the plugin. */
|
cannam@0
|
218 int pluginVersion;
|
cannam@24
|
219
|
cannam@24
|
220 /** Human-readable summary of copyright or licensing for plugin. */
|
cannam@0
|
221 const char *copyright;
|
cannam@24
|
222
|
cannam@24
|
223 /** Number of parameter inputs. */
|
cannam@0
|
224 unsigned int parameterCount;
|
cannam@24
|
225
|
cannam@24
|
226 /** Fixed descriptors for parameter inputs. */
|
cannam@0
|
227 const VampParameterDescriptor **parameters;
|
cannam@24
|
228
|
cannam@24
|
229 /** Number of programs. */
|
cannam@0
|
230 unsigned int programCount;
|
cannam@24
|
231
|
cannam@24
|
232 /** Fixed names for programs. */
|
cannam@0
|
233 const char **programs;
|
cannam@24
|
234
|
cannam@24
|
235 /** Preferred input domain for audio input (time or frequency). */
|
cannam@0
|
236 VampInputDomain inputDomain;
|
cannam@24
|
237
|
cannam@24
|
238 /** Create and return a new instance of this plugin. */
|
cannam@0
|
239 VampPluginHandle (*instantiate)(const struct _VampPluginDescriptor *,
|
cannam@0
|
240 float inputSampleRate);
|
cannam@0
|
241
|
cannam@24
|
242 /** Destroy an instance of this plugin. */
|
cannam@0
|
243 void (*cleanup)(VampPluginHandle);
|
cannam@0
|
244
|
cannam@24
|
245 /** Initialise an instance following parameter configuration. */
|
cannam@0
|
246 int (*initialise)(VampPluginHandle,
|
cannam@0
|
247 unsigned int inputChannels,
|
cannam@0
|
248 unsigned int stepSize,
|
cannam@0
|
249 unsigned int blockSize);
|
cannam@0
|
250
|
cannam@24
|
251 /** Reset an instance, ready to use again on new input data. */
|
cannam@0
|
252 void (*reset)(VampPluginHandle);
|
cannam@0
|
253
|
cannam@24
|
254 /** Get a parameter value. */
|
cannam@0
|
255 float (*getParameter)(VampPluginHandle, int);
|
cannam@24
|
256
|
cannam@24
|
257 /** Set a parameter value. May only be called before initialise. */
|
cannam@0
|
258 void (*setParameter)(VampPluginHandle, int, float);
|
cannam@0
|
259
|
cannam@24
|
260 /** Get the current program (if programCount > 0). */
|
cannam@0
|
261 unsigned int (*getCurrentProgram)(VampPluginHandle);
|
cannam@24
|
262
|
cannam@24
|
263 /** Set the current program. May only be called before initialise. */
|
cannam@0
|
264 void (*selectProgram)(VampPluginHandle, unsigned int);
|
cannam@0
|
265
|
cannam@24
|
266 /** Get the plugin's preferred processing window increment in samples. */
|
cannam@0
|
267 unsigned int (*getPreferredStepSize)(VampPluginHandle);
|
cannam@24
|
268
|
cannam@24
|
269 /** Get the plugin's preferred processing window size in samples. */
|
cannam@0
|
270 unsigned int (*getPreferredBlockSize)(VampPluginHandle);
|
cannam@24
|
271
|
cannam@24
|
272 /** Get the minimum number of input channels this plugin can handle. */
|
cannam@0
|
273 unsigned int (*getMinChannelCount)(VampPluginHandle);
|
cannam@24
|
274
|
cannam@24
|
275 /** Get the maximum number of input channels this plugin can handle. */
|
cannam@0
|
276 unsigned int (*getMaxChannelCount)(VampPluginHandle);
|
cannam@0
|
277
|
cannam@24
|
278 /** Get the number of feature outputs (distinct sets of results). */
|
cannam@0
|
279 unsigned int (*getOutputCount)(VampPluginHandle);
|
cannam@24
|
280
|
cannam@24
|
281 /** Get a descriptor for a given feature output. Returned pointer
|
cannam@24
|
282 is valid only until next call to getOutputDescriptor for this
|
cannam@24
|
283 handle, or releaseOutputDescriptor for this descriptor. Host
|
cannam@24
|
284 must call releaseOutputDescriptor after use. */
|
cannam@0
|
285 VampOutputDescriptor *(*getOutputDescriptor)(VampPluginHandle,
|
cannam@0
|
286 unsigned int);
|
cannam@24
|
287
|
cannam@24
|
288 /** Destroy a descriptor for a feature output. */
|
cannam@0
|
289 void (*releaseOutputDescriptor)(VampOutputDescriptor *);
|
cannam@0
|
290
|
cannam@24
|
291 /** Process an input block and return a set of features. Returned
|
cannam@24
|
292 pointer is valid only until next call to process,
|
cannam@24
|
293 getRemainingFeatures, or cleanup for this handle, or
|
cannam@24
|
294 releaseFeatureSet for this feature set. Host must call
|
cannam@24
|
295 releaseFeatureSet after use. */
|
cannam@12
|
296 VampFeatureList *(*process)(VampPluginHandle,
|
cannam@47
|
297 const float *const *inputBuffers,
|
cannam@0
|
298 int sec,
|
cannam@0
|
299 int nsec);
|
cannam@24
|
300
|
cannam@24
|
301 /** Return any remaining features at the end of processing. */
|
cannam@12
|
302 VampFeatureList *(*getRemainingFeatures)(VampPluginHandle);
|
cannam@24
|
303
|
cannam@24
|
304 /** Release a feature set returned from process or getRemainingFeatures. */
|
cannam@12
|
305 void (*releaseFeatureSet)(VampFeatureList *);
|
cannam@0
|
306
|
cannam@0
|
307 } VampPluginDescriptor;
|
cannam@0
|
308
|
cannam@24
|
309 /** Get the descriptor for a given plugin index in this library.
|
cannam@24
|
310 Return NULL if the index is outside the range of valid indices for
|
cannam@24
|
311 this plugin library. */
|
cannam@0
|
312 const VampPluginDescriptor *vampGetPluginDescriptor(unsigned int index);
|
cannam@0
|
313
|
cannam@24
|
314 /** Function pointer type for vampGetPluginDescriptor. */
|
cannam@0
|
315 typedef const VampPluginDescriptor *(*VampGetPluginDescriptorFunction)(unsigned int);
|
cannam@0
|
316
|
cannam@0
|
317 #ifdef __cplusplus
|
cannam@0
|
318 }
|
cannam@0
|
319 #endif
|
cannam@0
|
320
|
cannam@0
|
321 #endif
|