Chris@25: /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*- vi:set ts=8 sts=4 sw=4: */ Chris@25: Chris@25: /* Chris@25: Vamp Chris@25: Chris@25: An API for audio analysis and feature extraction plugins. Chris@25: Chris@25: Centre for Digital Music, Queen Mary, University of London. Chris@25: Copyright 2006-2009 Chris Cannam and QMUL. Chris@25: Chris@25: Permission is hereby granted, free of charge, to any person Chris@25: obtaining a copy of this software and associated documentation Chris@25: files (the "Software"), to deal in the Software without Chris@25: restriction, including without limitation the rights to use, copy, Chris@25: modify, merge, publish, distribute, sublicense, and/or sell copies Chris@25: of the Software, and to permit persons to whom the Software is Chris@25: furnished to do so, subject to the following conditions: Chris@25: Chris@25: The above copyright notice and this permission notice shall be Chris@25: included in all copies or substantial portions of the Software. Chris@25: Chris@25: THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, Chris@25: EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF Chris@25: MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND Chris@25: NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR Chris@25: ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF Chris@25: CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION Chris@25: WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Chris@25: Chris@25: Except as contained in this notice, the names of the Centre for Chris@25: Digital Music; Queen Mary, University of London; and Chris Cannam Chris@25: shall not be used in advertising or otherwise to promote the sale, Chris@25: use or other dealings in this Software without prior written Chris@25: authorization. Chris@25: */ Chris@25: Chris@25: #ifndef _VAMP_PLUGIN_INPUT_DOMAIN_ADAPTER_H_ Chris@25: #define _VAMP_PLUGIN_INPUT_DOMAIN_ADAPTER_H_ Chris@25: Chris@25: #include "hostguard.h" Chris@25: #include "PluginWrapper.h" Chris@25: Chris@25: _VAMP_SDK_HOSTSPACE_BEGIN(PluginInputDomainAdapter.h) Chris@25: Chris@25: namespace Vamp { Chris@25: Chris@25: namespace HostExt { Chris@25: Chris@25: /** Chris@25: * \class PluginInputDomainAdapter PluginInputDomainAdapter.h Chris@25: * Chris@25: * PluginInputDomainAdapter is a Vamp plugin adapter that converts Chris@25: * time-domain input into frequency-domain input for plugins that need Chris@25: * it. This permits a host to use time- and frequency-domain plugins Chris@25: * interchangeably without needing to handle the conversion itself. Chris@25: * Chris@25: * This adapter uses a basic windowed FFT (using Hann window by Chris@25: * default) that supports power-of-two block sizes only. If a Chris@25: * frequency domain plugin requests a non-power-of-two blocksize, the Chris@25: * adapter will adjust it to a nearby power of two instead. Thus, Chris@25: * getPreferredBlockSize() will always return a power of two if the Chris@25: * wrapped plugin is a frequency domain one. If the plugin doesn't Chris@25: * accept the adjusted power of two block size, initialise() will Chris@25: * fail. Chris@25: * Chris@25: * The adapter provides no way for the host to discover whether the Chris@25: * underlying plugin is actually a time or frequency domain plugin Chris@25: * (except that if the preferred block size is not a power of two, it Chris@25: * must be a time domain plugin). Chris@25: * Chris@25: * The FFT implementation is simple and self-contained, but unlikely Chris@25: * to be the fastest available: a host can usually do better if it Chris@25: * cares enough. Chris@25: * Chris@25: * The window shape for the FFT frame can be set using setWindowType Chris@25: * and the current shape retrieved using getWindowType. (This was Chris@25: * added in v2.3 of the SDK.) Chris@25: * Chris@25: * In every respect other than its input domain handling, the Chris@25: * PluginInputDomainAdapter behaves identically to the plugin that it Chris@25: * wraps. The wrapped plugin will be deleted when the wrapper is Chris@25: * deleted. Chris@25: * Chris@25: * \note This class was introduced in version 1.1 of the Vamp plugin SDK. Chris@25: */ Chris@25: Chris@25: class PluginInputDomainAdapter : public PluginWrapper Chris@25: { Chris@25: public: Chris@25: /** Chris@25: * Construct a PluginInputDomainAdapter wrapping the given plugin. Chris@25: * The adapter takes ownership of the plugin, which will be Chris@25: * deleted when the adapter is deleted. Chris@25: */ Chris@25: PluginInputDomainAdapter(Plugin *plugin); Chris@25: virtual ~PluginInputDomainAdapter(); Chris@25: Chris@25: bool initialise(size_t channels, size_t stepSize, size_t blockSize); Chris@25: void reset(); Chris@25: Chris@25: InputDomain getInputDomain() const; Chris@25: Chris@25: size_t getPreferredStepSize() const; Chris@25: size_t getPreferredBlockSize() const; Chris@25: Chris@25: FeatureSet process(const float *const *inputBuffers, RealTime timestamp); Chris@25: Chris@25: /** Chris@25: * ProcessTimestampMethod determines how the Chris@25: * PluginInputDomainAdapter handles timestamps for the data passed Chris@25: * to the process() function of the plugin it wraps, in the case Chris@25: * where the plugin is expecting frequency-domain data. Chris@25: * Chris@25: * The Vamp specification requires that the timestamp passed to Chris@25: * the plugin for frequency-domain input should be that of the Chris@25: * centre of the processing block, rather than the start as is the Chris@25: * case for time-domain input. Chris@25: * Chris@25: * Since PluginInputDomainAdapter aims to be transparent in use, Chris@25: * it needs to handle this timestamp adjustment itself. However, Chris@25: * some control is available over the method used for adjustment, Chris@25: * by means of the ProcessTimestampMethod setting. Chris@25: * Chris@25: * If ProcessTimestampMethod is set to ShiftTimestamp (the Chris@25: * default), then the data passed to the wrapped plugin will be Chris@25: * calculated from the same input data block as passed to the Chris@25: * wrapper, but the timestamp passed to the plugin will be Chris@25: * advanced by half of the window size. Chris@25: * Chris@25: * If ProcessTimestampMethod is set to ShiftData, then the Chris@25: * timestamp passed to the wrapped plugin will be the same as that Chris@25: * passed to the process call of the wrapper, but the data block Chris@25: * used to calculate the input will be shifted back (earlier) by Chris@25: * half of the window size, with half a block of zero padding at Chris@25: * the start of the first process call. This has the advantage of Chris@25: * preserving the first half block of audio without any Chris@25: * deterioration from window shaping. Chris@25: * Chris@25: * If ProcessTimestampMethod is set to NoShift, then no adjustment Chris@25: * will be made and the timestamps will be incorrect. Chris@25: */ Chris@25: enum ProcessTimestampMethod { Chris@25: ShiftTimestamp, Chris@25: ShiftData, Chris@25: NoShift Chris@25: }; Chris@25: Chris@25: /** Chris@25: * Set the method used for timestamp adjustment in plugins taking Chris@25: * frequency-domain input. See the ProcessTimestampMethod Chris@25: * documentation for details. Chris@25: * Chris@25: * This function must be called before the first call to Chris@25: * process(). Chris@25: */ Chris@25: void setProcessTimestampMethod(ProcessTimestampMethod); Chris@25: Chris@25: /** Chris@25: * Retrieve the method used for timestamp adjustment in plugins Chris@25: * taking frequency-domain input. See the ProcessTimestampMethod Chris@25: * documentation for details. Chris@25: */ Chris@25: ProcessTimestampMethod getProcessTimestampMethod() const; Chris@25: Chris@25: /** Chris@25: * Return the amount by which the timestamps supplied to process() Chris@25: * are being incremented when they are passed to the plugin's own Chris@25: * process() implementation. Chris@25: * Chris@25: * The Vamp API mandates that the timestamp passed to the plugin Chris@25: * for time-domain input should be the time of the first sample in Chris@25: * the block, but the timestamp passed for frequency-domain input Chris@25: * should be the timestamp of the centre of the block. Chris@25: * Chris@25: * The PluginInputDomainAdapter adjusts its timestamps properly so Chris@25: * that the plugin receives correct times, but in some Chris@25: * circumstances (such as for establishing the correct timing of Chris@25: * implicitly-timed features, i.e. features without their own Chris@25: * timestamps) the host may need to be aware that this adjustment Chris@25: * is taking place. Chris@25: * Chris@25: * If the plugin requires time-domain input or the Chris@25: * PluginInputDomainAdapter is configured with its Chris@25: * ProcessTimestampMethod set to ShiftData instead of Chris@25: * ShiftTimestamp, then this function will return zero. Chris@25: * Chris@25: * The result of calling this function before initialise() has Chris@25: * been called is undefined. Chris@25: */ Chris@25: RealTime getTimestampAdjustment() const; Chris@25: Chris@25: /** Chris@25: * The set of supported window shapes. Chris@25: */ Chris@25: enum WindowType { Chris@25: Chris@25: RectangularWindow = 0, Chris@25: Chris@25: BartlettWindow = 1, /// synonym for RectangularWindow Chris@25: TriangularWindow = 1, /// synonym for BartlettWindow Chris@25: Chris@25: HammingWindow = 2, Chris@25: Chris@25: HanningWindow = 3, /// synonym for HannWindow Chris@25: HannWindow = 3, /// synonym for HanningWindow Chris@25: Chris@25: BlackmanWindow = 4, Chris@25: Chris@25: NuttallWindow = 7, Chris@25: Chris@25: BlackmanHarrisWindow = 8 Chris@25: }; Chris@25: Chris@25: /** Chris@25: * Return the current window shape. The default is HanningWindow. Chris@25: */ Chris@25: WindowType getWindowType() const; Chris@25: Chris@25: /** Chris@25: * Set the current window shape. Chris@25: */ Chris@25: void setWindowType(WindowType type); Chris@25: Chris@25: Chris@25: protected: Chris@25: class Impl; Chris@25: Impl *m_impl; Chris@25: }; Chris@25: Chris@25: } Chris@25: Chris@25: } Chris@25: Chris@25: _VAMP_SDK_HOSTSPACE_END(PluginInputDomainAdapter.h) Chris@25: Chris@25: #endif