libs/vamp-sdk/vamp-hostsdk/PluginBufferingAdapter.h

   1 /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*-  vi:set ts=8 sts=4 sw=4: */
   2
   3 /*
   4     Vamp
   5
   6     An API for audio analysis and feature extraction plugins.
   7
   8     Centre for Digital Music, Queen Mary, University of London.
   9     Copyright 2006-2009 Chris Cannam and QMUL.
  10     This file by Mark Levy and Chris Cannam, Copyright 2007-2008 QMUL.
  11
  12     Permission is hereby granted, free of charge, to any person
  13     obtaining a copy of this software and associated documentation
  14     files (the "Software"), to deal in the Software without
  15     restriction, including without limitation the rights to use, copy,
  16     modify, merge, publish, distribute, sublicense, and/or sell copies
  17     of the Software, and to permit persons to whom the Software is
  18     furnished to do so, subject to the following conditions:
  19
  20     The above copyright notice and this permission notice shall be
  21     included in all copies or substantial portions of the Software.
  22
  23     THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  24     EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  25     MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  26     NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
  27     ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
  28     CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  29     WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  30
  31     Except as contained in this notice, the names of the Centre for
  32     Digital Music; Queen Mary, University of London; and Chris Cannam
  33     shall not be used in advertising or otherwise to promote the sale,
  34     use or other dealings in this Software without prior written
  35     authorization.
  36 */
  37
  38 #ifndef _VAMP_PLUGIN_BUFFERING_ADAPTER_H_
  39 #define _VAMP_PLUGIN_BUFFERING_ADAPTER_H_
  40
  41 #include "hostguard.h"
  42 #include "PluginWrapper.h"
  43
  44 _VAMP_SDK_HOSTSPACE_BEGIN(PluginBufferingAdapter.h)
  45
  46 namespace Vamp {
  47
  48 namespace HostExt {
  49
  50 /**
  51  * \class PluginBufferingAdapter PluginBufferingAdapter.h <vamp-hostsdk/PluginBufferingAdapter.h>
  52  *
  53  * PluginBufferingAdapter is a Vamp plugin adapter that allows plugins
  54  * to be used by a host supplying an audio stream in non-overlapping
  55  * buffers of arbitrary size.
  56  *
  57  * A host using PluginBufferingAdapter may ignore the preferred step
  58  * and block size reported by the plugin, and still expect the plugin
  59  * to run.  The value of blockSize and stepSize passed to initialise
  60  * should be the size of the buffer which the host will supply; the
  61  * stepSize should be equal to the blockSize.
  62  *
  63  * If the internal step size used for the plugin differs from that
  64  * supplied by the host, the adapter will modify the sample type and
  65  * rate specifications for the plugin outputs appropriately, and set
  66  * timestamps on the output features for outputs that formerly used a
  67  * different sample rate specification.  This is necessary in order to
  68  * obtain correct time stamping.
  69  *
  70  * In other respects, the PluginBufferingAdapter behaves identically
  71  * to the plugin that it wraps. The wrapped plugin will be deleted
  72  * when the wrapper is deleted.
  73  */
  74
  75 class PluginBufferingAdapter : public PluginWrapper
  76 {
  77 public:
  78     /**
  79      * Construct a PluginBufferingAdapter wrapping the given plugin.
  80      * The adapter takes ownership of the plugin, which will be
  81      * deleted when the adapter is deleted.
  82      */
  83     PluginBufferingAdapter(Plugin *plugin);
  84     virtual ~PluginBufferingAdapter();
  85
  86     /**
  87      * Return the preferred step size for this adapter.
  88      *
  89      * Because of the way this adapter works, its preferred step size
  90      * will always be the same as its preferred block size.  This may
  91      * or may not be the same as the preferred step size of the
  92      * underlying plugin, which may be obtained by calling
  93      * getPluginPreferredStepSize().
  94      */
  95     size_t getPreferredStepSize() const;
  96
  97     /**
  98      * Return the preferred block size for this adapter.
  99      *
 100      * This may or may not be the same as the preferred block size of
 101      * the underlying plugin, which may be obtained by calling
 102      * getPluginPreferredBlockSize().
 103      *
 104      * Note that this adapter may be initialised with any block size,
 105      * not just its supposedly preferred one.
 106      */
 107     size_t getPreferredBlockSize() const;
 108
 109     /**
 110      * Initialise the adapter (and therefore the plugin) for the given
 111      * number of channels.  Initialise the adapter for the given step
 112      * and block size, which must be equal.
 113      *
 114      * The step and block size used for the underlying plugin will
 115      * depend on its preferences, or any values previously passed to
 116      * setPluginStepSize and setPluginBlockSize.
 117      */
 118     bool initialise(size_t channels, size_t stepSize, size_t blockSize);
 119
 120     /**
 121      * Return the preferred step size of the plugin wrapped by this
 122      * adapter.
 123      *
 124      * This is included mainly for informational purposes.  This value
 125      * is not likely to be a valid step size for the adapter itself,
 126      * and it is not usually of any use in interpreting the results
 127      * (because the adapter re-writes OneSamplePerStep outputs to
 128      * FixedSampleRate so that the hop size no longer needs to be
 129      * known beforehand in order to interpret them).
 130      */
 131     size_t getPluginPreferredStepSize() const;
 132
 133     /**
 134      * Return the preferred block size of the plugin wrapped by this
 135      * adapter.
 136      *
 137      * This is included mainly for informational purposes.
 138      */
 139     size_t getPluginPreferredBlockSize() const;
 140
 141     /**
 142      * Set the step size that will be used for the underlying plugin
 143      * when initialise() is called.  If this is not set, the plugin's
 144      * own preferred step size will be used.  You will not usually
 145      * need to call this function.  If you do call it, it must be
 146      * before the first call to initialise().
 147      */
 148     void setPluginStepSize(size_t stepSize);
 149
 150     /**
 151      * Set the block size that will be used for the underlying plugin
 152      * when initialise() is called.  If this is not set, the plugin's
 153      * own preferred block size will be used.  You will not usually
 154      * need to call this function.  If you do call it, it must be
 155      * before the first call to initialise().
 156      */
 157     void setPluginBlockSize(size_t blockSize);
 158
 159     /**
 160      * Return the step and block sizes that were actually used when
 161      * initialising the underlying plugin.
 162      *
 163      * This is included mainly for informational purposes.  You will
 164      * not usually need to call this function.  If this is called
 165      * before initialise(), it will return 0 for both values.  If it
 166      * is called after a failed call to initialise(), it will return
 167      * the values that were used in the failed call to the plugin's
 168      * initialise() function.
 169      */
 170     void getActualStepAndBlockSizes(size_t &stepSize, size_t &blockSize);
 171
 172     void setParameter(std::string, float);
 173     void selectProgram(std::string);
 174
 175     OutputList getOutputDescriptors() const;
 176
 177     void reset();
 178
 179     FeatureSet process(const float *const *inputBuffers, RealTime timestamp);
 180
 181     FeatureSet getRemainingFeatures();
 182
 183 protected:
 184     class Impl;
 185     Impl *m_impl;
 186 };
 187
 188 }
 189
 190 }
 191
 192 _VAMP_SDK_HOSTSPACE_END(PluginBufferingAdapter.h)
 193
 194 #endif