annotate vamp/vamp.h @ 180:9a58bd07aa4d

* Part way to providing support for continuous-time averaging summaries
author cannam
date Wed, 03 Sep 2008 15:59:09 +0000
parents 006a775133b1
children d4fbd4e6fdbf
rev   line source
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@54 40 #ifdef __cplusplus
cannam@54 41 extern "C" {
cannam@54 42 #endif
cannam@54 43
cannam@54 44 /**
cannam@54 45 * Plugin API version. This is incremented when a change is made that
cannam@54 46 * changes the binary layout of the descriptor records. When this
cannam@54 47 * happens, there should be a mechanism for retaining compatibility
cannam@54 48 * with older hosts and/or plugins.
cannam@54 49 *
cannam@54 50 * See also the vampApiVersion field in the plugin descriptor, and the
cannam@54 51 * hostApiVersion argument to the vampGetPluginDescriptor function.
cannam@54 52 */
cannam@167 53 #define VAMP_API_VERSION 2
cannam@54 54
cannam@54 55 /**
cannam@0 56 * C language API for Vamp plugins.
cannam@0 57 *
cannam@0 58 * This is the formal plugin API for Vamp. Plugin authors may prefer
cannam@18 59 * to use the C++ classes provided in the Vamp plugin SDK, instead of
cannam@0 60 * using this API directly. There is an adapter class provided that
cannam@0 61 * makes C++ plugins available using this C API with relatively little
cannam@24 62 * work, and the C++ headers are more thoroughly documented.
cannam@24 63 *
cannam@24 64 * IMPORTANT: The comments in this file summarise the purpose of each
cannam@24 65 * of the declared fields and functions, but do not provide a complete
cannam@24 66 * guide to their permitted values and expected usage. Please refer
cannam@24 67 * to the C++ headers in the Vamp plugin SDK for further details and
cannam@24 68 * plugin lifecycle documentation.
cannam@0 69 */
cannam@0 70
cannam@0 71 typedef struct _VampParameterDescriptor
cannam@0 72 {
cannam@24 73 /** Computer-usable name of the parameter. Must not change. [a-zA-Z0-9_] */
cannam@49 74 const char *identifier;
cannam@49 75
cannam@49 76 /** Human-readable name of the parameter. May be translatable. */
cannam@0 77 const char *name;
cannam@24 78
cannam@49 79 /** Human-readable short text about the parameter. May be translatable. */
cannam@0 80 const char *description;
cannam@24 81
cannam@24 82 /** Human-readable unit of the parameter. */
cannam@0 83 const char *unit;
cannam@24 84
cannam@24 85 /** Minimum value. */
cannam@0 86 float minValue;
cannam@24 87
cannam@24 88 /** Maximum value. */
cannam@0 89 float maxValue;
cannam@24 90
cannam@24 91 /** Default value. Plugin is responsible for setting this on initialise. */
cannam@0 92 float defaultValue;
cannam@24 93
cannam@24 94 /** 1 if parameter values are quantized to a particular resolution. */
cannam@0 95 int isQuantized;
cannam@24 96
cannam@24 97 /** Quantization resolution, if isQuantized. */
cannam@0 98 float quantizeStep;
cannam@24 99
cannam@24 100 /** Human-readable names of the values, if isQuantized. May be NULL. */
cannam@9 101 const char **valueNames;
cannam@0 102
cannam@0 103 } VampParameterDescriptor;
cannam@0 104
cannam@0 105 typedef enum
cannam@0 106 {
cannam@24 107 /** Each process call returns results aligned with call's block start. */
cannam@0 108 vampOneSamplePerStep,
cannam@24 109
cannam@24 110 /** Returned results are evenly spaced at samplerate specified below. */
cannam@0 111 vampFixedSampleRate,
cannam@24 112
cannam@24 113 /** Returned results have their own individual timestamps. */
cannam@0 114 vampVariableSampleRate
cannam@0 115
cannam@0 116 } VampSampleType;
cannam@0 117
cannam@0 118 typedef struct _VampOutputDescriptor
cannam@0 119 {
cannam@24 120 /** Computer-usable name of the output. Must not change. [a-zA-Z0-9_] */
cannam@49 121 const char *identifier;
cannam@49 122
cannam@49 123 /** Human-readable name of the output. May be translatable. */
cannam@0 124 const char *name;
cannam@24 125
cannam@49 126 /** Human-readable short text about the output. May be translatable. */
cannam@0 127 const char *description;
cannam@24 128
cannam@24 129 /** Human-readable name of the unit of the output. */
cannam@0 130 const char *unit;
cannam@24 131
cannam@24 132 /** 1 if output has equal number of values for each returned result. */
cannam@9 133 int hasFixedBinCount;
cannam@24 134
cannam@24 135 /** Number of values per result, if hasFixedBinCount. */
cannam@9 136 unsigned int binCount;
cannam@24 137
cannam@24 138 /** Names of returned value bins, if hasFixedBinCount. May be NULL. */
cannam@9 139 const char **binNames;
cannam@24 140
cannam@24 141 /** 1 if each returned value falls within the same fixed min/max range. */
cannam@0 142 int hasKnownExtents;
cannam@24 143
cannam@24 144 /** Minimum value for a returned result in any bin, if hasKnownExtents. */
cannam@0 145 float minValue;
cannam@24 146
cannam@24 147 /** Maximum value for a returned result in any bin, if hasKnownExtents. */
cannam@0 148 float maxValue;
cannam@24 149
cannam@24 150 /** 1 if returned results are quantized to a particular resolution. */
cannam@0 151 int isQuantized;
cannam@24 152
cannam@24 153 /** Quantization resolution for returned results, if isQuantized. */
cannam@0 154 float quantizeStep;
cannam@24 155
cannam@24 156 /** Time positioning method for returned results (see VampSampleType). */
cannam@0 157 VampSampleType sampleType;
cannam@24 158
cannam@24 159 /** Sample rate of returned results, if sampleType is vampFixedSampleRate.
cannam@24 160 "Resolution" of result, if sampleType is vampVariableSampleRate. */
cannam@0 161 float sampleRate;
cannam@0 162
cannam@0 163 } VampOutputDescriptor;
cannam@0 164
cannam@0 165 typedef struct _VampFeature
cannam@0 166 {
cannam@24 167 /** 1 if the feature has a timestamp (i.e. if vampVariableSampleRate). */
cannam@0 168 int hasTimestamp;
cannam@24 169
cannam@24 170 /** Seconds component of timestamp. */
cannam@0 171 int sec;
cannam@24 172
cannam@24 173 /** Nanoseconds component of timestamp. */
cannam@0 174 int nsec;
cannam@24 175
cannam@24 176 /** Number of values. Must be binCount if hasFixedBinCount. */
cannam@0 177 unsigned int valueCount;
cannam@24 178
cannam@24 179 /** Values for this returned sample. */
cannam@0 180 float *values;
cannam@24 181
cannam@24 182 /** Label for this returned sample. May be NULL. */
cannam@0 183 char *label;
cannam@0 184
cannam@0 185 } VampFeature;
cannam@0 186
cannam@167 187 typedef struct _VampFeatureV2
cannam@167 188 {
cannam@167 189 /** 1 if the feature has a duration. */
cannam@167 190 int hasDuration;
cannam@167 191
cannam@167 192 /** Seconds component of duratiion. */
cannam@167 193 int durationSec;
cannam@167 194
cannam@167 195 /** Nanoseconds component of duration. */
cannam@167 196 int durationNsec;
cannam@167 197
cannam@167 198 } VampFeatureV2;
cannam@167 199
cannam@168 200 typedef union _VampFeatureUnion
cannam@168 201 {
cannam@168 202 // sizeof(featureV1) >= sizeof(featureV2) for backward compatibility
cannam@168 203 VampFeature v1;
cannam@168 204 VampFeatureV2 v2;
cannam@168 205
cannam@168 206 } VampFeatureUnion;
cannam@168 207
cannam@0 208 typedef struct _VampFeatureList
cannam@0 209 {
cannam@24 210 /** Number of features in this feature list. */
cannam@0 211 unsigned int featureCount;
cannam@24 212
cannam@168 213 /** Features in this feature list. May be NULL if featureCount is
cannam@168 214 zero.
cannam@0 215
cannam@168 216 If present, this array must contain featureCount feature
cannam@168 217 structures for a Vamp 1.0 plugin, or 2*featureCount feature
cannam@168 218 unions for a Vamp 2.0 plugin.
cannam@168 219
cannam@168 220 The features returned by a Vamp 2.0 plugin must consist of the
cannam@168 221 same feature structures as in 1.0 for the first featureCount
cannam@168 222 array elements, followed by featureCount unions that contain
cannam@168 223 pointers to V2 feature structures (or NULL pointers if no V2
cannam@168 224 feature structures are present).
cannam@168 225 */
cannam@168 226 VampFeatureUnion *features;
cannam@167 227
cannam@0 228 } VampFeatureList;
cannam@0 229
cannam@0 230 typedef enum
cannam@0 231 {
cannam@0 232 vampTimeDomain,
cannam@0 233 vampFrequencyDomain
cannam@0 234
cannam@0 235 } VampInputDomain;
cannam@0 236
cannam@0 237 typedef void *VampPluginHandle;
cannam@0 238
cannam@0 239 typedef struct _VampPluginDescriptor
cannam@0 240 {
cannam@50 241 /** API version with which this descriptor is compatible. */
cannam@50 242 unsigned int vampApiVersion;
cannam@50 243
cannam@24 244 /** Computer-usable name of the plugin. Must not change. [a-zA-Z0-9_] */
cannam@49 245 const char *identifier;
cannam@49 246
cannam@49 247 /** Human-readable name of the plugin. May be translatable. */
cannam@0 248 const char *name;
cannam@24 249
cannam@49 250 /** Human-readable short text about the plugin. May be translatable. */
cannam@0 251 const char *description;
cannam@24 252
cannam@24 253 /** Human-readable name of plugin's author or vendor. */
cannam@0 254 const char *maker;
cannam@24 255
cannam@24 256 /** Version number of the plugin. */
cannam@0 257 int pluginVersion;
cannam@24 258
cannam@24 259 /** Human-readable summary of copyright or licensing for plugin. */
cannam@0 260 const char *copyright;
cannam@24 261
cannam@24 262 /** Number of parameter inputs. */
cannam@0 263 unsigned int parameterCount;
cannam@24 264
cannam@24 265 /** Fixed descriptors for parameter inputs. */
cannam@0 266 const VampParameterDescriptor **parameters;
cannam@24 267
cannam@24 268 /** Number of programs. */
cannam@0 269 unsigned int programCount;
cannam@24 270
cannam@24 271 /** Fixed names for programs. */
cannam@0 272 const char **programs;
cannam@24 273
cannam@24 274 /** Preferred input domain for audio input (time or frequency). */
cannam@0 275 VampInputDomain inputDomain;
cannam@24 276
cannam@24 277 /** Create and return a new instance of this plugin. */
cannam@0 278 VampPluginHandle (*instantiate)(const struct _VampPluginDescriptor *,
cannam@0 279 float inputSampleRate);
cannam@0 280
cannam@24 281 /** Destroy an instance of this plugin. */
cannam@0 282 void (*cleanup)(VampPluginHandle);
cannam@0 283
cannam@24 284 /** Initialise an instance following parameter configuration. */
cannam@0 285 int (*initialise)(VampPluginHandle,
cannam@0 286 unsigned int inputChannels,
cannam@0 287 unsigned int stepSize,
cannam@0 288 unsigned int blockSize);
cannam@0 289
cannam@24 290 /** Reset an instance, ready to use again on new input data. */
cannam@0 291 void (*reset)(VampPluginHandle);
cannam@0 292
cannam@24 293 /** Get a parameter value. */
cannam@0 294 float (*getParameter)(VampPluginHandle, int);
cannam@24 295
cannam@24 296 /** Set a parameter value. May only be called before initialise. */
cannam@0 297 void (*setParameter)(VampPluginHandle, int, float);
cannam@0 298
cannam@24 299 /** Get the current program (if programCount > 0). */
cannam@0 300 unsigned int (*getCurrentProgram)(VampPluginHandle);
cannam@24 301
cannam@24 302 /** Set the current program. May only be called before initialise. */
cannam@0 303 void (*selectProgram)(VampPluginHandle, unsigned int);
cannam@0 304
cannam@24 305 /** Get the plugin's preferred processing window increment in samples. */
cannam@0 306 unsigned int (*getPreferredStepSize)(VampPluginHandle);
cannam@24 307
cannam@24 308 /** Get the plugin's preferred processing window size in samples. */
cannam@0 309 unsigned int (*getPreferredBlockSize)(VampPluginHandle);
cannam@24 310
cannam@24 311 /** Get the minimum number of input channels this plugin can handle. */
cannam@0 312 unsigned int (*getMinChannelCount)(VampPluginHandle);
cannam@24 313
cannam@24 314 /** Get the maximum number of input channels this plugin can handle. */
cannam@0 315 unsigned int (*getMaxChannelCount)(VampPluginHandle);
cannam@0 316
cannam@24 317 /** Get the number of feature outputs (distinct sets of results). */
cannam@0 318 unsigned int (*getOutputCount)(VampPluginHandle);
cannam@24 319
cannam@24 320 /** Get a descriptor for a given feature output. Returned pointer
cannam@24 321 is valid only until next call to getOutputDescriptor for this
cannam@24 322 handle, or releaseOutputDescriptor for this descriptor. Host
cannam@24 323 must call releaseOutputDescriptor after use. */
cannam@0 324 VampOutputDescriptor *(*getOutputDescriptor)(VampPluginHandle,
cannam@0 325 unsigned int);
cannam@24 326
cannam@24 327 /** Destroy a descriptor for a feature output. */
cannam@0 328 void (*releaseOutputDescriptor)(VampOutputDescriptor *);
cannam@0 329
cannam@24 330 /** Process an input block and return a set of features. Returned
cannam@24 331 pointer is valid only until next call to process,
cannam@24 332 getRemainingFeatures, or cleanup for this handle, or
cannam@24 333 releaseFeatureSet for this feature set. Host must call
cannam@24 334 releaseFeatureSet after use. */
cannam@12 335 VampFeatureList *(*process)(VampPluginHandle,
cannam@47 336 const float *const *inputBuffers,
cannam@0 337 int sec,
cannam@0 338 int nsec);
cannam@24 339
cannam@24 340 /** Return any remaining features at the end of processing. */
cannam@12 341 VampFeatureList *(*getRemainingFeatures)(VampPluginHandle);
cannam@24 342
cannam@24 343 /** Release a feature set returned from process or getRemainingFeatures. */
cannam@12 344 void (*releaseFeatureSet)(VampFeatureList *);
cannam@0 345
cannam@0 346 } VampPluginDescriptor;
cannam@0 347
cannam@160 348
cannam@24 349 /** Get the descriptor for a given plugin index in this library.
cannam@24 350 Return NULL if the index is outside the range of valid indices for
cannam@50 351 this plugin library.
cannam@50 352
cannam@50 353 The hostApiVersion argument tells the library code the highest
cannam@50 354 Vamp API version supported by the host. The function should
cannam@50 355 return a plugin descriptor compatible with the highest API version
cannam@50 356 supported by the library that is no higher than that supported by
cannam@50 357 the host. Provided the descriptor has the correct vampApiVersion
cannam@50 358 field for its actual compatibility level, the host should be able
cannam@50 359 to do the right thing with it: use it if possible, discard it
cannam@50 360 otherwise.
cannam@160 361
cannam@160 362 This is the only symbol that a Vamp plugin actually needs to
cannam@160 363 export from its shared object; all others can be hidden. See the
cannam@160 364 accompanying documentation for notes on how to achieve this with
cannam@160 365 certain compilers.
cannam@50 366 */
cannam@50 367 const VampPluginDescriptor *vampGetPluginDescriptor
cannam@50 368 (unsigned int hostApiVersion, unsigned int index);
cannam@0 369
cannam@160 370
cannam@24 371 /** Function pointer type for vampGetPluginDescriptor. */
cannam@50 372 typedef const VampPluginDescriptor *(*VampGetPluginDescriptorFunction)
cannam@50 373 (unsigned int, unsigned int);
cannam@0 374
cannam@0 375 #ifdef __cplusplus
cannam@0 376 }
cannam@0 377 #endif
cannam@0 378
cannam@0 379 #endif