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