SoundTouch

Do you like SoundTouch? Then please support SoundTouch development and maintaining by a donation!

Unrestricted Royalty-free license also available for commercial purposes, please contact us for more information!

Are you looking for professional audio application developer(s) to help in your project?

Please look here!

SoundTouch Audio Processing Library

Asking Questions

Where can I ask questions that SoundTouch documentation or this FAQ did not answer?

Please post your question to SourceForge SoundTouch discussion forum because answering questions there can benefit other users and developers (and notify the author if question stays unanswered for more than a week :) ). The forum's been quite quiet but let's see if that'd work better in the future.

General Usage

Is there source code example showing how to properly use SoundTouch in my own program?

Yes, see main.cpp in folder soundtouch/source/SoundStretch in the source code package.

Why calling SoundTouch 'putSamples' function doesn't always produce any output samples?

SoundTouch algorithm processes audio samples in batches of few tens of milliseconds, so that the algorithm gathers sufficient amount of samples into its internal processing buffer before running processing, and once suitable amount of samples is available, the algorithm processes these samples at one go.

In practice this can be seen that on some times calling 'putSamples' function may not produce any output samples if the algorithm haven't buffered enough samples for triggering processing run, and once enough samples are available, the function call produces seemingly more output samples at a time than was the amount of input samples during that call - because also earlier inputted samples were now processed.

Because in short term amount of output samples returned by SoundTouch is not in direct relation with amount of input samples, it's suggested to loop 'receiveSamples' function call to extract all available ready samples until output pipeline is emptied, i.e. the function returns zero:

pSoundTouch->putSamples(inputSampleBuffer, numInputSamples);

do
{
    SAMPLETYPE sampleBuffer[BUFF_SIZE];
    int buffSizeSamples = BUFF_SIZE / nChannels;

    nSamples = pSoundTouch->receiveSamples(sampleBuffer, buffSizeSamples);
    UseReadySound(sampleBuffer, nSamples * nChannels);
} while (nSamples != 0);

Notice that this approach produces larger amount of processed samples on same occasions, and no samples at other occasions. Usually this approach doesn't pose problems, but if it were desirable to guarantee some processed output samples after each processing rounds, then the trick is not to exhaust all ready samples by 'receiveSamples' at one go, but instead inspect with 'numSamples' function how many ready processed samples are available for output, and regulate amount of received samples so that some samples are left into SoundTouch output pipeline for subsequent processing rounds.

How to calculate how many output samples SoundTouch will produce when feeding in certain number of input samples?

Latest source codes have function SoundTouch::getInputOutputRatio() that returns ratio for calculating processed output track duration from the original input track duration.

This can also be calculated with the following formula:

Number_of_output_samples = Number_of_input_samples / (tempo_change * rate_change)

Example: Let tempo = 1.10 (i.e. +10% vs original) and rate = 0.95 (i.e. -5% vs original). The input-vs-output ratio is:

Number_of_output_samples = Number_of_input_samples / (1.10 * 0.95) 
                         = Number_of_input_samples / 1.045

- If original track duration is 1000000 samples, the processed output duration will be 956938 samples.
- If original track duration is  100.00 seconds, the processed output duration will be  95.69 seconds

Please notice that if applied for intermediate offsets inside an audio stream being processed, the offset given by the above ratio can deviate some tens of milliseconds from ideal offset, but this difference evens out at end of the processed audio stream so the full target duration will be exactly as given by the formula.

How to use SoundTouch for realtime audio processing?

Create a processing function that is called by realtime system once realtime input samples are available, so that this function puts realtime input samples into SoundTouch pipeline with 'putSamples' function call, and use 'receiveSamples' function for extracting resulting output samples for realtime output processing.

Can I process MP3 files with SoundStretch?

SoundStretch processes natively .wav audio files. However, you can apply separate LAME mp3 decoder/encoder software together with SoundStretch for processing mp3 files:

Process MP3 files in Windows:

First, get lame.exe program (download here) and unzip it into to the same folder with soundstretch.exe.

Here's a command-line example for processing myfle.mp3 into myfile_fast.mp3 with SoundStretch parameters -tempo=30 -pitch=-0318. Notice that whitespaces around the sole minus characters '-' are important:

lame -S --decode myfile.mp3 - | soundstretch stdin stdout -tempo=30 -pitch=-0.318 | lame -vS - myfile_fast.mp3

If you get headache from the above syntax, alternatively download a Windows .bat script for simplified mp3 processing. Same example with this script:

process myfile.mp3 myfile_fast.mp3 "-tempo=30 -pitch=-0.318"

Process MP3 files in Linux / Unix / Mac OSX (bash shell):

First, install LAME software (sudo apt-get install lame).

Then, a bash command example for processing myfle.mp3 into myfile_fast.mp3 with SoundStretch parameters -tempo=30 -pitch=-0318. Notice that whitespaces around sole minus characters '-' are important:

lame -S --decode myfile.mp3 - | ./soundstretch stdin stdout -tempo=30 -pitch=-0.318 | lame -vS - myfile_fast.mp3

Again, if the above syntax gave you headache, download a bash script for simplified mp3 processing. Same example with this script:

./process myfile.mp3 myfile_fast.mp3 -tempo=30 -pitch=-0.318

How to batch-process large number of audio files at a time?

The following script code snippets will apply soundstretch command for all .wav audio files within a directory, in these cases applying switch "-bpm=60" for each file.

Windows command-line / batch file:

set newbpm=60
for %%f in (*.wav) do soundstretch %%f %%~nf%newbpm%.wav -bpm=%newbpm%

Linux / Mac OSX / Unix (bash shell):

#!/bin/bash
bpm=60
for f in *.wav; do
    fname=$(basename $f)
    ext="${fname##*.}"
    base="${fname%.*}"
    ./soundstretch $f $base$bpm.$ext -bpm=$bpm
done

License

iPhone supports only static linkage. May I still use SoundTouch in my application?

Go for it - I don't mind if independent application developer uses static linkage instead of dynamic, as far as you otherwise follow license terms, i.e. include a copyright notice of SoundTouch usage in the application. If you're concerned with LGPL license terms, commercial license is also available upon request: see below.

We're creating commercial application and want to avoid (L)GPL licensed software. Is it possible to purchase non-GPL-licensed version of SoundTouch for commercial use?

Yes, it is possible to get commercial license. Please contact the author for more information.

Compiling & development

Can I use SoundTouch library with other programming languages than C++?

SoundTouch source code kit contains a DLL version of the library that allows invoking the SoundTouch routines from other programming languages (that is, still in Windows environment). What you still need is to create a wrapper for importing and interfacing the SoundTouch.dll functions for your favorite language.

SoundTouch source code kit contains SoundTouch wrapper for Delphi (Pascal)
Practice# software project has implemented a SoundTouch wrapper for C#

(a) Why SoundTouch library compiles in x64 instruction set, but crashes immediately after starting with a "Segmentation fault" error?

(b) Why SoundTouch library compiles in Mac OS X having Intel CPU, but crashes immediately after starting with a "Segmentation fault" error?

This issue deals with Intel 64bit instruction set that also Mac OS uses. Earlier releases of SoundTouch uses Intel CPU detection routine written for 32bit mode which uses stack management instructions that have since been erased from 64bit mode, hence the segmentation failure.

This issue has been fixed into latest SoundTouch development source codes, available for download in Source Code Repository.

Can I compile SoundTouch for iPhone, Android, Symbian, Blackberry or Raspberry Pi applications? How?

Yes, there are iPhone, Android, Symbian, Blackberry and Raspberry Pi applications using SoundTouch library.

Build scripts for Android SDK platform are included with the source code kit, see Android README. Raspberry Pi (usually) runs on Linux so GNU/Linux build instructions directly work also in Raspberry. Build details for iPhone and others are currently not alas available (please send us if you do have), but supposedly similar process as for Android should work for these platforms also.

How to compile SoundTouch for a target platform that doesn't support C++ exceptions?

SoundTouch uses standard C++ exceptions as safety guard against unexpected issues, yet exceptions shouldn't occur in normal use. If you feel that you can live without such safety guard, you can disable exceptions by compile-time switch ST_NO_EXCEPTION_HANDLING given either as -D compiler flag or as #define in file STTypes.h