annotate vamp/vamp.h @ 54:933fee59d33a

* doc updates
author cannam
date Fri, 30 Mar 2007 17:14:16 +0000
parents b907557b2fb9
children e841e2365b48
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@54 53 #define VAMP_API_VERSION 1
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@0 187 typedef struct _VampFeatureList
cannam@0 188 {
cannam@24 189 /** Number of features in this feature list. */
cannam@0 190 unsigned int featureCount;
cannam@24 191
cannam@24 192 /** Features in this feature list. May be NULL if featureCount is zero. */
cannam@0 193 VampFeature *features;
cannam@0 194
cannam@0 195 } VampFeatureList;
cannam@0 196
cannam@0 197 typedef enum
cannam@0 198 {
cannam@0 199 vampTimeDomain,
cannam@0 200 vampFrequencyDomain
cannam@0 201
cannam@0 202 } VampInputDomain;
cannam@0 203
cannam@0 204 typedef void *VampPluginHandle;
cannam@0 205
cannam@0 206 typedef struct _VampPluginDescriptor
cannam@0 207 {
cannam@50 208 /** API version with which this descriptor is compatible. */
cannam@50 209 unsigned int vampApiVersion;
cannam@50 210
cannam@24 211 /** Computer-usable name of the plugin. Must not change. [a-zA-Z0-9_] */
cannam@49 212 const char *identifier;
cannam@49 213
cannam@49 214 /** Human-readable name of the plugin. May be translatable. */
cannam@0 215 const char *name;
cannam@24 216
cannam@49 217 /** Human-readable short text about the plugin. May be translatable. */
cannam@0 218 const char *description;
cannam@24 219
cannam@24 220 /** Human-readable name of plugin's author or vendor. */
cannam@0 221 const char *maker;
cannam@24 222
cannam@24 223 /** Version number of the plugin. */
cannam@0 224 int pluginVersion;
cannam@24 225
cannam@24 226 /** Human-readable summary of copyright or licensing for plugin. */
cannam@0 227 const char *copyright;
cannam@24 228
cannam@24 229 /** Number of parameter inputs. */
cannam@0 230 unsigned int parameterCount;
cannam@24 231
cannam@24 232 /** Fixed descriptors for parameter inputs. */
cannam@0 233 const VampParameterDescriptor **parameters;
cannam@24 234
cannam@24 235 /** Number of programs. */
cannam@0 236 unsigned int programCount;
cannam@24 237
cannam@24 238 /** Fixed names for programs. */
cannam@0 239 const char **programs;
cannam@24 240
cannam@24 241 /** Preferred input domain for audio input (time or frequency). */
cannam@0 242 VampInputDomain inputDomain;
cannam@24 243
cannam@24 244 /** Create and return a new instance of this plugin. */
cannam@0 245 VampPluginHandle (*instantiate)(const struct _VampPluginDescriptor *,
cannam@0 246 float inputSampleRate);
cannam@0 247
cannam@24 248 /** Destroy an instance of this plugin. */
cannam@0 249 void (*cleanup)(VampPluginHandle);
cannam@0 250
cannam@24 251 /** Initialise an instance following parameter configuration. */
cannam@0 252 int (*initialise)(VampPluginHandle,
cannam@0 253 unsigned int inputChannels,
cannam@0 254 unsigned int stepSize,
cannam@0 255 unsigned int blockSize);
cannam@0 256
cannam@24 257 /** Reset an instance, ready to use again on new input data. */
cannam@0 258 void (*reset)(VampPluginHandle);
cannam@0 259
cannam@24 260 /** Get a parameter value. */
cannam@0 261 float (*getParameter)(VampPluginHandle, int);
cannam@24 262
cannam@24 263 /** Set a parameter value. May only be called before initialise. */
cannam@0 264 void (*setParameter)(VampPluginHandle, int, float);
cannam@0 265
cannam@24 266 /** Get the current program (if programCount > 0). */
cannam@0 267 unsigned int (*getCurrentProgram)(VampPluginHandle);
cannam@24 268
cannam@24 269 /** Set the current program. May only be called before initialise. */
cannam@0 270 void (*selectProgram)(VampPluginHandle, unsigned int);
cannam@0 271
cannam@24 272 /** Get the plugin's preferred processing window increment in samples. */
cannam@0 273 unsigned int (*getPreferredStepSize)(VampPluginHandle);
cannam@24 274
cannam@24 275 /** Get the plugin's preferred processing window size in samples. */
cannam@0 276 unsigned int (*getPreferredBlockSize)(VampPluginHandle);
cannam@24 277
cannam@24 278 /** Get the minimum number of input channels this plugin can handle. */
cannam@0 279 unsigned int (*getMinChannelCount)(VampPluginHandle);
cannam@24 280
cannam@24 281 /** Get the maximum number of input channels this plugin can handle. */
cannam@0 282 unsigned int (*getMaxChannelCount)(VampPluginHandle);
cannam@0 283
cannam@24 284 /** Get the number of feature outputs (distinct sets of results). */
cannam@0 285 unsigned int (*getOutputCount)(VampPluginHandle);
cannam@24 286
cannam@24 287 /** Get a descriptor for a given feature output. Returned pointer
cannam@24 288 is valid only until next call to getOutputDescriptor for this
cannam@24 289 handle, or releaseOutputDescriptor for this descriptor. Host
cannam@24 290 must call releaseOutputDescriptor after use. */
cannam@0 291 VampOutputDescriptor *(*getOutputDescriptor)(VampPluginHandle,
cannam@0 292 unsigned int);
cannam@24 293
cannam@24 294 /** Destroy a descriptor for a feature output. */
cannam@0 295 void (*releaseOutputDescriptor)(VampOutputDescriptor *);
cannam@0 296
cannam@24 297 /** Process an input block and return a set of features. Returned
cannam@24 298 pointer is valid only until next call to process,
cannam@24 299 getRemainingFeatures, or cleanup for this handle, or
cannam@24 300 releaseFeatureSet for this feature set. Host must call
cannam@24 301 releaseFeatureSet after use. */
cannam@12 302 VampFeatureList *(*process)(VampPluginHandle,
cannam@47 303 const float *const *inputBuffers,
cannam@0 304 int sec,
cannam@0 305 int nsec);
cannam@24 306
cannam@24 307 /** Return any remaining features at the end of processing. */
cannam@12 308 VampFeatureList *(*getRemainingFeatures)(VampPluginHandle);
cannam@24 309
cannam@24 310 /** Release a feature set returned from process or getRemainingFeatures. */
cannam@12 311 void (*releaseFeatureSet)(VampFeatureList *);
cannam@0 312
cannam@0 313 } VampPluginDescriptor;
cannam@0 314
cannam@24 315 /** Get the descriptor for a given plugin index in this library.
cannam@24 316 Return NULL if the index is outside the range of valid indices for
cannam@50 317 this plugin library.
cannam@50 318
cannam@50 319 The hostApiVersion argument tells the library code the highest
cannam@50 320 Vamp API version supported by the host. The function should
cannam@50 321 return a plugin descriptor compatible with the highest API version
cannam@50 322 supported by the library that is no higher than that supported by
cannam@50 323 the host. Provided the descriptor has the correct vampApiVersion
cannam@50 324 field for its actual compatibility level, the host should be able
cannam@50 325 to do the right thing with it: use it if possible, discard it
cannam@50 326 otherwise.
cannam@50 327 */
cannam@50 328 const VampPluginDescriptor *vampGetPluginDescriptor
cannam@50 329 (unsigned int hostApiVersion, unsigned int index);
cannam@0 330
cannam@24 331 /** Function pointer type for vampGetPluginDescriptor. */
cannam@50 332 typedef const VampPluginDescriptor *(*VampGetPluginDescriptorFunction)
cannam@50 333 (unsigned int, unsigned int);
cannam@0 334
cannam@0 335 #ifdef __cplusplus
cannam@0 336 }
cannam@0 337 #endif
cannam@0 338
cannam@0 339 #endif