libs/soundtouch/TDStretch.h

   1 ////////////////////////////////////////////////////////////////////////////////
   2 ///
   3 /// Sampled sound tempo changer/time stretch algorithm. Changes the sound tempo
   4 /// while maintaining the original pitch by using a time domain WSOLA-like method
   5 /// with several performance-increasing tweaks.
   6 ///
   7 /// Note : MMX optimized functions reside in a separate, platform-specific file,
   8 /// e.g. 'mmx_win.cpp' or 'mmx_gcc.cpp'
   9 ///
  10 /// Author        : Copyright (c) Olli Parviainen
  11 /// Author e-mail : oparviai @ iki.fi
  12 /// SoundTouch WWW: http://www.iki.fi/oparviai/soundtouch
  13 ///
  14 ////////////////////////////////////////////////////////////////////////////////
  15 //
  16 // Last changed  : $Date$
  17 // File revision : $Revision$
  18 //
  19 // $Id$
  20 //
  21 ////////////////////////////////////////////////////////////////////////////////
  22 //
  23 // License :
  24 //
  25 //  SoundTouch audio processing library
  26 //  Copyright (c) Olli Parviainen
  27 //
  28 //  This library is free software; you can redistribute it and/or
  29 //  modify it under the terms of the GNU Lesser General Public
  30 //  License as published by the Free Software Foundation; either
  31 //  version 2.1 of the License, or (at your option) any later version.
  32 //
  33 //  This library is distributed in the hope that it will be useful,
  34 //  but WITHOUT ANY WARRANTY; without even the implied warranty of
  35 //  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  36 //  Lesser General Public License for more details.
  37 //
  38 //  You should have received a copy of the GNU Lesser General Public
  39 //  License along with this library; if not, write to the Free Software
  40 //  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  41 //
  42 ////////////////////////////////////////////////////////////////////////////////
  43
  44 #ifndef TDStretch_H
  45 #define TDStretch_H
  46
  47 #include "STTypes.h"
  48 #include "RateTransposer.h"
  49 #include "FIFOSamplePipe.h"
  50
  51 namespace soundtouch
  52 {
  53
  54 // Default values for sound processing parameters:
  55
  56 /// Default length of a single processing sequence, in milliseconds. This determines to how
  57 /// long sequences the original sound is chopped in the time-stretch algorithm.
  58 ///
  59 /// The larger this value is, the lesser sequences are used in processing. In principle
  60 /// a bigger value sounds better when slowing down tempo, but worse when increasing tempo
  61 /// and vice versa.
  62 ///
  63 /// Increasing this value reduces computational burden & vice versa.
  64 #define DEFAULT_SEQUENCE_MS     82
  65
  66 /// Seeking window default length in milliseconds for algorithm that finds the best possible
  67 /// overlapping location. This determines from how wide window the algorithm may look for an
  68 /// optimal joining location when mixing the sound sequences back together.
  69 ///
  70 /// The bigger this window setting is, the higher the possibility to find a better mixing
  71 /// position will become, but at the same time large values may cause a "drifting" artifact
  72 /// because consequent sequences will be taken at more uneven intervals.
  73 ///
  74 /// If there's a disturbing artifact that sounds as if a constant frequency was drifting
  75 /// around, try reducing this setting.
  76 ///
  77 /// Increasing this value increases computational burden & vice versa.
  78 #define DEFAULT_SEEKWINDOW_MS   14
  79
  80 /// Overlap length in milliseconds. When the chopped sound sequences are mixed back together,
  81 /// to form a continuous sound stream, this parameter defines over how long period the two
  82 /// consecutive sequences are let to overlap each other.
  83 ///
  84 /// This shouldn't be that critical parameter. If you reduce the DEFAULT_SEQUENCE_MS setting
  85 /// by a large amount, you might wish to try a smaller value on this.
  86 ///
  87 /// Increasing this value increases computational burden & vice versa.
  88 #define DEFAULT_OVERLAP_MS      12
  89
  90
  91 /// Class that does the time-stretch (tempo change) effect for the processed
  92 /// sound.
  93 class TDStretch : public FIFOProcessor
  94 {
  95 protected:
  96     uint channels;
  97     uint sampleReq;
  98     float tempo;
  99
 100     SAMPLETYPE *pMidBuffer;
 101     SAMPLETYPE *pRefMidBuffer;
 102     SAMPLETYPE *pRefMidBufferUnaligned;
 103     uint overlapLength;
 104     uint overlapDividerBits;
 105     uint slopingDivider;
 106     uint seekLength;
 107     uint seekWindowLength;
 108     uint maxOffset;
 109     float nominalSkip;
 110     float skipFract;
 111     FIFOSampleBuffer outputBuffer;
 112     FIFOSampleBuffer inputBuffer;
 113     BOOL bQuickseek;
 114     BOOL bMidBufferDirty;
 115
 116     uint sampleRate;
 117     uint sequenceMs;
 118     uint seekWindowMs;
 119     uint overlapMs;
 120
 121     void acceptNewOverlapLength(uint newOverlapLength);
 122
 123     virtual void clearCrossCorrState();
 124     void calculateOverlapLength(uint overlapMs);
 125
 126     virtual LONG_SAMPLETYPE calcCrossCorrStereo(const SAMPLETYPE *mixingPos, const SAMPLETYPE *compare) const;
 127     virtual LONG_SAMPLETYPE calcCrossCorrMono(const SAMPLETYPE *mixingPos, const SAMPLETYPE *compare) const;
 128
 129     virtual uint seekBestOverlapPositionStereo(const SAMPLETYPE *refPos);
 130     virtual uint seekBestOverlapPositionStereoQuick(const SAMPLETYPE *refPos);
 131     virtual uint seekBestOverlapPositionMono(const SAMPLETYPE *refPos);
 132     virtual uint seekBestOverlapPositionMonoQuick(const SAMPLETYPE *refPos);
 133     uint seekBestOverlapPosition(const SAMPLETYPE *refPos);
 134
 135     virtual void overlapStereo(SAMPLETYPE *output, const SAMPLETYPE *input) const;
 136     virtual void overlapMono(SAMPLETYPE *output, const SAMPLETYPE *input) const;
 137
 138     void clearMidBuffer();
 139     void overlap(SAMPLETYPE *output, const SAMPLETYPE *input, uint ovlPos) const;
 140
 141     void precalcCorrReferenceMono();
 142     void precalcCorrReferenceStereo();
 143
 144     void processNominalTempo();
 145
 146     /// Changes the tempo of the given sound samples.
 147     /// Returns amount of samples returned in the "output" buffer.
 148     /// The maximum amount of samples that can be returned at a time is set by
 149     /// the 'set_returnBuffer_size' function.
 150     void processSamples();
 151
 152     TDStretch();
 153
 154 public:
 155     virtual ~TDStretch();
 156
 157     /// Use this function instead of "new" operator to create a new instance of this class.
 158     /// This function automatically chooses a correct feature set depending on if the CPU
 159     /// supports MMX/SSE/etc extensions.
 160     static TDStretch *newInstance();
 161
 162     /// Returns the output buffer object
 163     FIFOSamplePipe *getOutput() { return &outputBuffer; };
 164
 165     /// Returns the input buffer object
 166     FIFOSamplePipe *getInput() { return &inputBuffer; };
 167
 168     /// Sets new target tempo. Normal tempo = 'SCALE', smaller values represent slower
 169     /// tempo, larger faster tempo.
 170     void setTempo(float newTempo);
 171
 172     /// Returns nonzero if there aren't any samples available for outputting.
 173     virtual void clear();
 174
 175     /// Clears the input buffer
 176     void clearInput();
 177
 178     /// Sets the number of channels, 1 = mono, 2 = stereo
 179     void setChannels(uint numChannels);
 180
 181     /// Enables/disables the quick position seeking algorithm. Zero to disable,
 182     /// nonzero to enable
 183     void enableQuickSeek(BOOL enable);
 184
 185     /// Returns nonzero if the quick seeking algorithm is enabled.
 186     BOOL isQuickSeekEnabled() const;
 187
 188     /// Sets routine control parameters. These control are certain time constants
 189     /// defining how the sound is stretched to the desired duration.
 190     //
 191     /// 'sampleRate' = sample rate of the sound
 192     /// 'sequenceMS' = one processing sequence length in milliseconds
 193     /// 'seekwindowMS' = seeking window length for scanning the best overlapping
 194     ///      position
 195     /// 'overlapMS' = overlapping length
 196     void setParameters(uint sampleRate,                             ///< Samplerate of sound being processed (Hz)
 197                        uint sequenceMS = DEFAULT_SEQUENCE_MS,       ///< Single processing sequence length (ms)
 198                        uint seekwindowMS = DEFAULT_SEEKWINDOW_MS,   ///< Offset seeking window length (ms)
 199                        uint overlapMS = DEFAULT_OVERLAP_MS          ///< Sequence overlapping length (ms)
 200                        );
 201
 202     /// Get routine control parameters, see setParameters() function.
 203     /// Any of the parameters to this function can be NULL, in such case corresponding parameter
 204     /// value isn't returned.
 205     void getParameters(uint *pSampleRate, uint *pSequenceMs, uint *pSeekWindowMs, uint *pOverlapMs);
 206
 207     /// Adds 'numsamples' pcs of samples from the 'samples' memory position into
 208     /// the input of the object.
 209     virtual void putSamples(
 210             const SAMPLETYPE *samples,  ///< Input sample data
 211             uint numSamples                         ///< Number of samples in 'samples' so that one sample
 212                                                     ///< contains both channels if stereo
 213             );
 214 };
 215
 216
 217
 218 // Implementation-specific class declarations:
 219
 220 #ifdef ALLOW_MMX
 221     /// Class that implements MMX optimized routines for 16bit integer samples type.
 222     class TDStretchMMX : public TDStretch
 223     {
 224     protected:
 225         long calcCrossCorrStereo(const short *mixingPos, const short *compare) const;
 226         virtual void overlapStereo(short *output, const short *input) const;
 227         virtual void clearCrossCorrState();
 228     };
 229 #endif /// ALLOW_MMX
 230
 231
 232 #ifdef ALLOW_3DNOW
 233     /// Class that implements 3DNow! optimized routines for floating point samples type.
 234     class TDStretch3DNow : public TDStretch
 235     {
 236     protected:
 237         double calcCrossCorrStereo(const float *mixingPos, const float *compare) const;
 238     };
 239 #endif /// ALLOW_3DNOW
 240
 241
 242 #ifdef ALLOW_SSE
 243     /// Class that implements SSE optimized routines for floating point samples type.
 244     class TDStretchSSE : public TDStretch
 245     {
 246     protected:
 247         double calcCrossCorrStereo(const float *mixingPos, const float *compare) const;
 248     };
 249
 250 #endif /// ALLOW_SSE
 251
 252 }
 253 #endif  /// TDStretch_H