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