annotate vamp-hostsdk/PluginSummarisingAdapter.h @ 390:06988ce35ff0 vh

Initial draft of C API for plugin loading
author Chris Cannam
date Wed, 20 May 2015 16:12:18 +0100
parents 2e16d99867bd
children 8ffb8985ae8f
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@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