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