PluginSummarisingAdapter is a Vamp plugin adapter that provides summarisation methods such as mean and median averages of output features, for use in any context where an available plugin produces individual values but the result that is actually needed is some sort of aggregate. More...
#include <vamp-hostsdk/PluginSummarisingAdapter.h>
Public Types | |
| enum | SummaryType { Minimum = 0, Maximum = 1, Mean = 2, Median = 3, Mode = 4, Sum = 5, Variance = 6, StandardDeviation = 7, Count = 8, UnknownSummaryType = 999 } |
| enum | AveragingMethod { SampleAverage = 0, ContinuousTimeAverage = 1 } |
| AveragingMethod indicates how the adapter should handle average-based summaries of features whose results are not equally spaced in time. More... | |
| typedef std::set< RealTime > | SegmentBoundaries |
| enum | InputDomain { TimeDomain, FrequencyDomain } |
| typedef std::vector< OutputDescriptor > | OutputList |
| typedef std::vector< Feature > | FeatureList |
| typedef std::map< int, FeatureList > | FeatureSet |
| typedef std::vector< ParameterDescriptor > | ParameterList |
| typedef std::vector< std::string > | ProgramList |
Public Member Functions | |
| PluginSummarisingAdapter (Plugin *plugin) | |
| Construct a PluginSummarisingAdapter wrapping the given plugin. More... | |
| virtual | ~PluginSummarisingAdapter () |
| bool | initialise (size_t channels, size_t stepSize, size_t blockSize) |
| Initialise a plugin to prepare it for use with the given number of input channels, step size (window increment, in sample frames) and block size (window size, in sample frames). More... | |
| void | reset () |
| Reset the plugin after use, to prepare it for another clean run. More... | |
| FeatureSet | process (const float *const *inputBuffers, RealTime timestamp) |
| Process a single block of input data. More... | |
| FeatureSet | getRemainingFeatures () |
| After all blocks have been processed, calculate and return any remaining features derived from the complete input. More... | |
| void | setSummarySegmentBoundaries (const SegmentBoundaries &) |
| Specify a series of segment boundaries, such that one summary will be returned for each of the contiguous intra-boundary segments. More... | |
| FeatureList | getSummaryForOutput (int output, SummaryType type, AveragingMethod method=SampleAverage) |
| Return summaries of the features that were returned on the given output, using the given SummaryType and AveragingMethod. More... | |
| FeatureSet | getSummaryForAllOutputs (SummaryType type, AveragingMethod method=SampleAverage) |
| Return summaries of the features that were returned on all of the plugin's outputs, using the given SummaryType and AveragingMethod. More... | |
| InputDomain | getInputDomain () const |
| Get the plugin's required input domain. More... | |
| unsigned int | getVampApiVersion () const |
| Get the Vamp API compatibility level of the plugin. More... | |
| std::string | getIdentifier () const |
| Get the computer-usable name of the plugin. More... | |
| std::string | getName () const |
| Get a human-readable name or title of the plugin. More... | |
| std::string | getDescription () const |
| Get a human-readable description for the plugin, typically a line of text that may optionally be displayed in addition to the plugin's "name". More... | |
| std::string | getMaker () const |
| Get the name of the author or vendor of the plugin in human-readable form. More... | |
| int | getPluginVersion () const |
| Get the version number of the plugin. More... | |
| std::string | getCopyright () const |
| Get the copyright statement or licensing summary for the plugin. More... | |
| ParameterList | getParameterDescriptors () const |
| Get the controllable parameters of this plugin. More... | |
| float | getParameter (std::string) const |
| Get the value of a named parameter. More... | |
| void | setParameter (std::string, float) |
| Set a named parameter. More... | |
| ProgramList | getPrograms () const |
| Get the program settings available in this plugin. More... | |
| std::string | getCurrentProgram () const |
| Get the current program. More... | |
| void | selectProgram (std::string) |
| Select a program. More... | |
| size_t | getPreferredStepSize () const |
| Get the preferred step size (window increment – the distance in sample frames between the start frames of consecutive blocks passed to the process() function) for the plugin. More... | |
| size_t | getPreferredBlockSize () const |
| Get the preferred block size (window size – the number of sample frames passed in each block to the process() function). More... | |
| size_t | getMinChannelCount () const |
| Get the minimum supported number of input channels. More... | |
| size_t | getMaxChannelCount () const |
| Get the maximum supported number of input channels. More... | |
| OutputList | getOutputDescriptors () const |
| Get the outputs of this plugin. More... | |
| template<typename WrapperType > | |
| WrapperType * | getWrapper () |
| Return a pointer to the plugin wrapper of type WrapperType surrounding this wrapper's plugin, if present. More... | |
| virtual std::string | getType () const |
| Used to distinguish between Vamp::Plugin and other potential sibling subclasses of PluginBase. More... | |
Protected Attributes | |
| Impl * | m_impl |
| Plugin * | m_plugin |
| float | m_inputSampleRate |
Detailed Description
PluginSummarisingAdapter is a Vamp plugin adapter that provides summarisation methods such as mean and median averages of output features, for use in any context where an available plugin produces individual values but the result that is actually needed is some sort of aggregate.
To make use of PluginSummarisingAdapter, the host should configure, initialise and run the plugin through the adapter interface just as normal. Then, after the process and getRemainingFeatures methods have been properly called and processing is complete, the host may call getSummaryForOutput or getSummaryForAllOutputs to obtain summarised features: averages, maximum values, etc, depending on the SummaryType passed to the function.
By default PluginSummarisingAdapter calculates a single summary of each output's feature across the whole duration of processed audio. A host needing summaries of sub-segments of the whole audio may call setSummarySegmentBoundaries before retrieving the summaries, providing a list of times such that one summary will be provided for each segment between two consecutive times.
PluginSummarisingAdapter is straightforward rather than fast. It calculates all of the summary types for all outputs always, and then returns only the ones that are requested. It is designed on the basis that, for most features, summarising and storing summarised results is far cheaper than calculating the results in the first place. If this is not true for your particular feature, PluginSummarisingAdapter may not be the best approach for you.
- Note
- This class was introduced in version 2.0 of the Vamp plugin SDK.
Definition at line 86 of file PluginSummarisingAdapter.h.
Member Typedef Documentation
◆ SegmentBoundaries
| typedef std::set<RealTime> Vamp::HostExt::PluginSummarisingAdapter::SegmentBoundaries |
Definition at line 104 of file PluginSummarisingAdapter.h.
◆ OutputList
|
inherited |
Definition at line 335 of file vamp-sdk/Plugin.h.
◆ FeatureList
|
inherited |
Definition at line 393 of file vamp-sdk/Plugin.h.
◆ FeatureSet
|
inherited |
Definition at line 395 of file vamp-sdk/Plugin.h.
◆ ParameterList
|
inherited |
Definition at line 203 of file vamp-sdk/PluginBase.h.
◆ ProgramList
|
inherited |
Definition at line 225 of file vamp-sdk/PluginBase.h.
Member Enumeration Documentation
◆ SummaryType
| Enumerator | |
|---|---|
| Minimum | |
| Maximum | |
| Mean | |
| Median | |
| Mode | |
| Sum | |
| Variance | |
| StandardDeviation | |
| Count | |
| UnknownSummaryType | |
Definition at line 121 of file PluginSummarisingAdapter.h.
◆ AveragingMethod
AveragingMethod indicates how the adapter should handle average-based summaries of features whose results are not equally spaced in time.
If SampleAverage is specified, summary types based on averages will be calculated by treating each result individually without regard to its time: for example, the mean will be the sum of all values divided by the number of values.
If ContinuousTimeAverage is specified, each feature will be considered to have a duration, either as specified in the feature's duration field, or until the following feature: thus, for example, the mean will be the sum of the products of values and durations, divided by the total duration.
Although SampleAverage is useful for many types of feature, ContinuousTimeAverage is essential for some situations, for example finding the result that spans the largest proportion of the input given a feature that emits a new result only when the value changes (the modal value integrated over time).
| Enumerator | |
|---|---|
| SampleAverage | |
| ContinuousTimeAverage | |
Definition at line 157 of file PluginSummarisingAdapter.h.
◆ InputDomain
|
inherited |
| Enumerator | |
|---|---|
| TimeDomain | |
| FrequencyDomain | |
Definition at line 152 of file vamp-sdk/Plugin.h.
Constructor & Destructor Documentation
◆ PluginSummarisingAdapter()
| Vamp::HostExt::PluginSummarisingAdapter::PluginSummarisingAdapter | ( | Plugin * | plugin | ) |
Construct a PluginSummarisingAdapter wrapping the given plugin.
The adapter takes ownership of the plugin, which will be deleted when the adapter is deleted.
◆ ~PluginSummarisingAdapter()
|
virtual |
Member Function Documentation
◆ initialise()
|