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-2009 Chris Cannam and QMUL. 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_PLUGIN_INPUT_DOMAIN_ADAPTER_H_ cannam@110: #define _VAMP_PLUGIN_INPUT_DOMAIN_ADAPTER_H_ cannam@110: cannam@110: #include "hostguard.h" cannam@110: #include "PluginWrapper.h" cannam@110: cannam@110: _VAMP_SDK_HOSTSPACE_BEGIN(PluginInputDomainAdapter.h) cannam@110: cannam@110: namespace Vamp { cannam@110: cannam@110: namespace HostExt { cannam@110: cannam@110: /** cannam@110: * \class PluginInputDomainAdapter PluginInputDomainAdapter.h cannam@110: * cannam@110: * PluginInputDomainAdapter is a Vamp plugin adapter that converts cannam@110: * time-domain input into frequency-domain input for plugins that need cannam@110: * it. This permits a host to use time- and frequency-domain plugins cannam@110: * interchangeably without needing to handle the conversion itself. cannam@110: * cannam@110: * This adapter uses a basic windowed FFT (using Hann window by cannam@110: * default) that supports power-of-two block sizes only. If a cannam@110: * frequency domain plugin requests a non-power-of-two blocksize, the cannam@110: * adapter will adjust it to a nearby power of two instead. Thus, cannam@110: * getPreferredBlockSize() will always return a power of two if the cannam@110: * wrapped plugin is a frequency domain one. If the plugin doesn't cannam@110: * accept the adjusted power of two block size, initialise() will cannam@110: * fail. cannam@110: * cannam@110: * The adapter provides no way for the host to discover whether the cannam@110: * underlying plugin is actually a time or frequency domain plugin cannam@110: * (except that if the preferred block size is not a power of two, it cannam@110: * must be a time domain plugin). cannam@110: * cannam@110: * The FFT implementation is simple and self-contained, but unlikely cannam@110: * to be the fastest available: a host can usually do better if it cannam@110: * cares enough. cannam@110: * cannam@110: * The window shape for the FFT frame can be set using setWindowType cannam@110: * and the current shape retrieved using getWindowType. (This was cannam@110: * added in v2.3 of the SDK.) cannam@110: * cannam@110: * In every respect other than its input domain handling, the cannam@110: * PluginInputDomainAdapter behaves identically to the plugin that it cannam@110: * wraps. The wrapped plugin will be deleted when the wrapper is cannam@110: * deleted. cannam@110: * cannam@110: * \note This class was introduced in version 1.1 of the Vamp plugin SDK. cannam@110: */ cannam@110: cannam@110: class PluginInputDomainAdapter : public PluginWrapper cannam@110: { cannam@110: public: cannam@110: /** cannam@110: * Construct a PluginInputDomainAdapter wrapping the given plugin. cannam@110: * The adapter takes ownership of the plugin, which will be cannam@110: * deleted when the adapter is deleted. cannam@110: */ cannam@110: PluginInputDomainAdapter(Plugin *plugin); cannam@110: virtual ~PluginInputDomainAdapter(); cannam@110: cannam@110: bool initialise(size_t channels, size_t stepSize, size_t blockSize); cannam@110: void reset(); cannam@110: cannam@110: InputDomain getInputDomain() const; cannam@110: cannam@110: size_t getPreferredStepSize() const; cannam@110: size_t getPreferredBlockSize() const; cannam@110: cannam@110: FeatureSet process(const float *const *inputBuffers, RealTime timestamp); cannam@110: cannam@110: /** cannam@110: * ProcessTimestampMethod determines how the cannam@110: * PluginInputDomainAdapter handles timestamps for the data passed cannam@110: * to the process() function of the plugin it wraps, in the case cannam@110: * where the plugin is expecting frequency-domain data. cannam@110: * cannam@110: * The Vamp specification requires that the timestamp passed to cannam@110: * the plugin for frequency-domain input should be that of the cannam@110: * centre of the processing block, rather than the start as is the cannam@110: * case for time-domain input. cannam@110: * cannam@110: * Since PluginInputDomainAdapter aims to be transparent in use, cannam@110: * it needs to handle this timestamp adjustment itself. However, cannam@110: * some control is available over the method used for adjustment, cannam@110: * by means of the ProcessTimestampMethod setting. cannam@110: * cannam@110: * If ProcessTimestampMethod is set to ShiftTimestamp (the cannam@110: * default), then the data passed to the wrapped plugin will be cannam@110: * calculated from the same input data block as passed to the cannam@110: * wrapper, but the timestamp passed to the plugin will be cannam@110: * advanced by half of the window size. cannam@110: * cannam@110: * If ProcessTimestampMethod is set to ShiftData, then the cannam@110: * timestamp passed to the wrapped plugin will be the same as that cannam@110: * passed to the process call of the wrapper, but the data block cannam@110: * used to calculate the input will be shifted back (earlier) by cannam@110: * half of the window size, with half a block of zero padding at cannam@110: * the start of the first process call. This has the advantage of cannam@110: * preserving the first half block of audio without any cannam@110: * deterioration from window shaping. cannam@110: * cannam@110: * If ProcessTimestampMethod is set to NoShift, then no adjustment cannam@110: * will be made and the timestamps will be incorrect. cannam@110: */ cannam@110: enum ProcessTimestampMethod { cannam@110: ShiftTimestamp, cannam@110: ShiftData, cannam@110: NoShift cannam@110: }; cannam@110: cannam@110: /** cannam@110: * Set the method used for timestamp adjustment in plugins taking cannam@110: * frequency-domain input. See the ProcessTimestampMethod cannam@110: * documentation for details. cannam@110: * cannam@110: * This function must be called before the first call to cannam@110: * process(). cannam@110: */ cannam@110: void setProcessTimestampMethod(ProcessTimestampMethod); cannam@110: cannam@110: /** cannam@110: * Retrieve the method used for timestamp adjustment in plugins cannam@110: * taking frequency-domain input. See the ProcessTimestampMethod cannam@110: * documentation for details. cannam@110: */ cannam@110: ProcessTimestampMethod getProcessTimestampMethod() const; cannam@110: cannam@110: /** cannam@110: * Return the amount by which the timestamps supplied to process() cannam@110: * are being incremented when they are passed to the plugin's own cannam@110: * process() implementation. cannam@110: * cannam@110: * The Vamp API mandates that the timestamp passed to the plugin cannam@110: * for time-domain input should be the time of the first sample in cannam@110: * the block, but the timestamp passed for frequency-domain input cannam@110: * should be the timestamp of the centre of the block. cannam@110: * cannam@110: * The PluginInputDomainAdapter adjusts its timestamps properly so cannam@110: * that the plugin receives correct times, but in some cannam@110: * circumstances (such as for establishing the correct timing of cannam@110: * implicitly-timed features, i.e. features without their own cannam@110: * timestamps) the host may need to be aware that this adjustment cannam@110: * is taking place. cannam@110: * cannam@110: * If the plugin requires time-domain input or the cannam@110: * PluginInputDomainAdapter is configured with its cannam@110: * ProcessTimestampMethod set to ShiftData instead of cannam@110: * ShiftTimestamp, then this function will return zero. cannam@110: * cannam@110: * The result of calling this function before initialise() has cannam@110: * been called is undefined. cannam@110: */ cannam@110: RealTime getTimestampAdjustment() const; cannam@110: cannam@110: /** cannam@110: * The set of supported window shapes. cannam@110: */ cannam@110: enum WindowType { cannam@110: cannam@110: RectangularWindow = 0, cannam@110: cannam@110: BartlettWindow = 1, /// synonym for RectangularWindow cannam@110: TriangularWindow = 1, /// synonym for BartlettWindow cannam@110: cannam@110: HammingWindow = 2, cannam@110: cannam@110: HanningWindow = 3, /// synonym for HannWindow cannam@110: HannWindow = 3, /// synonym for HanningWindow cannam@110: cannam@110: BlackmanWindow = 4, cannam@110: cannam@110: NuttallWindow = 7, cannam@110: cannam@110: BlackmanHarrisWindow = 8 cannam@110: }; cannam@110: cannam@110: /** cannam@110: * Return the current window shape. The default is HanningWindow. cannam@110: */ cannam@110: WindowType getWindowType() const; cannam@110: cannam@110: /** cannam@110: * Set the current window shape. cannam@110: */ cannam@110: void setWindowType(WindowType type); cannam@110: cannam@110: cannam@110: protected: cannam@110: class Impl; cannam@110: Impl *m_impl; cannam@110: }; cannam@110: cannam@110: } cannam@110: cannam@110: } cannam@110: cannam@110: _VAMP_SDK_HOSTSPACE_END(PluginInputDomainAdapter.h) cannam@110: cannam@110: #endif