Chris@12: /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*- vi:set ts=8 sts=4 sw=4: */ Chris@12: Chris@12: /* Chris@12: Vamp Chris@12: Chris@12: An API for audio analysis and feature extraction plugins. Chris@12: Chris@12: Centre for Digital Music, Queen Mary, University of London. Chris@12: Copyright 2006-2009 Chris Cannam and QMUL. Chris@12: Chris@12: Permission is hereby granted, free of charge, to any person Chris@12: obtaining a copy of this software and associated documentation Chris@12: files (the "Software"), to deal in the Software without Chris@12: restriction, including without limitation the rights to use, copy, Chris@12: modify, merge, publish, distribute, sublicense, and/or sell copies Chris@12: of the Software, and to permit persons to whom the Software is Chris@12: furnished to do so, subject to the following conditions: Chris@12: Chris@12: The above copyright notice and this permission notice shall be Chris@12: included in all copies or substantial portions of the Software. Chris@12: Chris@12: THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, Chris@12: EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF Chris@12: MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND Chris@12: NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR Chris@12: ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF Chris@12: CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION Chris@12: WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Chris@12: Chris@12: Except as contained in this notice, the names of the Centre for Chris@12: Digital Music; Queen Mary, University of London; and Chris Cannam Chris@12: shall not be used in advertising or otherwise to promote the sale, Chris@12: use or other dealings in this Software without prior written Chris@12: authorization. Chris@12: */ Chris@12: Chris@12: #ifndef _VAMP_PLUGIN_SUMMARISING_ADAPTER_H_ Chris@12: #define _VAMP_PLUGIN_SUMMARISING_ADAPTER_H_ Chris@12: Chris@12: #include "hostguard.h" Chris@12: #include "PluginWrapper.h" Chris@12: Chris@12: #include Chris@12: Chris@12: _VAMP_SDK_HOSTSPACE_BEGIN(PluginSummarisingAdapter.h) Chris@12: Chris@12: namespace Vamp { Chris@12: Chris@12: namespace HostExt { Chris@12: Chris@12: /** Chris@12: * \class PluginSummarisingAdapter PluginSummarisingAdapter.h Chris@12: * Chris@12: * PluginSummarisingAdapter is a Vamp plugin adapter that provides Chris@12: * summarisation methods such as mean and median averages of output Chris@12: * features, for use in any context where an available plugin produces Chris@12: * individual values but the result that is actually needed is some Chris@12: * sort of aggregate. Chris@12: * Chris@12: * To make use of PluginSummarisingAdapter, the host should configure, Chris@12: * initialise and run the plugin through the adapter interface just as Chris@12: * normal. Then, after the process and getRemainingFeatures methods Chris@12: * have been properly called and processing is complete, the host may Chris@12: * call getSummaryForOutput or getSummaryForAllOutputs to obtain Chris@12: * summarised features: averages, maximum values, etc, depending on Chris@12: * the SummaryType passed to the function. Chris@12: * Chris@12: * By default PluginSummarisingAdapter calculates a single summary of Chris@12: * each output's feature across the whole duration of processed audio. Chris@12: * A host needing summaries of sub-segments of the whole audio may Chris@12: * call setSummarySegmentBoundaries before retrieving the summaries, Chris@12: * providing a list of times such that one summary will be provided Chris@12: * for each segment between two consecutive times. Chris@12: * Chris@12: * PluginSummarisingAdapter is straightforward rather than fast. It Chris@12: * calculates all of the summary types for all outputs always, and Chris@12: * then returns only the ones that are requested. It is designed on Chris@12: * the basis that, for most features, summarising and storing Chris@12: * summarised results is far cheaper than calculating the results in Chris@12: * the first place. If this is not true for your particular feature, Chris@12: * PluginSummarisingAdapter may not be the best approach for you. Chris@12: * Chris@12: * \note This class was introduced in version 2.0 of the Vamp plugin SDK. Chris@12: */ Chris@12: Chris@12: class PluginSummarisingAdapter : public PluginWrapper Chris@12: { Chris@12: public: Chris@12: /** Chris@12: * Construct a PluginSummarisingAdapter wrapping the given plugin. Chris@12: * The adapter takes ownership of the plugin, which will be Chris@12: * deleted when the adapter is deleted. Chris@12: */ Chris@12: PluginSummarisingAdapter(Plugin *plugin); Chris@12: virtual ~PluginSummarisingAdapter(); Chris@12: Chris@12: bool initialise(size_t channels, size_t stepSize, size_t blockSize); Chris@12: Chris@12: void reset(); Chris@12: Chris@12: FeatureSet process(const float *const *inputBuffers, RealTime timestamp); Chris@12: FeatureSet getRemainingFeatures(); Chris@12: Chris@12: typedef std::set SegmentBoundaries; Chris@12: Chris@12: /** Chris@12: * Specify a series of segment boundaries, such that one summary Chris@12: * will be returned for each of the contiguous intra-boundary Chris@12: * segments. This function must be called before Chris@12: * getSummaryForOutput or getSummaryForAllOutputs. Chris@12: * Chris@12: * Note that you cannot retrieve results with multiple different Chris@12: * segmentations by repeatedly calling this function followed by Chris@12: * one of the getSummary functions. The summaries are all Chris@12: * calculated at the first call to any getSummary function, and Chris@12: * once the summaries have been calculated, they remain Chris@12: * calculated. Chris@12: */ Chris@12: void setSummarySegmentBoundaries(const SegmentBoundaries &); Chris@12: Chris@12: enum SummaryType { Chris@12: Minimum = 0, Chris@12: Maximum = 1, Chris@12: Mean = 2, Chris@12: Median = 3, Chris@12: Mode = 4, Chris@12: Sum = 5, Chris@12: Variance = 6, Chris@12: StandardDeviation = 7, Chris@12: Count = 8, Chris@12: Chris@12: UnknownSummaryType = 999 Chris@12: }; Chris@12: Chris@12: /** Chris@12: * AveragingMethod indicates how the adapter should handle Chris@12: * average-based summaries of features whose results are not Chris@12: * equally spaced in time. Chris@12: * Chris@12: * If SampleAverage is specified, summary types based on averages Chris@12: * will be calculated by treating each result individually without Chris@12: * regard to its time: for example, the mean will be the sum of Chris@12: * all values divided by the number of values. Chris@12: * Chris@12: * If ContinuousTimeAverage is specified, each feature will be Chris@12: * considered to have a duration, either as specified in the Chris@12: * feature's duration field, or until the following feature: thus, Chris@12: * for example, the mean will be the sum of the products of values Chris@12: * and durations, divided by the total duration. Chris@12: * Chris@12: * Although SampleAverage is useful for many types of feature, Chris@12: * ContinuousTimeAverage is essential for some situations, for Chris@12: * example finding the result that spans the largest proportion of Chris@12: * the input given a feature that emits a new result only when the Chris@12: * value changes (the modal value integrated over time). Chris@12: */ Chris@12: enum AveragingMethod { Chris@12: SampleAverage = 0, Chris@12: ContinuousTimeAverage = 1 Chris@12: }; Chris@12: Chris@12: /** Chris@12: * Return summaries of the features that were returned on the Chris@12: * given output, using the given SummaryType and AveragingMethod. Chris@12: * Chris@12: * The plugin must have been fully run (process() and Chris@12: * getRemainingFeatures() calls all made as appropriate) before Chris@12: * this function is called. Chris@12: */ Chris@12: FeatureList getSummaryForOutput(int output, Chris@12: SummaryType type, Chris@12: AveragingMethod method = SampleAverage); Chris@12: Chris@12: /** Chris@12: * Return summaries of the features that were returned on all of Chris@12: * the plugin's outputs, using the given SummaryType and Chris@12: * AveragingMethod. Chris@12: * Chris@12: * The plugin must have been fully run (process() and Chris@12: * getRemainingFeatures() calls all made as appropriate) before Chris@12: * this function is called. Chris@12: */ Chris@12: FeatureSet getSummaryForAllOutputs(SummaryType type, Chris@12: AveragingMethod method = SampleAverage); Chris@12: Chris@12: protected: Chris@12: class Impl; Chris@12: Impl *m_impl; Chris@12: }; Chris@12: Chris@12: } Chris@12: Chris@12: } Chris@12: Chris@12: _VAMP_SDK_HOSTSPACE_END(PluginSummarisingAdapter.h) Chris@12: Chris@12: #endif