Mercurial > hg > vamp-plugin-sdk
changeset 248:c88a3cdb0215
* Tidy up --list-full output a bit
* Some documentation, including docs for PluginSummarisingAdapter
| author | cannam |
|---|---|
| date | Tue, 11 Nov 2008 12:07:09 +0000 |
| parents | 5bfed156b45d |
| children | 2fa6932ab195 |
| files | host/vamp-simple-host.cpp src/vamp-hostsdk/PluginSummarisingAdapter.cpp vamp-hostsdk/PluginBufferingAdapter.h vamp-hostsdk/PluginChannelAdapter.h vamp-hostsdk/PluginInputDomainAdapter.h vamp-hostsdk/PluginSummarisingAdapter.h |
| diffstat | 6 files changed, 138 insertions(+), 55 deletions(-) [+] |
line wrap: on
line diff
--- a/host/vamp-simple-host.cpp Tue Nov 11 09:49:12 2008 +0000 +++ b/host/vamp-simple-host.cpp Tue Nov 11 12:07:09 2008 +0000 @@ -630,28 +630,28 @@ } else if (verbosity == PluginInformationDetailed) { cout << header(plugin->getName(), 2); - cout << "- Identifier: " + cout << " - Identifier: " << key << endl; - cout << "- Plugin Version: " + cout << " - Plugin Version: " << plugin->getPluginVersion() << endl; - cout << "- Vamp API Version: " + cout << " - Vamp API Version: " << plugin->getVampApiVersion() << endl; - cout << "- Maker: \"" + cout << " - Maker: \"" << plugin->getMaker() << "\"" << endl; - cout << "- Copyright: \"" + cout << " - Copyright: \"" << plugin->getCopyright() << "\"" << endl; - cout << "- Description: \"" + cout << " - Description: \"" << plugin->getDescription() << "\"" << endl; - cout << "- Input Domain: " + cout << " - Input Domain: " << (plugin->getInputDomain() == Vamp::Plugin::TimeDomain ? "Time Domain" : "Frequency Domain") << endl; - cout << "- Default Step Size: " + cout << " - Default Step Size: " << plugin->getPreferredStepSize() << endl; - cout << "- Default Block Size: " + cout << " - Default Block Size: " << plugin->getPreferredBlockSize() << endl; - cout << "- Minimum Channels: " + cout << " - Minimum Channels: " << plugin->getMinChannelCount() << endl; - cout << "- Maximum Channels: " + cout << " - Maximum Channels: " << plugin->getMaxChannelCount() << endl; } else if (verbosity == PluginIds) { @@ -667,21 +667,21 @@ for (size_t j = 0; j < params.size(); ++j) { Plugin::ParameterDescriptor &pd(params[j]); cout << "\nParameter " << j+1 << ": \"" << pd.name << "\"" << endl; - cout << "- Identifier: " << pd.identifier << endl; - cout << "- Description: \"" << pd.description << "\"" << endl; + cout << " - Identifier: " << pd.identifier << endl; + cout << " - Description: \"" << pd.description << "\"" << endl; if (pd.unit != "") { - cout << "- Unit: " << pd.unit << endl; + cout << " - Unit: " << pd.unit << endl; } - cout << "- Range: "; + cout << " - Range: "; cout << pd.minValue << " -> " << pd.maxValue << endl; - cout << "- Default: "; + cout << " - Default: "; cout << pd.defaultValue << endl; if (pd.isQuantized) { - cout << "- Quantize Step: " + cout << " - Quantize Step: " << pd.quantizeStep << endl; } if (!pd.valueNames.empty()) { - cout << "- Value Names: "; + cout << " - Value Names: "; for (size_t k = 0; k < pd.valueNames.size(); ++k) { if (k > 0) cout << ", "; cout << "\"" << pd.valueNames[k] << "\""; @@ -696,31 +696,39 @@ for (size_t j = 0; j < outputs.size(); ++j) { Plugin::OutputDescriptor &od(outputs[j]); cout << "\nOutput " << j+1 << ": \"" << od.name << "\"" << endl; - cout << "- Identifier: " << od.identifier << endl; - cout << "- Description: \"" << od.description << "\"" << endl; + cout << " - Identifier: " << od.identifier << endl; + cout << " - Description: \"" << od.description << "\"" << endl; if (od.unit != "") { - cout << "- Unit: " << od.unit << endl; + cout << " - Unit: " << od.unit << endl; } if (od.hasFixedBinCount) { - cout << "- Default Bin Count: " << od.binCount << endl; + cout << " - Default Bin Count: " << od.binCount << endl; } if (!od.binNames.empty()) { - cout << "- Bin Names: "; + bool have = false; for (size_t k = 0; k < od.binNames.size(); ++k) { - if (k > 0) cout << ", "; - cout << "\"" << od.binNames[k] << "\""; + if (od.binNames[k] != "") { + have = true; break; + } } - cout << endl; + if (have) { + cout << " - Bin Names: "; + for (size_t k = 0; k < od.binNames.size(); ++k) { + if (k > 0) cout << ", "; + cout << "\"" << od.binNames[k] << "\""; + } + cout << endl; + } } if (od.hasKnownExtents) { - cout << "- Default Extents: "; + cout << " - Default Extents: "; cout << od.minValue << " -> " << od.maxValue << endl; } if (od.isQuantized) { - cout << "- Quantize Step: " + cout << " - Quantize Step: " << od.quantizeStep << endl; } - cout << "- Sample Type: " + cout << " - Sample Type: " << (od.sampleType == Plugin::OutputDescriptor::OneSamplePerStep ? "One Sample Per Step" : @@ -730,10 +738,10 @@ "Variable Sample Rate") << endl; if (od.sampleType != Plugin::OutputDescriptor::OneSamplePerStep) { - cout << "- Default Rate: " + cout << " - Default Rate: " << od.sampleRate << endl; } - cout << "- Has Duration: " + cout << " - Has Duration: " << (od.hasDuration ? "Yes" : "No") << endl; } }
--- a/src/vamp-hostsdk/PluginSummarisingAdapter.cpp Tue Nov 11 09:49:12 2008 +0000 +++ b/src/vamp-hostsdk/PluginSummarisingAdapter.cpp Tue Nov 11 12:07:09 2008 +0000 @@ -430,23 +430,18 @@ RealTime timestamp, bool final) { -//!!! to do: use timestamp to determine which segment we're on - -//!!! What should happen if a feature's duration spans a segment -// boundary? I think we probably want to chop it, and pretend that it -// appears in both -- don't we? do we? A very long feature (e.g. key, -// if the whole audio is in a single key) might span many or all -// segments, and we want that to be reflected in the results (e.g. it -// is the modal key in all of those segments, not just the first). -// That is actually quite complicated to do! + // What should happen if a feature's duration spans a segment + // boundary? I think we probably want to chop it, and pretend + // that it appears in both. A very long feature (e.g. key, if the + // whole audio is in a single key) might span many or all + // segments, and we want that to be reflected in the results + // (e.g. it is the modal key in all of those segments, not just + // the first). This is actually quite complicated to do. -//!!! This affects how we record things. If features spanning a -// boundary should be chopped, then we need to have per-segment -// accumulators (and the feature value goes into both -- perhaps we -// need a separate phase to split the accumulator up into segments). -// If features spanning a boundary should be counted only in the first -// segment, with their full duration, then we should store them in a -// single accumulator and distribute into segments only on reduce. + // If features spanning a boundary should be chopped, then we need + // to have per-segment accumulators (and the feature value goes + // into both -- with a separate phase to split the accumulator up + // into segments). #ifdef DEBUG_PLUGIN_SUMMARISING_ADAPTER std::cerr << "output " << output << ": timestamp " << timestamp << ", prev timestamp " << m_prevTimestamps[output] << ", final " << final << std::endl; @@ -627,10 +622,10 @@ << source.results.size() << std::endl; #endif - //!!! This is basically nonsense if the results have no values - //!!! (i.e. their times and counts are the only things of - //!!! interest) but perhaps it's the user's problem if they - //!!! ask for segmentation in that case + // This is basically nonsense if the results have no values + // (i.e. their times and counts are the only things of + // interest)... but perhaps it's the user's problem if they + // ask for segmentation (or any summary at all) in that case for (int n = 0; n < source.results.size(); ++n) {
--- a/vamp-hostsdk/PluginBufferingAdapter.h Tue Nov 11 09:49:12 2008 +0000 +++ b/vamp-hostsdk/PluginBufferingAdapter.h Tue Nov 11 12:07:09 2008 +0000 @@ -73,7 +73,12 @@ class PluginBufferingAdapter : public PluginWrapper { public: - PluginBufferingAdapter(Plugin *plugin); // I take ownership of plugin + /** + * Construct a PluginBufferingAdapter wrapping the given plugin. + * The adapter takes ownership of the plugin, which will be + * deleted when the adapter is deleted. + */ + PluginBufferingAdapter(Plugin *plugin); virtual ~PluginBufferingAdapter(); /**
--- a/vamp-hostsdk/PluginChannelAdapter.h Tue Nov 11 09:49:12 2008 +0000 +++ b/vamp-hostsdk/PluginChannelAdapter.h Tue Nov 11 12:07:09 2008 +0000 @@ -110,7 +110,12 @@ class PluginChannelAdapter : public PluginWrapper { public: - PluginChannelAdapter(Plugin *plugin); // I take ownership of plugin + /** + * Construct a PluginChannelAdapter wrapping the given plugin. + * The adapter takes ownership of the plugin, which will be + * deleted when the adapter is deleted. + */ + PluginChannelAdapter(Plugin *plugin); virtual ~PluginChannelAdapter(); bool initialise(size_t channels, size_t stepSize, size_t blockSize);
--- a/vamp-hostsdk/PluginInputDomainAdapter.h Tue Nov 11 09:49:12 2008 +0000 +++ b/vamp-hostsdk/PluginInputDomainAdapter.h Tue Nov 11 12:07:09 2008 +0000 @@ -80,7 +80,12 @@ class PluginInputDomainAdapter : public PluginWrapper { public: - PluginInputDomainAdapter(Plugin *plugin); // I take ownership of plugin + /** + * Construct a PluginInputDomainAdapter wrapping the given plugin. + * The adapter takes ownership of the plugin, which will be + * deleted when the adapter is deleted. + */ + PluginInputDomainAdapter(Plugin *plugin); virtual ~PluginInputDomainAdapter(); bool initialise(size_t channels, size_t stepSize, size_t blockSize);
--- a/vamp-hostsdk/PluginSummarisingAdapter.h Tue Nov 11 09:49:12 2008 +0000 +++ b/vamp-hostsdk/PluginSummarisingAdapter.h Tue Nov 11 12:07:09 2008 +0000 @@ -49,13 +49,47 @@ /** * \class PluginSummarisingAdapter PluginSummarisingAdapter.h <vamp-hostsdk/PluginSummarisingAdapter.h> * + * 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. */ class PluginSummarisingAdapter : public PluginWrapper { public: - PluginSummarisingAdapter(Plugin *plugin); // I take ownership of 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(Plugin *plugin); virtual ~PluginSummarisingAdapter(); bool initialise(size_t channels, size_t stepSize, size_t blockSize); @@ -64,6 +98,20 @@ FeatureSet getRemainingFeatures(); typedef std::set<RealTime> SegmentBoundaries; + + /** + * Specify a series of segment boundaries, such that one summary + * will be returned for each of the contiguous intra-boundary + * segments. This function must be called before + * getSummaryForOutput or getSummaryForAllOutputs. + * + * Note that you cannot retrieve results with multiple different + * segmentations by repeatedly calling this function followed by + * one of the getSummary functions. The summaries are all + * calculated at the first call to any getSummary function, and + * once the summaries have been calculated, they remain + * calculated. + */ void setSummarySegmentBoundaries(const SegmentBoundaries &); enum SummaryType { @@ -107,10 +155,27 @@ ContinuousTimeAverage = 1, }; + /** + * Return summaries of the features that were returned on the + * given output, using the given SummaryType and AveragingMethod. + * + * The plugin must have been fully run (process() and + * getRemainingFeatures() calls all made as appropriate) before + * this function is called. + */ FeatureList getSummaryForOutput(int output, 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. + * + * The plugin must have been fully run (process() and + * getRemainingFeatures() calls all made as appropriate) before + * this function is called. + */ FeatureSet getSummaryForAllOutputs(SummaryType type, AveragingMethod method = SampleAverage);