From 76f76ffb84ca4fb3bed1fbddf53d611ac37b24f9 Mon Sep 17 00:00:00 2001 From: oparviai Date: Mon, 18 May 2015 15:28:41 +0000 Subject: [PATCH] - Update documentation - Updated version numbers to 1.9 - Disable OpenMP by default, to be enabled by developer --- README.html | 143 ++++++++++++------ configure.ac | 2 +- include/SoundTouch.h | 4 +- .../README-SoundTouch-Android.html | 21 +++ source/Android-lib/jni/Android.mk | 5 +- source/SoundTouch/SoundTouch.vcproj | 3 - 6 files changed, 123 insertions(+), 55 deletions(-) diff --git a/README.html b/README.html index 2ec83fc..1e51257 100644 --- a/README.html +++ b/README.html @@ -13,8 +13,8 @@
-

SoundTouch audio processing library v1.8.1pre

-

SoundTouch library Copyright © Olli Parviainen 2001-2014

+

SoundTouch audio processing library v1.9

+

SoundTouch library Copyright © Olli Parviainen 2001-2015

1. Introduction

SoundTouch is an open-source audio processing library that allows @@ -34,9 +34,13 @@ same time

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

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.

+

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 @@ -82,7 +86,9 @@ Notice that "configure" file is not available before running the 

make         -
-

Builds the SoundTouch library & SoundStretch utility.

+

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

@@ -123,7 +129,7 @@ directly and remove the following definition:
#define SOUNDTOUCH_ALLOW_X86_OPTIMIZATIONS 1
-

2.2.3 Compiling Shared Library / DLL version

+

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 @@ -137,7 +143,15 @@ sstrip SoundTouch.dll

2.1. Building in Android

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

+ 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

@@ -333,28 +347,55 @@ function with parameter  id of SETTING_USE_QUICKSEEK and value

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 expected multi-core processing speed-up gain +ranges between +30% (on high-spec dual-core x86) to 170% (on moderately low-spec +quad-core ARM).

+

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

+ 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 @@ -500,17 +541,29 @@ 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

-

1.8.1pre:

+

1.9:

1.8.0:

 

5.2. SoundStretch application Change History

-

1.8.1:

+

1.9:

@@ -734,9 +787,9 @@ switch "-bpm"

6. Acknowledgements

Kudos for these people who have contributed to development or -submitted bugfixes since SoundTouch v1.3.1:

+submitted bugfixes:

@@ -789,6 +838,6 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

- README.html file updated on April-2014

+ README.html file updated in May-2015

diff --git a/configure.ac b/configure.ac index a399835..bbf98cd 100644 --- a/configure.ac +++ b/configure.ac @@ -19,7 +19,7 @@ dnl this program; if not, write to the Free Software Foundation, Inc., 59 Temple dnl Place - Suite 330, Boston, MA 02111-1307, USA # Process this file with autoconf to produce a configure script. -AC_INIT(SoundTouch, 1.8.0, [http://www.surina.net/soundtouch]) +AC_INIT(SoundTouch, 1.9.0, [http://www.surina.net/soundtouch]) AC_CONFIG_AUX_DIR(config) AC_CONFIG_MACRO_DIR([config/m4]) AM_CONFIG_HEADER([config.h include/soundtouch_config.h]) diff --git a/include/SoundTouch.h b/include/SoundTouch.h index db9100b..081c37e 100644 --- a/include/SoundTouch.h +++ b/include/SoundTouch.h @@ -79,10 +79,10 @@ namespace soundtouch { /// Soundtouch library version string -#define SOUNDTOUCH_VERSION "1.8.0" +#define SOUNDTOUCH_VERSION "1.9.0" /// SoundTouch library version id -#define SOUNDTOUCH_VERSION_ID (10800) +#define SOUNDTOUCH_VERSION_ID (10900) // // Available setting IDs for the 'setSetting' & 'get_setting' functions: diff --git a/source/Android-lib/README-SoundTouch-Android.html b/source/Android-lib/README-SoundTouch-Android.html index 171f680..62198d4 100644 --- a/source/Android-lib/README-SoundTouch-Android.html +++ b/source/Android-lib/README-SoundTouch-Android.html @@ -51,6 +51,27 @@ variable "NDK". That's easiest done by adding the NDK path definition at end of your ~/.bash_profile file, for instance as follows:

    NDK=/cygdrive/d/Android/android-ndk-r6
+

Enabling OpenMP parallel computing mode

+

+ SoundTouch supports OpenMP for parallel computing in multi-core + environments, and these improvements can be enabled also in the Android + build. See the SoundTouch main README.html file for generic notes about the + OpenMP implementation.

+

+ To enable OpenMP mode in Android compilation, edit file Android.mk + and enable the "-fopenmp" flag in LOCAL_CFLAGS and LOCAL_LDFLAGS variables. + This is done by removing hash # from before the following lines in the + Android.mk file, before compiling the library:

+
    LOCAL_CFLAGS += -fopenmp
+   LOCAL_LDFLAGS += -fopenmp
+

OpenMP COMPATIBILITY NOTE: Android NDK has a threading issue +(at least until NDK v10) that causes the native library crash with fatal signal +11 if calling OpenMP-improved routines from a background thread. SoundTouch has +a workaround for this issue in soundtouch-jni.cpp, and this workaround requires +calling function SoundTouch.getVersionString() from the Android +application's main thread at least once before calling other SoundTouch +processing routines. See the SoundTouch Android example application and comments +in the soundtouch-jni.cpp source code file for more details.

Calling SoundTouch native routines from Android application

diff --git a/source/Android-lib/jni/Android.mk b/source/Android-lib/jni/Android.mk index 98fbbf7..16efe69 100644 --- a/source/Android-lib/jni/Android.mk +++ b/source/Android-lib/jni/Android.mk @@ -39,9 +39,10 @@ LOCAL_LDLIBS += -llog # Custom Flags: # -fvisibility=hidden : don't export all symbols -# -fopenmp : enable these flags to allow using OpenMP for parallel computation -LOCAL_CFLAGS += -fvisibility=hidden -I ../../../include -fdata-sections -ffunction-sections #-fopenmp +LOCAL_CFLAGS += -fvisibility=hidden -I ../../../include -fdata-sections -ffunction-sections +# OpenMP mode : enable these flags to enable using OpenMP for parallel computation +#LOCAL_CFLAGS += -fopenmp #LOCAL_LDFLAGS += -fopenmp diff --git a/source/SoundTouch/SoundTouch.vcproj b/source/SoundTouch/SoundTouch.vcproj index d993300..b657a1f 100644 --- a/source/SoundTouch/SoundTouch.vcproj +++ b/source/SoundTouch/SoundTouch.vcproj @@ -53,7 +53,6 @@ RuntimeLibrary="0" EnableFunctionLevelLinking="true" FloatingPointModel="2" - OpenMP="true" UsePrecompiledHeader="0" PrecompiledHeaderFile=".\Release/SoundTouch.pch" AssemblerListingLocation=".\Release/" @@ -210,7 +209,6 @@ BasicRuntimeChecks="3" RuntimeLibrary="1" FloatingPointModel="2" - OpenMP="false" UsePrecompiledHeader="0" PrecompiledHeaderFile=".\Debug/SoundTouch.pch" AssemblerListingLocation=".\Debug/" @@ -370,7 +368,6 @@ RuntimeLibrary="0" EnableFunctionLevelLinking="true" FloatingPointModel="2" - OpenMP="true" UsePrecompiledHeader="0" PrecompiledHeaderFile=".\$(OutDir)/SoundTouch.pch" AssemblerListingLocation=".\$(OutDir)/"