cannam@110: /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*- vi:set ts=8 sts=4 sw=4: */ cannam@110: cannam@110: /* cannam@110: Vamp cannam@110: cannam@110: An API for audio analysis and feature extraction plugins. cannam@110: cannam@110: Centre for Digital Music, Queen Mary, University of London. cannam@110: Copyright 2006 Chris Cannam. cannam@110: cannam@110: Permission is hereby granted, free of charge, to any person cannam@110: obtaining a copy of this software and associated documentation cannam@110: files (the "Software"), to deal in the Software without cannam@110: restriction, including without limitation the rights to use, copy, cannam@110: modify, merge, publish, distribute, sublicense, and/or sell copies cannam@110: of the Software, and to permit persons to whom the Software is cannam@110: furnished to do so, subject to the following conditions: cannam@110: cannam@110: The above copyright notice and this permission notice shall be cannam@110: included in all copies or substantial portions of the Software. cannam@110: cannam@110: THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, cannam@110: EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF cannam@110: MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND cannam@110: NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR cannam@110: ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF cannam@110: CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION cannam@110: WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. cannam@110: cannam@110: Except as contained in this notice, the names of the Centre for cannam@110: Digital Music; Queen Mary, University of London; and Chris Cannam cannam@110: shall not be used in advertising or otherwise to promote the sale, cannam@110: use or other dealings in this Software without prior written cannam@110: authorization. cannam@110: */ cannam@110: cannam@110: #ifndef _VAMP_SDK_PLUGIN_H_ cannam@110: #define _VAMP_SDK_PLUGIN_H_ cannam@110: cannam@110: #include cannam@110: #include cannam@110: #include cannam@110: cannam@110: #include "PluginBase.h" cannam@110: #include "RealTime.h" cannam@110: cannam@110: #include "plugguard.h" cannam@110: _VAMP_SDK_PLUGSPACE_BEGIN(Plugin.h) cannam@110: cannam@110: namespace Vamp { cannam@110: cannam@110: /** cannam@110: * \class Plugin Plugin.h cannam@110: * cannam@110: * Vamp::Plugin is a base class for plugin instance classes cannam@110: * that provide feature extraction from audio or related data. cannam@110: * cannam@110: * In most cases, the input will be audio and the output will be a cannam@110: * stream of derived data at a lower sampling resolution than the cannam@110: * input. cannam@110: * cannam@110: * Note that this class inherits several abstract methods from cannam@110: * PluginBase. These must be implemented by the subclass. cannam@110: * cannam@110: * cannam@110: * PLUGIN LIFECYCLE cannam@110: * cannam@110: * Feature extraction plugins are managed differently from real-time cannam@110: * plugins (such as VST effects). The main difference is that the cannam@110: * parameters for a feature extraction plugin are configured before cannam@110: * the plugin is used, and do not change during use. cannam@110: * cannam@110: * 1. Host constructs the plugin, passing it the input sample rate. cannam@110: * The plugin may do basic initialisation, but should not do anything cannam@110: * computationally expensive at this point. You must make sure your cannam@110: * plugin is cheap to construct, otherwise you'll seriously affect the cannam@110: * startup performance of almost all hosts. If you have serious cannam@110: * initialisation to do, the proper place is in initialise() (step 5). cannam@110: * cannam@110: * 2. Host may query the plugin's available outputs. cannam@110: * cannam@110: * 3. Host queries programs and parameter descriptors, and may set cannam@110: * some or all of them. Parameters that are not explicitly set should cannam@110: * take their default values as specified in the parameter descriptor. cannam@110: * When a program is set, the parameter values may change and the host cannam@110: * will re-query them to check. cannam@110: * cannam@110: * 4. Host queries the preferred step size, block size and number of cannam@110: * channels. These may all vary depending on the parameter values. cannam@110: * (Note however that you cannot make the number of distinct outputs cannam@110: * dependent on parameter values.) cannam@110: * cannam@110: * 5. Plugin is properly initialised with a call to initialise. This cannam@110: * fixes the step size, block size, and number of channels, as well as cannam@110: * all of the parameter and program settings. If the values passed in cannam@110: * to initialise do not match the plugin's advertised preferred values cannam@110: * from step 4, the plugin may refuse to initialise and return false cannam@110: * (although if possible it should accept the new values). Any cannam@110: * computationally expensive setup code should take place here. cannam@110: * cannam@110: * 6. Host finally checks the number of values, resolution, extents cannam@110: * etc per output (which may vary depending on the number of channels, cannam@110: * step size and block size as well as the parameter values). cannam@110: * cannam@110: * 7. Host will repeatedly call the process method to pass in blocks cannam@110: * of input data. This method may return features extracted from that cannam@110: * data (if the plugin is causal). cannam@110: * cannam@110: * 8. Host will call getRemainingFeatures exactly once, after all the cannam@110: * input data has been processed. This may return any non-causal or cannam@110: * leftover features. cannam@110: * cannam@110: * 9. At any point after initialise was called, the host may cannam@110: * optionally call the reset method and restart processing. (This cannam@110: * does not mean it can change the parameters, which are fixed from cannam@110: * initialise until destruction.) cannam@110: * cannam@110: * A plugin does not need to handle the case where setParameter or cannam@110: * selectProgram is called after initialise has been called. It's the cannam@110: * host's responsibility not to do that. Similarly, the plugin may cannam@110: * safely assume that initialise is called no more than once. cannam@110: */ cannam@110: cannam@110: class Plugin : public PluginBase cannam@110: { cannam@110: public: cannam@110: virtual ~Plugin() { } cannam@110: cannam@110: /** cannam@110: * Initialise a plugin to prepare it for use with the given number cannam@110: * of input channels, step size (window increment, in sample cannam@110: * frames) and block size (window size, in sample frames). cannam@110: * cannam@110: * The input sample rate should have been already specified at cannam@110: * construction time. cannam@110: * cannam@110: * Return true for successful initialisation, false if the number cannam@110: * of input channels, step size and/or block size cannot be cannam@110: * supported. cannam@110: */ cannam@110: virtual bool initialise(size_t inputChannels, cannam@110: size_t stepSize, cannam@110: size_t blockSize) = 0; cannam@110: cannam@110: /** cannam@110: * Reset the plugin after use, to prepare it for another clean cannam@110: * run. Not called for the first initialisation (i.e. initialise cannam@110: * must also do a reset). cannam@110: */ cannam@110: virtual void reset() = 0; cannam@110: cannam@110: enum InputDomain { TimeDomain, FrequencyDomain }; cannam@110: cannam@110: /** cannam@110: * Get the plugin's required input domain. cannam@110: * cannam@110: * If this is TimeDomain, the samples provided to the process() cannam@110: * function (below) will be in the time domain, as for a cannam@110: * traditional audio processing plugin. cannam@110: * cannam@110: * If this is FrequencyDomain, the host will carry out a windowed cannam@110: * FFT of size equal to the negotiated block size on the data cannam@110: * before passing the frequency bin data in to process(). The cannam@110: * input data for the FFT will be rotated so as to place the cannam@110: * origin in the centre of the block. cannam@110: * The plugin does not get to choose the window type -- the host cannam@110: * will either let the user do so, or will use a Hanning window. cannam@110: */ cannam@110: virtual InputDomain getInputDomain() const = 0; cannam@110: cannam@110: /** cannam@110: * Get the preferred block size (window size -- the number of cannam@110: * sample frames passed in each block to the process() function). cannam@110: * This should be called before initialise(). cannam@110: * cannam@110: * A plugin that can handle any block size may return 0. The cannam@110: * final block size will be set in the initialise() call. cannam@110: */ cannam@110: virtual size_t getPreferredBlockSize() const { return 0; } cannam@110: cannam@110: /** cannam@110: * Get the preferred step size (window increment -- the distance cannam@110: * in sample frames between the start frames of consecutive blocks cannam@110: * passed to the process() function) for the plugin. This should cannam@110: * be called before initialise(). cannam@110: * cannam@110: * A plugin may return 0 if it has no particular interest in the cannam@110: * step size. In this case, the host should make the step size cannam@110: * equal to the block size if the plugin is accepting input in the cannam@110: * time domain. If the plugin is accepting input in the frequency cannam@110: * domain, the host may use any step size. The final step size cannam@110: * will be set in the initialise() call. cannam@110: */ cannam@110: virtual size_t getPreferredStepSize() const { return 0; } cannam@110: cannam@110: /** cannam@110: * Get the minimum supported number of input channels. cannam@110: */ cannam@110: virtual size_t getMinChannelCount() const { return 1; } cannam@110: cannam@110: /** cannam@110: * Get the maximum supported number of input channels. cannam@110: */ cannam@110: virtual size_t getMaxChannelCount() const { return 1; } cannam@110: cannam@110: struct OutputDescriptor cannam@110: { cannam@110: /** cannam@110: * The name of the output, in computer-usable form. Should be cannam@110: * reasonably short and without whitespace or punctuation, using cannam@110: * the characters [a-zA-Z0-9_-] only. cannam@110: * Example: "zero_crossing_count" cannam@110: */ cannam@110: std::string identifier; cannam@110: cannam@110: /** cannam@110: * The human-readable name of the output. cannam@110: * Example: "Zero Crossing Counts" cannam@110: */ cannam@110: std::string name; cannam@110: cannam@110: /** cannam@110: * A human-readable short text describing the output. May be cannam@110: * empty if the name has said it all already. cannam@110: * Example: "The number of zero crossing points per processing block" cannam@110: */ cannam@110: std::string description; cannam@110: cannam@110: /** cannam@110: * The unit of the output, in human-readable form. cannam@110: */ cannam@110: std::string unit; cannam@110: cannam@110: /** cannam@110: * True if the output has the same number of values per sample cannam@110: * for every output sample. Outputs for which this is false cannam@110: * are unlikely to be very useful in a general-purpose host. cannam@110: */ cannam@110: bool hasFixedBinCount; cannam@110: cannam@110: /** cannam@110: * The number of values per result of the output. Undefined cannam@110: * if hasFixedBinCount is false. If this is zero, the output cannam@110: * is point data (i.e. only the time of each output is of cannam@110: * interest, the value list will be empty). cannam@110: */ cannam@110: size_t binCount; cannam@110: cannam@110: /** cannam@110: * The (human-readable) names of each of the bins, if cannam@110: * appropriate. This is always optional. cannam@110: */ cannam@110: std::vector binNames; cannam@110: cannam@110: /** cannam@110: * True if the results in each output bin fall within a fixed cannam@110: * numeric range (minimum and maximum values). Undefined if cannam@110: * binCount is zero. cannam@110: */ cannam@110: bool hasKnownExtents; cannam@110: cannam@110: /** cannam@110: * Minimum value of the results in the output. Undefined if cannam@110: * hasKnownExtents is false or binCount is zero. cannam@110: */ cannam@110: float minValue; cannam@110: cannam@110: /** cannam@110: * Maximum value of the results in the output. Undefined if cannam@110: * hasKnownExtents is false or binCount is zero. cannam@110: */ cannam@110: float maxValue; cannam@110: cannam@110: /** cannam@110: * True if the output values are quantized to a particular cannam@110: * resolution. Undefined if binCount is zero. cannam@110: */ cannam@110: bool isQuantized; cannam@110: cannam@110: /** cannam@110: * Quantization resolution of the output values (e.g. 1.0 if cannam@110: * they are all integers). Undefined if isQuantized is false cannam@110: * or binCount is zero. cannam@110: */ cannam@110: float quantizeStep; cannam@110: cannam@110: enum SampleType { cannam@110: cannam@110: /// Results from each process() align with that call's block start cannam@110: OneSamplePerStep, cannam@110: cannam@110: /// Results are evenly spaced in time (sampleRate specified below) cannam@110: FixedSampleRate, cannam@110: cannam@110: /// Results are unevenly spaced and have individual timestamps cannam@110: VariableSampleRate cannam@110: }; cannam@110: cannam@110: /** cannam@110: * Positioning in time of the output results. cannam@110: */ cannam@110: SampleType sampleType; cannam@110: cannam@110: /** cannam@110: * Sample rate of the output results, as samples per second. cannam@110: * Undefined if sampleType is OneSamplePerStep. cannam@110: * cannam@110: * If sampleType is VariableSampleRate and this value is cannam@110: * non-zero, then it may be used to calculate a resolution for cannam@110: * the output (i.e. the "duration" of each sample, in time, cannam@110: * will be 1/sampleRate seconds). It's recommended to set cannam@110: * this to zero if that behaviour is not desired. cannam@110: */ cannam@110: float sampleRate; cannam@110: cannam@110: /** cannam@110: * True if the returned results for this output are known to cannam@110: * have a duration field. cannam@110: */ cannam@110: bool hasDuration; cannam@110: cannam@110: OutputDescriptor() : // defaults for mandatory non-class-type members cannam@110: hasFixedBinCount(false), hasKnownExtents(false), isQuantized(false), cannam@110: sampleType(OneSamplePerStep), sampleRate(0), hasDuration(false) { } cannam@110: }; cannam@110: cannam@110: typedef std::vector OutputList; cannam@110: cannam@110: /** cannam@110: * Get the outputs of this plugin. An output's index in this list cannam@110: * is used as its numeric index when looking it up in the cannam@110: * FeatureSet returned from the process() call. cannam@110: */ cannam@110: virtual OutputList getOutputDescriptors() const = 0; cannam@110: cannam@110: struct Feature cannam@110: { cannam@110: /** cannam@110: * True if an output feature has its own timestamp. This is cannam@110: * mandatory if the output has VariableSampleRate, optional if cannam@110: * the output has FixedSampleRate, and unused if the output cannam@110: * has OneSamplePerStep. cannam@110: */ cannam@110: bool hasTimestamp; cannam@110: cannam@110: /** cannam@110: * Timestamp of the output feature. This is mandatory if the cannam@110: * output has VariableSampleRate or if the output has cannam@110: * FixedSampleRate and hasTimestamp is true, and unused cannam@110: * otherwise. cannam@110: */ cannam@110: RealTime timestamp; cannam@110: cannam@110: /** cannam@110: * True if an output feature has a specified duration. This cannam@110: * is optional if the output has VariableSampleRate or cannam@110: * FixedSampleRate, and and unused if the output has cannam@110: * OneSamplePerStep. cannam@110: */ cannam@110: bool hasDuration; cannam@110: cannam@110: /** cannam@110: * Duration of the output feature. This is mandatory if the cannam@110: * output has VariableSampleRate or FixedSampleRate and cannam@110: * hasDuration is true, and unused otherwise. cannam@110: */ cannam@110: RealTime duration; cannam@110: cannam@110: /** cannam@110: * Results for a single sample of this feature. If the output cannam@110: * hasFixedBinCount, there must be the same number of values cannam@110: * as the output's binCount count. cannam@110: */ cannam@110: std::vector values; cannam@110: cannam@110: /** cannam@110: * Label for the sample of this feature. cannam@110: */ cannam@110: std::string label; cannam@110: cannam@110: Feature() : // defaults for mandatory non-class-type members cannam@110: hasTimestamp(false), hasDuration(false) { } cannam@110: }; cannam@110: cannam@110: typedef std::vector FeatureList; cannam@110: cannam@110: typedef std::map FeatureSet; // key is output no cannam@110: cannam@110: /** cannam@110: * Process a single block of input data. cannam@110: * cannam@110: * If the plugin's inputDomain is TimeDomain, inputBuffers will cannam@110: * point to one array of floats per input channel, and each of cannam@110: * these arrays will contain blockSize consecutive audio samples cannam@110: * (the host will zero-pad as necessary). The timestamp in this cannam@110: * case will be the real time in seconds of the start of the cannam@110: * supplied block of samples. cannam@110: * cannam@110: * If the plugin's inputDomain is FrequencyDomain, inputBuffers cannam@110: * will point to one array of floats per input channel, and each cannam@110: * of these arrays will contain blockSize/2+1 consecutive pairs of cannam@110: * real and imaginary component floats corresponding to bins cannam@110: * 0..(blockSize/2) of the FFT output. That is, bin 0 (the first cannam@110: * pair of floats) contains the DC output, up to bin blockSize/2 cannam@110: * which contains the Nyquist-frequency output. There will cannam@110: * therefore be blockSize+2 floats per channel in total. The cannam@110: * timestamp will be the real time in seconds of the centre of the cannam@110: * FFT input window (i.e. the very first block passed to process cannam@110: * might contain the FFT of half a block of zero samples and the cannam@110: * first half-block of the actual data, with a timestamp of zero). cannam@110: * cannam@110: * Return any features that have become available after this cannam@110: * process call. (These do not necessarily have to fall within cannam@110: * the process block, except for OneSamplePerStep outputs.) cannam@110: */ cannam@110: virtual FeatureSet process(const float *const *inputBuffers, cannam@110: RealTime timestamp) = 0; cannam@110: cannam@110: /** cannam@110: * After all blocks have been processed, calculate and return any cannam@110: * remaining features derived from the complete input. cannam@110: */ cannam@110: virtual FeatureSet getRemainingFeatures() = 0; cannam@110: cannam@110: /** cannam@110: * Used to distinguish between Vamp::Plugin and other potential cannam@110: * sibling subclasses of PluginBase. Do not reimplement this cannam@110: * function in your subclass. cannam@110: */ cannam@110: virtual std::string getType() const { return "Feature Extraction Plugin"; } cannam@110: cannam@110: protected: cannam@110: Plugin(float inputSampleRate) : cannam@110: m_inputSampleRate(inputSampleRate) { } cannam@110: cannam@110: float m_inputSampleRate; cannam@110: }; cannam@110: cannam@110: } cannam@110: cannam@110: _VAMP_SDK_PLUGSPACE_END(Plugin.h) cannam@110: cannam@110: #endif cannam@110: cannam@110: cannam@110: