Chris@49
|
1 /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*- vi:set ts=8 sts=4 sw=4: */
|
Chris@0
|
2
|
Chris@0
|
3 /*
|
Chris@52
|
4 Sonic Visualiser
|
Chris@52
|
5 An audio file viewer and annotation editor.
|
Chris@52
|
6 Centre for Digital Music, Queen Mary, University of London.
|
Chris@52
|
7 This file copyright 2006 Chris Cannam.
|
Chris@0
|
8
|
Chris@52
|
9 This program is free software; you can redistribute it and/or
|
Chris@52
|
10 modify it under the terms of the GNU General Public License as
|
Chris@52
|
11 published by the Free Software Foundation; either version 2 of the
|
Chris@52
|
12 License, or (at your option) any later version. See the file
|
Chris@52
|
13 COPYING included with this distribution for more information.
|
Chris@0
|
14 */
|
Chris@0
|
15
|
Chris@0
|
16 #ifndef _FEATURE_EXTRACTION_PLUGIN_H_
|
Chris@0
|
17 #define _FEATURE_EXTRACTION_PLUGIN_H_
|
Chris@0
|
18
|
Chris@50
|
19 #include "PluginInstance.h"
|
Chris@0
|
20
|
Chris@0
|
21 #include <string>
|
Chris@0
|
22 #include <vector>
|
Chris@0
|
23 #include <map>
|
Chris@0
|
24
|
Chris@0
|
25 #include "base/RealTime.h"
|
Chris@0
|
26
|
Chris@0
|
27 /**
|
Chris@0
|
28 * FeatureExtractionPlugin is a base class for plugin instance classes
|
Chris@0
|
29 * that provide feature extraction from audio or related data.
|
Chris@0
|
30 *
|
Chris@0
|
31 * In most cases, the input will be audio and the output will be a
|
Chris@0
|
32 * stream of derived data at a lower sampling resolution than the
|
Chris@0
|
33 * input.
|
Chris@50
|
34 *
|
Chris@50
|
35 * Note that this class inherits several abstract methods from
|
Chris@50
|
36 * PluginInstance, that must be implemented by the subclass.
|
Chris@0
|
37 */
|
Chris@0
|
38
|
Chris@50
|
39 class FeatureExtractionPlugin : public PluginInstance
|
Chris@0
|
40 {
|
Chris@0
|
41 public:
|
Chris@0
|
42 /**
|
Chris@0
|
43 * Initialise a plugin to prepare it for use with the given number
|
Chris@0
|
44 * of input channels, step size (window increment, in sample
|
Chris@0
|
45 * frames) and block size (window size, in sample frames).
|
Chris@0
|
46 *
|
Chris@0
|
47 * The input sample rate should have been already specified at
|
Chris@0
|
48 * construction time.
|
Chris@0
|
49 *
|
Chris@0
|
50 * Return true for successful initialisation, false if the number
|
Chris@0
|
51 * of input channels, step size and/or block size cannot be
|
Chris@0
|
52 * supported.
|
Chris@0
|
53 */
|
Chris@0
|
54 virtual bool initialise(size_t inputChannels,
|
Chris@0
|
55 size_t stepSize,
|
Chris@0
|
56 size_t blockSize) = 0;
|
Chris@0
|
57
|
Chris@0
|
58 /**
|
Chris@0
|
59 * Reset the plugin after use, to prepare it for another clean
|
Chris@0
|
60 * run. Not called for the first initialisation (i.e. initialise
|
Chris@0
|
61 * must also do a reset).
|
Chris@0
|
62 */
|
Chris@0
|
63 virtual void reset() = 0;
|
Chris@0
|
64
|
Chris@0
|
65 /**
|
Chris@0
|
66 * Get the preferred step size (window increment -- the distance
|
Chris@0
|
67 * in sample frames between the start frames of consecutive blocks
|
Chris@0
|
68 * passed to the process() function) for the plugin. This should
|
Chris@0
|
69 * be called before initialise().
|
Chris@0
|
70 */
|
Chris@0
|
71 virtual size_t getPreferredStepSize() const = 0;
|
Chris@0
|
72
|
Chris@0
|
73 /**
|
Chris@0
|
74 * Get the preferred block size (window size -- the number of
|
Chris@0
|
75 * sample frames passed in each block to the process() function).
|
Chris@0
|
76 * This should be called before initialise().
|
Chris@0
|
77 */
|
Chris@0
|
78 virtual size_t getPreferredBlockSize() const { return getPreferredStepSize(); }
|
Chris@0
|
79
|
Chris@0
|
80 /**
|
Chris@0
|
81 * Get the minimum supported number of input channels.
|
Chris@0
|
82 */
|
Chris@0
|
83 virtual size_t getMinChannelCount() const { return 1; }
|
Chris@0
|
84
|
Chris@0
|
85 /**
|
Chris@0
|
86 * Get the maximum supported number of input channels.
|
Chris@0
|
87 */
|
Chris@0
|
88 virtual size_t getMaxChannelCount() const { return 1; }
|
Chris@0
|
89
|
Chris@0
|
90 struct OutputDescriptor
|
Chris@0
|
91 {
|
Chris@0
|
92 /**
|
Chris@0
|
93 * The name of the output, in computer-usable form. Should be
|
Chris@0
|
94 * reasonably short and without whitespace or punctuation.
|
Chris@0
|
95 */
|
Chris@0
|
96 std::string name;
|
Chris@0
|
97
|
Chris@0
|
98 /**
|
Chris@0
|
99 * The human-readable name of the output.
|
Chris@0
|
100 */
|
Chris@0
|
101 std::string description;
|
Chris@0
|
102
|
Chris@0
|
103 /**
|
Chris@0
|
104 * The unit of the output, in human-readable form.
|
Chris@0
|
105 */
|
Chris@0
|
106 std::string unit;
|
Chris@0
|
107
|
Chris@0
|
108 /**
|
Chris@0
|
109 * True if the output has the same number of values per result
|
Chris@0
|
110 * for every output result. Outputs for which this is false
|
Chris@0
|
111 * are unlikely to be very useful in a general-purpose host.
|
Chris@0
|
112 */
|
Chris@0
|
113 bool hasFixedValueCount;
|
Chris@0
|
114
|
Chris@0
|
115 /**
|
Chris@0
|
116 * The number of values per result of the output. Undefined
|
Chris@0
|
117 * if hasFixedValueCount is false. If this is zero, the output
|
Chris@0
|
118 * is point data (i.e. only the time of each output is of
|
Chris@0
|
119 * interest, the value list will be empty).
|
Chris@0
|
120 *
|
Chris@0
|
121 * Note that this gives the number of values of a single
|
Chris@0
|
122 * output result, not of the output stream (which has one more
|
Chris@0
|
123 * dimension: time).
|
Chris@0
|
124 */
|
Chris@0
|
125 size_t valueCount;
|
Chris@0
|
126
|
Chris@0
|
127 /**
|
Chris@19
|
128 * The names of each of the values, if appropriate. This is
|
Chris@19
|
129 * always optional.
|
Chris@19
|
130 */
|
Chris@19
|
131 std::vector<std::string> valueNames;
|
Chris@19
|
132
|
Chris@19
|
133 /**
|
Chris@0
|
134 * True if the results in the output have a fixed numeric
|
Chris@0
|
135 * range (minimum and maximum values). Undefined if
|
Chris@0
|
136 * valueCount is zero.
|
Chris@0
|
137 */
|
Chris@0
|
138 bool hasKnownExtents;
|
Chris@0
|
139
|
Chris@0
|
140 /**
|
Chris@0
|
141 * Minimum value of the results in the output. Undefined if
|
Chris@0
|
142 * hasKnownExtents is false or valueCount is zero.
|
Chris@0
|
143 */
|
Chris@0
|
144 float minValue;
|
Chris@0
|
145
|
Chris@0
|
146 /**
|
Chris@0
|
147 * Maximum value of the results in the output. Undefined if
|
Chris@0
|
148 * hasKnownExtents is false or valueCount is zero.
|
Chris@0
|
149 */
|
Chris@0
|
150 float maxValue;
|
Chris@0
|
151
|
Chris@0
|
152 /**
|
Chris@0
|
153 * True if the output values are quantized to a particular
|
Chris@0
|
154 * resolution. Undefined if valueCount is zero.
|
Chris@0
|
155 */
|
Chris@0
|
156 bool isQuantized;
|
Chris@0
|
157
|
Chris@0
|
158 /**
|
Chris@0
|
159 * Quantization resolution of the output values (e.g. 1.0 if
|
Chris@0
|
160 * they are all integers). Undefined if isQuantized is false
|
Chris@0
|
161 * or valueCount is zero.
|
Chris@0
|
162 */
|
Chris@0
|
163 float quantizeStep;
|
Chris@0
|
164
|
Chris@0
|
165 enum SampleType {
|
Chris@0
|
166
|
Chris@0
|
167 /// Results from each process() align with that call's block start
|
Chris@0
|
168 OneSamplePerStep,
|
Chris@0
|
169
|
Chris@0
|
170 /// Results are evenly spaced in time (sampleRate specified below)
|
Chris@0
|
171 FixedSampleRate,
|
Chris@0
|
172
|
Chris@0
|
173 /// Results are unevenly spaced and have individual timestamps
|
Chris@0
|
174 VariableSampleRate
|
Chris@0
|
175 };
|
Chris@0
|
176
|
Chris@0
|
177 /**
|
Chris@0
|
178 * Positioning in time of the output results.
|
Chris@0
|
179 */
|
Chris@0
|
180 SampleType sampleType;
|
Chris@0
|
181
|
Chris@0
|
182 /**
|
Chris@0
|
183 * Sample rate of the output results. Undefined if sampleType
|
Chris@0
|
184 * is OneSamplePerStep.
|
Chris@0
|
185 *
|
Chris@0
|
186 * If sampleType is VariableSampleRate and this value is
|
Chris@0
|
187 * non-zero, then it may be used to calculate a resolution for
|
Chris@0
|
188 * the output (i.e. the "duration" of each value, in time).
|
Chris@0
|
189 * It's recommended to set this to zero if that behaviour is
|
Chris@0
|
190 * not desired.
|
Chris@0
|
191 */
|
Chris@0
|
192 float sampleRate;
|
Chris@0
|
193 };
|
Chris@0
|
194
|
Chris@0
|
195 typedef std::vector<OutputDescriptor> OutputList;
|
Chris@0
|
196
|
Chris@0
|
197 /**
|
Chris@0
|
198 * Get the outputs of this plugin. An output's index in this list
|
Chris@0
|
199 * is used as its numeric index when looking it up in the
|
Chris@0
|
200 * FeatureSet returned from the process() call.
|
Chris@0
|
201 */
|
Chris@0
|
202 virtual OutputList getOutputDescriptors() const = 0;
|
Chris@0
|
203
|
Chris@0
|
204 struct Feature
|
Chris@0
|
205 {
|
Chris@0
|
206 /**
|
Chris@0
|
207 * True if an output feature has its own timestamp. This is
|
Chris@0
|
208 * mandatory if the output has VariableSampleRate, and is
|
Chris@0
|
209 * likely to be disregarded otherwise.
|
Chris@0
|
210 */
|
Chris@0
|
211 bool hasTimestamp;
|
Chris@0
|
212
|
Chris@0
|
213 /**
|
Chris@0
|
214 * Timestamp of the output feature. This is mandatory if the
|
Chris@0
|
215 * output has VariableSampleRate, and is likely to be
|
Chris@0
|
216 * disregarded otherwise. Undefined if hasTimestamp is false.
|
Chris@0
|
217 */
|
Chris@0
|
218 RealTime timestamp;
|
Chris@0
|
219
|
Chris@0
|
220 /**
|
Chris@0
|
221 * Results for a single sample of this feature. If the output
|
Chris@0
|
222 * hasFixedValueCount, there must be the same number of values
|
Chris@0
|
223 * as the output's valueCount count.
|
Chris@0
|
224 */
|
Chris@0
|
225 std::vector<float> values;
|
Chris@0
|
226
|
Chris@0
|
227 /**
|
Chris@0
|
228 * Label for the sample of this feature.
|
Chris@0
|
229 */
|
Chris@0
|
230 std::string label;
|
Chris@0
|
231 };
|
Chris@0
|
232
|
Chris@0
|
233 typedef std::vector<Feature> FeatureList;
|
Chris@0
|
234 typedef std::map<int, FeatureList> FeatureSet; // key is output no
|
Chris@0
|
235
|
Chris@0
|
236 /**
|
Chris@0
|
237 * Process a single block of input data. inputBuffers points to
|
Chris@0
|
238 * one array of floats per input channel, and each of those arrays
|
Chris@0
|
239 * contains the blockSize number of samples (the host will
|
Chris@0
|
240 * zero-pad as necessary). The timestamp is the real time in
|
Chris@0
|
241 * seconds of the start of the supplied block of samples.
|
Chris@0
|
242 *
|
Chris@0
|
243 * Return any features that have become available after this
|
Chris@0
|
244 * process call. (These do not necessarily have to fall within
|
Chris@0
|
245 * the process block, except for OneSamplePerStep outputs.)
|
Chris@0
|
246 */
|
Chris@0
|
247 virtual FeatureSet process(float **inputBuffers,
|
Chris@0
|
248 RealTime timestamp) = 0;
|
Chris@0
|
249
|
Chris@0
|
250 /**
|
Chris@0
|
251 * After all blocks have been processed, calculate and return any
|
Chris@0
|
252 * remaining features derived from the complete input.
|
Chris@0
|
253 */
|
Chris@0
|
254 virtual FeatureSet getRemainingFeatures() = 0;
|
Chris@0
|
255
|
Chris@0
|
256 protected:
|
Chris@0
|
257 FeatureExtractionPlugin(float inputSampleRate) :
|
Chris@0
|
258 m_inputSampleRate(inputSampleRate) { }
|
Chris@0
|
259
|
Chris@0
|
260 float m_inputSampleRate;
|
Chris@0
|
261 };
|
Chris@0
|
262
|
Chris@0
|
263 #endif
|
Chris@0
|
264
|
Chris@0
|
265
|
Chris@0
|
266
|