SoundTouch library README
Author: Olli Parviainen
Description: Readme file for SoundTouch audio processing library

# SoundTouch audio processing library v1.2.2pre2 (24/Oct/2004)

SoundTouch library Copyright (c) Olli Parviainen 2002-2004

# 1. Introduction

SoundTouch is an open-source audio processing library that allows changing the sound tempo, pitch and playback rate parameters independently from each other, i.e.:

- Sound tempo can be incresed or decreased while maintaining the original pitch
- Sound pitch can be incresed or decreased while maintaining the original tempo
- Change playback rate that affects both tempo and pitch at the same time
- Choose any combination of tempo/pitch/rate

### 1.1 Contact information

Author email: oparviai @ iki.fi

SoundTouch WWW page: http://www.iki.fi/oparviai/soundtouch

> Note: The above URL is a relay address that will forward the browser to the actual server. If you'll create a link to SoundTouch library page, please use the above URL instead of the actual address, so that the correct link address will be maintained although the pages would move to another server.

## 2. Compiling SoundTouch

Before compiling, notice that you can choose sample data format if it's desirable to use floating point sample data instead of 16bit integers. See section "sample data format" for more information.

### 2.1. Building in Microsoft Windows

Project files for Microsoft Visual C++ 6.0 are supplied with the source code package. Please notice that SoundTouch library uses processor-specific optimizations for Pentium III and AMD processors that require a “processor pack” upgrade for the Visual Studio 6.0 to be installed in order to support these optimizations. The processor pack upgrade can be downloaded from Microsoft site at this URL:

http://msdn.microsoft.com/vstudio/downloads/tools/ppack/default.aspx

If the above URL is unavailable or removed, go to http://msdn.microsoft.com and perform a search with keywords “processor pack”.

Visual Studio .NET supports required instructions by default and thus doesn't require installing the processor pack.

To build the binaries with Visual C++ 6.0 compiler, either run "make-win.bat" script or open the appropriate project files in source code directories with Visual Studio. The final executable will appear under the "SoundTouch\bin" directory. If using the Visual Studio IDE instead of the “make-win.bat” script, directories “bin” and “lib” have to be created manually to the SoundTouch package root for the final executables. The “make-win.bat” script creates these directories automatically.

Also other C++ compilers than Visual C++ can be used, but project or makefiles then have to be adapted accordingly. Performance optimizations are written in Visual C++ compatible syntax, they may or may not be compatible with other compilers. If using GCC (Gnu C Compiler) compiler package such as DJGPP or Cygwin, please see next chapter for instructions.

### 2.2. Building in Gnu platforms

The SoundTouch library can be compiled in practically any platform supporting GNU compiler (GCC) tools. SoundTouch have been tested with gcc versions 3.2.3., but it shouldn't be very specific about the gcc version. Assembler-level performance optimizations for GNU platform are currently available in x86 platforms only, they are automatically disabled and replaced with standard C routines in other processor platforms.

To build and install the binaries, run the following commands in SoundTouch/ directory:

    configure    -
| Configures the SoundTouch package for local environment.
    make         -
| Builds the SoundTouch library & SoundStretch utility.
    make install -
| Installs the SoundTouch & BPM libraries to /usr/local/lib and SoundStretch utility to /usr/local/bin. Please notice that 'root' access may be required to install the binaries to the destination locations.

## 3. About implementation & Usage tips

### 3.1. Supported sample data formats

The sample data format can be chosen between 16bit signed integer and 32bit floating point values, the default is 16bit signed inteher. The sample data format is chosen in file "STTypes.h" by choosing one of the following defines:

- #define INTEGER_SAMPLES for 16bit signed integer
- #define FLOAT_SAMPLES for 32bit floating point

The sample data can have either single (mono) or double (stereo) audio channel. Stereo data is interleaved so that every other data value is for left channel and every second for right channel. Notice that while it'd be possible in theory to process stereo sound as two separate mono channels, this isn't recommended because processing the channels separately would result in losing the phase coherency between the channels, which consequently would ruin the stereo effect.

Sample rates between 8000-48000Hz are supported.

### 3.2. Processing latency

The processing and latency constraints of the SoundTouch library are:

- Input/output processing latency for the SoundTouch processor is around 100 ms. This is when time-strething is used; if rate transposing effect alone is used, the latency requirement is much shorter, see section 'About algorithms'.
- Processing CD-quality sound (16bit stereo sound with 44100Hz samplerate) in real-time or faster is possible starting from processors equivalent to Intel Pentium 133Mhz or better, if using "quick" processing algorithm. If not using the "quick" mode or if floating point sample data are being used, several times more CPU power is typically required.

### 3.3. About algorithms

SoundTouch provides three seemingly independent effects: tempo, pitch and playback rate control. These three controls are implemented as ombination of two primary effects, samplerate transposing and time-stretching.

Samplerate transposing affects both the audio stream duration and pitch. It's implemented simply by converting the original audio sample stream to desired duration by interpolating from the original audio samples. In SoundTouch, linear interpolation with anti-alias filtering is used. Theoretically a higher-order interpolation provide better result than 1st order linear interpolation, but in audio application linear interpolation together with anti-alias filtering perform subjectively about as well as higher-order filtering would.

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

Samplerate transposing and time-streching are then used together to produce the tempo, pitch and rate controls:

- 'Tempo' control is implemented purely by time-stretching.
- 'Rate' control is implemented purely by samplerate transposing.
- 'Pitch' control is implemented as a combination of time-stretching and samplerate transposing. For example, to increase pitch the audio stream is first time-stretched to longer duration (without affecting pitch) and then transposed back to original duration by samplerate transposing, which simultaneously reduces duration and increases pitch. The result is original duration but increased pitch.

### 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     82
>     #define DEFAULT_SEEKWINDOW_MS   28
>     #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. Determines to how long sequences the original sound is chopped in time-stretch algorithm. The larger this value is, the lesser sequences are used in processing. In principle a bigger value sounds better when slowing down tempo, but worse when increasing tempo and vice versa.
- DEFAULT_SEEKWINDOW_MS: Seeking window default length in milliseconds for algorithm that seeks for the best possible overlapping location. This determines from how wide sample "window" the algorithm can look for 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 neighbouring 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.
- DEFAULT_OVERLAP_MS: Overlap length in milliseconds. When the chopped sound sequences are mixed back together to form again a continuous sound stream, this parameter defines over how long period the two consecutive sequences are let to overlap 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 summarizes how the parameter can be adjusted for different applications:

Parameter name | Default value magnitude | Larger value affects... | Smaller value affects... | Music | Speech | Effect in 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 | Default value usually good | A smaller value than default might be better | 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. | Default value usually good, unless a "drifting" artifact is disturbing. | Default value usually good | 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

### 3.5 Performance Optimizations

General optimizations:

The time-stretch routine has a 'quick' mode that substantially speeds up the algorithm but may degrade the sound quality by a small amount. This mode is activated by calling SoundTouch::setSetting() function with parameter id of SETTING_USE_QUICKSEEK and value "1", i.e.

>     setSetting(SETTING_USE_QUICKSEEK, 1);

CPU-specific optimizations:

- Intel MMX optimized routines are used with compatible CPUs when 16bit integer sample type is used. MMX optimizations are available both in Win32 and Gnu/x86 platforms. Compatible processors are Intel PentiumMMX and later; AMD K6-2, Athlon and later.
- Intel SSE optimized routines are used with compatible CPUs when floating point sample type is used. SSE optimizations are currently implemented for Win32 platform only. Processors compatible with SSE extension are Intel processors starting from Pentium-III, and AMD processors starting from Athlon XP.
- AMD 3DNow! optimized routines are used with compatible CPUs when floating point sample type is used, but SSE extension isn't supported . 3DNow! optimizations are currently implemented for Win32 platform only. These optimizations are used in AMD K6-2 and Athlon(classic) CPU's; better performing SSE routines are used with AMD processor starting from Athlon XP.

## 4. SoundStretch audio processing utility

SoundStretch audio processing utility
Copyright (c) Olli Parviainen 2002-2003

SoundStretch is a simple command-line application that can change tempo, pitch and playback rates of WAV sound files. This program is intended primarily to demonstrate how the "SoundTouch" library can be used to process sound in own programs, but it can as well be used for processing sound files.

### 4.1. SoundStretch Usage Instructions

SoundStretch Usage syntax:

>     soundstretch infile.wav outfile.wav [switches]

Where:

    "infile.wav"
| is name of the input sound data file (in .WAV audio file format).
    "outfile.wav"
| is name of the output sound file where the resulting sound is saved (in .WAV audio file format). This parameter may be omitted if it's not desired to save the output (e.g. when only calculating BPM rate with '-bpm' switch).
     [switches]
| Are one or more control switch.

Available control switches are:

    -tempo=n
| Change sound tempo by n percents (n = -95.0 .. +5000.0 %)
    -pitch=n
| Change sound pitch by n semitones (n = -60.0 .. + 60.0 semitones)
    -rate=n
| Change sound playback rate by n percents (n = -95.0 .. +5000.0 %)
    -bpm=n
| Detect the Beats-Per-Minute (BPM) rate of the sound and adjust the tempo to meet 'n' BPMs. If this switch is defined, the "-tempo=n" switch value is ignored. If "=n" is omitted, i.e. switch "-bpm" is used alone, the program just calculates and displays the BPM rate but doesn't adjust tempo ccording to the BPM value.
    -quick
| Use quicker tempo change algorithm. Gains speed but loses sound quality.
    -naa
| Don't use anti-alias filtering in samplerate transposing. Gains speed but loses sound quality.
    -license
| Displays the program license text (LGPL)

Notes:

- The numerical switch values can be entered using either integer (e.g. "-tempo=123") or decimal (e.g. "-tempo=123.45") numbers.
- The "-naa" and/or "-quick" switches can be used to reduce CPU usage while compromising some sound quality
- The BPM detection algorithm works by detecting repeating low-frequency (<250Hz) sound patterns and thus works mostly with most rock/pop music with bass or drum beat. The BPM detection doesn't work on pieces such as classical music without distinct, repeating bass frequency patterns. Also pieces with varying tempo, varying bass patterns or very complex bass patterns (jazz, hiphop) may produce odd BPM readings.
  In cases when the bass pattern drifts a bit around a nominal beat rate (e.g. drummer is again drunken :), the BPM algorithm may report incorrect harmonic one-halft of one-thirdth of the correct BPM value; in such case the system could for example report BPM value of 50 or 100 instead of correct BPM value of 150.

### 4.2. SoundStretch usage examples

Example 1

The following command increases tempo of the sound file "originalfile.wav" by 12.5% and saves result to file "destinationfile.wav":

>     soundstretch originalfile.wav destinationfile.wav -tempo=12.5

Example 2

The following command decreases the sound pitch (key) of the sound file "orig.wav" by two semitones and saves the result to file "dest.wav":

>     soundstretch orig.wav dest.wav -pitch=-2

Example 3

The following command processes the file "orig.wav" by decreasing the sound tempo by 25.3% and increasing the sound pitch (key) by 1.5 semitones. Result is saved to file "dest.wav":

>     soundstretch orig.wav dest.wav -tempo=-25.3 -pitch=1.5

Example 4

The following command detects the BPM rate of the file "orig.wav" and adjusts the tempo to match 100 beats per minute. Result is saved to file "dest.wav":

>     soundstretch orig.wav dest.wav -bpm=100

## 5. Change History

### 5.1. SoundTouch library Change History

v1.2.2:

- Fixed tempo routine output duration inaccuracy due to rounding error
- Implemented separate processing routines for integer and floating arithmetics to allow improvements to floating point routines (earlier used algorithms mostly optimized for integer arithmetics also for floating point samples)
- Fixed a bug that distorts sound if samplerate 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.
- 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 organization 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

### 5.2. SoundStretch application Change History

v1.2.2:

- No changes

v1.2.1:

- Fixed 64bit address space bugs.

v1.2.0:

- Added support for 32bit floating point sample data type
- Restructured the BPM routines into separate library
- Fixed big-endian conversion bugs in WAV file routines (hopefully :)

v1.1.1:

- Fixed bugs in WAV file reading & added byte-order conversion for big-endian processors.
- Moved SoundStretch source code under 'example' directory to highlight difference from SoundTouch stuff.
- Replaced windows makefiles by script using the .dsw files
- Output file name isn't required if output isn't desired (e.g. if using the switch '-bpm' in plain format only)

v1.1:

- Fixed "Release" settings in Microsoft Visual C++ project file (.dsp)
- Added beats-per-minute (BPM) detection routine and command-line switch "-bpm"

v1.01:

- Initial release

## 6. 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 as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

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

$Id: README.html,v 1.11 2003/12/27 11:12:26 Olli Exp $