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 
455 
456 #endif
457 
458 
459 
std::vector< OutputDescriptor > OutputList
bool hasDuration
True if the returned results for this output are known to have a duration field.
std::string label
Label for the sample of this feature.
Vamp::Plugin is a base class for plugin instance classes that provide feature extraction from audio o...
virtual size_t getPreferredStepSize() const
Get the preferred step size (window increment – the distance in sample frames between the start fram...
float sampleRate
Sample rate of the output results, as samples per second.
bool hasFixedBinCount
True if the output has the same number of values per sample for every output sample.
std::vector< float > values
Results for a single sample of this feature.
Results are evenly spaced in time (sampleRate specified below)
std::map< int, FeatureList > FeatureSet
Definition: FFT.h:43
float quantizeStep
Quantization resolution of the output values (e.g.
RealTime timestamp
Timestamp of the output feature.
std::string description
A human-readable short text describing the output.
Plugin(float inputSampleRate)
std::string identifier
The name of the output, in computer-usable form.
float minValue
Minimum value of the results in the output.
virtual ~Plugin()
std::vector< std::string > binNames
The (human-readable) names of each of the bins, if appropriate.
float maxValue
Maximum value of the results in the output.
float m_inputSampleRate
RealTime duration
Duration of the output feature.
std::string unit
The unit of the output, in human-readable form.
std::string name
The human-readable name of the output.
RealTime represents time values to nanosecond precision with accurate arithmetic and frame-rate conve...
bool hasTimestamp
True if an output feature has its own timestamp.
virtual std::string getType() const
Used to distinguish between Vamp::Plugin and other potential sibling subclasses of PluginBase...
#define _VAMP_SDK_PLUGSPACE_BEGIN(h)
Definition: plugguard.h:79
float getInputSampleRate() const
Retrieve the input sample rate set on construction.
std::vector< Feature > FeatureList
#define _VAMP_SDK_PLUGSPACE_END(h)
Definition: plugguard.h:80
bool hasDuration
True if an output feature has a specified duration.
Results from each process() align with that call&#39;s block start.
virtual size_t getMaxChannelCount() const
Get the maximum supported number of input channels.
A base class for plugins with optional configurable parameters, programs, etc.
size_t binCount
The number of values per result of the output.
bool isQuantized
True if the output values are quantized to a particular resolution.
virtual size_t getPreferredBlockSize() const
Get the preferred block size (window size – the number of sample frames passed in each block to the ...
virtual size_t getMinChannelCount() const
Get the minimum supported number of input channels.
SampleType sampleType
Positioning in time of the output results.
bool hasKnownExtents
True if the results in each output bin fall within a fixed numeric range (minimum and maximum values)...