diff --git a/README.html b/README.html index 6ace201..baa3bd4 100644 --- a/README.html +++ b/README.html @@ -1,586 +1,618 @@ + SoundTouch library README - - - + + + -
-

SoundTouch audio processing library v2.1.3 pre

-

SoundTouch library Copyright © Olli Parviainen 2001-2019

-
-

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 +

+

SoundTouch audio processing library v2.2

+

SoundTouch library Copyright © Olli Parviainen 2001-2020

+
+

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

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
-
+ 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.2.3 Compiling portable Shared Library / DLL version in GNU environment

+

The GNU compilation does not automatically create a shared-library version of + SoundTouch (.so or .dll) that features position-independent code and C-language + api that are more suitable for cross-language development than C++ libraries.

+

Use script "make-gnu-dll-sh" to build a portable dynamic library version if such is desired.

-

2.3. Building in Android

-

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

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.

+

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.

-

2.4. Building in Mac

-

Install autoconf tool as instructed in http://macappstore.org/autoconf/.

-

Then, build as described above in section "Building in Gnu platforms".

+

2.4. Building in Mac

+

Install autoconf tool as instructed in http://macappstore.org/autoconf/.

+

Then, build as described above in section "Building in Gnu platforms".

-
-

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

+
+

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 sample type is 32bit floating point format, + which also provides better sound quality than integer format because + integer algorithms need to scale already intermediate calculation results to + avoid integer overflows. These early integer scalings can slightly degrade + output quality.

+

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

+

Integer vs floating point:

+

Floating point sample type is generally recommended because it provides + better sound quality.

+ +

However, execution speed difference between integer and floating point processing + depends on the CPU architecture. As rule of thumb, +

+

+

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:

+ +

The algorithms are tuned to utilize autovectorization efficiently + also in other CPU architectures, for example ARM cpus see approx 2.4x processing + speedup when NEON SIMD support is present. +

+

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

+

2.1.2:

@@ -589,7 +621,8 @@ this corresponds to lowering the pitch by -0.318 semitones:

2.1.1: