From 9d718a8cdf29ecd7a313a2c7ae65066f7e6e3dc7 Mon Sep 17 00:00:00 2001 From: Uwe Klotz Date: Sun, 18 Nov 2018 16:59:17 +0100 Subject: Update bundled SoundTouch from 2.1.0 to 2.1.1 --- lib/soundtouch/BPMDetect.cpp | 6 +- lib/soundtouch/README.html | 1837 +++++++++++++++++++++--------------------- lib/soundtouch/SoundTouch.h | 4 +- lib/soundtouch/readme.md | 2 + 4 files changed, 931 insertions(+), 918 deletions(-) (limited to 'lib') diff --git a/lib/soundtouch/BPMDetect.cpp b/lib/soundtouch/BPMDetect.cpp index 01202f0e80..3ecda49f61 100644 --- a/lib/soundtouch/BPMDetect.cpp +++ b/lib/soundtouch/BPMDetect.cpp @@ -186,8 +186,10 @@ BPMDetect::BPMDetect(int numChannels, int aSampleRate) : // choose decimation factor so that result is approx. 1000 Hz decimateBy = sampleRate / TARGET_SRATE; - assert(decimateBy > 0); - assert(INPUT_BLOCK_SIZE < decimateBy * DECIMATED_BLOCK_SIZE); + if ((decimateBy <= 0) || (decimateBy * DECIMATED_BLOCK_SIZE < INPUT_BLOCK_SIZE)) + { + ST_THROW_RT_ERROR("Too small samplerate"); + } // Calculate window length & starting item according to desired min & max bpms windowLen = (60 * sampleRate) / (decimateBy * MIN_BPM); diff --git a/lib/soundtouch/README.html b/lib/soundtouch/README.html index 93734321e0..84a5345831 100644 --- a/lib/soundtouch/README.html +++ b/lib/soundtouch/README.html @@ -1,914 +1,923 @@ - - - - SoundTouch library README - - - - - - - -
-

SoundTouch audio processing library v2.1

-

SoundTouch library Copyright © Olli Parviainen 2001-2018

-
-

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.:

- -

1.1 Contact information

-

Author email: oparviai 'at' iki.fi

-

SoundTouch WWW page: http://soundtouch.surina.net

-

SoundTouch git repository: https://gitlab.com/soundtouch/soundtouch.git

-
-

2. Compiling SoundTouch

-

Before compiling, notice that you can choose the 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.

-

Also notice that SoundTouch can use OpenMP instructions for parallel -computation to accelerate the runtime processing speed in multi-core systems, -however, these improvements need to be separately enabled before compiling. See -OpenMP notes in Chapter 3 below.

-

2.1. Building in Microsoft Windows

-

Project files for Microsoft Visual C++ are supplied with the source -code package. Go to Microsoft WWW page to download - -Microsoft Visual Studio Express version for free. -

-

To build the binaries with Visual C++ 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 may need to -be created manually to the SoundTouch package root for the final -executables. The make-win.bat script creates these directories -automatically.

-

C# example: The source code package includes also a C# example - application for Windows that shows how to invoke SoundTouch.dll - dynamic-load library for processing mp3 audio. -

OpenMP NOTE: If activating the OpenMP parallel computing in -the compilation, the target program will require additional vcomp dll library to -properly run. In Visual C++ 9.0 these libraries can be found in the following -folders.

- -

In Visual Studio 2008, a SP1 version may be required for these libraries. In -other VC++ versions the required library will be expectedly found in similar -"redist" location.

-

Notice that as minor demonstration of a "dll hell" phenomenon both the 32-bit -and 64-bit version of vcomp90.dll have the same filename but different contents, -thus choose the proper version to allow the program start.

-

2.2. Building in Gnu platforms

-

The SoundTouch library compiles in practically any platform -supporting GNU compiler (GCC) tools. SoundTouch requires GCC version 4.3 or later.

-

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

- - - - - - - - - - - - - - - - - - - -
- 
./bootstrap  -
- 		Creates "configure" file with -local autoconf/automake toolset.
-
- 
./configure  -
- 		-

Configures the SoundTouch package for the local environment. -Notice that "configure" file is not available before running the -"./bootstrap" command as above.
-

-
- 
make         -
- 		-

Builds the SoundTouch library & SoundStretch utility. You can - optionally add "-j" switch after "make" to speed up the compilation in - multi-core systems.

-
- 
make install -
- 		-

Installs the SoundTouch & BPM libraries to /usr/local/lib -and SoundStretch utility to /usr/local/bin. Please notice that -'root' privileges may be required to install the binaries to the -destination locations.

-
-

2.2.1 Required GNU tools

-

Bash shell, GNU C++ compiler, libtool, autoconf and automake tools -are required for compiling the SoundTouch library. These are usually -included with the GNU/Linux distribution, but if not, install these -packages first. For example, Ubuntu Linux can acquire and install -these with the following command:

-
sudo apt-get install automake autoconf libtool build-essential
-

2.2.2 Problems with GCC compiler compatibility

-

At the release time the SoundTouch package has been tested to -compile in GNU/Linux platform. However, If you have problems getting the -SoundTouch library compiled, try disabling optimizations that are specific for -x86 processors by running ./configure script with switch -

-
--enable-x86-optimizations=no
-
- -Alternatively, if you don't use GNU Configure system, edit file "include/STTypes.h" -directly and remove the following definition:
- 
#define SOUNDTOUCH_ALLOW_X86_OPTIMIZATIONS 1
-
- -

2.2.3 Compiling Shared Library / DLL version in Cygwin

-

- The GNU compilation does not automatically create a shared-library version of - SoundTouch (.so or .dll). If such is desired, then you can create it as follows - after running the usual compilation:

-
- 
g++ -shared -static -DDLL_EXPORTS -I../../include -o SoundTouch.dll \
-     SoundTouchDLL.cpp ../SoundTouch/.libs/libSoundTouch.a
-sstrip SoundTouch.dll
-
- -

2.3. Building in Android

-

Android compilation instructions are within the - source code package, see file "source/Android-lib/README-SoundTouch-Android.html" - in the source code package.

-

The Android compilation automatically builds separate .so library binaries -for ARM, X86 and MIPS processor architectures. For optimal device support, -include all these .so library binaries into the Android .apk application -package, so the target Android device can automatically choose the proper -library binary version to use.

-

The source/Android-lib folder includes also an Android -example application that processes WAV audio files using SoundTouch library in -Android devices.

- -
-

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 32bit floating point format, -which will also provide slightly better sound quality over the integer format.

-

In Windows environment, the sample data format is chosen in file -"STTypes.h" by choosing one of the following defines:

- -

In GNU environment, the floating sample format is used by default, -but integer sample format can be chosen by giving the following switch -to the configure script:

-
- 
./configure --enable-integer-samples
-
-

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-48000H are supported.

-

3.2. Processing latency

-

The processing and latency constraints of the SoundTouch library are:

- -

3.3. About algorithms

-

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

-

Sample rate transposing affects both the audio stream -duration and pitch. It's implemented simply by converting the original -audio sample stream to the 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 performs subjectively about as well as -higher-order filtering would.

-

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.

-

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

- -

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 the -following #defines in file "TDStretch.h":

-
- 
#define DEFAULT_SEQUENCE_MS     AUTOMATIC
#define DEFAULT_SEEKWINDOW_MS   AUTOMATIC
#define DEFAULT_OVERLAP_MS      8
-
-

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

- -

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 nameDefault value magnitudeLarger value affects...Smaller value affects...Effect to CPU burden
- 
SEQUENCE_MS
- 		Default value is relatively large, chosen for -slowing down music tempoLarger 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 tempoLarger value eases finding a good mixing -position, but may cause a "drifting" artifactSmaller 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
-

3.5 Performance Optimizations

-

General optimizations:

-

The time-stretch routine has a 'quick' mode that substantially -speeds up the algorithm but may slightly compromise the sound quality. -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 x86 specific SIMD optimizations are implemented using compiler -intrinsics, providing about a 3x processing speedup for x86 compatible -processors vs. non-SIMD implementation:

- -

3.5 OpenMP parallel computation

-

SoundTouch 1.9 onwards support running the algorithms parallel in several CPU -cores. Based on benchmark the experienced multi-core processing speed-up gain -ranges between +30% (on a high-spec dual-core x86 Windows PC) to 215% (on a moderately low-spec -quad-core ARM of Raspberry Pi2).

-

See an external blog article with more detailed discussion about the - -SoundTouch OpenMP optimization.

-

The parallel computing support is implemented using OpenMP spec 3.0 -instructions. These instructions are supported by Visual C++ 2008 and later, and -GCC v4.2 and later. Compilers that do not supporting OpenMP will ignore these -optimizations and routines will still work properly. Possible warnings about -unknown #pragmas are related to OpenMP support and can be safely ignored.

-

The OpenMP improvements are disabled by default, and need to be enabled by -developer during compile-time. Reason for this is that parallel processing adds -moderate runtime overhead in managing the multi-threading, so it may not be -necessary nor desirable in all applications. For example real-time processing -that is not constrained by CPU power will not benefit of speed-up provided by -the parallel processing, in the contrary it may increase power consumption due -to the increased overhead.

-

However, applications that run on low-spec multi-core CPUs and may otherwise -have possibly constrained performance will benefit of the OpenMP improvements. -This include for example multi-core embedded devices.

-

OpenMP parallel computation can be enabled before compiling SoundTouch -library as follows:

- -
-

4. SoundStretch audio processing utility -

-

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

-

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 your own program, but it can as well be used -for processing sound files.

-

4.1. SoundStretch Usage Instructions

-

SoundStretch Usage syntax:

-
- 
soundstretch infilename outfilename [switches]
-
-

Where:

- - - - - - - - - - - - - - - -
- 
"infilename"
- 		Name of the input sound data file (in .WAV audio -file format). Give "stdin" as filename to use standard input pipe.
- 
"outfilename"
- 		Name of the output sound file where the -resulting sound is saved (in .WAV audio file format). This parameter -may be omitted if you don't want to save the output (e.g. when -only calculating BPM rate with '-bpm' switch). Give "stdout" as -filename to use standard output pipe.
- 
[switches]
- 		Are one or more control switches.
-

Available control switches are:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- 
-tempo=n
- 		Change the sound tempo by n percents (n = -95.0 -.. +5000.0 %)
- 
-pitch=n
- 		Change the sound pitch by n semitones (n = -60.0 -.. + 60.0 semitones)
- 
-rate=n
- 		Change the 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. When this switch is -applied, the "-tempo" switch is ignored. If "=n" is omitted, i.e. -switch "-bpm" is used alone, then the BPM rate is estimated and -displayed, but tempo not adjusted according to the BPM value.
- 
-quick
- 		Use quicker tempo change algorithm. Gains speed -but loses sound quality.
- 
-naa
- 		Don't use anti-alias filtering in sample rate -transposing. Gains speed but loses sound quality.
- 
-license
- 		Displays the program license text (LGPL)
-

Notes:

- -

4.2. SoundStretch usage examples

-

Example 1

-

The following command increases tempo of the sound file -"originalfile.wav" by 12.5% and stores 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 stores 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. Resulting .wav audio data is directed to standard output -pipe:

-
- 
soundstretch orig.wav stdout -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 stored -to file "dest.wav":

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

Example 5

-

The following command reads .wav sound data from standard input pipe -and estimates the BPM rate:

-
- 
soundstretch stdin -bpm
-
-

Example 6

-

The following command tunes song from original 440Hz tuning to 432Hz tuning: -this corresponds to lowering the pitch by -0.318 semitones:

-
- 
soundstretch original.wav output.wav -pitch=-0.318
-
-
-

5. Change History

-

5.1. SoundTouch library Change History

-

2.1:

- -

2.0:

- -

1.9.2:

- -

1.9.1:

- -

1.9:

- -

1.8.0:

- -

1.7.1:

- -

1.7.0:

- -

1.6.0:

- -

1.5.0:

- -

1.4.1:

- -

1.4.0:

- -

1.3.1:

- -

1.3.0:

- -

1.2.1:

- -

1.2.0:

- -

1.1.1:

- -

1.0.1:

- -

1.0:

- -

5.2. SoundStretch application Change History

-

1.9:

- - -

1.7.0:

- -

1.5.0:

- -

1.4.0:

- -

1.3.0:

- -

1.2.1:

- -

1.2.0:

- -

1.1.1:

- -

1.1:

- -

1.01:

- -
-

6. Acknowledgements

-

Kudos for these people who have contributed to development or -submitted bugfixes:

- -

Moral greetings to all other contributors and users also!

-
-

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 version 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

-

---

-

commercial license alternative also available, contact author for details.

-
-

README.html file updated in May-2018

- - + + + + SoundTouch library README + + + + + + + +
+

SoundTouch audio processing library v2.1.1

+

SoundTouch library Copyright © Olli Parviainen 2001-2018

+
+

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.:

+ +

1.1 Contact information

+

Author email: oparviai 'at' iki.fi

+

SoundTouch WWW page: http://soundtouch.surina.net

+

SoundTouch git repository: https://gitlab.com/soundtouch/soundtouch.git

+
+

2. Compiling SoundTouch

+

Before compiling, notice that you can choose the 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.

+

Also notice that SoundTouch can use OpenMP instructions for parallel +computation to accelerate the runtime processing speed in multi-core systems, +however, these improvements need to be separately enabled before compiling. See +OpenMP notes in Chapter 3 below.

+

2.1. Building in Microsoft Windows

+

Project files for Microsoft Visual C++ are supplied with the source +code package. Go to Microsoft WWW page to download + +Microsoft Visual Studio Express version for free. +

+

To build the binaries with Visual C++ 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 may need to +be created manually to the SoundTouch package root for the final +executables. The make-win.bat script creates these directories +automatically.

+

C# example: The source code package includes also a C# example + application for Windows that shows how to invoke SoundTouch.dll + dynamic-load library for processing mp3 audio. +

OpenMP NOTE: If activating the OpenMP parallel computing in +the compilation, the target program will require additional vcomp dll library to +properly run. In Visual C++ 9.0 these libraries can be found in the following +folders.

+ +

In Visual Studio 2008, a SP1 version may be required for these libraries. In +other VC++ versions the required library will be expectedly found in similar +"redist" location.

+

Notice that as minor demonstration of a "dll hell" phenomenon both the 32-bit +and 64-bit version of vcomp90.dll have the same filename but different contents, +thus choose the proper version to allow the program start.

+

2.2. Building in Gnu platforms

+

The SoundTouch library compiles in practically any platform +supporting GNU compiler (GCC) tools. SoundTouch requires GCC version 4.3 or later.

+

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

+ + + + + + + + + + + + + + + + + + + +
+ 
./bootstrap  -
+ 		Creates "configure" file with +local autoconf/automake toolset.
+
+ 
./configure  -
+ 		+

Configures the SoundTouch package for the local environment. +Notice that "configure" file is not available before running the +"./bootstrap" command as above.
+

+
+ 
make         -
+ 		+

Builds the SoundTouch library & SoundStretch utility. You can + optionally add "-j" switch after "make" to speed up the compilation in + multi-core systems.

+
+ 
make install -
+ 		+

Installs the SoundTouch & BPM libraries to /usr/local/lib +and SoundStretch utility to /usr/local/bin. Please notice that +'root' privileges may be required to install the binaries to the +destination locations.

+
+

2.2.1 Required GNU tools

+

Bash shell, GNU C++ compiler, libtool, autoconf and automake tools +are required for compiling the SoundTouch library. These are usually +included with the GNU/Linux distribution, but if not, install these +packages first. For example, Ubuntu Linux can acquire and install +these with the following command:

+
sudo apt-get install automake autoconf libtool build-essential
+

2.2.2 Problems with GCC compiler compatibility

+

At the release time the SoundTouch package has been tested to +compile in GNU/Linux platform. However, If you have problems getting the +SoundTouch library compiled, try disabling optimizations that are specific for +x86 processors by running ./configure script with switch +

+
--enable-x86-optimizations=no
+
+ +Alternatively, if you don't use GNU Configure system, edit file "include/STTypes.h" +directly and remove the following definition:
+ 
#define SOUNDTOUCH_ALLOW_X86_OPTIMIZATIONS 1
+
+ +

2.2.3 Compiling Shared Library / DLL version in Cygwin

+

+ The GNU compilation does not automatically create a shared-library version of + SoundTouch (.so or .dll). If such is desired, then you can create it as follows + after running the usual compilation:

+
+ 
g++ -shared -static -DDLL_EXPORTS -I../../include -o SoundTouch.dll \
+     SoundTouchDLL.cpp ../SoundTouch/.libs/libSoundTouch.a
+sstrip SoundTouch.dll
+
+ +

2.3. Building in Android

+

Android compilation instructions are within the + source code package, see file "source/Android-lib/README-SoundTouch-Android.html" + in the source code package.

+

The Android compilation automatically builds separate .so library binaries +for ARM, X86 and MIPS processor architectures. For optimal device support, +include all these .so library binaries into the Android .apk application +package, so the target Android device can automatically choose the proper +library binary version to use.

+

The source/Android-lib folder includes also an Android +example application that processes WAV audio files using SoundTouch library in +Android devices.

+ +
+

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 32bit floating point format, +which will also provide slightly better sound quality over the integer format.

+

In Windows environment, the sample data format is chosen in file +"STTypes.h" by choosing one of the following defines:

+ +

In GNU environment, the floating sample format is used by default, +but integer sample format can be chosen by giving the following switch +to the configure script:

+
+ 
./configure --enable-integer-samples
+
+

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-48000H are supported.

+

3.2. Processing latency

+

The processing and latency constraints of the SoundTouch library are:

+ +

3.3. About algorithms

+

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

+

Sample rate transposing affects both the audio stream +duration and pitch. It's implemented simply by converting the original +audio sample stream to the 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 performs subjectively about as well as +higher-order filtering would.

+

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.

+

Sample rate transposing and time-stretching are then used together +to produce the tempo, pitch and rate controls:

+ +

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 the +following #defines in file "TDStretch.h":

+
+ 
#define DEFAULT_SEQUENCE_MS     AUTOMATIC
#define DEFAULT_SEEKWINDOW_MS   AUTOMATIC
#define DEFAULT_OVERLAP_MS      8
+
+

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

+ +

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 nameDefault value magnitudeLarger value affects...Smaller value affects...Effect to CPU burden
+ 
SEQUENCE_MS
+ 		Default value is relatively large, chosen for +slowing down music tempoLarger 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 tempoLarger value eases finding a good mixing +position, but may cause a "drifting" artifactSmaller 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
+

3.5 Performance Optimizations

+

General optimizations:

+

The time-stretch routine has a 'quick' mode that substantially +speeds up the algorithm but may slightly compromise the sound quality. +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 x86 specific SIMD optimizations are implemented using compiler +intrinsics, providing about a 3x processing speedup for x86 compatible +processors vs. non-SIMD implementation:

+ +

3.5 OpenMP parallel computation

+

SoundTouch 1.9 onwards support running the algorithms parallel in several CPU +cores. Based on benchmark the experienced multi-core processing speed-up gain +ranges between +30% (on a high-spec dual-core x86 Windows PC) to 215% (on a moderately low-spec +quad-core ARM of Raspberry Pi2).

+

See an external blog article with more detailed discussion about the + +SoundTouch OpenMP optimization.

+

The parallel computing support is implemented using OpenMP spec 3.0 +instructions. These instructions are supported by Visual C++ 2008 and later, and +GCC v4.2 and later. Compilers that do not supporting OpenMP will ignore these +optimizations and routines will still work properly. Possible warnings about +unknown #pragmas are related to OpenMP support and can be safely ignored.

+

The OpenMP improvements are disabled by default, and need to be enabled by +developer during compile-time. Reason for this is that parallel processing adds +moderate runtime overhead in managing the multi-threading, so it may not be +necessary nor desirable in all applications. For example real-time processing +that is not constrained by CPU power will not benefit of speed-up provided by +the parallel processing, in the contrary it may increase power consumption due +to the increased overhead.

+

However, applications that run on low-spec multi-core CPUs and may otherwise +have possibly constrained performance will benefit of the OpenMP improvements. +This include for example multi-core embedded devices.

+

OpenMP parallel computation can be enabled before compiling SoundTouch +library as follows:

+ +
+

4. SoundStretch audio processing utility +

+

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

+

SoundStretch is a simple command-line application t