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