annotate vamp-hostsdk/PluginSummarisingAdapter.h @ 255:88ef5ffdbe8d

* docs
author cannam
date Wed, 12 Nov 2008 14:11:01 +0000
parents c88a3cdb0215
children 4454843ff384
rev   line source
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@233 9 Copyright 2006-2008 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@233 45 namespace Vamp {
cannam@233 46
cannam@233 47 namespace HostExt {
cannam@233 48
cannam@233 49 /**
cannam@233 50 * \class PluginSummarisingAdapter PluginSummarisingAdapter.h <vamp-hostsdk/PluginSummarisingAdapter.h>
cannam@233 51 *
cannam@248 52 * PluginSummarisingAdapter is a Vamp plugin adapter that provides
cannam@248 53 * summarisation methods such as mean and median averages of output
cannam@248 54 * features, for use in any context where an available plugin produces
cannam@248 55 * individual values but the result that is actually needed is some
cannam@248 56 * sort of aggregate.
cannam@248 57 *
cannam@248 58 * To make use of PluginSummarisingAdapter, the host should configure,
cannam@248 59 * initialise and run the plugin through the adapter interface just as
cannam@248 60 * normal. Then, after the process and getRemainingFeatures methods
cannam@248 61 * have been properly called and processing is complete, the host may
cannam@248 62 * call getSummaryForOutput or getSummaryForAllOutputs to obtain
cannam@248 63 * summarised features: averages, maximum values, etc, depending on
cannam@248 64 * the SummaryType passed to the function.
cannam@248 65 *
cannam@248 66 * By default PluginSummarisingAdapter calculates a single summary of
cannam@248 67 * each output's feature across the whole duration of processed audio.
cannam@248 68 * A host needing summaries of sub-segments of the whole audio may
cannam@248 69 * call setSummarySegmentBoundaries before retrieving the summaries,
cannam@248 70 * providing a list of times such that one summary will be provided
cannam@248 71 * for each segment between two consecutive times.
cannam@248 72 *
cannam@248 73 * PluginSummarisingAdapter is straightforward rather than fast. It
cannam@248 74 * calculates all of the summary types for all outputs always, and
cannam@248 75 * then returns only the ones that are requested. It is designed on
cannam@248 76 * the basis that, for most features, summarising and storing
cannam@248 77 * summarised results is far cheaper than calculating the results in
cannam@248 78 * the first place. If this is not true for your particular feature,
cannam@248 79 * PluginSummarisingAdapter may not be the best approach for you.
cannam@248 80 *
cannam@233 81 * \note This class was introduced in version 2.0 of the Vamp plugin SDK.
cannam@233 82 */
cannam@233 83
cannam@233 84 class PluginSummarisingAdapter : public PluginWrapper
cannam@233 85 {
cannam@233 86 public:
cannam@248 87 /**
cannam@248 88 * Construct a PluginSummarisingAdapter wrapping the given plugin.
cannam@248 89 * The adapter takes ownership of the plugin, which will be
cannam@248 90 * deleted when the adapter is deleted.
cannam@248 91 */
cannam@248 92 PluginSummarisingAdapter(Plugin *plugin);
cannam@233 93 virtual ~PluginSummarisingAdapter();
cannam@233 94
cannam@233 95 bool initialise(size_t channels, size_t stepSize, size_t blockSize);
cannam@233 96
cannam@233 97 FeatureSet process(const float *const *inputBuffers, RealTime timestamp);
cannam@233 98 FeatureSet getRemainingFeatures();
cannam@233 99
cannam@233 100 typedef std::set<RealTime> SegmentBoundaries;
cannam@248 101
cannam@248 102 /**
cannam@248 103 * Specify a series of segment boundaries, such that one summary
cannam@248 104 * will be returned for each of the contiguous intra-boundary
cannam@248 105 * segments. This function must be called before
cannam@248 106 * getSummaryForOutput or getSummaryForAllOutputs.
cannam@248 107 *
cannam@248 108 * Note that you cannot retrieve results with multiple different
cannam@248 109 * segmentations by repeatedly calling this function followed by
cannam@248 110 * one of the getSummary functions. The summaries are all
cannam@248 111 * calculated at the first call to any getSummary function, and
cannam@248 112 * once the summaries have been calculated, they remain
cannam@248 113 * calculated.
cannam@248 114 */
cannam@233 115 void setSummarySegmentBoundaries(const SegmentBoundaries &);
cannam@233 116
cannam@233 117 enum SummaryType {
cannam@233 118 Minimum = 0,
cannam@233 119 Maximum = 1,
cannam@233 120 Mean = 2,
cannam@233 121 Median = 3,
cannam@233 122 Mode = 4,
cannam@233 123 Sum = 5,
cannam@233 124 Variance = 6,
cannam@233 125 StandardDeviation = 7,
cannam@233 126 Count = 8,
cannam@233 127
cannam@233 128 UnknownSummaryType = 999
cannam@233 129 };
cannam@233 130
cannam@233 131 /**
cannam@233 132 * AveragingMethod indicates how the adapter should handle
cannam@233 133 * average-based summaries of features whose results are not
cannam@233 134 * equally spaced in time.
cannam@233 135 *
cannam@233 136 * If SampleAverage is specified, summary types based on averages
cannam@233 137 * will be calculated by treating each result individually without
cannam@233 138 * regard to its time: for example, the mean will be the sum of
cannam@233 139 * all values divided by the number of values.
cannam@233 140 *
cannam@233 141 * If ContinuousTimeAverage is specified, each feature will be
cannam@233 142 * considered to have a duration, either as specified in the
cannam@233 143 * feature's duration field, or until the following feature: thus,
cannam@233 144 * for example, the mean will be the sum of the products of values
cannam@233 145 * and durations, divided by the total duration.
cannam@233 146 *
cannam@233 147 * Although SampleAverage is useful for many types of feature,
cannam@233 148 * ContinuousTimeAverage is essential for some situations, for
cannam@233 149 * example finding the result that spans the largest proportion of
cannam@233 150 * the input given a feature that emits a new result only when the
cannam@233 151 * value changes (the modal value integrated over time).
cannam@233 152 */
cannam@233 153 enum AveragingMethod {
cannam@233 154 SampleAverage = 0,
cannam@233 155 ContinuousTimeAverage = 1,
cannam@233 156 };
cannam@233 157
cannam@248 158 /**
cannam@248 159 * Return summaries of the features that were returned on the
cannam@248 160 * given output, using the given SummaryType and AveragingMethod.
cannam@248 161 *
cannam@248 162 * The plugin must have been fully run (process() and
cannam@248 163 * getRemainingFeatures() calls all made as appropriate) before
cannam@248 164 * this function is called.
cannam@248 165 */
cannam@233 166 FeatureList getSummaryForOutput(int output,
cannam@233 167 SummaryType type,
cannam@233 168 AveragingMethod method = SampleAverage);
cannam@233 169
cannam@248 170 /**
cannam@248 171 * Return summaries of the features that were returned on all of
cannam@248 172 * the plugin's outputs, using the given SummaryType and
cannam@248 173 * AveragingMethod.
cannam@248 174 *
cannam@248 175 * The plugin must have been fully run (process() and
cannam@248 176 * getRemainingFeatures() calls all made as appropriate) before
cannam@248 177 * this function is called.
cannam@248 178 */
cannam@233 179 FeatureSet getSummaryForAllOutputs(SummaryType type,
cannam@233 180 AveragingMethod method = SampleAverage);
cannam@233 181
cannam@233 182 protected:
cannam@233 183 class Impl;
cannam@233 184 Impl *m_impl;
cannam@233 185 };
cannam@233 186
cannam@233 187 }
cannam@233 188
cannam@233 189 }
cannam@233 190
cannam@233 191 #endif