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