mirror of
https://github.com/cookiengineer/audacity
synced 2026-01-13 08:05:52 +01:00
Move library tree where it belongs
This commit is contained in:
ra
388
lib-src/libvamp/vamp/vamp.h
Normal file
388
lib-src/libvamp/vamp/vamp.h
Normal file
@@ -0,0 +1,388 @@
|
||||
/* -*- 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;
|
||||
|
||||
/** 1 if the returned results for this output are known to have a
|
||||
duration field.
|
||||
|
||||
This field is new in Vamp API version 2; it must not be tested
|
||||
for plugins that report an older API version in their plugin
|
||||
descriptor.
|
||||
*/
|
||||
int hasDuration;
|
||||
|
||||
} 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 API version 1 plugin, or 2*featureCount
|
||||
feature unions for a Vamp API version 2 plugin.
|
||||
|
||||
The features returned by an API version 2 plugin must consist
|
||||
of the same feature structures as in API version 1 for the
|
||||
first featureCount array elements, followed by featureCount
|
||||
unions that contain VampFeatureV2 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
|
||||
Reference in New Issue
Block a user