annotate vamp/vamp.h @ 541:0e32c328b02a tip

Added tag vamp-plugin-sdk-v2.10 for changeset fa74c473e48c
author Chris Cannam
date Mon, 18 May 2020 11:53:49 +0100
parents 8701366604c7
children
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 {
Chris@481 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 {
Chris@481 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@192 163 /** 1 if the returned results for this output are known to have a
cannam@192 164 duration field.
cannam@192 165
cannam@192 166 This field is new in Vamp API version 2; it must not be tested
cannam@192 167 for plugins that report an older API version in their plugin
cannam@192 168 descriptor.
cannam@192 169 */
cannam@192 170 int hasDuration;
cannam@192 171
cannam@0 172 } VampOutputDescriptor;
cannam@0 173
cannam@0 174 typedef struct _VampFeature
cannam@0 175 {
cannam@24 176 /** 1 if the feature has a timestamp (i.e. if vampVariableSampleRate). */
cannam@0 177 int hasTimestamp;
cannam@24 178
cannam@24 179 /** Seconds component of timestamp. */
cannam@0 180 int sec;
cannam@24 181
cannam@24 182 /** Nanoseconds component of timestamp. */
cannam@0 183 int nsec;
cannam@24 184
cannam@24 185 /** Number of values. Must be binCount if hasFixedBinCount. */
cannam@0 186 unsigned int valueCount;
cannam@24 187
cannam@24 188 /** Values for this returned sample. */
cannam@0 189 float *values;
cannam@24 190
cannam@24 191 /** Label for this returned sample. May be NULL. */
cannam@0 192 char *label;
cannam@0 193
cannam@0 194 } VampFeature;
cannam@0 195
cannam@167 196 typedef struct _VampFeatureV2
cannam@167 197 {
cannam@167 198 /** 1 if the feature has a duration. */
cannam@167 199 int hasDuration;
cannam@167 200
cannam@167 201 /** Seconds component of duratiion. */
cannam@167 202 int durationSec;
cannam@167 203
cannam@167 204 /** Nanoseconds component of duration. */
cannam@167 205 int durationNsec;
cannam@167 206
cannam@167 207 } VampFeatureV2;
cannam@167 208
cannam@168 209 typedef union _VampFeatureUnion
cannam@168 210 {
cannam@168 211 // sizeof(featureV1) >= sizeof(featureV2) for backward compatibility
cannam@168 212 VampFeature v1;
cannam@168 213 VampFeatureV2 v2;
cannam@168 214
cannam@168 215 } VampFeatureUnion;
cannam@168 216
cannam@0 217 typedef struct _VampFeatureList
cannam@0 218 {
cannam@24 219 /** Number of features in this feature list. */
cannam@0 220 unsigned int featureCount;
cannam@24 221
cannam@168 222 /** Features in this feature list. May be NULL if featureCount is
cannam@168 223 zero.
cannam@0 224
cannam@168 225 If present, this array must contain featureCount feature
cannam@192 226 structures for a Vamp API version 1 plugin, or 2*featureCount
cannam@192 227 feature unions for a Vamp API version 2 plugin.
cannam@168 228
cannam@192 229 The features returned by an API version 2 plugin must consist
cannam@192 230 of the same feature structures as in API version 1 for the
cannam@192 231 first featureCount array elements, followed by featureCount
cannam@192 232 unions that contain VampFeatureV2 structures (or NULL pointers
cannam@192 233 if no V2 feature structures are present).
cannam@168 234 */
cannam@168 235 VampFeatureUnion *features;
cannam@167 236
cannam@0 237 } VampFeatureList;
cannam@0 238
cannam@0 239 typedef enum
cannam@0 240 {
cannam@0 241 vampTimeDomain,
cannam@0 242 vampFrequencyDomain
cannam@0 243
cannam@0 244 } VampInputDomain;
cannam@0 245
cannam@0 246 typedef void *VampPluginHandle;
cannam@0 247
cannam@0 248 typedef struct _VampPluginDescriptor
cannam@0 249 {
cannam@50 250 /** API version with which this descriptor is compatible. */
cannam@50 251 unsigned int vampApiVersion;
cannam@50 252
Chris@388 253 /** Computer-usable name of the plugin. Must not change. [a-zA-Z0-9_-] */
cannam@49 254 const char *identifier;
cannam@49 255
cannam@49 256 /** Human-readable name of the plugin. May be translatable. */
cannam@0 257 const char *name;
cannam@24 258
cannam@49 259 /** Human-readable short text about the plugin. May be translatable. */
cannam@0 260 const char *description;
cannam@24 261
cannam@24 262 /** Human-readable name of plugin's author or vendor. */
cannam@0 263 const char *maker;
cannam@24 264
cannam@24 265 /** Version number of the plugin. */
cannam@0 266 int pluginVersion;
cannam@24 267
cannam@24 268 /** Human-readable summary of copyright or licensing for plugin. */
cannam@0 269 const char *copyright;
cannam@24 270
cannam@24 271 /** Number of parameter inputs. */
cannam@0 272 unsigned int parameterCount;
cannam@24 273
cannam@24 274 /** Fixed descriptors for parameter inputs. */
cannam@0 275 const VampParameterDescriptor **parameters;
cannam@24 276
cannam@24 277 /** Number of programs. */
cannam@0 278 unsigned int programCount;
cannam@24 279
cannam@24 280 /** Fixed names for programs. */
cannam@0 281 const char **programs;
cannam@24 282
cannam@24 283 /** Preferred input domain for audio input (time or frequency). */
cannam@0 284 VampInputDomain inputDomain;
cannam@24 285
cannam@24 286 /** Create and return a new instance of this plugin. */
cannam@0 287 VampPluginHandle (*instantiate)(const struct _VampPluginDescriptor *,
cannam@0 288 float inputSampleRate);
cannam@0 289
cannam@24 290 /** Destroy an instance of this plugin. */
cannam@0 291 void (*cleanup)(VampPluginHandle);
cannam@0 292
cannam@24 293 /** Initialise an instance following parameter configuration. */
cannam@0 294 int (*initialise)(VampPluginHandle,
cannam@0 295 unsigned int inputChannels,
cannam@0 296 unsigned int stepSize,
cannam@0 297 unsigned int blockSize);
cannam@0 298
cannam@24 299 /** Reset an instance, ready to use again on new input data. */
cannam@0 300 void (*reset)(VampPluginHandle);
cannam@0 301
cannam@24 302 /** Get a parameter value. */
cannam@0 303 float (*getParameter)(VampPluginHandle, int);
cannam@24 304
cannam@24 305 /** Set a parameter value. May only be called before initialise. */
cannam@0 306 void (*setParameter)(VampPluginHandle, int, float);
cannam@0 307
cannam@24 308 /** Get the current program (if programCount > 0). */
cannam@0 309 unsigned int (*getCurrentProgram)(VampPluginHandle);
cannam@24 310
cannam@24 311 /** Set the current program. May only be called before initialise. */
cannam@0 312 void (*selectProgram)(VampPluginHandle, unsigned int);
cannam@0 313
cannam@24 314 /** Get the plugin's preferred processing window increment in samples. */
cannam@0 315 unsigned int (*getPreferredStepSize)(VampPluginHandle);
cannam@24 316
cannam@24 317 /** Get the plugin's preferred processing window size in samples. */
cannam@0 318 unsigned int (*getPreferredBlockSize)(VampPluginHandle);
cannam@24 319
cannam@24 320 /** Get the minimum number of input channels this plugin can handle. */
cannam@0 321 unsigned int (*getMinChannelCount)(VampPluginHandle);
cannam@24 322
cannam@24 323 /** Get the maximum number of input channels this plugin can handle. */
cannam@0 324 unsigned int (*getMaxChannelCount)(VampPluginHandle);
cannam@0 325
cannam@24 326 /** Get the number of feature outputs (distinct sets of results). */
cannam@0 327 unsigned int (*getOutputCount)(VampPluginHandle);
cannam@24 328
cannam@24 329 /** Get a descriptor for a given feature output. Returned pointer
cannam@24 330 is valid only until next call to getOutputDescriptor for this
cannam@24 331 handle, or releaseOutputDescriptor for this descriptor. Host
cannam@24 332 must call releaseOutputDescriptor after use. */
cannam@0 333 VampOutputDescriptor *(*getOutputDescriptor)(VampPluginHandle,
cannam@192 334 unsigned int);
cannam@24 335
cannam@24 336 /** Destroy a descriptor for a feature output. */
cannam@0 337 void (*releaseOutputDescriptor)(VampOutputDescriptor *);
cannam@0 338
cannam@24 339 /** Process an input block and return a set of features. Returned
cannam@24 340 pointer is valid only until next call to process,
cannam@24 341 getRemainingFeatures, or cleanup for this handle, or
cannam@24 342 releaseFeatureSet for this feature set. Host must call
cannam@24 343 releaseFeatureSet after use. */
cannam@12 344 VampFeatureList *(*process)(VampPluginHandle,
cannam@47 345 const float *const *inputBuffers,
cannam@0 346 int sec,
cannam@0 347 int nsec);
cannam@24 348
cannam@24 349 /** Return any remaining features at the end of processing. */
cannam@12 350 VampFeatureList *(*getRemainingFeatures)(VampPluginHandle);
cannam@24 351
cannam@24 352 /** Release a feature set returned from process or getRemainingFeatures. */
cannam@12 353 void (*releaseFeatureSet)(VampFeatureList *);
cannam@0 354
cannam@0 355 } VampPluginDescriptor;
cannam@0 356
cannam@160 357
cannam@24 358 /** Get the descriptor for a given plugin index in this library.
cannam@24 359 Return NULL if the index is outside the range of valid indices for
cannam@50 360 this plugin library.
cannam@50 361
cannam@50 362 The hostApiVersion argument tells the library code the highest
cannam@50 363 Vamp API version supported by the host. The function should
cannam@50 364 return a plugin descriptor compatible with the highest API version
cannam@50 365 supported by the library that is no higher than that supported by
cannam@50 366 the host. Provided the descriptor has the correct vampApiVersion
cannam@50 367 field for its actual compatibility level, the host should be able
cannam@50 368 to do the right thing with it: use it if possible, discard it
cannam@50 369 otherwise.
cannam@160 370
cannam@160 371 This is the only symbol that a Vamp plugin actually needs to
cannam@160 372 export from its shared object; all others can be hidden. See the
cannam@160 373 accompanying documentation for notes on how to achieve this with
cannam@160 374 certain compilers.
cannam@50 375 */
cannam@50 376 const VampPluginDescriptor *vampGetPluginDescriptor
cannam@50 377 (unsigned int hostApiVersion, unsigned int index);
cannam@0 378
cannam@160 379
cannam@24 380 /** Function pointer type for vampGetPluginDescriptor. */
cannam@50 381 typedef const VampPluginDescriptor *(*VampGetPluginDescriptorFunction)
cannam@50 382 (unsigned int, unsigned int);
cannam@0 383
cannam@0 384 #ifdef __cplusplus
cannam@0 385 }
cannam@0 386 #endif
cannam@0 387
cannam@0 388 #endif