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