libs/vamp-sdk/vamp/vamp.h

   1 /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*-  vi:set ts=8 sts=4 sw=4: */
   2
   3 /*
   4     Vamp
   5
   6     An API for audio analysis and feature extraction plugins.
   7
   8     Centre for Digital Music, Queen Mary, University of London.
   9     Copyright 2006 Chris Cannam.
  10
  11     Permission is hereby granted, free of charge, to any person
  12     obtaining a copy of this software and associated documentation
  13     files (the "Software"), to deal in the Software without
  14     restriction, including without limitation the rights to use, copy,
  15     modify, merge, publish, distribute, sublicense, and/or sell copies
  16     of the Software, and to permit persons to whom the Software is
  17     furnished to do so, subject to the following conditions:
  18
  19     The above copyright notice and this permission notice shall be
  20     included in all copies or substantial portions of the Software.
  21
  22     THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  23     EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  24     MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  25     NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
  26     ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
  27     CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  28     WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  29
  30     Except as contained in this notice, the names of the Centre for
  31     Digital Music; Queen Mary, University of London; and Chris Cannam
  32     shall not be used in advertising or otherwise to promote the sale,
  33     use or other dealings in this Software without prior written
  34     authorization.
  35 */
  36
  37 #ifndef VAMP_HEADER_INCLUDED
  38 #define VAMP_HEADER_INCLUDED
  39
  40 #ifdef __cplusplus
  41 extern "C" {
  42 #endif
  43
  44 /**
  45  * Plugin API version.  This is incremented when a change is made that
  46  * changes the binary layout of the descriptor records.  When this
  47  * happens, there should be a mechanism for retaining compatibility
  48  * with older hosts and/or plugins.
  49  *
  50  * See also the vampApiVersion field in the plugin descriptor, and the
  51  * hostApiVersion argument to the vampGetPluginDescriptor function.
  52  */
  53 #define VAMP_API_VERSION 2
  54
  55 /**
  56  * C language API for Vamp plugins.
  57  *
  58  * This is the formal plugin API for Vamp.  Plugin authors may prefer
  59  * to use the C++ classes provided in the Vamp plugin SDK, instead of
  60  * using this API directly.  There is an adapter class provided that
  61  * makes C++ plugins available using this C API with relatively little
  62  * work, and the C++ headers are more thoroughly documented.
  63  *
  64  * IMPORTANT: The comments in this file summarise the purpose of each
  65  * of the declared fields and functions, but do not provide a complete
  66  * guide to their permitted values and expected usage.  Please refer
  67  * to the C++ headers in the Vamp plugin SDK for further details and
  68  * plugin lifecycle documentation.
  69  */
  70
  71 typedef struct _VampParameterDescriptor
  72 {
  73     /** Computer-usable name of the parameter. Must not change. [a-zA-Z0-9_] */
  74     const char *identifier;
  75
  76     /** Human-readable name of the parameter. May be translatable. */
  77     const char *name;
  78
  79     /** Human-readable short text about the parameter.  May be translatable. */
  80     const char *description;
  81
  82     /** Human-readable unit of the parameter. */
  83     const char *unit;
  84
  85     /** Minimum value. */
  86     float minValue;
  87
  88     /** Maximum value. */
  89     float maxValue;
  90
  91     /** Default value. Plugin is responsible for setting this on initialise. */
  92     float defaultValue;
  93
  94     /** 1 if parameter values are quantized to a particular resolution. */
  95     int isQuantized;
  96
  97     /** Quantization resolution, if isQuantized. */
  98     float quantizeStep;
  99
 100     /** Human-readable names of the values, if isQuantized.  May be NULL. */
 101     const char **valueNames;
 102
 103 } VampParameterDescriptor;
 104
 105 typedef enum
 106 {
 107     /** Each process call returns results aligned with call's block start. */
 108     vampOneSamplePerStep,
 109
 110     /** Returned results are evenly spaced at samplerate specified below. */
 111     vampFixedSampleRate,
 112
 113     /** Returned results have their own individual timestamps. */
 114     vampVariableSampleRate
 115
 116 } VampSampleType;
 117
 118 typedef struct _VampOutputDescriptor
 119 {
 120     /** Computer-usable name of the output. Must not change. [a-zA-Z0-9_] */
 121     const char *identifier;
 122
 123     /** Human-readable name of the output. May be translatable. */
 124     const char *name;
 125
 126     /** Human-readable short text about the output. May be translatable. */
 127     const char *description;
 128
 129     /** Human-readable name of the unit of the output. */
 130     const char *unit;
 131
 132     /** 1 if output has equal number of values for each returned result. */
 133     int hasFixedBinCount;
 134
 135     /** Number of values per result, if hasFixedBinCount. */
 136     unsigned int binCount;
 137
 138     /** Names of returned value bins, if hasFixedBinCount.  May be NULL. */
 139     const char **binNames;
 140
 141     /** 1 if each returned value falls within the same fixed min/max range. */
 142     int hasKnownExtents;
 143
 144     /** Minimum value for a returned result in any bin, if hasKnownExtents. */
 145     float minValue;
 146
 147     /** Maximum value for a returned result in any bin, if hasKnownExtents. */
 148     float maxValue;
 149
 150     /** 1 if returned results are quantized to a particular resolution. */
 151     int isQuantized;
 152
 153     /** Quantization resolution for returned results, if isQuantized. */
 154     float quantizeStep;
 155
 156     /** Time positioning method for returned results (see VampSampleType). */
 157     VampSampleType sampleType;
 158
 159     /** Sample rate of returned results, if sampleType is vampFixedSampleRate.
 160        "Resolution" of result, if sampleType is vampVariableSampleRate. */
 161     float sampleRate;
 162
 163     /** 1 if the returned results for this output are known to have a
 164         duration field.
 165
 166         This field is new in Vamp API version 2; it must not be tested
 167         for plugins that report an older API version in their plugin
 168         descriptor.
 169     */
 170     int hasDuration;
 171
 172 } VampOutputDescriptor;
 173
 174 typedef struct _VampFeature
 175 {
 176     /** 1 if the feature has a timestamp (i.e. if vampVariableSampleRate). */
 177     int hasTimestamp;
 178
 179     /** Seconds component of timestamp. */
 180     int sec;
 181
 182     /** Nanoseconds component of timestamp. */
 183     int nsec;
 184
 185     /** Number of values.  Must be binCount if hasFixedBinCount. */
 186     unsigned int valueCount;
 187
 188     /** Values for this returned sample. */
 189     float *values;
 190
 191     /** Label for this returned sample.  May be NULL. */
 192     char *label;
 193
 194 } VampFeature;
 195
 196 typedef struct _VampFeatureV2
 197 {
 198     /** 1 if the feature has a duration. */
 199     int hasDuration;
 200
 201     /** Seconds component of duratiion. */
 202     int durationSec;
 203
 204     /** Nanoseconds component of duration. */
 205     int durationNsec;
 206
 207 } VampFeatureV2;
 208
 209 typedef union _VampFeatureUnion
 210 {
 211     // sizeof(featureV1) >= sizeof(featureV2) for backward compatibility
 212     VampFeature   v1;
 213     VampFeatureV2 v2;
 214
 215 } VampFeatureUnion;
 216
 217 typedef struct _VampFeatureList
 218 {
 219     /** Number of features in this feature list. */
 220     unsigned int featureCount;
 221
 222     /** Features in this feature list.  May be NULL if featureCount is
 223         zero.
 224
 225         If present, this array must contain featureCount feature
 226         structures for a Vamp API version 1 plugin, or 2*featureCount
 227         feature unions for a Vamp API version 2 plugin.
 228
 229         The features returned by an API version 2 plugin must consist
 230         of the same feature structures as in API version 1 for the
 231         first featureCount array elements, followed by featureCount
 232         unions that contain VampFeatureV2 structures (or NULL pointers
 233         if no V2 feature structures are present).
 234      */
 235     VampFeatureUnion *features;
 236
 237 } VampFeatureList;
 238
 239 typedef enum
 240 {
 241     vampTimeDomain,
 242     vampFrequencyDomain
 243
 244 } VampInputDomain;
 245
 246 typedef void *VampPluginHandle;
 247
 248 typedef struct _VampPluginDescriptor
 249 {
 250     /** API version with which this descriptor is compatible. */
 251     unsigned int vampApiVersion;
 252
 253     /** Computer-usable name of the plugin. Must not change. [a-zA-Z0-9_] */
 254     const char *identifier;
 255
 256     /** Human-readable name of the plugin. May be translatable. */
 257     const char *name;
 258
 259     /** Human-readable short text about the plugin. May be translatable. */
 260     const char *description;
 261
 262     /** Human-readable name of plugin's author or vendor. */
 263     const char *maker;
 264
 265     /** Version number of the plugin. */
 266     int pluginVersion;
 267
 268     /** Human-readable summary of copyright or licensing for plugin. */
 269     const char *copyright;
 270
 271     /** Number of parameter inputs. */
 272     unsigned int parameterCount;
 273
 274     /** Fixed descriptors for parameter inputs. */
 275     const VampParameterDescriptor **parameters;
 276
 277     /** Number of programs. */
 278     unsigned int programCount;
 279
 280     /** Fixed names for programs. */
 281     const char **programs;
 282
 283     /** Preferred input domain for audio input (time or frequency). */
 284     VampInputDomain inputDomain;
 285
 286     /** Create and return a new instance of this plugin. */
 287     VampPluginHandle (*instantiate)(const struct _VampPluginDescriptor *,
 288                                    float inputSampleRate);
 289
 290     /** Destroy an instance of this plugin. */
 291     void (*cleanup)(VampPluginHandle);
 292
 293     /** Initialise an instance following parameter configuration. */
 294     int (*initialise)(VampPluginHandle,
 295                       unsigned int inputChannels,
 296                       unsigned int stepSize,
 297                       unsigned int blockSize);
 298
 299     /** Reset an instance, ready to use again on new input data. */
 300     void (*reset)(VampPluginHandle);
 301
 302     /** Get a parameter value. */
 303     float (*getParameter)(VampPluginHandle, int);
 304
 305     /** Set a parameter value. May only be called before initialise. */
 306     void  (*setParameter)(VampPluginHandle, int, float);
 307
 308     /** Get the current program (if programCount > 0). */
 309     unsigned int (*getCurrentProgram)(VampPluginHandle);
 310
 311     /** Set the current program. May only be called before initialise. */
 312     void  (*selectProgram)(VampPluginHandle, unsigned int);
 313
 314     /** Get the plugin's preferred processing window increment in samples. */
 315     unsigned int (*getPreferredStepSize)(VampPluginHandle);
 316
 317     /** Get the plugin's preferred processing window size in samples. */
 318     unsigned int (*getPreferredBlockSize)(VampPluginHandle);
 319
 320     /** Get the minimum number of input channels this plugin can handle. */
 321     unsigned int (*getMinChannelCount)(VampPluginHandle);
 322
 323     /** Get the maximum number of input channels this plugin can handle. */
 324     unsigned int (*getMaxChannelCount)(VampPluginHandle);
 325
 326     /** Get the number of feature outputs (distinct sets of results). */
 327     unsigned int (*getOutputCount)(VampPluginHandle);
 328
 329     /** Get a descriptor for a given feature output. Returned pointer
 330         is valid only until next call to getOutputDescriptor for this
 331         handle, or releaseOutputDescriptor for this descriptor. Host
 332         must call releaseOutputDescriptor after use. */
 333     VampOutputDescriptor *(*getOutputDescriptor)(VampPluginHandle,
 334                                                  unsigned int);
 335
 336     /** Destroy a descriptor for a feature output. */
 337     void (*releaseOutputDescriptor)(VampOutputDescriptor *);
 338
 339     /** Process an input block and return a set of features. Returned
 340         pointer is valid only until next call to process,
 341         getRemainingFeatures, or cleanup for this handle, or
 342         releaseFeatureSet for this feature set. Host must call
 343         releaseFeatureSet after use. */
 344     VampFeatureList *(*process)(VampPluginHandle,
 345                                 const float *const *inputBuffers,
 346                                 int sec,
 347                                 int nsec);
 348
 349     /** Return any remaining features at the end of processing. */
 350     VampFeatureList *(*getRemainingFeatures)(VampPluginHandle);
 351
 352     /** Release a feature set returned from process or getRemainingFeatures. */
 353     void (*releaseFeatureSet)(VampFeatureList *);
 354
 355 } VampPluginDescriptor;
 356
 357
 358 /** Get the descriptor for a given plugin index in this library.
 359     Return NULL if the index is outside the range of valid indices for
 360     this plugin library.
 361
 362     The hostApiVersion argument tells the library code the highest
 363     Vamp API version supported by the host.  The function should
 364     return a plugin descriptor compatible with the highest API version
 365     supported by the library that is no higher than that supported by
 366     the host.  Provided the descriptor has the correct vampApiVersion
 367     field for its actual compatibility level, the host should be able
 368     to do the right thing with it: use it if possible, discard it
 369     otherwise.
 370
 371     This is the only symbol that a Vamp plugin actually needs to
 372     export from its shared object; all others can be hidden.  See the
 373     accompanying documentation for notes on how to achieve this with
 374     certain compilers.
 375 */
 376 const VampPluginDescriptor *vampGetPluginDescriptor
 377     (unsigned int hostApiVersion, unsigned int index);
 378
 379
 380 /** Function pointer type for vampGetPluginDescriptor. */
 381 typedef const VampPluginDescriptor *(*VampGetPluginDescriptorFunction)
 382     (unsigned int, unsigned int);
 383
 384 #ifdef __cplusplus
 385 }
 386 #endif
 387
 388 #endif