PageRenderTime 507ms CodeModel.GetById 222ms app.highlight 7ms RepoModel.GetById 274ms app.codeStats 0ms

/external/pysoundtouch14/libsoundtouch/SoundTouch.h

http://echo-nest-remix.googlecode.com/
C++ Header | 252 lines | 58 code | 44 blank | 150 comment | 0 complexity | a416f9ef96abd9d067492775ecd349c0 MD5 | raw file
  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 'at' iki.fi
 40/// SoundTouch WWW: http://www.surina.net/soundtouch
 41///
 42////////////////////////////////////////////////////////////////////////////////
 43//
 44// Last changed  : $Date: 2008-12-25 19:03:48 +0200 (Thu, 25 Dec 2008) $
 45// File revision : $Revision: 4 $
 46//
 47// $Id: SoundTouch.h 40 2008-12-25 17:03:48Z oparviai $
 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
 78namespace soundtouch
 79{
 80
 81/// Soundtouch library version string
 82#define SOUNDTOUCH_VERSION          "1.4.0"

 83
 84/// SoundTouch library version id
 85#define SOUNDTOUCH_VERSION_ID       (10400)

 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
119class SoundTouch : public FIFOProcessor
120{
121private:
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
144protected :
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
154public:
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    int getSetting(int 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