SoundTouch library README

##### Note: This readme is shortened version of the original SoundTouch readme providing documentation for the time stretching feature.
SoundTouch WWW page: http://www.surina.net/soundtouch

# SoundTouch audio processing library v1.4.0

SoundTouch library Copyright (c) Olli Parviainen 2002-2009

## 3. About implementation & Usage tips

### 3.3. About algorithms

Time-stretching means changing the audio stream duration without affecting it's pitch. SoundTouch uses WSOLA-like time-stretching routines that operate in the time domain. Compared to sample rate transposing, time-stretching is a much heavier operation and also requires a longer processing "window" of sound samples used by the processing algorithm, thus increasing the algorithm input/output latency. Typical i/o latency for the SoundTouch time-stretch algorithm is around 100 ms.

### 3.4 Tuning the algorithm parameters

The time-stretch algorithm has few parameters that can be tuned to optimize sound quality for certain application. The current default parameters have been chosen by iterative if-then analysis (read: "trial and error") to obtain best subjective sound quality in pop/rock music processing, but in applications processing different kind of sound the default parameter set may result into a sub-optimal result.

The time-stretch algorithm default parameter values are set by these #defines in file "TDStretch.h":

>     #define DEFAULT_SEQUENCE_MS     AUTOMATIC
>     #define DEFAULT_SEEKWINDOW_MS   AUTOMATIC
>     #define DEFAULT_OVERLAP_MS      12

These parameters affect to the time-stretch algorithm as follows:

- DEFAULT_SEQUENCE_MS: This is the default length of a single processing sequence in milliseconds which determines the how the original sound is chopped in the time-stretch algorithm. Larger values mean fewer sequences are used in processing. In principle a larger value sounds better when slowing down the tempo, but worse when increasing the tempo and vice versa.
  By default, this setting value is calculated automatically according to tempo value.
- DEFAULT_SEEKWINDOW_MS: The seeking window default length in milliseconds is for the algorithm that seeks the best possible overlapping location. This determines from how wide a sample "window" the algorithm can use to find an optimal mixing location when the sound sequences are to be linked back together.
  The bigger this window setting is, the higher the possibility to find a better mixing position becomes, but at the same time large values may cause a "drifting" sound artifact because neighboring sequences can be chosen at more uneven intervals. If there's a disturbing artifact that sounds as if a constant frequency was drifting around, try reducing this setting.
  By default, this setting value is calculated automatically according to tempo value.
- DEFAULT_OVERLAP_MS: Overlap length in milliseconds. When the sound sequences are mixed back together to form again a continuous sound stream, this parameter defines how much the ends of the consecutive sequences will overlap with each other.
  This shouldn't be that critical parameter. If you reduce the DEFAULT_SEQUENCE_MS setting by a large amount, you might wish to try a smaller value on this.

Notice that these parameters can also be set during execution time with functions "TDStretch::setParameters()" and "SoundTouch::setSetting()".

The table below summaries how the parameters can be adjusted for different applications:

Parameter name | Default value magnitude | Larger value affects... | Smaller value affects... | Effect to CPU burden

    SEQUENCE_MS

Default value is relatively large, chosen for slowing down music tempo

Larger value is usually better for slowing down tempo. Growing the value decelerates the "echoing" artifact when slowing down the tempo.

Smaller value might be better for speeding up tempo. Reducing the value accelerates the "echoing" artifact when slowing down the tempo

Increasing the parameter value reduces computation burden

    SEEKWINDOW_MS

Default value is relatively large, chosen for slowing down music tempo

Larger value eases finding a good mixing position, but may cause a "drifting" artifact

Smaller reduce possibility to find a good mixing position, but reduce the "drifting" artifact.

Increasing the parameter value increases computation burden

    OVERLAP_MS

Default value is relatively large, chosen to suit with above parameters.

If you reduce the "sequence ms" setting, you might wish to try a smaller value.

Increasing the parameter value increases computation burden

## 5. Change History

### 5.1. SoundTouch library Change History

1.4.0:

- Improved sound quality by automatic calculation of time stretch algorithm processing parameters according to tempo setting
- Moved BPM detection routines from SoundStretch application into SoundTouch library
- Bugfixes: Usage of uninitialied variables, GNU build scripts, compiler errors due to 'const' keyword mismatch.
- Source code cleanup

v1.3.1:

- Changed static class declaration to GCC 4.x compiler compatible syntax.
- Enabled MMX/SSE-optimized routines also for GCC compilers. Earlier the MMX/SSE-optimized routines were written in compiler-specific inline assembler, now these routines are migrated to use compiler intrinsic syntax which allows compiling the same MMX/SSE-optimized source code with both Visual C++ and GCC compilers.
- Set floating point as the default sample format and added switch to the GNU configure script for selecting the other sample format.

v1.3.0:

- Fixed tempo routine output duration inaccuracy due to rounding error
- Implemented separate processing routines for integer and floating arithmetic to allow improvements to floating point routines (earlier used algorithms mostly optimized for integer arithmetic also for floating point samples)
- Fixed a bug that distorts sound if sample rate changes during the sound stream
- Fixed a memory leak that appeared in MMX/SSE/3DNow! optimized routines
- Reduced redundant code pieces in MMX/SSE/3DNow! optimized routines vs. the standard C routines.
- MMX routine incompatibility with new gcc compiler versions
- Other miscellaneous bug fixes

v1.2.1:

- Added automake/autoconf scripts for GNU platforms (in courtesy of David Durham)
- Fixed SCALE overflow bug in rate transposer routine.
- Fixed 64bit address space bugs.
- Created a 'soundtouch' namespace for SAMPLETYPE definitions.

v1.2.0:

- Added support for 32bit floating point sample data type with SSE/3DNow! optimizations for Win32 platform (SSE/3DNow! optimizations currently not supported in GCC environment)
- Replaced 'make-gcc' script for GNU environment by master Makefile
- Added time-stretch routine configurability to SoundTouch main class
- Bugfixes

v1.1.1:

- Moved SoundTouch under lesser GPL license (LGPL). This allows using SoundTouch library in programs that aren't released under GPL license.
- Changed MMX routine organiation so that MMX optimized routines are now implemented in classes that are derived from the basic classes having the standard non-mmx routines.
- MMX routines to support gcc version 3.
- Replaced windows makefiles by script using the .dsw files

v1.01:

- "mmx_gcc.cpp": Added "using namespace std" and removed "return 0" from a function with void return value to fix compiler errors when compiling the library in Solaris environment.
- Moved file "FIFOSampleBuffer.h" to "include" directory to allow accessing the FIFOSampleBuffer class from external files.

v1.0:

- Initial release

## 6. Acknowledgements

Kudos for these people who have submitted bugfixed since SoundTouch v1.3.1:

- Arthur A
- Richard Ash
- Stanislav Brabec
- Brian Cameron
- Justin Frankel
- Jason Garland
- Takashi Iwai

Moral greetings to all other contributors as well!

## 7. LICENSE

SoundTouch audio processing library
Copyright (c) Olli Parviainen

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License vesrion 2.1 as published by the Free Software Foundation.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA