vamp.h
Go to the documentation of this file.
/* -*- 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
#define VAMP_API_VERSION 2
typedef struct _VampParameterDescriptor
{
const char *identifier;
const char *name;
const char *description;
const char *unit;
float minValue;
float maxValue;
float defaultValue;
int isQuantized;
float quantizeStep;
const char **valueNames;
} VampParameterDescriptor;
typedef enum
{
vampOneSamplePerStep,
vampFixedSampleRate,
vampVariableSampleRate
} VampSampleType;
typedef struct _VampOutputDescriptor
{
const char *identifier;
const char *name;
const char *description;
const char *unit;
int hasFixedBinCount;
unsigned int binCount;
const char **binNames;
int hasKnownExtents;
float minValue;
float maxValue;
int isQuantized;
float quantizeStep;
VampSampleType sampleType;
float sampleRate;
int hasDuration;
} VampOutputDescriptor;
typedef struct _VampFeature
{
int hasTimestamp;
int sec;
int nsec;
unsigned int valueCount;
float *values;
char *label;
} VampFeature;
typedef struct _VampFeatureV2
{
int hasDuration;
int durationSec;
int durationNsec;
} VampFeatureV2;
typedef union _VampFeatureUnion
{
// sizeof(featureV1) >= sizeof(featureV2) for backward compatibility
VampFeature v1;
VampFeatureV2 v2;
} VampFeatureUnion;
typedef struct _VampFeatureList
{
unsigned int featureCount;
VampFeatureUnion *features;
} VampFeatureList;
typedef enum
{
vampTimeDomain,
vampFrequencyDomain
} VampInputDomain;
typedef void *VampPluginHandle;
typedef struct _VampPluginDescriptor
{
unsigned int vampApiVersion;
const char *identifier;
const char *name;
const char *description;
const char *maker;
int pluginVersion;
const char *copyright;
unsigned int parameterCount;
const VampParameterDescriptor **parameters;
unsigned int programCount;
const char **programs;
VampInputDomain inputDomain;
VampPluginHandle (*instantiate)(const struct _VampPluginDescriptor *,
float inputSampleRate);
void (*cleanup)(VampPluginHandle);
int (*initialise)(VampPluginHandle,
unsigned int inputChannels,
unsigned int stepSize,
unsigned int blockSize);
void (*reset)(VampPluginHandle);
float (*getParameter)(VampPluginHandle, int);
void (*setParameter)(VampPluginHandle, int, float);
unsigned int (*getCurrentProgram)(VampPluginHandle);
void (*selectProgram)(VampPluginHandle, unsigned int);
unsigned int (*getPreferredStepSize)(VampPluginHandle);
unsigned int (*getPreferredBlockSize)(VampPluginHandle);
unsigned int (*getMinChannelCount)(VampPluginHandle);
unsigned int (*getMaxChannelCount)(VampPluginHandle);
unsigned int (*getOutputCount)(VampPluginHandle);
VampOutputDescriptor *(*getOutputDescriptor)(VampPluginHandle,
unsigned int);
void (*releaseOutputDescriptor)(VampOutputDescriptor *);
VampFeatureList *(*process)(VampPluginHandle,
const float *const *inputBuffers,
int sec,
int nsec);
VampFeatureList *(*getRemainingFeatures)(VampPluginHandle);
void (*releaseFeatureSet)(VampFeatureList *);
} VampPluginDescriptor;
const VampPluginDescriptor *vampGetPluginDescriptor
(unsigned int hostApiVersion, unsigned int index);
typedef const VampPluginDescriptor *(*VampGetPluginDescriptorFunction)
(unsigned int, unsigned int);
#ifdef __cplusplus
}
#endif
#endif
_VampFeature::sec
int sec
Seconds component of timestamp.
Definition: vamp.h:180
_VampOutputDescriptor::maxValue
float maxValue
Maximum value for a returned result in any bin, if hasKnownExtents.
Definition: vamp.h:148
VampInputDomain
VampInputDomain
Definition: vamp.h:239
vampTimeDomain
Definition: vamp.h:241
VampOutputDescriptor
struct _VampOutputDescriptor VampOutputDescriptor
VampFeatureV2
struct _VampFeatureV2 VampFeatureV2
_VampFeatureUnion::v2
VampFeatureV2 v2
Definition: vamp.h:213
_VampPluginDescriptor::selectProgram
void(* selectProgram)(VampPluginHandle, unsigned int)
Set the current program.
Definition: vamp.h:312
vampOneSamplePerStep
Each process call returns results aligned with call&#39;s block start.
Definition: vamp.h:108
_VampOutputDescriptor::binCount
unsigned int binCount
Number of values per result, if hasFixedBinCount.
Definition: vamp.h:136
_VampPluginDescriptor::reset
void(* reset)(VampPluginHandle)
Reset an instance, ready to use again on new input data.
Definition: vamp.h:300
_VampOutputDescriptor::identifier
const char * identifier
Computer-usable name of the output.
Definition: vamp.h:121
_VampPluginDescriptor::getOutputCount
unsigned int(* getOutputCount)(VampPluginHandle)
Get the number of feature outputs (distinct sets of results).
Definition: vamp.h:327
_VampOutputDescriptor::minValue
float minValue
Minimum value for a returned result in any bin, if hasKnownExtents.
Definition: vamp.h:145
VampFeatureList
struct _VampFeatureList VampFeatureList
_VampFeatureUnion::v1
VampFeature v1
Definition: vamp.h:212
_VampPluginDescriptor::maker
const char * maker
Human-readable name of plugin&#39;s author or vendor.
Definition: vamp.h:263
_VampFeature::hasTimestamp
int hasTimestamp
1 if the feature has a timestamp (i.e.
Definition: vamp.h:177
_VampFeature
Definition: vamp.h:174
_VampParameterDescriptor
C language API for Vamp plugins.
Definition: vamp.h:71
_VampFeatureV2::durationSec
int durationSec
Seconds component of duratiion.
Definition: vamp.h:202
_VampParameterDescriptor::valueNames
const char ** valueNames
Human-readable names of the values, if isQuantized.
Definition: vamp.h:101
_VampOutputDescriptor::unit
const char * unit
Human-readable name of the unit of the output.
Definition: vamp.h:130
_VampPluginDescriptor::copyright
const char * copyright
Human-readable summary of copyright or licensing for plugin.
Definition: vamp.h:269
_VampParameterDescriptor::name
const char * name
Human-readable name of the parameter.
Definition: vamp.h:77
_VampFeatureList
Definition: vamp.h:217
_VampParameterDescriptor::isQuantized
int isQuantized
1 if parameter values are quantized to a particular resolution.
Definition: vamp.h:95
_VampPluginDescriptor::setParameter
void(* setParameter)(VampPluginHandle, int, float)
Set a parameter value.
Definition: vamp.h:306
_VampPluginDescriptor::programs
const char ** programs
Fixed names for programs.
Definition: vamp.h:281
_VampPluginDescriptor::getPreferredStepSize
unsigned int(* getPreferredStepSize)(VampPluginHandle)
Get the plugin&#39;s preferred processing window increment in samples.
Definition: vamp.h:315
_VampPluginDescriptor::identifier
const char * identifier
Computer-usable name of the plugin.
Definition: vamp.h:254
_VampOutputDescriptor
Definition: vamp.h:118
_VampPluginDescriptor::parameters
const VampParameterDescriptor ** parameters
Fixed descriptors for parameter inputs.
Definition: vamp.h:275
VampParameterDescriptor
struct _VampParameterDescriptor VampParameterDescriptor
C language API for Vamp plugins.
_VampOutputDescriptor::hasKnownExtents
int hasKnownExtents
1 if each returned value falls within the same fixed min/max range.
Definition: vamp.h:142
_VampPluginDescriptor::inputDomain
VampInputDomain inputDomain
Preferred input domain for audio input (time or frequency).
Definition: vamp.h:284
_VampPluginDescriptor
Definition: vamp.h:248
_VampFeatureV2::durationNsec
int durationNsec
Nanoseconds component of duration.
Definition: vamp.h:205
_VampPluginDescriptor::getMinChannelCount
unsigned int(* getMinChannelCount)(VampPluginHandle)
Get the minimum number of input channels this plugin can handle.
Definition: vamp.h:321
_VampParameterDescriptor::quantizeStep
float quantizeStep
Quantization resolution, if isQuantized.
Definition: vamp.h:98
_VampFeatureList::featureCount
unsigned int featureCount
Number of features in this feature list.
Definition: vamp.h:220
_VampParameterDescriptor::description
const char * description
Human-readable short text about the parameter.
Definition: vamp.h:80
VampSampleType
VampSampleType
Definition: vamp.h:105
_VampPluginDescriptor::programCount
unsigned int programCount
Number of programs.
Definition: vamp.h:278
vampGetPluginDescriptor
const VampPluginDescriptor * vampGetPluginDescriptor(unsigned int hostApiVersion, unsigned int index)
Get the descriptor for a given plugin index in this library.
Definition: plugins.cpp:54
_VampPluginDescriptor::cleanup
void(* cleanup)(VampPluginHandle)
Destroy an instance of this plugin.
Definition: vamp.h:291
_VampPluginDescriptor::getParameter
float(* getParameter)(VampPluginHandle, int)
Get a parameter value.
Definition: vamp.h:303
_VampOutputDescriptor::hasDuration
int hasDuration
1 if the returned results for this output are known to have a duration field.
Definition: vamp.h:170
vampVariableSampleRate
Returned results have their own individual timestamps.
Definition: vamp.h:114
_VampOutputDescriptor::isQuantized
int isQuantized
1 if returned results are quantized to a particular resolution.
Definition: vamp.h:151
_VampPluginDescriptor::pluginVersion
int pluginVersion
Version number of the plugin.
Definition: vamp.h:266
VampPluginHandle
void * VampPluginHandle
Definition: vamp.h:246
_VampParameterDescriptor::maxValue
float maxValue
Maximum value.
Definition: vamp.h:89
_VampFeatureUnion
Definition: vamp.h:209
VampPluginDescriptor
struct _VampPluginDescriptor VampPluginDescriptor
_VampPluginDescriptor::vampApiVersion
unsigned int vampApiVersion
API version with which this descriptor is compatible.
Definition: vamp.h:251
_VampOutputDescriptor::name
const char * name
Human-readable name of the output.
Definition: vamp.h:124
_VampFeature::label
char * label
Label for this returned sample.
Definition: vamp.h:192
_VampParameterDescriptor::defaultValue
float defaultValue
Default value.
Definition: vamp.h:92
vampFrequencyDomain
Definition: vamp.h:242
_VampFeatureList::features
VampFeatureUnion * features
Features in this feature list.
Definition: vamp.h:235
_VampPluginDescriptor::getMaxChannelCount
unsigned int(* getMaxChannelCount)(VampPluginHandle)
Get the maximum number of input channels this plugin can handle.
Definition: vamp.h:324
_VampPluginDescriptor::getPreferredBlockSize
unsigned int(* getPreferredBlockSize)(VampPluginHandle)
Get the plugin&#39;s preferred processing window size in samples.
Definition: vamp.h:318
vampFixedSampleRate
Returned results are evenly spaced at samplerate specified below.
Definition: vamp.h:111
_VampPluginDescriptor::initialise
int(* initialise)(VampPluginHandle, unsigned int inputChannels, unsigned int stepSize, unsigned int blockSize)
Initialise an instance following parameter configuration.
Definition: vamp.h:294
_VampPluginDescriptor::name
const char * name
Human-readable name of the plugin.
Definition: vamp.h:257
_VampOutputDescriptor::hasFixedBinCount
int hasFixedBinCount
1 if output has equal number of values for each returned result.
Definition: vamp.h:133
VampFeatureUnion
union _VampFeatureUnion VampFeatureUnion
_VampPluginDescriptor::releaseFeatureSet
void(* releaseFeatureSet)(VampFeatureList *)
Release a feature set returned from process or getRemainingFeatures.
Definition: vamp.h:353
_VampPluginDescriptor::description
const char * description
Human-readable short text about the plugin.
Definition: vamp.h:260
_VampFeature::valueCount
unsigned int valueCount
Number of values.
Definition: vamp.h:186
VampFeature
struct _VampFeature VampFeature
_VampPluginDescriptor::parameterCount
unsigned int parameterCount
Number of parameter inputs.
Definition: vamp.h:272
_VampOutputDescriptor::description
const char * description
Human-readable short text about the output.
Definition: vamp.h:127
_VampParameterDescriptor::identifier
const char * identifier
Computer-usable name of the parameter.
Definition: vamp.h:74
_VampParameterDescriptor::minValue
float minValue
Minimum value.
Definition: vamp.h:86
_VampOutputDescriptor::quantizeStep
float quantizeStep
Quantization resolution for returned results, if isQuantized.
Definition: vamp.h:154
_VampFeature::values
float * values
Values for this returned sample.
Definition: vamp.h:189
_VampParameterDescriptor::unit
const char * unit
Human-readable unit of the parameter.
Definition: vamp.h:83
_VampPluginDescriptor::getCurrentProgram
unsigned int(* getCurrentProgram)(VampPluginHandle)
Get the current program (if programCount > 0).
Definition: vamp.h:309
_VampOutputDescriptor::binNames
const char ** binNames
Names of returned value bins, if hasFixedBinCount.
Definition: vamp.h:139
_VampOutputDescriptor::sampleType
VampSampleType sampleType
Time positioning method for returned results (see VampSampleType).
Definition: vamp.h:157
_VampPluginDescriptor::releaseOutputDescriptor
void(* releaseOutputDescriptor)(VampOutputDescriptor *)
Destroy a descriptor for a feature output.
Definition: vamp.h:337
_VampOutputDescriptor::sampleRate
float sampleRate
Sample rate of returned results, if sampleType is vampFixedSampleRate.
Definition: vamp.h:161
_VampFeature::nsec
int nsec
Nanoseconds component of timestamp.
Definition: vamp.h:183
_VampFeatureV2::hasDuration
int hasDuration
1 if the feature has a duration.
Definition: vamp.h:199
_VampFeatureV2
Definition: vamp.h:196