cannam@233
|
1 /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*- vi:set ts=8 sts=4 sw=4: */
|
cannam@233
|
2
|
cannam@233
|
3 /*
|
cannam@233
|
4 Vamp
|
cannam@233
|
5
|
cannam@233
|
6 An API for audio analysis and feature extraction plugins.
|
cannam@233
|
7
|
cannam@233
|
8 Centre for Digital Music, Queen Mary, University of London.
|
cannam@290
|
9 Copyright 2006-2009 Chris Cannam and QMUL.
|
cannam@233
|
10
|
cannam@233
|
11 Permission is hereby granted, free of charge, to any person
|
cannam@233
|
12 obtaining a copy of this software and associated documentation
|
cannam@233
|
13 files (the "Software"), to deal in the Software without
|
cannam@233
|
14 restriction, including without limitation the rights to use, copy,
|
cannam@233
|
15 modify, merge, publish, distribute, sublicense, and/or sell copies
|
cannam@233
|
16 of the Software, and to permit persons to whom the Software is
|
cannam@233
|
17 furnished to do so, subject to the following conditions:
|
cannam@233
|
18
|
cannam@233
|
19 The above copyright notice and this permission notice shall be
|
cannam@233
|
20 included in all copies or substantial portions of the Software.
|
cannam@233
|
21
|
cannam@233
|
22 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
cannam@233
|
23 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
cannam@233
|
24 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
cannam@233
|
25 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
|
cannam@233
|
26 ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
|
cannam@233
|
27 CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
cannam@233
|
28 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
cannam@233
|
29
|
cannam@233
|
30 Except as contained in this notice, the names of the Centre for
|
cannam@233
|
31 Digital Music; Queen Mary, University of London; and Chris Cannam
|
cannam@233
|
32 shall not be used in advertising or otherwise to promote the sale,
|
cannam@233
|
33 use or other dealings in this Software without prior written
|
cannam@233
|
34 authorization.
|
cannam@233
|
35 */
|
cannam@233
|
36
|
cannam@233
|
37 #ifndef _VAMP_PLUGIN_SUMMARISING_ADAPTER_H_
|
cannam@233
|
38 #define _VAMP_PLUGIN_SUMMARISING_ADAPTER_H_
|
cannam@233
|
39
|
cannam@243
|
40 #include "hostguard.h"
|
cannam@233
|
41 #include "PluginWrapper.h"
|
cannam@233
|
42
|
cannam@233
|
43 #include <set>
|
cannam@233
|
44
|
cannam@263
|
45 _VAMP_SDK_HOSTSPACE_BEGIN(PluginSummarisingAdapter.h)
|
cannam@263
|
46
|
cannam@233
|
47 namespace Vamp {
|
cannam@233
|
48
|
cannam@233
|
49 namespace HostExt {
|
cannam@233
|
50
|
cannam@233
|
51 /**
|
cannam@233
|
52 * \class PluginSummarisingAdapter PluginSummarisingAdapter.h <vamp-hostsdk/PluginSummarisingAdapter.h>
|
cannam@233
|
53 *
|
cannam@248
|
54 * PluginSummarisingAdapter is a Vamp plugin adapter that provides
|
cannam@248
|
55 * summarisation methods such as mean and median averages of output
|
cannam@248
|
56 * features, for use in any context where an available plugin produces
|
cannam@248
|
57 * individual values but the result that is actually needed is some
|
cannam@248
|
58 * sort of aggregate.
|
cannam@248
|
59 *
|
cannam@248
|
60 * To make use of PluginSummarisingAdapter, the host should configure,
|
cannam@248
|
61 * initialise and run the plugin through the adapter interface just as
|
cannam@248
|
62 * normal. Then, after the process and getRemainingFeatures methods
|
cannam@248
|
63 * have been properly called and processing is complete, the host may
|
cannam@248
|
64 * call getSummaryForOutput or getSummaryForAllOutputs to obtain
|
cannam@248
|
65 * summarised features: averages, maximum values, etc, depending on
|
cannam@248
|
66 * the SummaryType passed to the function.
|
cannam@248
|
67 *
|
cannam@248
|
68 * By default PluginSummarisingAdapter calculates a single summary of
|
cannam@248
|
69 * each output's feature across the whole duration of processed audio.
|
cannam@248
|
70 * A host needing summaries of sub-segments of the whole audio may
|
cannam@248
|
71 * call setSummarySegmentBoundaries before retrieving the summaries,
|
cannam@248
|
72 * providing a list of times such that one summary will be provided
|
cannam@248
|
73 * for each segment between two consecutive times.
|
cannam@248
|
74 *
|
cannam@248
|
75 * PluginSummarisingAdapter is straightforward rather than fast. It
|
cannam@248
|
76 * calculates all of the summary types for all outputs always, and
|
cannam@248
|
77 * then returns only the ones that are requested. It is designed on
|
cannam@248
|
78 * the basis that, for most features, summarising and storing
|
cannam@248
|
79 * summarised results is far cheaper than calculating the results in
|
cannam@248
|
80 * the first place. If this is not true for your particular feature,
|
cannam@248
|
81 * PluginSummarisingAdapter may not be the best approach for you.
|
cannam@248
|
82 *
|
cannam@233
|
83 * \note This class was introduced in version 2.0 of the Vamp plugin SDK.
|
cannam@233
|
84 */
|
cannam@233
|
85
|
cannam@233
|
86 class PluginSummarisingAdapter : public PluginWrapper
|
cannam@233
|
87 {
|
cannam@233
|
88 public:
|
cannam@248
|
89 /**
|
cannam@248
|
90 * Construct a PluginSummarisingAdapter wrapping the given plugin.
|
cannam@248
|
91 * The adapter takes ownership of the plugin, which will be
|
cannam@248
|
92 * deleted when the adapter is deleted.
|
cannam@248
|
93 */
|
cannam@248
|
94 PluginSummarisingAdapter(Plugin *plugin);
|
cannam@233
|
95 virtual ~PluginSummarisingAdapter();
|
cannam@233
|
96
|
cannam@233
|
97 bool initialise(size_t channels, size_t stepSize, size_t blockSize);
|
cannam@233
|
98
|
cannam@275
|
99 void reset();
|
cannam@275
|
100
|
cannam@233
|
101 FeatureSet process(const float *const *inputBuffers, RealTime timestamp);
|
cannam@233
|
102 FeatureSet getRemainingFeatures();
|
cannam@233
|
103
|
cannam@233
|
104 typedef std::set<RealTime> SegmentBoundaries;
|
cannam@248
|
105
|
cannam@248
|
106 /**
|
cannam@248
|
107 * Specify a series of segment boundaries, such that one summary
|
cannam@248
|
108 * will be returned for each of the contiguous intra-boundary
|
cannam@248
|
109 * segments. This function must be called before
|
cannam@248
|
110 * getSummaryForOutput or getSummaryForAllOutputs.
|
cannam@248
|
111 *
|
cannam@248
|
112 * Note that you cannot retrieve results with multiple different
|
cannam@248
|
113 * segmentations by repeatedly calling this function followed by
|
cannam@248
|
114 * one of the getSummary functions. The summaries are all
|
cannam@248
|
115 * calculated at the first call to any getSummary function, and
|
cannam@248
|
116 * once the summaries have been calculated, they remain
|
cannam@248
|
117 * calculated.
|
cannam@248
|
118 */
|
cannam@233
|
119 void setSummarySegmentBoundaries(const SegmentBoundaries &);
|
cannam@233
|
120
|
cannam@233
|
121 enum SummaryType {
|
cannam@233
|
122 Minimum = 0,
|
cannam@233
|
123 Maximum = 1,
|
cannam@233
|
124 Mean = 2,
|
cannam@233
|
125 Median = 3,
|
cannam@233
|
126 Mode = 4,
|
cannam@233
|
127 Sum = 5,
|
cannam@233
|
128 Variance = 6,
|
cannam@233
|
129 StandardDeviation = 7,
|
cannam@233
|
130 Count = 8,
|
cannam@233
|
131
|
cannam@233
|
132 UnknownSummaryType = 999
|
cannam@233
|
133 };
|
cannam@233
|
134
|
cannam@233
|
135 /**
|
cannam@233
|
136 * AveragingMethod indicates how the adapter should handle
|
cannam@233
|
137 * average-based summaries of features whose results are not
|
cannam@233
|
138 * equally spaced in time.
|
cannam@233
|
139 *
|
cannam@233
|
140 * If SampleAverage is specified, summary types based on averages
|
cannam@233
|
141 * will be calculated by treating each result individually without
|
cannam@233
|
142 * regard to its time: for example, the mean will be the sum of
|
cannam@233
|
143 * all values divided by the number of values.
|
cannam@233
|
144 *
|
cannam@233
|
145 * If ContinuousTimeAverage is specified, each feature will be
|
cannam@233
|
146 * considered to have a duration, either as specified in the
|
cannam@233
|
147 * feature's duration field, or until the following feature: thus,
|
cannam@233
|
148 * for example, the mean will be the sum of the products of values
|
cannam@233
|
149 * and durations, divided by the total duration.
|
cannam@233
|
150 *
|
cannam@233
|
151 * Although SampleAverage is useful for many types of feature,
|
cannam@233
|
152 * ContinuousTimeAverage is essential for some situations, for
|
cannam@233
|
153 * example finding the result that spans the largest proportion of
|
cannam@233
|
154 * the input given a feature that emits a new result only when the
|
cannam@233
|
155 * value changes (the modal value integrated over time).
|
cannam@233
|
156 */
|
cannam@233
|
157 enum AveragingMethod {
|
cannam@233
|
158 SampleAverage = 0,
|
cannam@291
|
159 ContinuousTimeAverage = 1
|
cannam@233
|
160 };
|
cannam@233
|
161
|
cannam@248
|
162 /**
|
cannam@248
|
163 * Return summaries of the features that were returned on the
|
cannam@248
|
164 * given output, using the given SummaryType and AveragingMethod.
|
cannam@248
|
165 *
|
cannam@248
|
166 * The plugin must have been fully run (process() and
|
cannam@248
|
167 * getRemainingFeatures() calls all made as appropriate) before
|
cannam@248
|
168 * this function is called.
|
cannam@248
|
169 */
|
cannam@233
|
170 FeatureList getSummaryForOutput(int output,
|
cannam@233
|
171 SummaryType type,
|
cannam@233
|
172 AveragingMethod method = SampleAverage);
|
cannam@233
|
173
|
cannam@248
|
174 /**
|
cannam@248
|
175 * Return summaries of the features that were returned on all of
|
cannam@248
|
176 * the plugin's outputs, using the given SummaryType and
|
cannam@248
|
177 * AveragingMethod.
|
cannam@248
|
178 *
|
cannam@248
|
179 * The plugin must have been fully run (process() and
|
cannam@248
|
180 * getRemainingFeatures() calls all made as appropriate) before
|
cannam@248
|
181 * this function is called.
|
cannam@248
|
182 */
|
cannam@233
|
183 FeatureSet getSummaryForAllOutputs(SummaryType type,
|
cannam@233
|
184 AveragingMethod method = SampleAverage);
|
cannam@233
|
185
|
cannam@233
|
186 protected:
|
cannam@233
|
187 class Impl;
|
cannam@233
|
188 Impl *m_impl;
|
cannam@233
|
189 };
|
cannam@233
|
190
|
cannam@233
|
191 }
|
cannam@233
|
192
|
cannam@233
|
193 }
|
cannam@233
|
194
|
cannam@263
|
195 _VAMP_SDK_HOSTSPACE_END(PluginSummarisingAdapter.h)
|
cannam@263
|
196
|
cannam@233
|
197 #endif
|