vamp-sdk/Plugin.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_SDK_PLUGIN_H_
#define _VAMP_SDK_PLUGIN_H_
#include <string>
#include <vector>
#include <map>
#include "PluginBase.h"
#include "RealTime.h"
#include "plugguard.h"
_VAMP_SDK_PLUGSPACE_BEGIN(Plugin.h)
namespace Vamp {
class Plugin : public PluginBase
{
public:
virtual ~Plugin() { }
virtual bool initialise(size_t inputChannels,
size_t stepSize,
size_t blockSize) = 0;
virtual void reset() = 0;
enum InputDomain { TimeDomain, FrequencyDomain };
virtual InputDomain getInputDomain() const = 0;
virtual size_t getPreferredBlockSize() const { return 0; }
virtual size_t getPreferredStepSize() const { return 0; }
virtual size_t getMinChannelCount() const { return 1; }
virtual size_t getMaxChannelCount() const { return 1; }
struct OutputDescriptor
{
std::string identifier;
std::string name;
std::string description;
std::string unit;
bool hasFixedBinCount;
size_t binCount;
std::vector<std::string> binNames;
bool hasKnownExtents;
float minValue;
float maxValue;
bool isQuantized;
float quantizeStep;
enum SampleType {
OneSamplePerStep,
FixedSampleRate,
VariableSampleRate
};
SampleType sampleType;
float sampleRate;
bool hasDuration;
OutputDescriptor() : // defaults for mandatory non-class-type members
hasFixedBinCount(false),
binCount(0),
hasKnownExtents(false),
minValue(0),
maxValue(0),
isQuantized(false),
quantizeStep(0),
sampleType(OneSamplePerStep),
sampleRate(0),
hasDuration(false) { }
};
typedef std::vector<OutputDescriptor> OutputList;
virtual OutputList getOutputDescriptors() const = 0;
struct Feature
{
bool hasTimestamp;
RealTime timestamp;
bool hasDuration;
RealTime duration;
std::vector<float> values;
std::string label;
Feature() : // defaults for mandatory non-class-type members
hasTimestamp(false), hasDuration(false) { }
};
typedef std::vector<Feature> FeatureList;
typedef std::map<int, FeatureList> FeatureSet; // key is output no
virtual FeatureSet process(const float *const *inputBuffers,
RealTime timestamp) = 0;
virtual FeatureSet getRemainingFeatures() = 0;
virtual std::string getType() const { return "Feature Extraction Plugin"; }
float getInputSampleRate() const { return m_inputSampleRate; }
protected:
Plugin(float inputSampleRate) :
m_inputSampleRate(inputSampleRate) { }
float m_inputSampleRate;
};
}
_VAMP_SDK_PLUGSPACE_END(Plugin.h)
#endif
Vamp::PluginBase
A base class for plugins with optional configurable parameters, programs, etc.
Definition vamp-sdk/PluginBase.h:61
Vamp::Plugin
Vamp::Plugin is a base class for plugin instance classes that provide feature extraction from audio o...
Definition vamp-sdk/Plugin.h:125
Vamp::Plugin::FeatureList
std::vector< Feature > FeatureList
Definition vamp-sdk/Plugin.h:393
Vamp::Plugin::getMaxChannelCount
virtual size_t getMaxChannelCount() const
Get the maximum supported number of input channels.
Definition vamp-sdk/Plugin.h:204
Vamp::Plugin::Plugin
Plugin(float inputSampleRate)
Definition vamp-sdk/Plugin.h:446
Vamp::Plugin::OutputList
std::vector< OutputDescriptor > OutputList
Definition vamp-sdk/Plugin.h:335
Vamp::Plugin::getPreferredStepSize
virtual size_t getPreferredStepSize() const
Get the preferred step size (window increment – the distance in sample frames between the start frame...
Definition vamp-sdk/Plugin.h:194
Vamp::Plugin::InputDomain
InputDomain
Definition vamp-sdk/Plugin.h:152
Vamp::Plugin::~Plugin
virtual ~Plugin()
Definition vamp-sdk/Plugin.h:127
Vamp::Plugin::FeatureSet
std::map< int, FeatureList > FeatureSet
Definition vamp-sdk/Plugin.h:395
Vamp::Plugin::getType
virtual std::string getType() const
Used to distinguish between Vamp::Plugin and other potential sibling subclasses of PluginBase.
Definition vamp-sdk/Plugin.h:438
Vamp::Plugin::m_inputSampleRate
float m_inputSampleRate
Definition vamp-sdk/Plugin.h:449
Vamp::Plugin::getInputSampleRate
float getInputSampleRate() const
Retrieve the input sample rate set on construction.
Definition vamp-sdk/Plugin.h:443
Vamp::Plugin::reset
virtual void reset()=0
Reset the plugin after use, to prepare it for another clean run.
Vamp::Plugin::getMinChannelCount
virtual size_t getMinChannelCount() const
Get the minimum supported number of input channels.
Definition vamp-sdk/Plugin.h:199
Vamp::Plugin::getOutputDescriptors
virtual OutputList getOutputDescriptors() const =0
Get the outputs of this plugin.
Vamp::Plugin::getInputDomain
virtual InputDomain getInputDomain() const =0
Get the plugin's required input domain.
Vamp::Plugin::getPreferredBlockSize
virtual size_t getPreferredBlockSize() const
Get the preferred block size (window size – the number of sample frames passed in each block to the p...
Definition vamp-sdk/Plugin.h:179
Vamp::Plugin::process
virtual FeatureSet process(const float *const *inputBuffers, RealTime timestamp)=0
Process a single block of input data.
Vamp::Plugin::getRemainingFeatures
virtual FeatureSet getRemainingFeatures()=0
After all blocks have been processed, calculate and return any remaining features derived from the co...
Vamp::Plugin::initialise
virtual bool initialise(size_t inputChannels, size_t stepSize, size_t blockSize)=0
Initialise a plugin to prepare it for use with the given number of input channels,...
Vamp
Definition FFT.h:43
plugguard.h
_VAMP_SDK_PLUGSPACE_BEGIN
#define _VAMP_SDK_PLUGSPACE_BEGIN(h)
Definition plugguard.h:79
_VAMP_SDK_PLUGSPACE_END
#define _VAMP_SDK_PLUGSPACE_END(h)
Definition plugguard.h:80
Vamp::Plugin::Feature
Definition vamp-sdk/Plugin.h:345
Vamp::Plugin::Feature::hasDuration
bool hasDuration
True if an output feature has a specified duration.
Definition vamp-sdk/Plugin.h:368
Vamp::Plugin::Feature::values
std::vector< float > values
Results for a single sample of this feature.
Definition vamp-sdk/Plugin.h:382
Vamp::Plugin::Feature::label
std::string label
Label for the sample of this feature.
Definition vamp-sdk/Plugin.h:387
Vamp::Plugin::Feature::hasTimestamp
bool hasTimestamp
True if an output feature has its own timestamp.
Definition vamp-sdk/Plugin.h:352
Vamp::Plugin::Feature::timestamp
RealTime timestamp
Timestamp of the output feature.
Definition vamp-sdk/Plugin.h:360
Vamp::Plugin::Feature::Feature
Feature()
Definition vamp-sdk/Plugin.h:389
Vamp::Plugin::Feature::duration
RealTime duration
Duration of the output feature.
Definition vamp-sdk/Plugin.h:375
Vamp::Plugin::OutputDescriptor
Definition vamp-sdk/Plugin.h:207
Vamp::Plugin::OutputDescriptor::sampleType
SampleType sampleType
Positioning in time of the output results.
Definition vamp-sdk/Plugin.h:302
Vamp::Plugin::OutputDescriptor::isQuantized
bool isQuantized
True if the output values are quantized to a particular resolution.
Definition vamp-sdk/Plugin.h:278
Vamp::Plugin::OutputDescriptor::OutputDescriptor
OutputDescriptor()
Definition vamp-sdk/Plugin.h:322
Vamp::Plugin::OutputDescriptor::binNames
std::vector< std::string > binNames
The (human-readable) names of each of the bins, if appropriate.
Definition vamp-sdk/Plugin.h:253
Vamp::Plugin::OutputDescriptor::quantizeStep
float quantizeStep
Quantization resolution of the output values (e.g.
Definition vamp-sdk/Plugin.h:285
Vamp::Plugin::OutputDescriptor::maxValue
float maxValue
Maximum value of the results in the output.
Definition vamp-sdk/Plugin.h:272
Vamp::Plugin::OutputDescriptor::unit
std::string unit
The unit of the output, in human-readable form.
Definition vamp-sdk/Plugin.h:232
Vamp::Plugin::OutputDescriptor::hasDuration
bool hasDuration
True if the returned results for this output are known to have a duration field.
Definition vamp-sdk/Plugin.h:320
Vamp::Plugin::OutputDescriptor::name
std::string name
The human-readable name of the output.
Definition vamp-sdk/Plugin.h:220
Vamp::Plugin::OutputDescriptor::SampleType
SampleType
Definition vamp-sdk/Plugin.h:287
Vamp::Plugin::OutputDescriptor::OneSamplePerStep
@ OneSamplePerStep
Results from each process() align with that call's block start.
Definition vamp-sdk/Plugin.h:290
Vamp::Plugin::OutputDescriptor::FixedSampleRate
@ FixedSampleRate
Results are evenly spaced in time (sampleRate specified below)
Definition vamp-sdk/Plugin.h:293
Vamp::Plugin::OutputDescriptor::minValue
float minValue
Minimum value of the results in the output.
Definition vamp-sdk/Plugin.h:266
Vamp::Plugin::OutputDescriptor::sampleRate
float sampleRate
Sample rate of the output results, as samples per second.
Definition vamp-sdk/Plugin.h:314
Vamp::Plugin::OutputDescriptor::identifier
std::string identifier
The name of the output, in computer-usable form.
Definition vamp-sdk/Plugin.h:214
Vamp::Plugin::OutputDescriptor::hasKnownExtents
bool hasKnownExtents
True if the results in each output bin fall within a fixed numeric range (minimum and maximum values)...
Definition vamp-sdk/Plugin.h:260
Vamp::Plugin::OutputDescriptor::hasFixedBinCount
bool hasFixedBinCount
True if the output has the same number of values per sample for every output sample.
Definition vamp-sdk/Plugin.h:239
Vamp::Plugin::OutputDescriptor::description
std::string description
A human-readable short text describing the output.
Definition vamp-sdk/Plugin.h:227
Vamp::Plugin::OutputDescriptor::binCount
size_t binCount
The number of values per result of the output.
Definition vamp-sdk/Plugin.h:247
Vamp::RealTime
RealTime represents time values to nanosecond precision with accurate arithmetic and frame-rate conve...
Definition vamp-sdk/RealTime.h:67
PluginBase.h
RealTime.h