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 > < ! - - . n o r m a l { f o n t - f a m i l y : A r i a l }
-->< / style >
< / head >
< body class = "normal" >
< hr >
< h1 > SoundTouch in Android< / h1 >
< hr >
< h2 > Compiling SoundTouch for Android< / h2 >
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 >
2012-12-28 15:49:08 +01:00
< p style = "font-weight: 700" > Software prerequisites:< / p >
< ul >
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 >
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 >
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.
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
2012-12-28 20:55:23 +01:00
eases taking backup snapshots of your full development environment.< / p >
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,
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 >
2012-12-28 15:49:08 +01:00
< pre > $NDK/ndk-build< / pre >
< p > This will build the ARMv5 and ARMv7 versions of SoundTouch library (including
also the example JNI
2012-12-28 20:55:23 +01:00
interface, see below) into the " libs" subdirectory.< / 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
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 >
< hr / >
< h2 >
Android floating-point performance considerations< / h2 >
< p >
2012-12-28 20:55:23 +01:00
Default build target for
Android NDK is ARMv5 CPU generation, as that works in
2012-12-28 15:49:08 +01:00
all ARM-based Android devices.< p >
This has a pitfall though: For ideal sound quality SoundTouch should be compiled
2012-12-28 20:55:23 +01:00
to use floating-point algorithms, however, all low-end Android devices do not
have floating-point hardware in their CPUs, and hence the default ARMv5 compilation uses software-emulation for floating-point calculations instead of
hardware floating-point to allow running the binary executables also in low-end devices.< p >
2012-12-28 15:49:08 +01:00
The floating point software-emulation is however several tens of times slower
than real hardware-level floating-point calculations, making
2012-12-28 20:55:23 +01:00
floating-point-intensive applications such as SoundTouch infeasible with low-end
2012-12-28 15:49:08 +01:00
devices.< p >
As workaround, the SoundTouch Android compilation builds two separate versions
of the library:< ul >
2012-12-28 20:55:23 +01:00
< li > ARMv5 version that compiles SoundTouch using integer algorithm version. The integer
2012-12-28 15:49:08 +01:00
algorithm version compromises the sound quality but provides good performance also
with low-end
2012-12-28 20:55:23 +01:00
devices without hardware floating-point support in the CPU level.< / li >
2012-12-28 15:49:08 +01:00
< li > ARMv7 version that compiles SoundTouch using hardware floating-point algorithms.
These algorithms provide ideal sound quality yet do not work in simpler CPU
2012-12-28 20:55:23 +01:00
models.< / li >
2012-12-28 15:49:08 +01:00
< / ul >
< p >
2012-12-28 20:55:23 +01:00
These two library compilations are already defined in file " < b > jni/Application.mk< / b > "
so that these two separate library targets are automatically built under the " < b > libs< / b > "
2012-12-28 15:49:08 +01:00
directory. As far as you include both these compiled library versions into your
2012-12-28 20:55:23 +01:00
application delivery, the Android devices can automatically select the right
library version based on the available device' s capabilities.< p >
2012-12-28 15:49:08 +01:00
Please yet be aware that depending on capabilities of the Android devices you
will need to provide the SoundTouch routines with samples in either integer or
floating-point format, so build your interface routines to take this into
account.< hr / >
< h2 >
Calling SoundTouch native routines from Android application< / h2 >
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++
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 >
2012-12-28 20:55:23 +01:00
The SoundTouch source code package provides source code example how to
2012-12-28 15:49:08 +01:00
use JNI to call native c++ routines from a Java class through the following
source code file pair:< ul >
< li > < b > Android-lib/jni/soundtouch-jni.cpp< / b > : This file contains c/c++ routine that
2012-12-28 20:55:23 +01:00
calls SoundTouch library routine to return the library version string to the main
2012-12-28 15:49:08 +01:00
Android application. The NDK compiles this file along with the SoundTouch
2012-12-28 20:55:23 +01:00
routines into the native binary library.< / li >
2012-12-28 15:49:08 +01:00
< li > < b > Android-lib/src/net/surina/soundtouch/SoundTouch.java< / b > : This file provides
2012-12-28 20:55:23 +01:00
a Java interface class to load the native library and to invoke the native routine implemented in
the file < b > soundtouch-jni.cpp< / b > < / li >
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
2012-12-28 20:55:23 +01:00
implement and integrate the desired SoundTouch library capabilities into your Android application.< / p >
2012-12-28 15:49:08 +01:00
< hr / >
< p style = "text-align: center" > < i > Copyright © Olli Parviainen< / i > < / p >
<!--
2012-12-28 20:55:23 +01:00
$Id$
2012-12-28 15:49:08 +01:00
-->
< / body >
< / html >
