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