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!


.


COOL! Tempo / Pitch control tool Audioshift now available for Android mobile phones & tablets running Android OS v2.3-3.2! Click icon below for FREE install:

Available in Android Market

SoundTouch Audio Processing Library


F.A.Q - Frequently Asked Questions


General Usage

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?

Alas, not.

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.


Algorithms & Implementation

There is no SSE version of calcCrossCorrMon. Is there a reason for only having the stereo version?

Intel CPU/SSE instruction architecture has limitation that requires SSE memory data accesses to be arranged at 16 byte boundaries for optimal performance, so that SSE memory data accesses violating this 16byte line access alignment incurs a remarkable performance penalty into CPU pipeline.

In stereo sound each floating point sample consists of 2*32bit = 8 bytes of data, so every second sample can be properly aligned and every second misaligned against this 16byte boundary. If you inspect carefully the SSE stereo routines, there's actually an optional optimization kludge that skips every second correlation round to avoid misaligned correlation calculation rounds - resulting in a very minor compromise in processing quality yet yields multiple-fold performance increase.

For mono sound this issue gets more difficult as only every fourth sample were properly aligned and three out of four misaligned. It were possible to make SSE routine for mono sound also, but due to misaligned data accessed the achieved speedup ratio vs traditional implementation were not quite as good to justify the effort.


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 or Symbian applications? How?

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

See below for build instructions for Android platform. Build details for iPhone or Symbian 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.


Android build instructions

Beginning from SoundTouch release 1.7.1, the source code package now includes Android compilation makefiles, instructions and source code examples. See Readme for SoundTouch-Android for more information.

In general level, prepare SoundTouch library for Android /ARM compilation as follows:

  • Switch off exception handling as Android does not support C++ exceptions. That's easiest done by taking latest source codes and defining ST_NO_EXCEPTION_HANDLING either as -D compiler flag, or #define that in STTypes.h file
  • Add *.cpp files from SoundTouch library to your Android.mk file
  • Add copyright notice about usage of SoundTouch library into your application about information to comply with the license

That's it, SoundTouch compiles and is ready for use.


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 remove the exceptions as follows:

  • Latest Source Code snapshot allows disabling exceptions by compile-time switch ST_NO_EXCEPTION_HANDLING given either as -D compiler flag or as #define in file STTypes.h
  • In older SoundTouch versions remove throw clauses in source codes

Copyright Olli Parviainen