annotate vamp-hostsdk/PluginInputDomainAdapter.h @ 541:0e32c328b02a tip

Added tag vamp-plugin-sdk-v2.10 for changeset fa74c473e48c
author Chris Cannam
date Mon, 18 May 2020 11:53:49 +0100
parents 8ffb8985ae8f
children
rev   line source
cannam@233 1 /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*- vi:set ts=8 sts=4 sw=4: */
cannam@233 2
cannam@233 3 /*
cannam@233 4 Vamp
cannam@233 5
cannam@233 6 An API for audio analysis and feature extraction plugins.
cannam@233 7
cannam@233 8 Centre for Digital Music, Queen Mary, University of London.
cannam@290 9 Copyright 2006-2009 Chris Cannam and QMUL.
cannam@233 10
cannam@233 11 Permission is hereby granted, free of charge, to any person
cannam@233 12 obtaining a copy of this software and associated documentation
cannam@233 13 files (the "Software"), to deal in the Software without
cannam@233 14 restriction, including without limitation the rights to use, copy,
cannam@233 15 modify, merge, publish, distribute, sublicense, and/or sell copies
cannam@233 16 of the Software, and to permit persons to whom the Software is
cannam@233 17 furnished to do so, subject to the following conditions:
cannam@233 18
cannam@233 19 The above copyright notice and this permission notice shall be
cannam@233 20 included in all copies or substantial portions of the Software.
cannam@233 21
cannam@233 22 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
cannam@233 23 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
cannam@233 24 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
cannam@233 25 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
cannam@233 26 ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
cannam@233 27 CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
cannam@233 28 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
cannam@233 29
cannam@233 30 Except as contained in this notice, the names of the Centre for
cannam@233 31 Digital Music; Queen Mary, University of London; and Chris Cannam
cannam@233 32 shall not be used in advertising or otherwise to promote the sale,
cannam@233 33 use or other dealings in this Software without prior written
cannam@233 34 authorization.
cannam@233 35 */
cannam@233 36
cannam@233 37 #ifndef _VAMP_PLUGIN_INPUT_DOMAIN_ADAPTER_H_
cannam@233 38 #define _VAMP_PLUGIN_INPUT_DOMAIN_ADAPTER_H_
cannam@233 39
cannam@243 40 #include "hostguard.h"
cannam@233 41 #include "PluginWrapper.h"
cannam@233 42
cannam@263 43 _VAMP_SDK_HOSTSPACE_BEGIN(PluginInputDomainAdapter.h)
cannam@263 44
cannam@233 45 namespace Vamp {
cannam@233 46
cannam@233 47 namespace HostExt {
cannam@233 48
cannam@233 49 /**
cannam@233 50 * \class PluginInputDomainAdapter PluginInputDomainAdapter.h <vamp-hostsdk/PluginInputDomainAdapter.h>
cannam@233 51 *
cannam@233 52 * PluginInputDomainAdapter is a Vamp plugin adapter that converts
cannam@233 53 * time-domain input into frequency-domain input for plugins that need
cannam@233 54 * it. This permits a host to use time- and frequency-domain plugins
cannam@233 55 * interchangeably without needing to handle the conversion itself.
cannam@233 56 *
Chris@317 57 * This adapter uses a basic windowed FFT (using Hann window by
Chris@317 58 * default) that supports power-of-two block sizes only. If a
Chris@317 59 * frequency domain plugin requests a non-power-of-two blocksize, the
Chris@317 60 * adapter will adjust it to a nearby power of two instead. Thus,
Chris@317 61 * getPreferredBlockSize() will always return a power of two if the
Chris@317 62 * wrapped plugin is a frequency domain one. If the plugin doesn't
Chris@317 63 * accept the adjusted power of two block size, initialise() will
Chris@317 64 * fail.
cannam@233 65 *
cannam@233 66 * The adapter provides no way for the host to discover whether the
cannam@233 67 * underlying plugin is actually a time or frequency domain plugin
cannam@233 68 * (except that if the preferred block size is not a power of two, it
cannam@233 69 * must be a time domain plugin).
cannam@233 70 *
cannam@233 71 * The FFT implementation is simple and self-contained, but unlikely
cannam@233 72 * to be the fastest available: a host can usually do better if it
cannam@233 73 * cares enough.
cannam@233 74 *
Chris@317 75 * The window shape for the FFT frame can be set using setWindowType
Chris@317 76 * and the current shape retrieved using getWindowType. (This was
Chris@317 77 * added in v2.3 of the SDK.)
Chris@317 78 *
cannam@233 79 * In every respect other than its input domain handling, the
cannam@233 80 * PluginInputDomainAdapter behaves identically to the plugin that it
cannam@233 81 * wraps. The wrapped plugin will be deleted when the wrapper is
Chris@538 82 * deleted. If you wish to prevent this, call disownPlugin().
cannam@233 83 *
cannam@233 84 * \note This class was introduced in version 1.1 of the Vamp plugin SDK.
cannam@233 85 */
cannam@233 86
cannam@233 87 class PluginInputDomainAdapter : public PluginWrapper
cannam@233 88 {
cannam@233 89 public:
cannam@248 90 /**
cannam@248 91 * Construct a PluginInputDomainAdapter wrapping the given plugin.
cannam@248 92 * The adapter takes ownership of the plugin, which will be
Chris@538 93 * deleted when the adapter is deleted. If you wish to prevent
Chris@538 94 * this, call disownPlugin().
cannam@248 95 */
cannam@248 96 PluginInputDomainAdapter(Plugin *plugin);
cannam@233 97 virtual ~PluginInputDomainAdapter();
cannam@233 98
cannam@233 99 bool initialise(size_t channels, size_t stepSize, size_t blockSize);
cannam@288 100 void reset();
cannam@233 101
cannam@233 102 InputDomain getInputDomain() const;
cannam@233 103
cannam@233 104 size_t getPreferredStepSize() const;
cannam@233 105 size_t getPreferredBlockSize() const;
cannam@233 106
cannam@233 107 FeatureSet process(const float *const *inputBuffers, RealTime timestamp);
cannam@233 108
cannam@233 109 /**
cannam@288 110 * ProcessTimestampMethod determines how the
cannam@288 111 * PluginInputDomainAdapter handles timestamps for the data passed
cannam@288 112 * to the process() function of the plugin it wraps, in the case
cannam@288 113 * where the plugin is expecting frequency-domain data.
cannam@288 114 *
cannam@298 115 * The Vamp specification requires that the timestamp passed to
cannam@298 116 * the plugin for frequency-domain input should be that of the
cannam@298 117 * centre of the processing block, rather than the start as is the
cannam@298 118 * case for time-domain input.
cannam@288 119 *
cannam@298 120 * Since PluginInputDomainAdapter aims to be transparent in use,
cannam@298 121 * it needs to handle this timestamp adjustment itself. However,
cannam@298 122 * some control is available over the method used for adjustment,
cannam@298 123 * by means of the ProcessTimestampMethod setting.
cannam@288 124 *
cannam@298 125 * If ProcessTimestampMethod is set to ShiftTimestamp (the
cannam@298 126 * default), then the data passed to the wrapped plugin will be
cannam@298 127 * calculated from the same input data block as passed to the
cannam@298 128 * wrapper, but the timestamp passed to the plugin will be
cannam@298 129 * advanced by half of the window size.
cannam@288 130 *
cannam@298 131 * If ProcessTimestampMethod is set to ShiftData, then the
cannam@298 132 * timestamp passed to the wrapped plugin will be the same as that
cannam@298 133 * passed to the process call of the wrapper, but the data block
cannam@298 134 * used to calculate the input will be shifted back (earlier) by
cannam@298 135 * half of the window size, with half a block of zero padding at
cannam@298 136 * the start of the first process call. This has the advantage of
cannam@298 137 * preserving the first half block of audio without any
cannam@298 138 * deterioration from window shaping.
cannam@298 139 *
cannam@298 140 * If ProcessTimestampMethod is set to NoShift, then no adjustment
cannam@298 141 * will be made and the timestamps will be incorrect.
cannam@298 142 */
cannam@298 143 enum ProcessTimestampMethod {
cannam@298 144 ShiftTimestamp,
cannam@298 145 ShiftData,
cannam@298 146 NoShift
cannam@298 147 };
cannam@298 148
cannam@298 149 /**
cannam@298 150 * Set the method used for timestamp adjustment in plugins taking
cannam@298 151 * frequency-domain input. See the ProcessTimestampMethod
cannam@298 152 * documentation for details.
cannam@288 153 *
cannam@288 154 * This function must be called before the first call to
cannam@288 155 * process().
cannam@288 156 */
cannam@298 157 void setProcessTimestampMethod(ProcessTimestampMethod);
cannam@288 158
cannam@298 159 /**
cannam@298 160 * Retrieve the method used for timestamp adjustment in plugins
cannam@298 161 * taking frequency-domain input. See the ProcessTimestampMethod
cannam@298 162 * documentation for details.
cannam@298 163 */
cannam@288 164 ProcessTimestampMethod getProcessTimestampMethod() const;
cannam@288 165
cannam@288 166 /**
cannam@233 167 * Return the amount by which the timestamps supplied to process()
cannam@233 168 * are being incremented when they are passed to the plugin's own
cannam@233 169 * process() implementation.
cannam@233 170 *
cannam@233 171 * The Vamp API mandates that the timestamp passed to the plugin
cannam@233 172 * for time-domain input should be the time of the first sample in
cannam@233 173 * the block, but the timestamp passed for frequency-domain input
cannam@233 174 * should be the timestamp of the centre of the block.
cannam@233 175 *
cannam@233 176 * The PluginInputDomainAdapter adjusts its timestamps properly so
cannam@233 177 * that the plugin receives correct times, but in some
cannam@233 178 * circumstances (such as for establishing the correct timing of
cannam@233 179 * implicitly-timed features, i.e. features without their own
cannam@233 180 * timestamps) the host may need to be aware that this adjustment
cannam@233 181 * is taking place.
cannam@233 182 *
cannam@288 183 * If the plugin requires time-domain input or the
cannam@288 184 * PluginInputDomainAdapter is configured with its
cannam@288 185 * ProcessTimestampMethod set to ShiftData instead of
cannam@288 186 * ShiftTimestamp, then this function will return zero.
cannam@288 187 *
cannam@288 188 * The result of calling this function before initialise() has
cannam@288 189 * been called is undefined.
cannam@233 190 */
cannam@233 191 RealTime getTimestampAdjustment() const;
cannam@233 192
Chris@317 193 /**
Chris@317 194 * The set of supported window shapes.
Chris@317 195 */
Chris@317 196 enum WindowType {
Chris@317 197
Chris@317 198 RectangularWindow = 0,
Chris@317 199
Chris@317 200 BartlettWindow = 1, /// synonym for RectangularWindow
Chris@317 201 TriangularWindow = 1, /// synonym for BartlettWindow
Chris@317 202
Chris@317 203 HammingWindow = 2,
Chris@317 204
Chris@317 205 HanningWindow = 3, /// synonym for HannWindow
Chris@317 206 HannWindow = 3, /// synonym for HanningWindow
Chris@317 207
Chris@317 208 BlackmanWindow = 4,
Chris@317 209
Chris@317 210 NuttallWindow = 7,
Chris@317 211
Chris@317 212 BlackmanHarrisWindow = 8
Chris@317 213 };
Chris@317 214
Chris@317 215 /**
Chris@317 216 * Return the current window shape. The default is HanningWindow.
Chris@317 217 */
Chris@317 218 WindowType getWindowType() const;
Chris@317 219
Chris@317 220 /**
Chris@317 221 * Set the current window shape.
Chris@317 222 */
Chris@317 223 void setWindowType(WindowType type);
Chris@317 224
Chris@317 225
cannam@233 226 protected:
cannam@233 227 class Impl;
cannam@233 228 Impl *m_impl;
cannam@233 229 };
cannam@233 230
cannam@233 231 }
cannam@233 232
cannam@233 233 }
cannam@233 234
cannam@263 235 _VAMP_SDK_HOSTSPACE_END(PluginInputDomainAdapter.h)
cannam@263 236
cannam@233 237 #endif