annotate vamp/vamp.h @ 167:31eda4b11f2b

* First bit of Vamp v2 work -- add an optional duration to features in a backward compatible way. Warning: this code is unstable and experimental and may change significantly in the coming weeks.
author cannam
date Thu, 17 Jul 2008 08:52:26 +0000
parents 7fc1041daa9d
children 006a775133b1
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@0 200 typedef struct _VampFeatureList
cannam@0 201 {
cannam@24 202 /** Number of features in this feature list. */
cannam@0 203 unsigned int featureCount;
cannam@24 204
cannam@24 205 /** Features in this feature list. May be NULL if featureCount is zero. */
cannam@0 206 VampFeature *features;
cannam@0 207
cannam@167 208 /** Vamp 2.0 extended information for features in this feature list. */
cannam@167 209 VampFeatureV2 *featuresV2;
cannam@167 210
cannam@0 211 } VampFeatureList;
cannam@0 212
cannam@0 213 typedef enum
cannam@0 214 {
cannam@0 215 vampTimeDomain,
cannam@0 216 vampFrequencyDomain
cannam@0 217
cannam@0 218 } VampInputDomain;
cannam@0 219
cannam@0 220 typedef void *VampPluginHandle;
cannam@0 221
cannam@0 222 typedef struct _VampPluginDescriptor
cannam@0 223 {
cannam@50 224 /** API version with which this descriptor is compatible. */
cannam@50 225 unsigned int vampApiVersion;
cannam@50 226
cannam@24 227 /** Computer-usable name of the plugin. Must not change. [a-zA-Z0-9_] */
cannam@49 228 const char *identifier;
cannam@49 229
cannam@49 230 /** Human-readable name of the plugin. May be translatable. */
cannam@0 231 const char *name;
cannam@24 232
cannam@49 233 /** Human-readable short text about the plugin. May be translatable. */
cannam@0 234 const char *description;
cannam@24 235
cannam@24 236 /** Human-readable name of plugin's author or vendor. */
cannam@0 237 const char *maker;
cannam@24 238
cannam@24 239 /** Version number of the plugin. */
cannam@0 240 int pluginVersion;
cannam@24 241
cannam@24 242 /** Human-readable summary of copyright or licensing for plugin. */
cannam@0 243 const char *copyright;
cannam@24 244
cannam@24 245 /** Number of parameter inputs. */
cannam@0 246 unsigned int parameterCount;
cannam@24 247
cannam@24 248 /** Fixed descriptors for parameter inputs. */
cannam@0 249 const VampParameterDescriptor **parameters;
cannam@24 250
cannam@24 251 /** Number of programs. */
cannam@0 252 unsigned int programCount;
cannam@24 253
cannam@24 254 /** Fixed names for programs. */
cannam@0 255 const char **programs;
cannam@24 256
cannam@24 257 /** Preferred input domain for audio input (time or frequency). */
cannam@0 258 VampInputDomain inputDomain;
cannam@24 259
cannam@24 260 /** Create and return a new instance of this plugin. */
cannam@0 261 VampPluginHandle (*instantiate)(const struct _VampPluginDescriptor *,
cannam@0 262 float inputSampleRate);
cannam@0 263
cannam@24 264 /** Destroy an instance of this plugin. */
cannam@0 265 void (*cleanup)(VampPluginHandle);
cannam@0 266
cannam@24 267 /** Initialise an instance following parameter configuration. */
cannam@0 268 int (*initialise)(VampPluginHandle,
cannam@0 269 unsigned int inputChannels,
cannam@0 270 unsigned int stepSize,
cannam@0 271 unsigned int blockSize);
cannam@0 272
cannam@24 273 /** Reset an instance, ready to use again on new input data. */
cannam@0 274 void (*reset)(VampPluginHandle);
cannam@0 275
cannam@24 276 /** Get a parameter value. */
cannam@0 277 float (*getParameter)(VampPluginHandle, int);
cannam@24 278
cannam@24 279 /** Set a parameter value. May only be called before initialise. */
cannam@0 280 void (*setParameter)(VampPluginHandle, int, float);
cannam@0 281
cannam@24 282 /** Get the current program (if programCount > 0). */
cannam@0 283 unsigned int (*getCurrentProgram)(VampPluginHandle);
cannam@24 284
cannam@24 285 /** Set the current program. May only be called before initialise. */
cannam@0 286 void (*selectProgram)(VampPluginHandle, unsigned int);
cannam@0 287
cannam@24 288 /** Get the plugin's preferred processing window increment in samples. */
cannam@0 289 unsigned int (*getPreferredStepSize)(VampPluginHandle);
cannam@24 290
cannam@24 291 /** Get the plugin's preferred processing window size in samples. */
cannam@0 292 unsigned int (*getPreferredBlockSize)(VampPluginHandle);
cannam@24 293
cannam@24 294 /** Get the minimum number of input channels this plugin can handle. */
cannam@0 295 unsigned int (*getMinChannelCount)(VampPluginHandle);
cannam@24 296
cannam@24 297 /** Get the maximum number of input channels this plugin can handle. */
cannam@0 298 unsigned int (*getMaxChannelCount)(VampPluginHandle);
cannam@0 299
cannam@24 300 /** Get the number of feature outputs (distinct sets of results). */
cannam@0 301 unsigned int (*getOutputCount)(VampPluginHandle);
cannam@24 302
cannam@24 303 /** Get a descriptor for a given feature output. Returned pointer
cannam@24 304 is valid only until next call to getOutputDescriptor for this
cannam@24 305 handle, or releaseOutputDescriptor for this descriptor. Host
cannam@24 306 must call releaseOutputDescriptor after use. */
cannam@0 307 VampOutputDescriptor *(*getOutputDescriptor)(VampPluginHandle,
cannam@0 308 unsigned int);
cannam@24 309
cannam@24 310 /** Destroy a descriptor for a feature output. */
cannam@0 311 void (*releaseOutputDescriptor)(VampOutputDescriptor *);
cannam@0 312
cannam@24 313 /** Process an input block and return a set of features. Returned
cannam@24 314 pointer is valid only until next call to process,
cannam@24 315 getRemainingFeatures, or cleanup for this handle, or
cannam@24 316 releaseFeatureSet for this feature set. Host must call
cannam@24 317 releaseFeatureSet after use. */
cannam@12 318 VampFeatureList *(*process)(VampPluginHandle,
cannam@47 319 const float *const *inputBuffers,
cannam@0 320 int sec,
cannam@0 321 int nsec);
cannam@24 322
cannam@24 323 /** Return any remaining features at the end of processing. */
cannam@12 324 VampFeatureList *(*getRemainingFeatures)(VampPluginHandle);
cannam@24 325
cannam@24 326 /** Release a feature set returned from process or getRemainingFeatures. */
cannam@12 327 void (*releaseFeatureSet)(VampFeatureList *);
cannam@0 328
cannam@0 329 } VampPluginDescriptor;
cannam@0 330
cannam@160 331
cannam@24 332 /** Get the descriptor for a given plugin index in this library.
cannam@24 333 Return NULL if the index is outside the range of valid indices for
cannam@50 334 this plugin library.
cannam@50 335
cannam@50 336 The hostApiVersion argument tells the library code the highest
cannam@50 337 Vamp API version supported by the host. The function should
cannam@50 338 return a plugin descriptor compatible with the highest API version
cannam@50 339 supported by the library that is no higher than that supported by
cannam@50 340 the host. Provided the descriptor has the correct vampApiVersion
cannam@50 341 field for its actual compatibility level, the host should be able
cannam@50 342 to do the right thing with it: use it if possible, discard it
cannam@50 343 otherwise.
cannam@160 344
cannam@160 345 This is the only symbol that a Vamp plugin actually needs to
cannam@160 346 export from its shared object; all others can be hidden. See the
cannam@160 347 accompanying documentation for notes on how to achieve this with
cannam@160 348 certain compilers.
cannam@50 349 */
cannam@50 350 const VampPluginDescriptor *vampGetPluginDescriptor
cannam@50 351 (unsigned int hostApiVersion, unsigned int index);
cannam@0 352
cannam@160 353
cannam@24 354 /** Function pointer type for vampGetPluginDescriptor. */
cannam@50 355 typedef const VampPluginDescriptor *(*VampGetPluginDescriptorFunction)
cannam@50 356 (unsigned int, unsigned int);
cannam@0 357
cannam@0 358 #ifdef __cplusplus
cannam@0 359 }
cannam@0 360 #endif
cannam@0 361
cannam@0 362 #endif