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