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!

.


Audio Application development services

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

Please look here!


.

SoundTouch Audio Processing Library


F.A.Q - Frequently Asked Questions


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.


Is it possible to reliably predict the exact number of samples to feed to SoundTouch to get a certain number of output samples?

It's possible to predict an approximate number of input-vs-output samples, but alas not absolutely exact number of samples.

Over time SoundTouch returns amount of samples that is in linear ratio to input samples multiplied by tempo*rate parameters, but in short term the returned number of samples after a processing round deviates randomly within a couple of tens of milliseconds. 

This is because exact number of returned samples depends on specific characteristics of the sound stream being processed at given time, and as sound stream is inherently a random process, the number of samples returned after a processing round is also random process.

See also FAQ item related with sample processing logic.


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.


License

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

Go for it - I don't mind if your application 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.


(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


Copyright Olli Parviainen