michael@0: //////////////////////////////////////////////////////////////////////////////
michael@0: ///
michael@0: /// SoundTouch - main class for tempo/pitch/rate adjusting routines. 
michael@0: ///
michael@0: /// Notes:
michael@0: /// - Initialize the SoundTouch object instance by setting up the sound stream 
michael@0: ///   parameters with functions 'setSampleRate' and 'setChannels', then set 
michael@0: ///   desired tempo/pitch/rate settings with the corresponding functions.
michael@0: ///
michael@0: /// - The SoundTouch class behaves like a first-in-first-out pipeline: The 
michael@0: ///   samples that are to be processed are fed into one of the pipe by calling
michael@0: ///   function 'putSamples', while the ready processed samples can be read 
michael@0: ///   from the other end of the pipeline with function 'receiveSamples'.
michael@0: /// 
michael@0: /// - The SoundTouch processing classes require certain sized 'batches' of 
michael@0: ///   samples in order to process the sound. For this reason the classes buffer 
michael@0: ///   incoming samples until there are enough of samples available for 
michael@0: ///   processing, then they carry out the processing step and consequently
michael@0: ///   make the processed samples available for outputting.
michael@0: /// 
michael@0: /// - For the above reason, the processing routines introduce a certain 
michael@0: ///   'latency' between the input and output, so that the samples input to
michael@0: ///   SoundTouch may not be immediately available in the output, and neither 
michael@0: ///   the amount of outputtable samples may not immediately be in direct 
michael@0: ///   relationship with the amount of previously input samples.
michael@0: ///
michael@0: /// - The tempo/pitch/rate control parameters can be altered during processing.
michael@0: ///   Please notice though that they aren't currently protected by semaphores,
michael@0: ///   so in multi-thread application external semaphore protection may be
michael@0: ///   required.
michael@0: ///
michael@0: /// - This class utilizes classes 'TDStretch' for tempo change (without modifying
michael@0: ///   pitch) and 'RateTransposer' for changing the playback rate (that is, both 
michael@0: ///   tempo and pitch in the same ratio) of the sound. The third available control 
michael@0: ///   'pitch' (change pitch but maintain tempo) is produced by a combination of
michael@0: ///   combining the two other controls.
michael@0: ///
michael@0: /// Author        : Copyright (c) Olli Parviainen
michael@0: /// Author e-mail : oparviai 'at' iki.fi
michael@0: /// SoundTouch WWW: http://www.surina.net/soundtouch
michael@0: ///
michael@0: ////////////////////////////////////////////////////////////////////////////////
michael@0: //
michael@0: // Last changed  : $Date: 2014-04-06 10:57:21 -0500 (Sun, 06 Apr 2014) $
michael@0: // File revision : $Revision: 4 $
michael@0: //
michael@0: // $Id: SoundTouch.h 195 2014-04-06 15:57:21Z oparviai $
michael@0: //
michael@0: ////////////////////////////////////////////////////////////////////////////////
michael@0: //
michael@0: // License :
michael@0: //
michael@0: //  SoundTouch audio processing library
michael@0: //  Copyright (c) Olli Parviainen
michael@0: //
michael@0: //  This library is free software; you can redistribute it and/or
michael@0: //  modify it under the terms of the GNU Lesser General Public
michael@0: //  License as published by the Free Software Foundation; either
michael@0: //  version 2.1 of the License, or (at your option) any later version.
michael@0: //
michael@0: //  This library is distributed in the hope that it will be useful,
michael@0: //  but WITHOUT ANY WARRANTY; without even the implied warranty of
michael@0: //  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
michael@0: //  Lesser General Public License for more details.
michael@0: //
michael@0: //  You should have received a copy of the GNU Lesser General Public
michael@0: //  License along with this library; if not, write to the Free Software
michael@0: //  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
michael@0: //
michael@0: ////////////////////////////////////////////////////////////////////////////////
michael@0: 
michael@0: #ifndef SoundTouch_H
michael@0: #define SoundTouch_H
michael@0: 
michael@0: #include "FIFOSamplePipe.h"
michael@0: #include "STTypes.h"
michael@0: 
michael@0: namespace soundtouch
michael@0: {
michael@0: 
michael@0: /// Soundtouch library version string
michael@0: #define SOUNDTOUCH_VERSION          "1.8.0"
michael@0: 
michael@0: /// SoundTouch library version id
michael@0: #define SOUNDTOUCH_VERSION_ID       (10800)
michael@0: 
michael@0: //
michael@0: // Available setting IDs for the 'setSetting' & 'get_setting' functions:
michael@0: 
michael@0: /// Enable/disable anti-alias filter in pitch transposer (0 = disable)
michael@0: #define SETTING_USE_AA_FILTER       0
michael@0: 
michael@0: /// Pitch transposer anti-alias filter length (8 .. 128 taps, default = 32)
michael@0: #define SETTING_AA_FILTER_LENGTH    1
michael@0: 
michael@0: /// Enable/disable quick seeking algorithm in tempo changer routine
michael@0: /// (enabling quick seeking lowers CPU utilization but causes a minor sound
michael@0: ///  quality compromising)
michael@0: #define SETTING_USE_QUICKSEEK       2
michael@0: 
michael@0: /// Time-stretch algorithm single processing sequence length in milliseconds. This determines 
michael@0: /// to how long sequences the original sound is chopped in the time-stretch algorithm. 
michael@0: /// See "STTypes.h" or README for more information.
michael@0: #define SETTING_SEQUENCE_MS         3
michael@0: 
michael@0: /// Time-stretch algorithm seeking window length in milliseconds for algorithm that finds the 
michael@0: /// best possible overlapping location. This determines from how wide window the algorithm 
michael@0: /// may look for an optimal joining location when mixing the sound sequences back together. 
michael@0: /// See "STTypes.h" or README for more information.
michael@0: #define SETTING_SEEKWINDOW_MS       4
michael@0: 
michael@0: /// Time-stretch algorithm overlap length in milliseconds. When the chopped sound sequences 
michael@0: /// are mixed back together, to form a continuous sound stream, this parameter defines over 
michael@0: /// how long period the two consecutive sequences are let to overlap each other. 
michael@0: /// See "STTypes.h" or README for more information.
michael@0: #define SETTING_OVERLAP_MS          5
michael@0: 
michael@0: 
michael@0: /// Call "getSetting" with this ID to query nominal average processing sequence
michael@0: /// size in samples. This value tells approcimate value how many input samples 
michael@0: /// SoundTouch needs to gather before it does DSP processing run for the sample batch.
michael@0: ///
michael@0: /// Notices: 
michael@0: /// - This is read-only parameter, i.e. setSetting ignores this parameter
michael@0: /// - Returned value is approximate average value, exact processing batch
michael@0: ///   size may wary from time to time
michael@0: /// - This parameter value is not constant but may change depending on 
michael@0: ///   tempo/pitch/rate/samplerate settings.
michael@0: #define SETTING_NOMINAL_INPUT_SEQUENCE		6
michael@0: 
michael@0: 
michael@0: /// Call "getSetting" with this ID to query nominal average processing output 
michael@0: /// size in samples. This value tells approcimate value how many output samples 
michael@0: /// SoundTouch outputs once it does DSP processing run for a batch of input samples.
michael@0: ///	
michael@0: /// Notices: 
michael@0: /// - This is read-only parameter, i.e. setSetting ignores this parameter
michael@0: /// - Returned value is approximate average value, exact processing batch
michael@0: ///   size may wary from time to time
michael@0: /// - This parameter value is not constant but may change depending on 
michael@0: ///   tempo/pitch/rate/samplerate settings.
michael@0: #define SETTING_NOMINAL_OUTPUT_SEQUENCE		7
michael@0: 
michael@0: class EXPORT SoundTouch : public FIFOProcessor
michael@0: {
michael@0: private:
michael@0:     /// Rate transposer class instance
michael@0:     class RateTransposer *pRateTransposer;
michael@0: 
michael@0:     /// Time-stretch class instance
michael@0:     class TDStretch *pTDStretch;
michael@0: 
michael@0:     /// Virtual pitch parameter. Effective rate & tempo are calculated from these parameters.
michael@0:     float virtualRate;
michael@0: 
michael@0:     /// Virtual pitch parameter. Effective rate & tempo are calculated from these parameters.
michael@0:     float virtualTempo;
michael@0: 
michael@0:     /// Virtual pitch parameter. Effective rate & tempo are calculated from these parameters.
michael@0:     float virtualPitch;
michael@0: 
michael@0:     /// Flag: Has sample rate been set?
michael@0:     bool  bSrateSet;
michael@0: 
michael@0:     /// Calculates effective rate & tempo valuescfrom 'virtualRate', 'virtualTempo' and 
michael@0:     /// 'virtualPitch' parameters.
michael@0:     void calcEffectiveRateAndTempo();
michael@0: 
michael@0: protected :
michael@0:     /// Number of channels
michael@0:     uint  channels;
michael@0: 
michael@0:     /// Effective 'rate' value calculated from 'virtualRate', 'virtualTempo' and 'virtualPitch'
michael@0:     float rate;
michael@0: 
michael@0:     /// Effective 'tempo' value calculated from 'virtualRate', 'virtualTempo' and 'virtualPitch'
michael@0:     float tempo;
michael@0: 
michael@0: public:
michael@0:     SoundTouch();
michael@0:     virtual ~SoundTouch();
michael@0: 
michael@0:     /// Get SoundTouch library version string
michael@0:     static const char *getVersionString();
michael@0: 
michael@0:     /// Get SoundTouch library version Id
michael@0:     static uint getVersionId();
michael@0: 
michael@0:     /// Sets new rate control value. Normal rate = 1.0, smaller values
michael@0:     /// represent slower rate, larger faster rates.
michael@0:     void setRate(float newRate);
michael@0: 
michael@0:     /// Sets new tempo control value. Normal tempo = 1.0, smaller values
michael@0:     /// represent slower tempo, larger faster tempo.
michael@0:     void setTempo(float newTempo);
michael@0: 
michael@0:     /// Sets new rate control value as a difference in percents compared
michael@0:     /// to the original rate (-50 .. +100 %)
michael@0:     void setRateChange(float newRate);
michael@0: 
michael@0:     /// Sets new tempo control value as a difference in percents compared
michael@0:     /// to the original tempo (-50 .. +100 %)
michael@0:     void setTempoChange(float newTempo);
michael@0: 
michael@0:     /// Sets new pitch control value. Original pitch = 1.0, smaller values
michael@0:     /// represent lower pitches, larger values higher pitch.
michael@0:     void setPitch(float newPitch);
michael@0: 
michael@0:     /// Sets pitch change in octaves compared to the original pitch  
michael@0:     /// (-1.00 .. +1.00)
michael@0:     void setPitchOctaves(float newPitch);
michael@0: 
michael@0:     /// Sets pitch change in semi-tones compared to the original pitch
michael@0:     /// (-12 .. +12)
michael@0:     void setPitchSemiTones(int newPitch);
michael@0:     void setPitchSemiTones(float newPitch);
michael@0: 
michael@0:     /// Sets the number of channels, 1 = mono, 2 = stereo
michael@0:     void setChannels(uint numChannels);
michael@0: 
michael@0:     /// Sets sample rate.
michael@0:     void setSampleRate(uint srate);
michael@0: 
michael@0:     /// Flushes the last samples from the processing pipeline to the output.
michael@0:     /// Clears also the internal processing buffers.
michael@0:     //
michael@0:     /// Note: This function is meant for extracting the last samples of a sound
michael@0:     /// stream. This function may introduce additional blank samples in the end
michael@0:     /// of the sound stream, and thus it's not recommended to call this function
michael@0:     /// in the middle of a sound stream.
michael@0:     void flush();
michael@0: 
michael@0:     /// Adds 'numSamples' pcs of samples from the 'samples' memory position into
michael@0:     /// the input of the object. Notice that sample rate _has_to_ be set before
michael@0:     /// calling this function, otherwise throws a runtime_error exception.
michael@0:     virtual void putSamples(
michael@0:             const SAMPLETYPE *samples,  ///< Pointer to sample buffer.
michael@0:             uint numSamples                         ///< Number of samples in buffer. Notice
michael@0:                                                     ///< that in case of stereo-sound a single sample
michael@0:                                                     ///< contains data for both channels.
michael@0:             );
michael@0: 
michael@0:     /// Clears all the samples in the object's output and internal processing
michael@0:     /// buffers.
michael@0:     virtual void clear();
michael@0: 
michael@0:     /// Changes a setting controlling the processing system behaviour. See the
michael@0:     /// 'SETTING_...' defines for available setting ID's.
michael@0:     /// 
michael@0:     /// \return 'true' if the setting was succesfully changed
michael@0:     bool setSetting(int settingId,   ///< Setting ID number. see SETTING_... defines.
michael@0:                     int value        ///< New setting value.
michael@0:                     );
michael@0: 
michael@0:     /// Reads a setting controlling the processing system behaviour. See the
michael@0:     /// 'SETTING_...' defines for available setting ID's.
michael@0:     ///
michael@0:     /// \return the setting value.
michael@0:     int getSetting(int settingId    ///< Setting ID number, see SETTING_... defines.
michael@0:                    ) const;
michael@0: 
michael@0:     /// Returns number of samples currently unprocessed.
michael@0:     virtual uint numUnprocessedSamples() const;
michael@0: 
michael@0: 
michael@0:     /// Other handy functions that are implemented in the ancestor classes (see
michael@0:     /// classes 'FIFOProcessor' and 'FIFOSamplePipe')
michael@0:     ///
michael@0:     /// - receiveSamples() : Use this function to receive 'ready' processed samples from SoundTouch.
michael@0:     /// - numSamples()     : Get number of 'ready' samples that can be received with 
michael@0:     ///                      function 'receiveSamples()'
michael@0:     /// - isEmpty()        : Returns nonzero if there aren't any 'ready' samples.
michael@0:     /// - clear()          : Clears all samples from ready/processing buffers.
michael@0: };
michael@0: 
michael@0: }
michael@0: #endif