1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/media/libsoundtouch/src/SoundTouch.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,277 @@
1.4 +//////////////////////////////////////////////////////////////////////////////
1.5 +///
1.6 +/// SoundTouch - main class for tempo/pitch/rate adjusting routines.
1.7 +///
1.8 +/// Notes:
1.9 +/// - Initialize the SoundTouch object instance by setting up the sound stream
1.10 +/// parameters with functions 'setSampleRate' and 'setChannels', then set
1.11 +/// desired tempo/pitch/rate settings with the corresponding functions.
1.12 +///
1.13 +/// - The SoundTouch class behaves like a first-in-first-out pipeline: The
1.14 +/// samples that are to be processed are fed into one of the pipe by calling
1.15 +/// function 'putSamples', while the ready processed samples can be read
1.16 +/// from the other end of the pipeline with function 'receiveSamples'.
1.17 +///
1.18 +/// - The SoundTouch processing classes require certain sized 'batches' of
1.19 +/// samples in order to process the sound. For this reason the classes buffer
1.20 +/// incoming samples until there are enough of samples available for
1.21 +/// processing, then they carry out the processing step and consequently
1.22 +/// make the processed samples available for outputting.
1.23 +///
1.24 +/// - For the above reason, the processing routines introduce a certain
1.25 +/// 'latency' between the input and output, so that the samples input to
1.26 +/// SoundTouch may not be immediately available in the output, and neither
1.27 +/// the amount of outputtable samples may not immediately be in direct
1.28 +/// relationship with the amount of previously input samples.
1.29 +///
1.30 +/// - The tempo/pitch/rate control parameters can be altered during processing.
1.31 +/// Please notice though that they aren't currently protected by semaphores,
1.32 +/// so in multi-thread application external semaphore protection may be
1.33 +/// required.
1.34 +///
1.35 +/// - This class utilizes classes 'TDStretch' for tempo change (without modifying
1.36 +/// pitch) and 'RateTransposer' for changing the playback rate (that is, both
1.37 +/// tempo and pitch in the same ratio) of the sound. The third available control
1.38 +/// 'pitch' (change pitch but maintain tempo) is produced by a combination of
1.39 +/// combining the two other controls.
1.40 +///
1.41 +/// Author : Copyright (c) Olli Parviainen
1.42 +/// Author e-mail : oparviai 'at' iki.fi
1.43 +/// SoundTouch WWW: http://www.surina.net/soundtouch
1.44 +///
1.45 +////////////////////////////////////////////////////////////////////////////////
1.46 +//
1.47 +// Last changed : $Date: 2014-04-06 10:57:21 -0500 (Sun, 06 Apr 2014) $
1.48 +// File revision : $Revision: 4 $
1.49 +//
1.50 +// $Id: SoundTouch.h 195 2014-04-06 15:57:21Z oparviai $
1.51 +//
1.52 +////////////////////////////////////////////////////////////////////////////////
1.53 +//
1.54 +// License :
1.55 +//
1.56 +// SoundTouch audio processing library
1.57 +// Copyright (c) Olli Parviainen
1.58 +//
1.59 +// This library is free software; you can redistribute it and/or
1.60 +// modify it under the terms of the GNU Lesser General Public
1.61 +// License as published by the Free Software Foundation; either
1.62 +// version 2.1 of the License, or (at your option) any later version.
1.63 +//
1.64 +// This library is distributed in the hope that it will be useful,
1.65 +// but WITHOUT ANY WARRANTY; without even the implied warranty of
1.66 +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1.67 +// Lesser General Public License for more details.
1.68 +//
1.69 +// You should have received a copy of the GNU Lesser General Public
1.70 +// License along with this library; if not, write to the Free Software
1.71 +// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
1.72 +//
1.73 +////////////////////////////////////////////////////////////////////////////////
1.74 +
1.75 +#ifndef SoundTouch_H
1.76 +#define SoundTouch_H
1.77 +
1.78 +#include "FIFOSamplePipe.h"
1.79 +#include "STTypes.h"
1.80 +
1.81 +namespace soundtouch
1.82 +{
1.83 +
1.84 +/// Soundtouch library version string
1.85 +#define SOUNDTOUCH_VERSION "1.8.0"
1.86 +
1.87 +/// SoundTouch library version id
1.88 +#define SOUNDTOUCH_VERSION_ID (10800)
1.89 +
1.90 +//
1.91 +// Available setting IDs for the 'setSetting' & 'get_setting' functions:
1.92 +
1.93 +/// Enable/disable anti-alias filter in pitch transposer (0 = disable)
1.94 +#define SETTING_USE_AA_FILTER 0
1.95 +
1.96 +/// Pitch transposer anti-alias filter length (8 .. 128 taps, default = 32)
1.97 +#define SETTING_AA_FILTER_LENGTH 1
1.98 +
1.99 +/// Enable/disable quick seeking algorithm in tempo changer routine
1.100 +/// (enabling quick seeking lowers CPU utilization but causes a minor sound
1.101 +/// quality compromising)
1.102 +#define SETTING_USE_QUICKSEEK 2
1.103 +
1.104 +/// Time-stretch algorithm single processing sequence length in milliseconds. This determines
1.105 +/// to how long sequences the original sound is chopped in the time-stretch algorithm.
1.106 +/// See "STTypes.h" or README for more information.
1.107 +#define SETTING_SEQUENCE_MS 3
1.108 +
1.109 +/// Time-stretch algorithm seeking window length in milliseconds for algorithm that finds the
1.110 +/// best possible overlapping location. This determines from how wide window the algorithm
1.111 +/// may look for an optimal joining location when mixing the sound sequences back together.
1.112 +/// See "STTypes.h" or README for more information.
1.113 +#define SETTING_SEEKWINDOW_MS 4
1.114 +
1.115 +/// Time-stretch algorithm overlap length in milliseconds. When the chopped sound sequences
1.116 +/// are mixed back together, to form a continuous sound stream, this parameter defines over
1.117 +/// how long period the two consecutive sequences are let to overlap each other.
1.118 +/// See "STTypes.h" or README for more information.
1.119 +#define SETTING_OVERLAP_MS 5
1.120 +
1.121 +
1.122 +/// Call "getSetting" with this ID to query nominal average processing sequence
1.123 +/// size in samples. This value tells approcimate value how many input samples
1.124 +/// SoundTouch needs to gather before it does DSP processing run for the sample batch.
1.125 +///
1.126 +/// Notices:
1.127 +/// - This is read-only parameter, i.e. setSetting ignores this parameter
1.128 +/// - Returned value is approximate average value, exact processing batch
1.129 +/// size may wary from time to time
1.130 +/// - This parameter value is not constant but may change depending on
1.131 +/// tempo/pitch/rate/samplerate settings.
1.132 +#define SETTING_NOMINAL_INPUT_SEQUENCE 6
1.133 +
1.134 +
1.135 +/// Call "getSetting" with this ID to query nominal average processing output
1.136 +/// size in samples. This value tells approcimate value how many output samples
1.137 +/// SoundTouch outputs once it does DSP processing run for a batch of input samples.
1.138 +///
1.139 +/// Notices:
1.140 +/// - This is read-only parameter, i.e. setSetting ignores this parameter
1.141 +/// - Returned value is approximate average value, exact processing batch
1.142 +/// size may wary from time to time
1.143 +/// - This parameter value is not constant but may change depending on
1.144 +/// tempo/pitch/rate/samplerate settings.
1.145 +#define SETTING_NOMINAL_OUTPUT_SEQUENCE 7
1.146 +
1.147 +class EXPORT SoundTouch : public FIFOProcessor
1.148 +{
1.149 +private:
1.150 + /// Rate transposer class instance
1.151 + class RateTransposer *pRateTransposer;
1.152 +
1.153 + /// Time-stretch class instance
1.154 + class TDStretch *pTDStretch;
1.155 +
1.156 + /// Virtual pitch parameter. Effective rate & tempo are calculated from these parameters.
1.157 + float virtualRate;
1.158 +
1.159 + /// Virtual pitch parameter. Effective rate & tempo are calculated from these parameters.
1.160 + float virtualTempo;
1.161 +
1.162 + /// Virtual pitch parameter. Effective rate & tempo are calculated from these parameters.
1.163 + float virtualPitch;
1.164 +
1.165 + /// Flag: Has sample rate been set?
1.166 + bool bSrateSet;
1.167 +
1.168 + /// Calculates effective rate & tempo valuescfrom 'virtualRate', 'virtualTempo' and
1.169 + /// 'virtualPitch' parameters.
1.170 + void calcEffectiveRateAndTempo();
1.171 +
1.172 +protected :
1.173 + /// Number of channels
1.174 + uint channels;
1.175 +
1.176 + /// Effective 'rate' value calculated from 'virtualRate', 'virtualTempo' and 'virtualPitch'
1.177 + float rate;
1.178 +
1.179 + /// Effective 'tempo' value calculated from 'virtualRate', 'virtualTempo' and 'virtualPitch'
1.180 + float tempo;
1.181 +
1.182 +public:
1.183 + SoundTouch();
1.184 + virtual ~SoundTouch();
1.185 +
1.186 + /// Get SoundTouch library version string
1.187 + static const char *getVersionString();
1.188 +
1.189 + /// Get SoundTouch library version Id
1.190 + static uint getVersionId();
1.191 +
1.192 + /// Sets new rate control value. Normal rate = 1.0, smaller values
1.193 + /// represent slower rate, larger faster rates.
1.194 + void setRate(float newRate);
1.195 +
1.196 + /// Sets new tempo control value. Normal tempo = 1.0, smaller values
1.197 + /// represent slower tempo, larger faster tempo.
1.198 + void setTempo(float newTempo);
1.199 +
1.200 + /// Sets new rate control value as a difference in percents compared
1.201 + /// to the original rate (-50 .. +100 %)
1.202 + void setRateChange(float newRate);
1.203 +
1.204 + /// Sets new tempo control value as a difference in percents compared
1.205 + /// to the original tempo (-50 .. +100 %)
1.206 + void setTempoChange(float newTempo);
1.207 +
1.208 + /// Sets new pitch control value. Original pitch = 1.0, smaller values
1.209 + /// represent lower pitches, larger values higher pitch.
1.210 + void setPitch(float newPitch);
1.211 +
1.212 + /// Sets pitch change in octaves compared to the original pitch
1.213 + /// (-1.00 .. +1.00)
1.214 + void setPitchOctaves(float newPitch);
1.215 +
1.216 + /// Sets pitch change in semi-tones compared to the original pitch
1.217 + /// (-12 .. +12)
1.218 + void setPitchSemiTones(int newPitch);
1.219 + void setPitchSemiTones(float newPitch);
1.220 +
1.221 + /// Sets the number of channels, 1 = mono, 2 = stereo
1.222 + void setChannels(uint numChannels);
1.223 +
1.224 + /// Sets sample rate.
1.225 + void setSampleRate(uint srate);
1.226 +
1.227 + /// Flushes the last samples from the processing pipeline to the output.
1.228 + /// Clears also the internal processing buffers.
1.229 + //
1.230 + /// Note: This function is meant for extracting the last samples of a sound
1.231 + /// stream. This function may introduce additional blank samples in the end
1.232 + /// of the sound stream, and thus it's not recommended to call this function
1.233 + /// in the middle of a sound stream.
1.234 + void flush();
1.235 +
1.236 + /// Adds 'numSamples' pcs of samples from the 'samples' memory position into
1.237 + /// the input of the object. Notice that sample rate _has_to_ be set before
1.238 + /// calling this function, otherwise throws a runtime_error exception.
1.239 + virtual void putSamples(
1.240 + const SAMPLETYPE *samples, ///< Pointer to sample buffer.
1.241 + uint numSamples ///< Number of samples in buffer. Notice
1.242 + ///< that in case of stereo-sound a single sample
1.243 + ///< contains data for both channels.
1.244 + );
1.245 +
1.246 + /// Clears all the samples in the object's output and internal processing
1.247 + /// buffers.
1.248 + virtual void clear();
1.249 +
1.250 + /// Changes a setting controlling the processing system behaviour. See the
1.251 + /// 'SETTING_...' defines for available setting ID's.
1.252 + ///
1.253 + /// \return 'true' if the setting was succesfully changed
1.254 + bool setSetting(int settingId, ///< Setting ID number. see SETTING_... defines.
1.255 + int value ///< New setting value.
1.256 + );
1.257 +
1.258 + /// Reads a setting controlling the processing system behaviour. See the
1.259 + /// 'SETTING_...' defines for available setting ID's.
1.260 + ///
1.261 + /// \return the setting value.
1.262 + int getSetting(int settingId ///< Setting ID number, see SETTING_... defines.
1.263 + ) const;
1.264 +
1.265 + /// Returns number of samples currently unprocessed.
1.266 + virtual uint numUnprocessedSamples() const;
1.267 +
1.268 +
1.269 + /// Other handy functions that are implemented in the ancestor classes (see
1.270 + /// classes 'FIFOProcessor' and 'FIFOSamplePipe')
1.271 + ///
1.272 + /// - receiveSamples() : Use this function to receive 'ready' processed samples from SoundTouch.
1.273 + /// - numSamples() : Get number of 'ready' samples that can be received with
1.274 + /// function 'receiveSamples()'
1.275 + /// - isEmpty() : Returns nonzero if there aren't any 'ready' samples.
1.276 + /// - clear() : Clears all samples from ready/processing buffers.
1.277 +};
1.278 +
1.279 +}
1.280 +#endif
