annotate vamp/vamp.h @ 168:006a775133b1

* Re-do the way the v2 structure (with durations) is returned.
  I bungled backward compatibility -- I failed to spot the contiguous
  array returned from process()... duh.  Also bump library versions.

/* -*- c-basic-offset: 4 indent-tabs-mode: nil -*-  vi:set ts=8 sts=4 sw=4: */

/*
    Vamp

    An API for audio analysis and feature extraction plugins.

    Centre for Digital Music, Queen Mary, University of London.
    Copyright 2006 Chris Cannam.
  
    Permission is hereby granted, free of charge, to any person
    obtaining a copy of this software and associated documentation
    files (the "Software"), to deal in the Software without
    restriction, including without limitation the rights to use, copy,
    modify, merge, publish, distribute, sublicense, and/or sell copies
    of the Software, and to permit persons to whom the Software is
    furnished to do so, subject to the following conditions:

    The above copyright notice and this permission notice shall be
    included in all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
    ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
    CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
    WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

    Except as contained in this notice, the names of the Centre for
    Digital Music; Queen Mary, University of London; and Chris Cannam
    shall not be used in advertising or otherwise to promote the sale,
    use or other dealings in this Software without prior written
    authorization.
*/

#ifndef VAMP_HEADER_INCLUDED
#define VAMP_HEADER_INCLUDED

#ifdef __cplusplus
extern "C" {
#endif

/** 
 * Plugin API version.  This is incremented when a change is made that
 * changes the binary layout of the descriptor records.  When this
 * happens, there should be a mechanism for retaining compatibility
 * with older hosts and/or plugins.
 *
 * See also the vampApiVersion field in the plugin descriptor, and the
 * hostApiVersion argument to the vampGetPluginDescriptor function.
 */
#define VAMP_API_VERSION 2

/**
 * C language API for Vamp plugins.
 * 
 * This is the formal plugin API for Vamp.  Plugin authors may prefer
 * to use the C++ classes provided in the Vamp plugin SDK, instead of
 * using this API directly.  There is an adapter class provided that
 * makes C++ plugins available using this C API with relatively little
 * work, and the C++ headers are more thoroughly documented.
 *
 * IMPORTANT: The comments in this file summarise the purpose of each
 * of the declared fields and functions, but do not provide a complete
 * guide to their permitted values and expected usage.  Please refer
 * to the C++ headers in the Vamp plugin SDK for further details and
 * plugin lifecycle documentation.
 */

typedef struct _VampParameterDescriptor
{
    /** Computer-usable name of the parameter. Must not change. [a-zA-Z0-9_] */
    const char *identifier;

    /** Human-readable name of the parameter. May be translatable. */
    const char *name;

    /** Human-readable short text about the parameter.  May be translatable. */
    const char *description;

    /** Human-readable unit of the parameter. */
    const char *unit;

    /** Minimum value. */
    float minValue;

    /** Maximum value. */
    float maxValue;

    /** Default value. Plugin is responsible for setting this on initialise. */
    float defaultValue;

    /** 1 if parameter values are quantized to a particular resolution. */
    int isQuantized;

    /** Quantization resolution, if isQuantized. */
    float quantizeStep;

    /** Human-readable names of the values, if isQuantized.  May be NULL. */
    const char **valueNames;

} VampParameterDescriptor;

typedef enum
{
    /** Each process call returns results aligned with call's block start. */
    vampOneSamplePerStep,

    /** Returned results are evenly spaced at samplerate specified below. */
    vampFixedSampleRate,

    /** Returned results have their own individual timestamps. */
    vampVariableSampleRate

} VampSampleType;

typedef struct _VampOutputDescriptor
{
    /** Computer-usable name of the output. Must not change. [a-zA-Z0-9_] */
    const char *identifier;

    /** Human-readable name of the output. May be translatable. */
    const char *name;

    /** Human-readable short text about the output. May be translatable. */
    const char *description;

    /** Human-readable name of the unit of the output. */
    const char *unit;

    /** 1 if output has equal number of values for each returned result. */
    int hasFixedBinCount;

    /** Number of values per result, if hasFixedBinCount. */
    unsigned int binCount;

    /** Names of returned value bins, if hasFixedBinCount.  May be NULL. */
    const char **binNames;

    /** 1 if each returned value falls within the same fixed min/max range. */
    int hasKnownExtents;
    
    /** Minimum value for a returned result in any bin, if hasKnownExtents. */
    float minValue;

    /** Maximum value for a returned result in any bin, if hasKnownExtents. */
    float maxValue;

    /** 1 if returned results are quantized to a particular resolution. */
    int isQuantized;

    /** Quantization resolution for returned results, if isQuantized. */
    float quantizeStep;

    /** Time positioning method for returned results (see VampSampleType). */
    VampSampleType sampleType;

    /** Sample rate of returned results, if sampleType is vampFixedSampleRate.
       "Resolution" of result, if sampleType is vampVariableSampleRate. */
    float sampleRate;

} VampOutputDescriptor;

typedef struct _VampFeature
{
    /** 1 if the feature has a timestamp (i.e. if vampVariableSampleRate). */
    int hasTimestamp;

    /** Seconds component of timestamp. */
    int sec;

    /** Nanoseconds component of timestamp. */
    int nsec;

    /** Number of values.  Must be binCount if hasFixedBinCount. */
    unsigned int valueCount;

    /** Values for this returned sample. */
    float *values;

    /** Label for this returned sample.  May be NULL. */
    char *label;

} VampFeature;

typedef struct _VampFeatureV2
{
    /** 1 if the feature has a duration. */
    int hasDuration;

    /** Seconds component of duratiion. */
    int durationSec;

    /** Nanoseconds component of duration. */
    int durationNsec;

} VampFeatureV2;

typedef union _VampFeatureUnion
{
    // sizeof(featureV1) >= sizeof(featureV2) for backward compatibility
    VampFeature   v1;
    VampFeatureV2 v2;

} VampFeatureUnion;

typedef struct _VampFeatureList
{
    /** Number of features in this feature list. */
    unsigned int featureCount;

    /** Features in this feature list.  May be NULL if featureCount is
        zero.

        If present, this array must contain featureCount feature
        structures for a Vamp 1.0 plugin, or 2*featureCount feature
        unions for a Vamp 2.0 plugin.

        The features returned by a Vamp 2.0 plugin must consist of the
        same feature structures as in 1.0 for the first featureCount
        array elements, followed by featureCount unions that contain
        pointers to V2 feature structures (or NULL pointers if no V2
        feature structures are present).
     */
    VampFeatureUnion *features;

} VampFeatureList;

typedef enum
{
    vampTimeDomain,
    vampFrequencyDomain

} VampInputDomain;

typedef void *VampPluginHandle;

typedef struct _VampPluginDescriptor
{
    /** API version with which this descriptor is compatible. */
    unsigned int vampApiVersion;

    /** Computer-usable name of the plugin. Must not change. [a-zA-Z0-9_] */
    const char *identifier;

    /** Human-readable name of the plugin. May be translatable. */
    const char *name;

    /** Human-readable short text about the plugin. May be translatable. */
    const char *description;

    /** Human-readable name of plugin's author or vendor. */
    const char *maker;

    /** Version number of the plugin. */
    int pluginVersion;

    /** Human-readable summary of copyright or licensing for plugin. */
    const char *copyright;

    /** Number of parameter inputs. */
    unsigned int parameterCount;

    /** Fixed descriptors for parameter inputs. */
    const VampParameterDescriptor **parameters;

    /** Number of programs. */
    unsigned int programCount;

    /** Fixed names for programs. */
    const char **programs;

    /** Preferred input domain for audio input (time or frequency). */
    VampInputDomain inputDomain;

    /** Create and return a new instance of this plugin. */
    VampPluginHandle (*instantiate)(const struct _VampPluginDescriptor *,
                                   float inputSampleRate);

    /** Destroy an instance of this plugin. */
    void (*cleanup)(VampPluginHandle);

    /** Initialise an instance following parameter configuration. */
    int (*initialise)(VampPluginHandle,
                      unsigned int inputChannels,
                      unsigned int stepSize, 
                      unsigned int blockSize);

    /** Reset an instance, ready to use again on new input data. */
    void (*reset)(VampPluginHandle);

    /** Get a parameter value. */
    float (*getParameter)(VampPluginHandle, int);

    /** Set a parameter value. May only be called before initialise. */
    void  (*setParameter)(VampPluginHandle, int, float);

    /** Get the current program (if programCount > 0). */
    unsigned int (*getCurrentProgram)(VampPluginHandle);

    /** Set the current program. May only be called before initialise. */
    void  (*selectProgram)(VampPluginHandle, unsigned int);
    
    /** Get the plugin's preferred processing window increment in samples. */
    unsigned int (*getPreferredStepSize)(VampPluginHandle);

    /** Get the plugin's preferred processing window size in samples. */
    unsigned int (*getPreferredBlockSize)(VampPluginHandle);

    /** Get the minimum number of input channels this plugin can handle. */
    unsigned int (*getMinChannelCount)(VampPluginHandle);

    /** Get the maximum number of input channels this plugin can handle. */
    unsigned int (*getMaxChannelCount)(VampPluginHandle);

    /** Get the number of feature outputs (distinct sets of results). */
    unsigned int (*getOutputCount)(VampPluginHandle);

    /** Get a descriptor for a given feature output. Returned pointer
        is valid only until next call to getOutputDescriptor for this
        handle, or releaseOutputDescriptor for this descriptor. Host
        must call releaseOutputDescriptor after use. */
    VampOutputDescriptor *(*getOutputDescriptor)(VampPluginHandle,
                                                unsigned int);

    /** Destroy a descriptor for a feature output. */
    void (*releaseOutputDescriptor)(VampOutputDescriptor *);

    /** Process an input block and return a set of features. Returned
        pointer is valid only until next call to process,
        getRemainingFeatures, or cleanup for this handle, or
        releaseFeatureSet for this feature set. Host must call
        releaseFeatureSet after use. */
    VampFeatureList *(*process)(VampPluginHandle,
                                const float *const *inputBuffers,
                                int sec,
                                int nsec);

    /** Return any remaining features at the end of processing. */
    VampFeatureList *(*getRemainingFeatures)(VampPluginHandle);

    /** Release a feature set returned from process or getRemainingFeatures. */
    void (*releaseFeatureSet)(VampFeatureList *);

} VampPluginDescriptor;


/** Get the descriptor for a given plugin index in this library.
    Return NULL if the index is outside the range of valid indices for
    this plugin library.

    The hostApiVersion argument tells the library code the highest
    Vamp API version supported by the host.  The function should
    return a plugin descriptor compatible with the highest API version
    supported by the library that is no higher than that supported by
    the host.  Provided the descriptor has the correct vampApiVersion
    field for its actual compatibility level, the host should be able
    to do the right thing with it: use it if possible, discard it
    otherwise.

    This is the only symbol that a Vamp plugin actually needs to
    export from its shared object; all others can be hidden.  See the
    accompanying documentation for notes on how to achieve this with
    certain compilers.
*/
const VampPluginDescriptor *vampGetPluginDescriptor
    (unsigned int hostApiVersion, unsigned int index);


/** Function pointer type for vampGetPluginDescriptor. */
typedef const VampPluginDescriptor *(*VampGetPluginDescriptorFunction)
    (unsigned int, unsigned int);

#ifdef __cplusplus
}
#endif

#endif