soundtouch/source/Android-lib/README-SoundTouch-Android.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <title>SoundTouch in Android</title>
  <meta http-equiv="Content-Type"
 content="text/html; charset=windows-1252">
  <meta http-equiv="Content-Language" content="en-us">
  <meta name="author" content="Olli Parviainen">
  <meta name="description"
 content="Readme file for SoundTouch library Android compilation">
  <style> <!-- .normal { font-family: Arial }
  --></style>
</head>
<body class="normal">
<hr>
<h1>SoundTouch in Android</h1>
<hr>
<h2>Compiling SoundTouch for Android</h2>
<p>SoundTouch source code package contains &quot;Android-lib&quot; example project that compiles SoundTouch 
    source codes into Android native library, and gives an example of JNI interface 
    for invoking 
    the native SoundTouch routines from an Android application written in Java.</p>
<p style="font-weight: 700">Software prerequisites:</p>
<ul>
    <li>Android SDK environment for developing your own Android application. Visit the <a href="http://developer.android.com/index.html">Android developers' site</a> 
        for more information about the Android SDK and developing Android applications.</li>
    <li>Android NDK compiler kit for compiling native library binaries. The Android NDK 
        is <a href="http://developer.android.com/tools/sdk/ndk/index.html">
        available for download</a> at the Android developer tools site.</li>
    <li>In case you're working in Windows environment, install
        <a href="http://cygwin.com/install.html">
        Cygwin</a> to run the Android NDK/SDK compiler scripts</li>
    <li>Latest SoundTouch source code package available at <a href="http://soundtouch.surina.net/sourcecode.html">
        soundtouch.surina.net</a>.</li>
</ul>
<p><b>Hint: </b>As installing and configuring all the components for an Android SDK/NDK 
    environment requires fair effort, it&#39;s good idea to create a dedicated Virtual 
    Machine environment for the Android development environment installation. 
    Having the Android developer environment setup in dedicated Virtual Machine 
    allows keeping all these settings isolated from your other PC operations, and 
    eases taking backup snapshots of your full development environment.</p>
<p><b>Compiling</b></p>
<p>
    To compile the SoundTouch library source codes into an Android native library, 
    open Cygwin/bash shell, go to directory <b>&quot;soundtouch/source/Android-lib/jni&quot;</b> and invoke the NDK 
    compiler with following command:</p>
<pre>    $NDK/ndk-build</pre>
<p>This will build binaries for all the supported Android platforms (arm-v5, arm-v7, X86, MIPS etc) of SoundTouch library, plus the JNI wrapper interface as discussed below. The target binaries will be built into the &quot;libs&quot; subdirectory. As long as all these .so binary library versions are included in the APK Application delivery package, the target Android device can choose the correct library version to use. </p>
<p>Notice that to allow Cygwin/bash to locate the NDK compile scripts, you 
    need to define the location of the NDK installation defined in environment 
    variable &quot;NDK&quot;. That's easiest done by adding the NDK path definition at end of 
    your <b>~/.bash_profile</b> file, for instance as follows:</p>
<pre>    NDK=/cygdrive/d/Android/android-ndk-r6</pre>
<p><b>Enabling OpenMP parallel computing mode</b></p>
<p>
    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.</p>
<p>
    To enable OpenMP mode in Android compilation, edit file <strong>Android.mk</strong> 
	and enable the &quot;-fopenmp&quot; 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:</p>
<pre>    LOCAL_CFLAGS += -fopenmp
   LOCAL_LDFLAGS += -fopenmp</pre>
<p><strong>OpenMP COMPATIBILITY NOTE: </strong>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 <strong>SoundTouch.getVersionString() </strong>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 <strong>soundtouch-jni.cpp </strong>source code file for more details.</p>
<p>
    <strong>SoundTouch performance in Android</strong></p>
<p>
    See external blog articles for more discussion about the
	<a href="http://www.softwarecoven.com/parallel-computing-in-embedded-mobile-devices/">
	SoundTouch OpenMP implementation</a> and the
	<a href="http://www.softwarecoven.com/parallel-computing-with-openmp-in-android/">
	SoundTouch performance benchmark tests in Android environment</a>.</p>
<hr />
<h2>
    Calling SoundTouch native routines from Android application</h2>
    <p>The NDK tools build the SoundTouch c++ routines into a native binary library, while 
    Android applications are written in Java language. To call the SoundTouch and other c/c++ 
    routines from an Android java application code, you'll need to use Java Native 
    Interface (JNI).</p>
    <p>
        The SoundTouch source code package provides source code example how to 
        use JNI to call native c++ routines from a Java class, and provides source codes also for
	a simple example Android application:<ul>
	<li><b>ExampleActivity</b>: This is simple Android example application that
	utilizes SoundTouch native routines for processing WAV audio files. To build the example
	application, use Eclipse Android SDK environment to import the "ExampleActivity" project in the 	"Android-lib" folder into the Eclipse workspace. 
        <li><b>Android-lib/jni/soundtouch-jni.cpp</b>: This file contains c/c++ wrapper routines
	for performing elementary audio file processing with adjusted tempo/pitch/speed parameters
	from the Android application. The wrapper interface is not complete, but provides example
	that is easy to extend when necessary. The NDK compiles this file along with the SoundTouch 
            routines into the native binary library.</li>
        <li><b>Android-lib/src/net/surina/soundtouch/SoundTouch.java</b>: This file implements
	the Java interface class that loasd & accesses the JNI routines in the natively compiled library.
	The example Android application uses this class as interface for processing audio files 
	with SoundTouch.</li>
        <li><b>Android-lib/build.gradle</b>: Top level build script file for Android Studio 3.1.4+</li>
    </ul>
<p>
        Feel free to examine and extend the provided cpp/java source code example file pair to 
        implement and integrate the desired SoundTouch library capabilities into your own Android application.</p>
<hr />
<h2>
    Android floating-point performance considerations</h2>
<p>
        The make process will build dedicated binaries for each supported Android CPU hardware platform type.
</p><p>SoundTouch uses floating-point algorithms for ideal sound quality on all other platform than in the lowest-end ARMv5. That is because lowest-end Android devices are not guaranteed to 
        have floating-point hardware in their CPUs, so that the ARMv5 compilation uses by default software-emulation for floating-point calculations to allow running the binary executables also in low-end devices without floating-point hardware.<p>
        As floating point software-emulation is however several tens of times slower 
        than real hardware-level floating-point calculations, that would make running
        floating-point-intensive applications such as SoundTouch infeasible in these low-end 
        devices. As workaround, the SoundTouch Android compilation builds the ARMv5 version using integer algorithm versions. The integer 
            algorithm version compromises the sound quality but provides good performance also 
            with low-end devices without hardware floating-point support in the CPU level.</p>
        <p>When Android devices with more capable device is used, the device will automatically choose a proper library version for ideal sound quality.</p>
<hr />
    <p style="text-align: center"><i>Copyright &copy; Olli Parviainen</i></p>
</body>
</html>
Added files for Android example compilation 2012-12-28 15:49:08 +01:00			`<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">`
			`<html>`
			`<head>`
			`<title>SoundTouch in Android</title>`
			`<meta http-equiv="Content-Type"`
			`content="text/html; charset=windows-1252">`
			`<meta http-equiv="Content-Language" content="en-us">`
			`<meta name="author" content="Olli Parviainen">`
			`<meta name="description"`
			`content="Readme file for SoundTouch library Android compilation">`
			`<style> <!-- .normal { font-family: Arial }`
			`--></style>`
			`</head>`
			`<body class="normal">`
			`<hr>`
			`<h1>SoundTouch in Android</h1>`
			`<hr>`
			`<h2>Compiling SoundTouch for Android</h2>`
Fine tuning of Android compilation 2012-12-28 20:55:23 +01:00			`<p>SoundTouch source code package contains "Android-lib" example project that compiles SoundTouch`
			`source codes into Android native library, and gives an example of JNI interface`
			`for invoking`
			`the native SoundTouch routines from an Android application written in Java.</p>`
Added files for Android example compilation 2012-12-28 15:49:08 +01:00			`<p style="font-weight: 700">Software prerequisites:</p>`
			`<ul>`
Fine tuning of Android compilation 2012-12-28 20:55:23 +01:00			`<li>Android SDK environment for developing your own Android application. Visit the <a href="http://developer.android.com/index.html">Android developers' site</a>`
			`for more information about the Android SDK and developing Android applications.</li>`
			`<li>Android NDK compiler kit for compiling native library binaries. The Android NDK`
			`is <a href="http://developer.android.com/tools/sdk/ndk/index.html">`
			`available for download</a> at the Android developer tools site.</li>`
			`<li>In case you're working in Windows environment, install`
			`<a href="http://cygwin.com/install.html">`
			`Cygwin</a> to run the Android NDK/SDK compiler scripts</li>`
Added files for Android example compilation 2012-12-28 15:49:08 +01:00			`<li>Latest SoundTouch source code package available at <a href="http://soundtouch.surina.net/sourcecode.html">`
			`soundtouch.surina.net</a>.</li>`
			`</ul>`
Fine tuning of Android compilation 2012-12-28 20:55:23 +01:00			`<p><b>Hint: </b>As installing and configuring all the components for an Android SDK/NDK`
			`environment requires fair effort, it's good idea to create a dedicated Virtual`
			`Machine environment for the Android development environment installation.`
Added files for Android example compilation 2012-12-28 15:49:08 +01:00			`Having the Android developer environment setup in dedicated Virtual Machine`
			`allows keeping all these settings isolated from your other PC operations, and`
Fine tuning of Android compilation 2012-12-28 20:55:23 +01:00			`eases taking backup snapshots of your full development environment.</p>`
Added files for Android example compilation 2012-12-28 15:49:08 +01:00			`<p><b>Compiling</b></p>`
			`<p>`
			`To compile the SoundTouch library source codes into an Android native library,`
Fine tuning of Android compilation 2012-12-28 20:55:23 +01:00			`open Cygwin/bash shell, go to directory <b>"soundtouch/source/Android-lib/jni"</b> and invoke the NDK`
			`compiler with following command:</p>`
Added files for Android example compilation 2012-12-28 15:49:08 +01:00			`<pre> $NDK/ndk-build</pre>`
MIsc. source comment typos Found via `codespell -q 3` 2018-07-27 18:26:56 +02:00			`<p>This will build binaries for all the supported Android platforms (arm-v5, arm-v7, X86, MIPS etc) of SoundTouch library, plus the JNI wrapper interface as discussed below. The target binaries will be built into the "libs" subdirectory. As long as all these .so binary library versions are included in the APK Application delivery package, the target Android device can choose the correct library version to use. </p>`
Fine tuning of Android compilation 2012-12-28 20:55:23 +01:00			`<p>Notice that to allow Cygwin/bash to locate the NDK compile scripts, you`
			`need to define the location of the NDK installation defined in environment`
Added files for Android example compilation 2012-12-28 15:49:08 +01:00			`variable "NDK". That's easiest done by adding the NDK path definition at end of`
			`your <b>~/.bash_profile</b> file, for instance as follows:</p>`
			`<pre> NDK=/cygdrive/d/Android/android-ndk-r6</pre>`
- Update documentation - Updated version numbers to 1.9 - Disable OpenMP by default, to be enabled by developer 2015-05-18 17:28:41 +02:00			`<p><b>Enabling OpenMP parallel computing mode</b></p>`
			`<p>`
			`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.</p>`
			`<p>`
			`To enable OpenMP mode in Android compilation, edit file <strong>Android.mk</strong>`
			`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:</p>`
			`<pre> LOCAL_CFLAGS += -fopenmp`
			`LOCAL_LDFLAGS += -fopenmp</pre>`
			`<p><strong>OpenMP COMPATIBILITY NOTE: </strong>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 <strong>SoundTouch.getVersionString() </strong>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 <strong>soundtouch-jni.cpp </strong>source code file for more details.</p>`
Update Android doc 2015-11-11 22:47:19 +01:00			`<p>`
			`<strong>SoundTouch performance in Android</strong></p>`
			`<p>`
			`See external blog articles for more discussion about the`
			`<a href="http://www.softwarecoven.com/parallel-computing-in-embedded-mobile-devices/">`
			`SoundTouch OpenMP implementation</a> and the`
			`<a href="http://www.softwarecoven.com/parallel-computing-with-openmp-in-android/">`
			`SoundTouch performance benchmark tests in Android environment</a>.</p>`
Added files for Android example compilation 2012-12-28 15:49:08 +01:00			`<hr />`
			`<h2>`
			`Calling SoundTouch native routines from Android application</h2>`
Fine tuning of Android compilation 2012-12-28 20:55:23 +01:00			`<p>The NDK tools build the SoundTouch c++ routines into a native binary library, while`
			`Android applications are written in Java language. To call the SoundTouch and other c/c++`
Added files for Android example compilation 2012-12-28 15:49:08 +01:00			`routines from an Android java application code, you'll need to use Java Native`
			`Interface (JNI).</p>`
			`<p>`
Fine tuning of Android compilation 2012-12-28 20:55:23 +01:00			`The SoundTouch source code package provides source code example how to`
Developed more refined Android example application that also works in ARM & X86 platforms. 2015-05-15 02:07:10 +02:00			`use JNI to call native c++ routines from a Java class, and provides source codes also for`
			`a simple example Android application:<ul>`
			`<li><b>ExampleActivity</b>: This is simple Android example application that`
			`utilizes SoundTouch native routines for processing WAV audio files. To build the example`
			`application, use Eclipse Android SDK environment to import the "ExampleActivity" project in the "Android-lib" folder into the Eclipse workspace.`
			`<li><b>Android-lib/jni/soundtouch-jni.cpp</b>: This file contains c/c++ wrapper routines`
			`for performing elementary audio file processing with adjusted tempo/pitch/speed parameters`
			`from the Android application. The wrapper interface is not complete, but provides example`
			`that is easy to extend when necessary. The NDK compiles this file along with the SoundTouch`
Fine tuning of Android compilation 2012-12-28 20:55:23 +01:00			`routines into the native binary library.</li>`
Developed more refined Android example application that also works in ARM & X86 platforms. 2015-05-15 02:07:10 +02:00			`<li><b>Android-lib/src/net/surina/soundtouch/SoundTouch.java</b>: This file implements`
			`the Java interface class that loasd & accesses the JNI routines in the natively compiled library.`
			`The example Android application uses this class as interface for processing audio files`
			`with SoundTouch.</li>`
Adding gradle build for Android example 2018-09-19 13:08:51 +02:00			`<li><b>Android-lib/build.gradle</b>: Top level build script file for Android Studio 3.1.4+</li>`
Added files for Android example compilation 2012-12-28 15:49:08 +01:00			`</ul>`
			`<p>`
			`Feel free to examine and extend the provided cpp/java source code example file pair to`
Developed more refined Android example application that also works in ARM & X86 platforms. 2015-05-15 02:07:10 +02:00			`implement and integrate the desired SoundTouch library capabilities into your own Android application.</p>`
			`<hr />`
			`<h2>`
			`Android floating-point performance considerations</h2>`
			`<p>`
			`The make process will build dedicated binaries for each supported Android CPU hardware platform type.`
			`</p><p>SoundTouch uses floating-point algorithms for ideal sound quality on all other platform than in the lowest-end ARMv5. That is because lowest-end Android devices are not guaranteed to`
			`have floating-point hardware in their CPUs, so that the ARMv5 compilation uses by default software-emulation for floating-point calculations to allow running the binary executables also in low-end devices without floating-point hardware.<p>`
			`As floating point software-emulation is however several tens of times slower`
			`than real hardware-level floating-point calculations, that would make running`
			`floating-point-intensive applications such as SoundTouch infeasible in these low-end`
			`devices. As workaround, the SoundTouch Android compilation builds the ARMv5 version using integer algorithm versions. The integer`
			`algorithm version compromises the sound quality but provides good performance also`
			`with low-end devices without hardware floating-point support in the CPU level.</p>`
			`<p>When Android devices with more capable device is used, the device will automatically choose a proper library version for ideal sound quality.</p>`
Added files for Android example compilation 2012-12-28 15:49:08 +01:00			`<hr />`
			`<p style="text-align: center"><i>Copyright © Olli Parviainen</i></p>`
			`</body>`
Developed more refined Android example application that also works in ARM & X86 platforms. 2015-05-15 02:07:10 +02:00			`</html>`