annotate vamp/vamp.h @ 28:ca1309b937b6 vamp-plugin-sdk-v0.9rc1

* Update version numbers to 0.9
author cannam
date Fri, 12 May 2006 14:46:35 +0000
parents e252b1ab423f
children 3bbe244611bb
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@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@28 64 #define VAMP_API_VERSION "0.9"
cannam@18 65 #define VAMP_API_VERSION_MAJOR 0
cannam@28 66 #define VAMP_API_VERSION_MINOR 9
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@0 71 const char *name;
cannam@24 72
cannam@24 73 /** Human-readable name of the parameter. May be translatable. */
cannam@0 74 const char *description;
cannam@24 75
cannam@24 76 /** Human-readable unit of the parameter. */
cannam@0 77 const char *unit;
cannam@24 78
cannam@24 79 /** Minimum value. */
cannam@0 80 float minValue;
cannam@24 81
cannam@24 82 /** Maximum value. */
cannam@0 83 float maxValue;
cannam@24 84
cannam@24 85 /** Default value. Plugin is responsible for setting this on initialise. */
cannam@0 86 float defaultValue;
cannam@24 87
cannam@24 88 /** 1 if parameter values are quantized to a particular resolution. */
cannam@0 89 int isQuantized;
cannam@24 90
cannam@24 91 /** Quantization resolution, if isQuantized. */
cannam@0 92 float quantizeStep;
cannam@24 93
cannam@24 94 /** Human-readable names of the values, if isQuantized. May be NULL. */
cannam@9 95 const char **valueNames;
cannam@0 96
cannam@0 97 } VampParameterDescriptor;
cannam@0 98
cannam@0 99 typedef enum
cannam@0 100 {
cannam@24 101 /** Each process call returns results aligned with call's block start. */
cannam@0 102 vampOneSamplePerStep,
cannam@24 103
cannam@24 104 /** Returned results are evenly spaced at samplerate specified below. */
cannam@0 105 vampFixedSampleRate,
cannam@24 106
cannam@24 107 /** Returned results have their own individual timestamps. */
cannam@0 108 vampVariableSampleRate
cannam@0 109
cannam@0 110 } VampSampleType;
cannam@0 111
cannam@0 112 typedef struct _VampOutputDescriptor
cannam@0 113 {
cannam@24 114 /** Computer-usable name of the output. Must not change. [a-zA-Z0-9_] */
cannam@0 115 const char *name;
cannam@24 116
cannam@24 117 /** Human-readable name of the output. May be translatable. */
cannam@0 118 const char *description;
cannam@24 119
cannam@24 120 /** Human-readable name of the unit of the output. */
cannam@0 121 const char *unit;
cannam@24 122
cannam@24 123 /** 1 if output has equal number of values for each returned result. */
cannam@9 124 int hasFixedBinCount;
cannam@24 125
cannam@24 126 /** Number of values per result, if hasFixedBinCount. */
cannam@9 127 unsigned int binCount;
cannam@24 128
cannam@24 129 /** Names of returned value bins, if hasFixedBinCount. May be NULL. */
cannam@9 130 const char **binNames;
cannam@24 131
cannam@24 132 /** 1 if each returned value falls within the same fixed min/max range. */
cannam@0 133 int hasKnownExtents;
cannam@24 134
cannam@24 135 /** Minimum value for a returned result in any bin, if hasKnownExtents. */
cannam@0 136 float minValue;
cannam@24 137
cannam@24 138 /** Maximum value for a returned result in any bin, if hasKnownExtents. */
cannam@0 139 float maxValue;
cannam@24 140
cannam@24 141 /** 1 if returned results are quantized to a particular resolution. */
cannam@0 142 int isQuantized;
cannam@24 143
cannam@24 144 /** Quantization resolution for returned results, if isQuantized. */
cannam@0 145 float quantizeStep;
cannam@24 146
cannam@24 147 /** Time positioning method for returned results (see VampSampleType). */
cannam@0 148 VampSampleType sampleType;
cannam@24 149
cannam@24 150 /** Sample rate of returned results, if sampleType is vampFixedSampleRate.
cannam@24 151 "Resolution" of result, if sampleType is vampVariableSampleRate. */
cannam@0 152 float sampleRate;
cannam@0 153
cannam@0 154 } VampOutputDescriptor;
cannam@0 155
cannam@0 156 typedef struct _VampFeature
cannam@0 157 {
cannam@24 158 /** 1 if the feature has a timestamp (i.e. if vampVariableSampleRate). */
cannam@0 159 int hasTimestamp;
cannam@24 160
cannam@24 161 /** Seconds component of timestamp. */
cannam@0 162 int sec;
cannam@24 163
cannam@24 164 /** Nanoseconds component of timestamp. */
cannam@0 165 int nsec;
cannam@24 166
cannam@24 167 /** Number of values. Must be binCount if hasFixedBinCount. */
cannam@0 168 unsigned int valueCount;
cannam@24 169
cannam@24 170 /** Values for this returned sample. */
cannam@0 171 float *values;
cannam@24 172
cannam@24 173 /** Label for this returned sample. May be NULL. */
cannam@0 174 char *label;
cannam@0 175
cannam@0 176 } VampFeature;
cannam@0 177
cannam@0 178 typedef struct _VampFeatureList
cannam@0 179 {
cannam@24 180 /** Number of features in this feature list. */
cannam@0 181 unsigned int featureCount;
cannam@24 182
cannam@24 183 /** Features in this feature list. May be NULL if featureCount is zero. */
cannam@0 184 VampFeature *features;
cannam@0 185
cannam@0 186 } VampFeatureList;
cannam@0 187
cannam@0 188 typedef enum
cannam@0 189 {
cannam@0 190 vampTimeDomain,
cannam@0 191 vampFrequencyDomain
cannam@0 192
cannam@0 193 } VampInputDomain;
cannam@0 194
cannam@0 195 typedef void *VampPluginHandle;
cannam@0 196
cannam@0 197 typedef struct _VampPluginDescriptor
cannam@0 198 {
cannam@24 199 /** Computer-usable name of the plugin. Must not change. [a-zA-Z0-9_] */
cannam@0 200 const char *name;
cannam@24 201
cannam@24 202 /** Human-readable name of the plugin. May be translatable. */
cannam@0 203 const char *description;
cannam@24 204
cannam@24 205 /** Human-readable name of plugin's author or vendor. */
cannam@0 206 const char *maker;
cannam@24 207
cannam@24 208 /** Version number of the plugin. */
cannam@0 209 int pluginVersion;
cannam@24 210
cannam@24 211 /** Human-readable summary of copyright or licensing for plugin. */
cannam@0 212 const char *copyright;
cannam@24 213
cannam@24 214 /** Number of parameter inputs. */
cannam@0 215 unsigned int parameterCount;
cannam@24 216
cannam@24 217 /** Fixed descriptors for parameter inputs. */
cannam@0 218 const VampParameterDescriptor **parameters;
cannam@24 219
cannam@24 220 /** Number of programs. */
cannam@0 221 unsigned int programCount;
cannam@24 222
cannam@24 223 /** Fixed names for programs. */
cannam@0 224 const char **programs;
cannam@24 225
cannam@24 226 /** Preferred input domain for audio input (time or frequency). */
cannam@0 227 VampInputDomain inputDomain;
cannam@24 228
cannam@24 229 /** Create and return a new instance of this plugin. */
cannam@0 230 VampPluginHandle (*instantiate)(const struct _VampPluginDescriptor *,
cannam@0 231 float inputSampleRate);
cannam@0 232
cannam@24 233 /** Destroy an instance of this plugin. */
cannam@0 234 void (*cleanup)(VampPluginHandle);
cannam@0 235
cannam@24 236 /** Initialise an instance following parameter configuration. */
cannam@0 237 int (*initialise)(VampPluginHandle,
cannam@0 238 unsigned int inputChannels,
cannam@0 239 unsigned int stepSize,
cannam@0 240 unsigned int blockSize);
cannam@0 241
cannam@24 242 /** Reset an instance, ready to use again on new input data. */
cannam@0 243 void (*reset)(VampPluginHandle);
cannam@0 244
cannam@24 245 /** Get a parameter value. */
cannam@0 246 float (*getParameter)(VampPluginHandle, int);
cannam@24 247
cannam@24 248 /** Set a parameter value. May only be called before initialise. */
cannam@0 249 void (*setParameter)(VampPluginHandle, int, float);
cannam@0 250
cannam@24 251 /** Get the current program (if programCount > 0). */
cannam@0 252 unsigned int (*getCurrentProgram)(VampPluginHandle);
cannam@24 253
cannam@24 254 /** Set the current program. May only be called before initialise. */
cannam@0 255 void (*selectProgram)(VampPluginHandle, unsigned int);
cannam@0 256
cannam@24 257 /** Get the plugin's preferred processing window increment in samples. */
cannam@0 258 unsigned int (*getPreferredStepSize)(VampPluginHandle);
cannam@24 259
cannam@24 260 /** Get the plugin's preferred processing window size in samples. */
cannam@0 261 unsigned int (*getPreferredBlockSize)(VampPluginHandle);
cannam@24 262
cannam@24 263 /** Get the minimum number of input channels this plugin can handle. */
cannam@0 264 unsigned int (*getMinChannelCount)(VampPluginHandle);
cannam@24 265
cannam@24 266 /** Get the maximum number of input channels this plugin can handle. */
cannam@0 267 unsigned int (*getMaxChannelCount)(VampPluginHandle);
cannam@0 268
cannam@24 269 /** Get the number of feature outputs (distinct sets of results). */
cannam@0 270 unsigned int (*getOutputCount)(VampPluginHandle);
cannam@24 271
cannam@24 272 /** Get a descriptor for a given feature output. Returned pointer
cannam@24 273 is valid only until next call to getOutputDescriptor for this
cannam@24 274 handle, or releaseOutputDescriptor for this descriptor. Host
cannam@24 275 must call releaseOutputDescriptor after use. */
cannam@0 276 VampOutputDescriptor *(*getOutputDescriptor)(VampPluginHandle,
cannam@0 277 unsigned int);
cannam@24 278
cannam@24 279 /** Destroy a descriptor for a feature output. */
cannam@0 280 void (*releaseOutputDescriptor)(VampOutputDescriptor *);
cannam@0 281
cannam@24 282 /** Process an input block and return a set of features. Returned
cannam@24 283 pointer is valid only until next call to process,
cannam@24 284 getRemainingFeatures, or cleanup for this handle, or
cannam@24 285 releaseFeatureSet for this feature set. Host must call
cannam@24 286 releaseFeatureSet after use. */
cannam@12 287 VampFeatureList *(*process)(VampPluginHandle,
cannam@0 288 float **inputBuffers,
cannam@0 289 int sec,
cannam@0 290 int nsec);
cannam@24 291
cannam@24 292 /** Return any remaining features at the end of processing. */
cannam@12 293 VampFeatureList *(*getRemainingFeatures)(VampPluginHandle);
cannam@24 294
cannam@24 295 /** Release a feature set returned from process or getRemainingFeatures. */
cannam@12 296 void (*releaseFeatureSet)(VampFeatureList *);
cannam@0 297
cannam@0 298 } VampPluginDescriptor;
cannam@0 299
cannam@24 300 /** Get the descriptor for a given plugin index in this library.
cannam@24 301 Return NULL if the index is outside the range of valid indices for
cannam@24 302 this plugin library. */
cannam@0 303 const VampPluginDescriptor *vampGetPluginDescriptor(unsigned int index);
cannam@0 304
cannam@24 305 /** Function pointer type for vampGetPluginDescriptor. */
cannam@0 306 typedef const VampPluginDescriptor *(*VampGetPluginDescriptorFunction)(unsigned int);
cannam@0 307
cannam@0 308 #ifdef __cplusplus
cannam@0 309 }
cannam@0 310 #endif
cannam@0 311
cannam@0 312 #endif