VampPluginSDK  2.9
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 
50 namespace Vamp {
51 
124 class Plugin : public PluginBase
125 {
126 public:
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 
287  enum SampleType {
288 
291 
294 
296  VariableSampleRate
297  };
298 
303 
314  float sampleRate;
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 
431  virtual FeatureSet getRemainingFeatures() = 0;
432 
438  virtual std::string getType() const { return "Feature Extraction Plugin"; }
439 
443  float getInputSampleRate() const { return m_inputSampleRate; }
444 
445 protected:
446  Plugin(float inputSampleRate) :
447  m_inputSampleRate(inputSampleRate) { }
448 
450 };
451 
452 }
453 
454 _VAMP_SDK_PLUGSPACE_END(Plugin.h)
455 
456 #endif
457 
458 
459 
Vamp::Plugin::OutputDescriptor::sampleType
SampleType sampleType
Positioning in time of the output results.
Definition: vamp-sdk/Plugin.h:302
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::sampleRate
float sampleRate
Sample rate of the output results, as samples per second.
Definition: vamp-sdk/Plugin.h:314
Vamp::Plugin::Feature::values
std::vector< float > values
Results for a single sample of this feature.
Definition: vamp-sdk/Plugin.h:382
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::quantizeStep
float quantizeStep
Quantization resolution of the output values (e.g.
Definition: vamp-sdk/Plugin.h:285
Vamp::Plugin::~Plugin
virtual ~Plugin()
Definition: vamp-sdk/Plugin.h:127
Vamp::Plugin::Feature::label
std::string label
Label for the sample of this feature.
Definition: vamp-sdk/Plugin.h:387
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::FixedSampleRate
@ FixedSampleRate
Results are evenly spaced in time (sampleRate specified below)
Definition: vamp-sdk/Plugin.h:293
Vamp::Plugin::getInputSampleRate
float getInputSampleRate() const
Retrieve the input sample rate set on construction.
Definition: vamp-sdk/Plugin.h:443
Vamp::Plugin::OutputDescriptor::description
std::string description
A human-readable short text describing the output.
Definition: vamp-sdk/Plugin.h:227
Vamp::Plugin::Plugin
Plugin(float inputSampleRate)
Definition: vamp-sdk/Plugin.h:446
Vamp::Plugin::OutputDescriptor::identifier
std::string identifier
The name of the output, in computer-usable form.
Definition: vamp-sdk/Plugin.h:214
Vamp::Plugin::m_inputSampleRate
float m_inputSampleRate
Definition: vamp-sdk/Plugin.h:449
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::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::OutputDescriptor::minValue
float minValue
Minimum value of the results in the output.
Definition: vamp-sdk/Plugin.h:266
Vamp::Plugin::InputDomain
InputDomain
Definition: vamp-sdk/Plugin.h:152
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:206
Vamp::Plugin::getMinChannelCount
virtual size_t getMinChannelCount() const
Get the minimum supported number of input channels.
Definition: vamp-sdk/Plugin.h:199
_VAMP_SDK_PLUGSPACE_BEGIN
#define _VAMP_SDK_PLUGSPACE_BEGIN(h)
Definition: plugguard.h:79
Vamp::Plugin::getMaxChannelCount
virtual size_t getMaxChannelCount() const
Get the maximum supported number of input channels.
Definition: vamp-sdk/Plugin.h:204
plugguard.h
Vamp::Plugin::OutputDescriptor::maxValue
float maxValue
Maximum value of the results in the output.
Definition: vamp-sdk/Plugin.h:272
Vamp::Plugin::OutputDescriptor::OutputDescriptor
OutputDescriptor()
Definition: vamp-sdk/Plugin.h:322
Vamp::Plugin::OutputDescriptor::unit
std::string unit
The unit of the output, in human-readable form.
Definition: vamp-sdk/Plugin.h:232
Vamp::Plugin::Feature::Feature
Feature()
Definition: vamp-sdk/Plugin.h:389
Vamp::Plugin::OutputDescriptor::SampleType
SampleType
Definition: vamp-sdk/Plugin.h:287
Vamp::PluginBase
A base class for plugins with optional configurable parameters, programs, etc.
Definition: vamp-sdk/PluginBase.h:60
Vamp::Plugin
Definition: vamp-sdk/Plugin.h:124
Vamp::Plugin::Feature::timestamp
RealTime timestamp
Timestamp of the output feature.
Definition: vamp-sdk/Plugin.h:360
RealTime.h
Vamp::Plugin::OutputDescriptor::name
std::string name
The human-readable name of the output.
Definition: vamp-sdk/Plugin.h:220
Vamp::Plugin::OutputList
std::vector< OutputDescriptor > OutputList
Definition: vamp-sdk/Plugin.h:335
Vamp::Plugin::Feature::hasTimestamp
bool hasTimestamp
True if an output feature has its own timestamp.
Definition: vamp-sdk/Plugin.h:352
PluginBase.h
Vamp::Plugin::TimeDomain
@ TimeDomain
Definition: vamp-sdk/Plugin.h:152
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::OutputDescriptor::OneSamplePerStep
@ OneSamplePerStep
Results from each process() align with that call's block start.
Definition: vamp-sdk/Plugin.h:290
Vamp::Plugin::Feature
Definition: vamp-sdk/Plugin.h:344
Vamp::Plugin::Feature::hasDuration
bool hasDuration
True if an output feature has a specified duration.
Definition: vamp-sdk/Plugin.h:368
Vamp::RealTime
Definition: vamp-sdk/RealTime.h:66
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::OutputDescriptor::binCount
size_t binCount
The number of values per result of the output.
Definition: vamp-sdk/Plugin.h:247
Vamp::Plugin::FeatureList
std::vector< Feature > FeatureList
Definition: vamp-sdk/Plugin.h:393
Vamp
Definition: FFT.h:43
Vamp::Plugin::OutputDescriptor::isQuantized
bool isQuantized
True if the output values are quantized to a particular resolution.
Definition: vamp-sdk/Plugin.h:278
_VAMP_SDK_PLUGSPACE_END
#define _VAMP_SDK_PLUGSPACE_END(h)
Definition: plugguard.h:80
Vamp::Plugin::FeatureSet
std::map< int, FeatureList > FeatureSet
Definition: vamp-sdk/Plugin.h:395