annotate vamp-sdk/Plugin.h @ 3:0133b3513e2b

* Renamed sdk to vamp-sdk
author cannam
date Fri, 31 Mar 2006 15:08:27 +0000
parents
children 8f10d35a4090
rev   line source
cannam@3 1 /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*- vi:set ts=8 sts=4 sw=4: */
cannam@3 2
cannam@3 3 /*
cannam@3 4 Vamp
cannam@3 5
cannam@3 6 An API for audio analysis and feature extraction plugins.
cannam@3 7
cannam@3 8 Centre for Digital Music, Queen Mary, University of London.
cannam@3 9 Copyright 2006 Chris Cannam.
cannam@3 10
cannam@3 11 Permission is hereby granted, free of charge, to any person
cannam@3 12 obtaining a copy of this software and associated documentation
cannam@3 13 files (the "Software"), to deal in the Software without
cannam@3 14 restriction, including without limitation the rights to use, copy,
cannam@3 15 modify, merge, publish, distribute, sublicense, and/or sell copies
cannam@3 16 of the Software, and to permit persons to whom the Software is
cannam@3 17 furnished to do so, subject to the following conditions:
cannam@3 18
cannam@3 19 The above copyright notice and this permission notice shall be
cannam@3 20 included in all copies or substantial portions of the Software.
cannam@3 21
cannam@3 22 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
cannam@3 23 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
cannam@3 24 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
cannam@3 25 NONINFRINGEMENT. IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR
cannam@3 26 ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
cannam@3 27 CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
cannam@3 28 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
cannam@3 29
cannam@3 30 Except as contained in this notice, the names of the Centre for
cannam@3 31 Digital Music; Queen Mary, University of London; and Chris Cannam
cannam@3 32 shall not be used in advertising or otherwise to promote the sale,
cannam@3 33 use or other dealings in this Software without prior written
cannam@3 34 authorization.
cannam@3 35 */
cannam@3 36
cannam@3 37 #ifndef _VAMP_PLUGIN_H_
cannam@3 38 #define _VAMP_PLUGIN_H_
cannam@3 39
cannam@3 40 #include "PluginBase.h"
cannam@3 41 #include "RealTime.h"
cannam@3 42
cannam@3 43 #include <string>
cannam@3 44 #include <vector>
cannam@3 45 #include <map>
cannam@3 46
cannam@3 47 namespace Vamp {
cannam@3 48
cannam@3 49 /**
cannam@3 50 * Vamp::Plugin is a base class for plugin instance classes
cannam@3 51 * that provide feature extraction from audio or related data.
cannam@3 52 *
cannam@3 53 * In most cases, the input will be audio and the output will be a
cannam@3 54 * stream of derived data at a lower sampling resolution than the
cannam@3 55 * input.
cannam@3 56 *
cannam@3 57 * Note that this class inherits several abstract methods from
cannam@3 58 * PluginBase, that must be implemented by the subclass.
cannam@3 59 */
cannam@3 60
cannam@3 61 /**
cannam@3 62 * Plugin Lifecycle
cannam@3 63 * ================
cannam@3 64 *
cannam@3 65 * Feature extraction plugins are managed differently from real-time
cannam@3 66 * plugins (such as VST effects). The main difference is that the
cannam@3 67 * parameters for a feature extraction plugin are configured before
cannam@3 68 * the plugin is used, and do not change during use.
cannam@3 69 *
cannam@3 70 * 1. Host constructs the plugin, passing it the input sample rate.
cannam@3 71 * The plugin may do basic initialisation, but should not do anything
cannam@3 72 * computationally expensive at this point.
cannam@3 73 *
cannam@3 74 * 2. Host may query the plugin's available outputs.
cannam@3 75 *
cannam@3 76 * 3. Host queries programs and parameter descriptors, and may set
cannam@3 77 * some or all of them. Parameters that are not explicitly set should
cannam@3 78 * take their default values as specified in the parameter descriptor.
cannam@3 79 * When a program is set, the parameter values may change and the host
cannam@3 80 * will re-query them to check.
cannam@3 81 *
cannam@3 82 * 4. Host queries the preferred step size, block size, number of
cannam@3 83 * channels, and the number of values per feature for the plugin's
cannam@3 84 * outputs. These may all vary depending on the parameter values.
cannam@3 85 * (Note however that you cannot make the number of distinct outputs
cannam@3 86 * dependent on parameter values; nor can you make any of these depend
cannam@3 87 * on the number of input channels.)
cannam@3 88 *
cannam@3 89 * 5. Plugin is properly initialised with a call to initialise. This
cannam@3 90 * fixes the step size, block size, and number of channels, as well as
cannam@3 91 * all of the parameter and program settings. If the values passed in
cannam@3 92 * to initialise do not match the plugin's advertised preferred values
cannam@3 93 * from step 4, the plugin may refuse to initialise and return false
cannam@3 94 * (although if possible it should accept the new values).
cannam@3 95 *
cannam@3 96 * 6. Host will repeatedly call the process method to pass in blocks
cannam@3 97 * of input data. This method may return features extracted from that
cannam@3 98 * data (if the plugin is causal).
cannam@3 99 *
cannam@3 100 * 7. Host will call getRemainingFeatures exactly once, after all the
cannam@3 101 * input data has been processed. This may return any non-causal or
cannam@3 102 * leftover features.
cannam@3 103 *
cannam@3 104 * 8. At any point after initialise was called, the host may
cannam@3 105 * optionally call the reset method and restart processing. (This
cannam@3 106 * does not mean it can change the parameters, which are fixed from
cannam@3 107 * initialise until destruction.)
cannam@3 108 *
cannam@3 109 * A plugin does not need to handle the case where setParameter or
cannam@3 110 * selectProgram is called after initialise has been called. It's the
cannam@3 111 * host's responsibility not to do that.
cannam@3 112 */
cannam@3 113
cannam@3 114 class Plugin : public PluginBase
cannam@3 115 {
cannam@3 116 public:
cannam@3 117 /**
cannam@3 118 * Initialise a plugin to prepare it for use with the given number
cannam@3 119 * of input channels, step size (window increment, in sample
cannam@3 120 * frames) and block size (window size, in sample frames).
cannam@3 121 *
cannam@3 122 * The input sample rate should have been already specified at
cannam@3 123 * construction time.
cannam@3 124 *
cannam@3 125 * Return true for successful initialisation, false if the number
cannam@3 126 * of input channels, step size and/or block size cannot be
cannam@3 127 * supported.
cannam@3 128 */
cannam@3 129 virtual bool initialise(size_t inputChannels,
cannam@3 130 size_t stepSize,
cannam@3 131 size_t blockSize) = 0;
cannam@3 132
cannam@3 133 /**
cannam@3 134 * Reset the plugin after use, to prepare it for another clean
cannam@3 135 * run. Not called for the first initialisation (i.e. initialise
cannam@3 136 * must also do a reset).
cannam@3 137 */
cannam@3 138 virtual void reset() = 0;
cannam@3 139
cannam@3 140 enum InputDomain { TimeDomain, FrequencyDomain };
cannam@3 141
cannam@3 142 /**
cannam@3 143 * Get the plugin's required input domain. If this is TimeDomain,
cannam@3 144 * the samples provided to the process() function (below) will be
cannam@3 145 * in the time domain, as for a traditional audio processing
cannam@3 146 * plugin. If this is FrequencyDomain, the host will carry out a
cannam@3 147 * windowed FFT of size equal to the negotiated block size on the
cannam@3 148 * data before passing the frequency bin data in to process().
cannam@3 149 * The plugin does not get to choose the window type -- the host
cannam@3 150 * will either let the user do so, or will use a Hanning window.
cannam@3 151 */
cannam@3 152 virtual InputDomain getInputDomain() const = 0;
cannam@3 153
cannam@3 154 /**
cannam@3 155 * Get the preferred step size (window increment -- the distance
cannam@3 156 * in sample frames between the start frames of consecutive blocks
cannam@3 157 * passed to the process() function) for the plugin. This should
cannam@3 158 * be called before initialise().
cannam@3 159 */
cannam@3 160 virtual size_t getPreferredStepSize() const = 0;
cannam@3 161
cannam@3 162 /**
cannam@3 163 * Get the preferred block size (window size -- the number of
cannam@3 164 * sample frames passed in each block to the process() function).
cannam@3 165 * This should be called before initialise().
cannam@3 166 */
cannam@3 167 virtual size_t getPreferredBlockSize() const { return getPreferredStepSize(); }
cannam@3 168
cannam@3 169 /**
cannam@3 170 * Get the minimum supported number of input channels.
cannam@3 171 */
cannam@3 172 virtual size_t getMinChannelCount() const { return 1; }
cannam@3 173
cannam@3 174 /**
cannam@3 175 * Get the maximum supported number of input channels.
cannam@3 176 */
cannam@3 177 virtual size_t getMaxChannelCount() const { return 1; }
cannam@3 178
cannam@3 179 struct OutputDescriptor
cannam@3 180 {
cannam@3 181 /**
cannam@3 182 * The name of the output, in computer-usable form. Should be
cannam@3 183 * reasonably short and without whitespace or punctuation.
cannam@3 184 */
cannam@3 185 std::string name;
cannam@3 186
cannam@3 187 /**
cannam@3 188 * The human-readable name of the output.
cannam@3 189 */
cannam@3 190 std::string description;
cannam@3 191
cannam@3 192 /**
cannam@3 193 * The unit of the output, in human-readable form.
cannam@3 194 */
cannam@3 195 std::string unit;
cannam@3 196
cannam@3 197 /**
cannam@3 198 * True if the output has the same number of values per result
cannam@3 199 * for every output result. Outputs for which this is false
cannam@3 200 * are unlikely to be very useful in a general-purpose host.
cannam@3 201 */
cannam@3 202 bool hasFixedValueCount;
cannam@3 203
cannam@3 204 /**
cannam@3 205 * The number of values per result of the output. Undefined
cannam@3 206 * if hasFixedValueCount is false. If this is zero, the output
cannam@3 207 * is point data (i.e. only the time of each output is of
cannam@3 208 * interest, the value list will be empty).
cannam@3 209 *
cannam@3 210 * Note that this gives the number of values of a single
cannam@3 211 * output result, not of the output stream (which has one more
cannam@3 212 * dimension: time).
cannam@3 213 */
cannam@3 214 size_t valueCount;
cannam@3 215
cannam@3 216 /**
cannam@3 217 * The names of each of the values, if appropriate. This is
cannam@3 218 * always optional.
cannam@3 219 */
cannam@3 220 std::vector<std::string> valueNames;
cannam@3 221
cannam@3 222 /**
cannam@3 223 * True if the results in the output have a fixed numeric
cannam@3 224 * range (minimum and maximum values). Undefined if
cannam@3 225 * valueCount is zero.
cannam@3 226 */
cannam@3 227 bool hasKnownExtents;
cannam@3 228
cannam@3 229 /**
cannam@3 230 * Minimum value of the results in the output. Undefined if
cannam@3 231 * hasKnownExtents is false or valueCount is zero.
cannam@3 232 */
cannam@3 233 float minValue;
cannam@3 234
cannam@3 235 /**
cannam@3 236 * Maximum value of the results in the output. Undefined if
cannam@3 237 * hasKnownExtents is false or valueCount is zero.
cannam@3 238 */
cannam@3 239 float maxValue;
cannam@3 240
cannam@3 241 /**
cannam@3 242 * True if the output values are quantized to a particular
cannam@3 243 * resolution. Undefined if valueCount is zero.
cannam@3 244 */
cannam@3 245 bool isQuantized;
cannam@3 246
cannam@3 247 /**
cannam@3 248 * Quantization resolution of the output values (e.g. 1.0 if
cannam@3 249 * they are all integers). Undefined if isQuantized is false
cannam@3 250 * or valueCount is zero.
cannam@3 251 */
cannam@3 252 float quantizeStep;
cannam@3 253
cannam@3 254 enum SampleType {
cannam@3 255
cannam@3 256 /// Results from each process() align with that call's block start
cannam@3 257 OneSamplePerStep,
cannam@3 258
cannam@3 259 /// Results are evenly spaced in time (sampleRate specified below)
cannam@3 260 FixedSampleRate,
cannam@3 261
cannam@3 262 /// Results are unevenly spaced and have individual timestamps
cannam@3 263 VariableSampleRate
cannam@3 264 };
cannam@3 265
cannam@3 266 /**
cannam@3 267 * Positioning in time of the output results.
cannam@3 268 */
cannam@3 269 SampleType sampleType;
cannam@3 270
cannam@3 271 /**
cannam@3 272 * Sample rate of the output results. Undefined if sampleType
cannam@3 273 * is OneSamplePerStep.
cannam@3 274 *
cannam@3 275 * If sampleType is VariableSampleRate and this value is
cannam@3 276 * non-zero, then it may be used to calculate a resolution for
cannam@3 277 * the output (i.e. the "duration" of each value, in time).
cannam@3 278 * It's recommended to set this to zero if that behaviour is
cannam@3 279 * not desired.
cannam@3 280 */
cannam@3 281 float sampleRate;
cannam@3 282 };
cannam@3 283
cannam@3 284 typedef std::vector<OutputDescriptor> OutputList;
cannam@3 285
cannam@3 286 /**
cannam@3 287 * Get the outputs of this plugin. An output's index in this list
cannam@3 288 * is used as its numeric index when looking it up in the
cannam@3 289 * FeatureSet returned from the process() call.
cannam@3 290 */
cannam@3 291 virtual OutputList getOutputDescriptors() const = 0;
cannam@3 292
cannam@3 293 struct Feature
cannam@3 294 {
cannam@3 295 /**
cannam@3 296 * True if an output feature has its own timestamp. This is
cannam@3 297 * mandatory if the output has VariableSampleRate, and is
cannam@3 298 * likely to be disregarded otherwise.
cannam@3 299 */
cannam@3 300 bool hasTimestamp;
cannam@3 301
cannam@3 302 /**
cannam@3 303 * Timestamp of the output feature. This is mandatory if the
cannam@3 304 * output has VariableSampleRate, and is likely to be
cannam@3 305 * disregarded otherwise. Undefined if hasTimestamp is false.
cannam@3 306 */
cannam@3 307 RealTime timestamp;
cannam@3 308
cannam@3 309 /**
cannam@3 310 * Results for a single sample of this feature. If the output
cannam@3 311 * hasFixedValueCount, there must be the same number of values
cannam@3 312 * as the output's valueCount count.
cannam@3 313 */
cannam@3 314 std::vector<float> values;
cannam@3 315
cannam@3 316 /**
cannam@3 317 * Label for the sample of this feature.
cannam@3 318 */
cannam@3 319 std::string label;
cannam@3 320 };
cannam@3 321
cannam@3 322 typedef std::vector<Feature> FeatureList;
cannam@3 323 typedef std::map<int, FeatureList> FeatureSet; // key is output no
cannam@3 324
cannam@3 325 /**
cannam@3 326 * Process a single block of input data.
cannam@3 327 *
cannam@3 328 * If the plugin's inputDomain is TimeDomain, inputBuffers will
cannam@3 329 * point to one array of floats per input channel, and each of
cannam@3 330 * these arrays will contain blockSize consecutive audio samples
cannam@3 331 * (the host will zero-pad as necessary).
cannam@3 332 *
cannam@3 333 * If the plugin's inputDomain is FrequencyDomain, inputBuffers
cannam@3 334 * will point to one array of floats per input channel, and each
cannam@3 335 * of these arrays will contain blockSize/2 consecutive pairs of
cannam@3 336 * real and imaginary component floats corresponding to bins
cannam@3 337 * 0..(blockSize/2-1) of the FFT output.
cannam@3 338 *
cannam@3 339 * The timestamp is the real time in seconds of the start of the
cannam@3 340 * supplied block of samples.
cannam@3 341 *
cannam@3 342 * Return any features that have become available after this
cannam@3 343 * process call. (These do not necessarily have to fall within
cannam@3 344 * the process block, except for OneSamplePerStep outputs.)
cannam@3 345 */
cannam@3 346 virtual FeatureSet process(float **inputBuffers,
cannam@3 347 RealTime timestamp) = 0;
cannam@3 348
cannam@3 349 /**
cannam@3 350 * After all blocks have been processed, calculate and return any
cannam@3 351 * remaining features derived from the complete input.
cannam@3 352 */
cannam@3 353 virtual FeatureSet getRemainingFeatures() = 0;
cannam@3 354
cannam@3 355 virtual std::string getType() const { return "Feature Extraction Plugin"; }
cannam@3 356
cannam@3 357 protected:
cannam@3 358 Plugin(float inputSampleRate) :
cannam@3 359 m_inputSampleRate(inputSampleRate) { }
cannam@3 360
cannam@3 361 float m_inputSampleRate;
cannam@3 362 };
cannam@3 363
cannam@3 364 }
cannam@3 365
cannam@3 366 #endif
cannam@3 367
cannam@3 368
cannam@3 369