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
|