VampPluginSDK 2.10
vamp-sdk/Plugin.h
Go to the documentation of this file.
1/* -*- c-basic-offset: 4 indent-tabs-mode: nil -*- vi:set ts=8 sts=4 sw=4: */
2
3/*
4 Vamp
5
6 An API for audio analysis and feature extraction plugins.
7
8 Centre for Digital Music, Queen Mary, University of London.
9 Copyright 2006 Chris Cannam.
10
11 Permission is hereby granted, free of charge, to any person
12 obtaining a copy of this software and associated documentation
13 files (the "Software"), to deal in the Software without
14 restriction, including without limitation the rights to use, copy,
15 modify, merge, publish, distribute, sublicense, and/or sell copies
16 of the Software, and to permit persons to whom the Software is
17 furnished to do so, subject to the following conditions:
18
19 The above copyright notice and this permission notice shall be
20 included in all copies or substantial portions of the Software.
21
22 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
23 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
24 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
25 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
26 ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
27 CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
28 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
29
30 Except as contained in this notice, the names of the Centre for
31 Digital Music; Queen Mary, University of London; and Chris Cannam
32 shall not be used in advertising or otherwise to promote the sale,
33 use or other dealings in this Software without prior written
34 authorization.
35*/
36
37#ifndef _VAMP_SDK_PLUGIN_H_
38#define _VAMP_SDK_PLUGIN_H_
39
40#include <string>
41#include <vector>
42#include <map>
43
44#include "PluginBase.h"
45#include "RealTime.h"
46
47#include "plugguard.h"
49
50namespace Vamp {
51
124class Plugin : public PluginBase
125{
126public:
127 virtual ~Plugin() { }
128
141 virtual bool initialise(size_t inputChannels,
142 size_t stepSize,
143 size_t blockSize) = 0;
144
150 virtual void reset() = 0;
151
152 enum InputDomain { TimeDomain, FrequencyDomain };
153
169 virtual InputDomain getInputDomain() const = 0;
170
179 virtual size_t getPreferredBlockSize() const { return 0; }
180
194 virtual size_t getPreferredStepSize() const { return 0; }
195
199 virtual size_t getMinChannelCount() const { return 1; }
200
204 virtual size_t getMaxChannelCount() const { return 1; }
205
207 {
214 std::string identifier;
215
220 std::string name;
221
227 std::string description;
228
232 std::string unit;
233
240
247 size_t binCount;
248
253 std::vector<std::string> binNames;
254
261
266 float minValue;
267
272 float maxValue;
273
279
286
288
291
294
296 VariableSampleRate
297 };
298
303
315
321
322 OutputDescriptor() : // defaults for mandatory non-class-type members
323 hasFixedBinCount(false),
324 binCount(0),
325 hasKnownExtents(false),
326 minValue(0),
327 maxValue(0),
328 isQuantized(false),
329 quantizeStep(0),
330 sampleType(OneSamplePerStep),
331 sampleRate(0),
332 hasDuration(false) { }
333 };
334
335 typedef std::vector<OutputDescriptor> OutputList;
336
342 virtual OutputList getOutputDescriptors() const = 0;
343
344 struct Feature
345 {
353
361
369
376
382 std::vector<float> values;
383
387 std::string label;
388
389 Feature() : // defaults for mandatory non-class-type members
390 hasTimestamp(false), hasDuration(false) { }
391 };
392
393 typedef std::vector<Feature> FeatureList;
394
395 typedef std::map<int, FeatureList> FeatureSet; // key is output no
396
424 virtual FeatureSet process(const float *const *inputBuffers,
425 RealTime timestamp) = 0;
426
432
438 virtual std::string getType() const { return "Feature Extraction Plugin"; }
439
443 float getInputSampleRate() const { return m_inputSampleRate; }
444
445protected:
446 Plugin(float inputSampleRate) :
447 m_inputSampleRate(inputSampleRate) { }
448
450};
451
452}
453
455
456#endif
457
458
459
A base class for plugins with optional configurable parameters, programs, etc.
Vamp::Plugin is a base class for plugin instance classes that provide feature extraction from audio o...
std::vector< Feature > FeatureList
virtual size_t getMaxChannelCount() const
Get the maximum supported number of input channels.
Plugin(float inputSampleRate)
std::vector< OutputDescriptor > OutputList
virtual size_t getPreferredStepSize() const
Get the preferred step size (window increment – the distance in sample frames between the start frame...
virtual ~Plugin()
std::map< int, FeatureList > FeatureSet
virtual std::string getType() const
Used to distinguish between Vamp::Plugin and other potential sibling subclasses of PluginBase.
float m_inputSampleRate
float getInputSampleRate() const
Retrieve the input sample rate set on construction.
virtual void reset()=0
Reset the plugin after use, to prepare it for another clean run.
virtual size_t getMinChannelCount() const
Get the minimum supported number of input channels.
virtual OutputList getOutputDescriptors() const =0
Get the outputs of this plugin.
virtual InputDomain getInputDomain() const =0
Get the plugin's required input domain.
virtual size_t getPreferredBlockSize() const
Get the preferred block size (window size – the number of sample frames passed in each block to the p...
virtual FeatureSet process(const float *const *inputBuffers, RealTime timestamp)=0
Process a single block of input data.
virtual FeatureSet getRemainingFeatures()=0
After all blocks have been processed, calculate and return any remaining features derived from the co...
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,...
Definition: FFT.h:43
#define _VAMP_SDK_PLUGSPACE_BEGIN(h)
Definition: plugguard.h:79
#define _VAMP_SDK_PLUGSPACE_END(h)
Definition: plugguard.h:80
bool hasDuration
True if an output feature has a specified duration.
std::vector< float > values
Results for a single sample of this feature.
std::string label
Label for the sample of this feature.
bool hasTimestamp
True if an output feature has its own timestamp.
RealTime timestamp
Timestamp of the output feature.
RealTime duration
Duration of the output feature.
SampleType sampleType
Positioning in time of the output results.
bool isQuantized
True if the output values are quantized to a particular resolution.
std::vector< std::string > binNames
The (human-readable) names of each of the bins, if appropriate.
float quantizeStep
Quantization resolution of the output values (e.g.
float maxValue
Maximum value of the results in the output.
std::string unit
The unit of the output, in human-readable form.
bool hasDuration
True if the returned results for this output are known to have a duration field.
std::string name
The human-readable name of the output.
@ OneSamplePerStep
Results from each process() align with that call's block start.
@ FixedSampleRate
Results are evenly spaced in time (sampleRate specified below)
float minValue
Minimum value of the results in the output.
float sampleRate
Sample rate of the output results, as samples per second.
std::string identifier
The name of the output, in computer-usable form.
bool hasKnownExtents
True if the results in each output bin fall within a fixed numeric range (minimum and maximum values)...
bool hasFixedBinCount
True if the output has the same number of values per sample for every output sample.
std::string description
A human-readable short text describing the output.
size_t binCount
The number of values per result of the output.
RealTime represents time values to nanosecond precision with accurate arithmetic and frame-rate conve...