libs/soundtouch/SoundTouch.h

   1 //////////////////////////////////////////////////////////////////////////////
   2 ///
   3 /// SoundTouch - main class for tempo/pitch/rate adjusting routines.
   4 ///
   5 /// Notes:
   6 /// - Initialize the SoundTouch object instance by setting up the sound stream
   7 ///   parameters with functions 'setSampleRate' and 'setChannels', then set
   8 ///   desired tempo/pitch/rate settings with the corresponding functions.
   9 ///
  10 /// - The SoundTouch class behaves like a first-in-first-out pipeline: The
  11 ///   samples that are to be processed are fed into one of the pipe by calling
  12 ///   function 'putSamples', while the ready processed samples can be read
  13 ///   from the other end of the pipeline with function 'receiveSamples'.
  14 ///
  15 /// - The SoundTouch processing classes require certain sized 'batches' of
  16 ///   samples in order to process the sound. For this reason the classes buffer
  17 ///   incoming samples until there are enough of samples available for
  18 ///   processing, then they carry out the processing step and consequently
  19 ///   make the processed samples available for outputting.
  20 ///
  21 /// - For the above reason, the processing routines introduce a certain
  22 ///   'latency' between the input and output, so that the samples input to
  23 ///   SoundTouch may not be immediately available in the output, and neither
  24 ///   the amount of outputtable samples may not immediately be in direct
  25 ///   relationship with the amount of previously input samples.
  26 ///
  27 /// - The tempo/pitch/rate control parameters can be altered during processing.
  28 ///   Please notice though that they aren't currently protected by semaphores,
  29 ///   so in multi-thread application external semaphore protection may be
  30 ///   required.
  31 ///
  32 /// - This class utilizes classes 'TDStretch' for tempo change (without modifying
  33 ///   pitch) and 'RateTransposer' for changing the playback rate (that is, both
  34 ///   tempo and pitch in the same ratio) of the sound. The third available control
  35 ///   'pitch' (change pitch but maintain tempo) is produced by a combination of
  36 ///   combining the two other controls.
  37 ///
  38 /// Author        : Copyright (c) Olli Parviainen
  39 /// Author e-mail : oparviai @ iki.fi
  40 /// SoundTouch WWW: http://www.iki.fi/oparviai/soundtouch
  41 ///
  42 ////////////////////////////////////////////////////////////////////////////////
  43 //
  44 // Last changed  : $Date$
  45 // File revision : $Revision$
  46 //
  47 // $Id$
  48 //
  49 ////////////////////////////////////////////////////////////////////////////////
  50 //
  51 // License :
  52 //
  53 //  SoundTouch audio processing library
  54 //  Copyright (c) Olli Parviainen
  55 //
  56 //  This library is free software; you can redistribute it and/or
  57 //  modify it under the terms of the GNU Lesser General Public
  58 //  License as published by the Free Software Foundation; either
  59 //  version 2.1 of the License, or (at your option) any later version.
  60 //
  61 //  This library is distributed in the hope that it will be useful,
  62 //  but WITHOUT ANY WARRANTY; without even the implied warranty of
  63 //  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  64 //  Lesser General Public License for more details.
  65 //
  66 //  You should have received a copy of the GNU Lesser General Public
  67 //  License along with this library; if not, write to the Free Software
  68 //  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  69 //
  70 ////////////////////////////////////////////////////////////////////////////////
  71
  72 #ifndef SoundTouch_H
  73 #define SoundTouch_H
  74
  75 #include "FIFOSamplePipe.h"
  76 #include "STTypes.h"
  77
  78 namespace soundtouch
  79 {
  80
  81 /// Soundtouch library version string
  82 #define SOUNDTOUCH_VERSION          "1.3.0"
  83
  84 /// SoundTouch library version id
  85 #define SOUNDTOUCH_VERSION_ID       010300
  86
  87 //
  88 // Available setting IDs for the 'setSetting' & 'get_setting' functions:
  89
  90 /// Enable/disable anti-alias filter in pitch transposer (0 = disable)
  91 #define SETTING_USE_AA_FILTER       0
  92
  93 /// Pitch transposer anti-alias filter length (8 .. 128 taps, default = 32)
  94 #define SETTING_AA_FILTER_LENGTH    1
  95
  96 /// Enable/disable quick seeking algorithm in tempo changer routine
  97 /// (enabling quick seeking lowers CPU utilization but causes a minor sound
  98 ///  quality compromising)
  99 #define SETTING_USE_QUICKSEEK       2
 100
 101 /// Time-stretch algorithm single processing sequence length in milliseconds. This determines
 102 /// to how long sequences the original sound is chopped in the time-stretch algorithm.
 103 /// See "STTypes.h" or README for more information.
 104 #define SETTING_SEQUENCE_MS         3
 105
 106 /// Time-stretch algorithm seeking window length in milliseconds for algorithm that finds the
 107 /// best possible overlapping location. This determines from how wide window the algorithm
 108 /// may look for an optimal joining location when mixing the sound sequences back together.
 109 /// See "STTypes.h" or README for more information.
 110 #define SETTING_SEEKWINDOW_MS       4
 111
 112 /// Time-stretch algorithm overlap length in milliseconds. When the chopped sound sequences
 113 /// are mixed back together, to form a continuous sound stream, this parameter defines over
 114 /// how long period the two consecutive sequences are let to overlap each other.
 115 /// See "STTypes.h" or README for more information.
 116 #define SETTING_OVERLAP_MS          5
 117
 118
 119 class SoundTouch : public FIFOProcessor
 120 {
 121 private:
 122     /// Rate transposer class instance
 123     class RateTransposer *pRateTransposer;
 124
 125     /// Time-stretch class instance
 126     class TDStretch *pTDStretch;
 127
 128     /// Virtual pitch parameter. Effective rate & tempo are calculated from these parameters.
 129     float virtualRate;
 130
 131     /// Virtual pitch parameter. Effective rate & tempo are calculated from these parameters.
 132     float virtualTempo;
 133
 134     /// Virtual pitch parameter. Effective rate & tempo are calculated from these parameters.
 135     float virtualPitch;
 136
 137     /// Flag: Has sample rate been set?
 138     BOOL  bSrateSet;
 139
 140     /// Calculates effective rate & tempo valuescfrom 'virtualRate', 'virtualTempo' and
 141     /// 'virtualPitch' parameters.
 142     void calcEffectiveRateAndTempo();
 143
 144 protected :
 145     /// Number of channels
 146     uint  channels;
 147
 148     /// Effective 'rate' value calculated from 'virtualRate', 'virtualTempo' and 'virtualPitch'
 149     float rate;
 150
 151     /// Effective 'tempo' value calculated from 'virtualRate', 'virtualTempo' and 'virtualPitch'
 152     float tempo;
 153
 154 public:
 155     SoundTouch();
 156     virtual ~SoundTouch();
 157
 158     /// Get SoundTouch library version string
 159     static const char *getVersionString();
 160
 161     /// Get SoundTouch library version Id
 162     static uint getVersionId();
 163
 164     /// Sets new rate control value. Normal rate = 1.0, smaller values
 165     /// represent slower rate, larger faster rates.
 166     void setRate(float newRate);
 167
 168     /// Sets new tempo control value. Normal tempo = 1.0, smaller values
 169     /// represent slower tempo, larger faster tempo.
 170     void setTempo(float newTempo);
 171
 172     /// Sets new rate control value as a difference in percents compared
 173     /// to the original rate (-50 .. +100 %)
 174     void setRateChange(float newRate);
 175
 176     /// Sets new tempo control value as a difference in percents compared
 177     /// to the original tempo (-50 .. +100 %)
 178     void setTempoChange(float newTempo);
 179
 180     /// Sets new pitch control value. Original pitch = 1.0, smaller values
 181     /// represent lower pitches, larger values higher pitch.
 182     void setPitch(float newPitch);
 183
 184     /// Sets pitch change in octaves compared to the original pitch
 185     /// (-1.00 .. +1.00)
 186     void setPitchOctaves(float newPitch);
 187
 188     /// Sets pitch change in semi-tones compared to the original pitch
 189     /// (-12 .. +12)
 190     void setPitchSemiTones(int newPitch);
 191     void setPitchSemiTones(float newPitch);
 192
 193     /// Sets the number of channels, 1 = mono, 2 = stereo
 194     void setChannels(uint numChannels);
 195
 196     /// Sets sample rate.
 197     void setSampleRate(uint srate);
 198
 199     /// Flushes the last samples from the processing pipeline to the output.
 200     /// Clears also the internal processing buffers.
 201     //
 202     /// Note: This function is meant for extracting the last samples of a sound
 203     /// stream. This function may introduce additional blank samples in the end
 204     /// of the sound stream, and thus it's not recommended to call this function
 205     /// in the middle of a sound stream.
 206     void flush();
 207
 208     /// Adds 'numSamples' pcs of samples from the 'samples' memory position into
 209     /// the input of the object. Notice that sample rate _has_to_ be set before
 210     /// calling this function, otherwise throws a runtime_error exception.
 211     virtual void putSamples(
 212             const SAMPLETYPE *samples,  ///< Pointer to sample buffer.
 213             uint numSamples                         ///< Number of samples in buffer. Notice
 214                                                     ///< that in case of stereo-sound a single sample
 215                                                     ///< contains data for both channels.
 216             );
 217
 218     /// Clears all the samples in the object's output and internal processing
 219     /// buffers.
 220     virtual void clear();
 221
 222     /// Changes a setting controlling the processing system behaviour. See the
 223     /// 'SETTING_...' defines for available setting ID's.
 224     ///
 225     /// \return 'TRUE' if the setting was succesfully changed
 226     BOOL setSetting(uint settingId,   ///< Setting ID number. see SETTING_... defines.
 227                     uint value        ///< New setting value.
 228                     );
 229
 230     /// Reads a setting controlling the processing system behaviour. See the
 231     /// 'SETTING_...' defines for available setting ID's.
 232     ///
 233     /// \return the setting value.
 234     uint getSetting(uint settingId    ///< Setting ID number, see SETTING_... defines.
 235                     ) const;
 236
 237     /// Returns number of samples currently unprocessed.
 238     virtual uint numUnprocessedSamples() const;
 239
 240
 241     /// Other handy functions that are implemented in the ancestor classes (see
 242     /// classes 'FIFOProcessor' and 'FIFOSamplePipe')
 243     ///
 244     /// - receiveSamples() : Use this function to receive 'ready' processed samples from SoundTouch.
 245     /// - numSamples()     : Get number of 'ready' samples that can be received with
 246     ///                      function 'receiveSamples()'
 247     /// - isEmpty()        : Returns nonzero if there aren't any 'ready' samples.
 248     /// - clear()          : Clears all samples from ready/processing buffers.
 249 };
 250
 251 }
 252 #endif