cannam@99: /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*-  vi:set ts=8 sts=4 sw=4: */
cannam@99: 
cannam@99: /*
cannam@99:     Vamp
cannam@99: 
cannam@99:     An API for audio analysis and feature extraction plugins.
cannam@99: 
cannam@99:     Centre for Digital Music, Queen Mary, University of London.
cannam@99:     Copyright 2006 Chris Cannam.
cannam@99:   
cannam@99:     Permission is hereby granted, free of charge, to any person
cannam@99:     obtaining a copy of this software and associated documentation
cannam@99:     files (the "Software"), to deal in the Software without
cannam@99:     restriction, including without limitation the rights to use, copy,
cannam@99:     modify, merge, publish, distribute, sublicense, and/or sell copies
cannam@99:     of the Software, and to permit persons to whom the Software is
cannam@99:     furnished to do so, subject to the following conditions:
cannam@99: 
cannam@99:     The above copyright notice and this permission notice shall be
cannam@99:     included in all copies or substantial portions of the Software.
cannam@99: 
cannam@99:     THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
cannam@99:     EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
cannam@99:     MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
cannam@99:     NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
cannam@99:     ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
cannam@99:     CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
cannam@99:     WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
cannam@99: 
cannam@99:     Except as contained in this notice, the names of the Centre for
cannam@99:     Digital Music; Queen Mary, University of London; and Chris Cannam
cannam@99:     shall not be used in advertising or otherwise to promote the sale,
cannam@99:     use or other dealings in this Software without prior written
cannam@99:     authorization.
cannam@99: */
cannam@99: 
cannam@99: #ifndef VAMP_HEADER_INCLUDED
cannam@99: #define VAMP_HEADER_INCLUDED
cannam@99: 
cannam@99: #ifdef __cplusplus
cannam@99: extern "C" {
cannam@99: #endif
cannam@99: 
cannam@99: /** 
cannam@99:  * Plugin API version.  This is incremented when a change is made that
cannam@99:  * changes the binary layout of the descriptor records.  When this
cannam@99:  * happens, there should be a mechanism for retaining compatibility
cannam@99:  * with older hosts and/or plugins.
cannam@99:  *
cannam@99:  * See also the vampApiVersion field in the plugin descriptor, and the
cannam@99:  * hostApiVersion argument to the vampGetPluginDescriptor function.
cannam@99:  */
cannam@99: #define VAMP_API_VERSION 2
cannam@99: 
cannam@99: /**
cannam@99:  * C language API for Vamp plugins.
cannam@99:  * 
cannam@99:  * This is the formal plugin API for Vamp.  Plugin authors may prefer
cannam@99:  * to use the C++ classes provided in the Vamp plugin SDK, instead of
cannam@99:  * using this API directly.  There is an adapter class provided that
cannam@99:  * makes C++ plugins available using this C API with relatively little
cannam@99:  * work, and the C++ headers are more thoroughly documented.
cannam@99:  *
cannam@99:  * IMPORTANT: The comments in this file summarise the purpose of each
cannam@99:  * of the declared fields and functions, but do not provide a complete
cannam@99:  * guide to their permitted values and expected usage.  Please refer
cannam@99:  * to the C++ headers in the Vamp plugin SDK for further details and
cannam@99:  * plugin lifecycle documentation.
cannam@99:  */
cannam@99: 
cannam@99: typedef struct _VampParameterDescriptor
cannam@99: {
cannam@99:     /** Computer-usable name of the parameter. Must not change. [a-zA-Z0-9_] */
cannam@99:     const char *identifier;
cannam@99: 
cannam@99:     /** Human-readable name of the parameter. May be translatable. */
cannam@99:     const char *name;
cannam@99: 
cannam@99:     /** Human-readable short text about the parameter.  May be translatable. */
cannam@99:     const char *description;
cannam@99: 
cannam@99:     /** Human-readable unit of the parameter. */
cannam@99:     const char *unit;
cannam@99: 
cannam@99:     /** Minimum value. */
cannam@99:     float minValue;
cannam@99: 
cannam@99:     /** Maximum value. */
cannam@99:     float maxValue;
cannam@99: 
cannam@99:     /** Default value. Plugin is responsible for setting this on initialise. */
cannam@99:     float defaultValue;
cannam@99: 
cannam@99:     /** 1 if parameter values are quantized to a particular resolution. */
cannam@99:     int isQuantized;
cannam@99: 
cannam@99:     /** Quantization resolution, if isQuantized. */
cannam@99:     float quantizeStep;
cannam@99: 
cannam@99:     /** Human-readable names of the values, if isQuantized.  May be NULL. */
cannam@99:     const char **valueNames;
cannam@99: 
cannam@99: } VampParameterDescriptor;
cannam@99: 
cannam@99: typedef enum
cannam@99: {
cannam@99:     /** Each process call returns results aligned with call's block start. */
cannam@99:     vampOneSamplePerStep,
cannam@99: 
cannam@99:     /** Returned results are evenly spaced at samplerate specified below. */
cannam@99:     vampFixedSampleRate,
cannam@99: 
cannam@99:     /** Returned results have their own individual timestamps. */
cannam@99:     vampVariableSampleRate
cannam@99: 
cannam@99: } VampSampleType;
cannam@99: 
cannam@99: typedef struct _VampOutputDescriptor
cannam@99: {
cannam@99:     /** Computer-usable name of the output. Must not change. [a-zA-Z0-9_] */
cannam@99:     const char *identifier;
cannam@99: 
cannam@99:     /** Human-readable name of the output. May be translatable. */
cannam@99:     const char *name;
cannam@99: 
cannam@99:     /** Human-readable short text about the output. May be translatable. */
cannam@99:     const char *description;
cannam@99: 
cannam@99:     /** Human-readable name of the unit of the output. */
cannam@99:     const char *unit;
cannam@99: 
cannam@99:     /** 1 if output has equal number of values for each returned result. */
cannam@99:     int hasFixedBinCount;
cannam@99: 
cannam@99:     /** Number of values per result, if hasFixedBinCount. */
cannam@99:     unsigned int binCount;
cannam@99: 
cannam@99:     /** Names of returned value bins, if hasFixedBinCount.  May be NULL. */
cannam@99:     const char **binNames;
cannam@99: 
cannam@99:     /** 1 if each returned value falls within the same fixed min/max range. */
cannam@99:     int hasKnownExtents;
cannam@99:     
cannam@99:     /** Minimum value for a returned result in any bin, if hasKnownExtents. */
cannam@99:     float minValue;
cannam@99: 
cannam@99:     /** Maximum value for a returned result in any bin, if hasKnownExtents. */
cannam@99:     float maxValue;
cannam@99: 
cannam@99:     /** 1 if returned results are quantized to a particular resolution. */
cannam@99:     int isQuantized;
cannam@99: 
cannam@99:     /** Quantization resolution for returned results, if isQuantized. */
cannam@99:     float quantizeStep;
cannam@99: 
cannam@99:     /** Time positioning method for returned results (see VampSampleType). */
cannam@99:     VampSampleType sampleType;
cannam@99: 
cannam@99:     /** Sample rate of returned results, if sampleType is vampFixedSampleRate.
cannam@99:        "Resolution" of result, if sampleType is vampVariableSampleRate. */
cannam@99:     float sampleRate;
cannam@99: 
cannam@99:     /** 1 if the returned results for this output are known to have a
cannam@99:         duration field.
cannam@99: 
cannam@99:         This field is new in Vamp API version 2; it must not be tested
cannam@99:         for plugins that report an older API version in their plugin
cannam@99:         descriptor.
cannam@99:     */
cannam@99:     int hasDuration;
cannam@99: 
cannam@99: } VampOutputDescriptor;
cannam@99: 
cannam@99: typedef struct _VampFeature
cannam@99: {
cannam@99:     /** 1 if the feature has a timestamp (i.e. if vampVariableSampleRate). */
cannam@99:     int hasTimestamp;
cannam@99: 
cannam@99:     /** Seconds component of timestamp. */
cannam@99:     int sec;
cannam@99: 
cannam@99:     /** Nanoseconds component of timestamp. */
cannam@99:     int nsec;
cannam@99: 
cannam@99:     /** Number of values.  Must be binCount if hasFixedBinCount. */
cannam@99:     unsigned int valueCount;
cannam@99: 
cannam@99:     /** Values for this returned sample. */
cannam@99:     float *values;
cannam@99: 
cannam@99:     /** Label for this returned sample.  May be NULL. */
cannam@99:     char *label;
cannam@99: 
cannam@99: } VampFeature;
cannam@99: 
cannam@99: typedef struct _VampFeatureV2
cannam@99: {
cannam@99:     /** 1 if the feature has a duration. */
cannam@99:     int hasDuration;
cannam@99: 
cannam@99:     /** Seconds component of duratiion. */
cannam@99:     int durationSec;
cannam@99: 
cannam@99:     /** Nanoseconds component of duration. */
cannam@99:     int durationNsec;
cannam@99: 
cannam@99: } VampFeatureV2;
cannam@99: 
cannam@99: typedef union _VampFeatureUnion
cannam@99: {
cannam@99:     // sizeof(featureV1) >= sizeof(featureV2) for backward compatibility
cannam@99:     VampFeature   v1;
cannam@99:     VampFeatureV2 v2;
cannam@99: 
cannam@99: } VampFeatureUnion;
cannam@99: 
cannam@99: typedef struct _VampFeatureList
cannam@99: {
cannam@99:     /** Number of features in this feature list. */
cannam@99:     unsigned int featureCount;
cannam@99: 
cannam@99:     /** Features in this feature list.  May be NULL if featureCount is
cannam@99:         zero.
cannam@99: 
cannam@99:         If present, this array must contain featureCount feature
cannam@99:         structures for a Vamp API version 1 plugin, or 2*featureCount
cannam@99:         feature unions for a Vamp API version 2 plugin.
cannam@99: 
cannam@99:         The features returned by an API version 2 plugin must consist
cannam@99:         of the same feature structures as in API version 1 for the
cannam@99:         first featureCount array elements, followed by featureCount
cannam@99:         unions that contain VampFeatureV2 structures (or NULL pointers
cannam@99:         if no V2 feature structures are present).
cannam@99:      */
cannam@99:     VampFeatureUnion *features;
cannam@99: 
cannam@99: } VampFeatureList;
cannam@99: 
cannam@99: typedef enum
cannam@99: {
cannam@99:     vampTimeDomain,
cannam@99:     vampFrequencyDomain
cannam@99: 
cannam@99: } VampInputDomain;
cannam@99: 
cannam@99: typedef void *VampPluginHandle;
cannam@99: 
cannam@99: typedef struct _VampPluginDescriptor
cannam@99: {
cannam@99:     /** API version with which this descriptor is compatible. */
cannam@99:     unsigned int vampApiVersion;
cannam@99: 
cannam@99:     /** Computer-usable name of the plugin. Must not change. [a-zA-Z0-9_] */
cannam@99:     const char *identifier;
cannam@99: 
cannam@99:     /** Human-readable name of the plugin. May be translatable. */
cannam@99:     const char *name;
cannam@99: 
cannam@99:     /** Human-readable short text about the plugin. May be translatable. */
cannam@99:     const char *description;
cannam@99: 
cannam@99:     /** Human-readable name of plugin's author or vendor. */
cannam@99:     const char *maker;
cannam@99: 
cannam@99:     /** Version number of the plugin. */
cannam@99:     int pluginVersion;
cannam@99: 
cannam@99:     /** Human-readable summary of copyright or licensing for plugin. */
cannam@99:     const char *copyright;
cannam@99: 
cannam@99:     /** Number of parameter inputs. */
cannam@99:     unsigned int parameterCount;
cannam@99: 
cannam@99:     /** Fixed descriptors for parameter inputs. */
cannam@99:     const VampParameterDescriptor **parameters;
cannam@99: 
cannam@99:     /** Number of programs. */
cannam@99:     unsigned int programCount;
cannam@99: 
cannam@99:     /** Fixed names for programs. */
cannam@99:     const char **programs;
cannam@99: 
cannam@99:     /** Preferred input domain for audio input (time or frequency). */
cannam@99:     VampInputDomain inputDomain;
cannam@99: 
cannam@99:     /** Create and return a new instance of this plugin. */
cannam@99:     VampPluginHandle (*instantiate)(const struct _VampPluginDescriptor *,
cannam@99:                                    float inputSampleRate);
cannam@99: 
cannam@99:     /** Destroy an instance of this plugin. */
cannam@99:     void (*cleanup)(VampPluginHandle);
cannam@99: 
cannam@99:     /** Initialise an instance following parameter configuration. */
cannam@99:     int (*initialise)(VampPluginHandle,
cannam@99:                       unsigned int inputChannels,
cannam@99:                       unsigned int stepSize, 
cannam@99:                       unsigned int blockSize);
cannam@99: 
cannam@99:     /** Reset an instance, ready to use again on new input data. */
cannam@99:     void (*reset)(VampPluginHandle);
cannam@99: 
cannam@99:     /** Get a parameter value. */
cannam@99:     float (*getParameter)(VampPluginHandle, int);
cannam@99: 
cannam@99:     /** Set a parameter value. May only be called before initialise. */
cannam@99:     void  (*setParameter)(VampPluginHandle, int, float);
cannam@99: 
cannam@99:     /** Get the current program (if programCount > 0). */
cannam@99:     unsigned int (*getCurrentProgram)(VampPluginHandle);
cannam@99: 
cannam@99:     /** Set the current program. May only be called before initialise. */
cannam@99:     void  (*selectProgram)(VampPluginHandle, unsigned int);
cannam@99:     
cannam@99:     /** Get the plugin's preferred processing window increment in samples. */
cannam@99:     unsigned int (*getPreferredStepSize)(VampPluginHandle);
cannam@99: 
cannam@99:     /** Get the plugin's preferred processing window size in samples. */
cannam@99:     unsigned int (*getPreferredBlockSize)(VampPluginHandle);
cannam@99: 
cannam@99:     /** Get the minimum number of input channels this plugin can handle. */
cannam@99:     unsigned int (*getMinChannelCount)(VampPluginHandle);
cannam@99: 
cannam@99:     /** Get the maximum number of input channels this plugin can handle. */
cannam@99:     unsigned int (*getMaxChannelCount)(VampPluginHandle);
cannam@99: 
cannam@99:     /** Get the number of feature outputs (distinct sets of results). */
cannam@99:     unsigned int (*getOutputCount)(VampPluginHandle);
cannam@99: 
cannam@99:     /** Get a descriptor for a given feature output. Returned pointer
cannam@99:         is valid only until next call to getOutputDescriptor for this
cannam@99:         handle, or releaseOutputDescriptor for this descriptor. Host
cannam@99:         must call releaseOutputDescriptor after use. */
cannam@99:     VampOutputDescriptor *(*getOutputDescriptor)(VampPluginHandle,
cannam@99:                                                  unsigned int);
cannam@99: 
cannam@99:     /** Destroy a descriptor for a feature output. */
cannam@99:     void (*releaseOutputDescriptor)(VampOutputDescriptor *);
cannam@99: 
cannam@99:     /** Process an input block and return a set of features. Returned
cannam@99:         pointer is valid only until next call to process,
cannam@99:         getRemainingFeatures, or cleanup for this handle, or
cannam@99:         releaseFeatureSet for this feature set. Host must call
cannam@99:         releaseFeatureSet after use. */
cannam@99:     VampFeatureList *(*process)(VampPluginHandle,
cannam@99:                                 const float *const *inputBuffers,
cannam@99:                                 int sec,
cannam@99:                                 int nsec);
cannam@99: 
cannam@99:     /** Return any remaining features at the end of processing. */
cannam@99:     VampFeatureList *(*getRemainingFeatures)(VampPluginHandle);
cannam@99: 
cannam@99:     /** Release a feature set returned from process or getRemainingFeatures. */
cannam@99:     void (*releaseFeatureSet)(VampFeatureList *);
cannam@99: 
cannam@99: } VampPluginDescriptor;
cannam@99: 
cannam@99: 
cannam@99: /** Get the descriptor for a given plugin index in this library.
cannam@99:     Return NULL if the index is outside the range of valid indices for
cannam@99:     this plugin library.
cannam@99: 
cannam@99:     The hostApiVersion argument tells the library code the highest
cannam@99:     Vamp API version supported by the host.  The function should
cannam@99:     return a plugin descriptor compatible with the highest API version
cannam@99:     supported by the library that is no higher than that supported by
cannam@99:     the host.  Provided the descriptor has the correct vampApiVersion
cannam@99:     field for its actual compatibility level, the host should be able
cannam@99:     to do the right thing with it: use it if possible, discard it
cannam@99:     otherwise.
cannam@99: 
cannam@99:     This is the only symbol that a Vamp plugin actually needs to
cannam@99:     export from its shared object; all others can be hidden.  See the
cannam@99:     accompanying documentation for notes on how to achieve this with
cannam@99:     certain compilers.
cannam@99: */
cannam@99: const VampPluginDescriptor *vampGetPluginDescriptor
cannam@99:     (unsigned int hostApiVersion, unsigned int index);
cannam@99: 
cannam@99: 
cannam@99: /** Function pointer type for vampGetPluginDescriptor. */
cannam@99: typedef const VampPluginDescriptor *(*VampGetPluginDescriptorFunction)
cannam@99:     (unsigned int, unsigned int);
cannam@99: 
cannam@99: #ifdef __cplusplus
cannam@99: }
cannam@99: #endif
cannam@99: 
cannam@99: #endif