Added files for Android example compilation

2024-11-09 20:33:03 +01:00 · 2012-12-28 14:49:08 +00:00 · 2012-12-28 14:49:08 +00:00 · 9b902ef3b7
commit 9b902ef3b7
parent c3f4ff9532
5 changed files with 236 additions and 0 deletions
--- a/source/Android-lib/README-SoundTouch-Android.html
+++ b/source/Android-lib/README-SoundTouch-Android.html
@ -0,0 +1,118 @@
+<!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 example project that compiles SoundTouch 
+    into Android native library, and gives an example JNI interface that can invoke 
+    the native SoundTouch routines from an Android application.</p>
+<p style="font-weight: 700">Software prerequisites:</p>
+<ul>
+    <li>Android SDK environment for developing your own Android application. For more 
+        information about the Android SDK and developing the applications please visit 
+        the <a href="http://developer.android.com/index.html">Android developers' site</a>.</li>
+    <li>Android NDK compiler kit to create native library compilations. Follow this link 
+        to         <a href="http://developer.android.com/tools/sdk/ndk/index.html">
+        download the Android NDK</a> from the Android developer tools site.</li>
+    <li>In case you're working in Windows environment, you'll need <a href="http://cygwin.com/install.html">
+        Cygwin</a> to invoke the Android NDK/SDK compile 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 setting up all the components and settings for an Android SDK/NDK 
+    environment requires fair effort, I recommend creating a dedicated clean Virtual 
+    Machine environment and installing all the Android developer tools into there. 
+    Having the Android developer environment setup in dedicated Virtual Machine 
+    allows keeping all these settings isolated from your other PC operations, and 
+    eases creating full backup snapshots of your 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 and go to directory <b>&quot;soundtouch/source/Android-lib/jni&quot;</b> and invoke the NDK 
+    compiler as follows:</p>
+<pre>    $NDK/ndk-build</pre>
+<p>This will build the ARMv5 and ARMv7 versions of SoundTouch library (including 
+    also the example JNI 
+    interface, see below) into &quot;libs&quot; folder.</p>
+<p>Notice that in order for Cygwin/bash to locate the NDK compile scripts, you'll 
+    need to have 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>
+<hr />
+<h2>
+    Android floating-point performance considerations</h2>
+<p>
+        Android NDK builds default compilation for ARMv5 CPU generation that works in 
+        all ARM-based Android devices.<p>
+        This has a pitfall though: For ideal sound quality SoundTouch should be compiled 
+        to use floating-point algorithms, however, some low-end Android devices do not 
+        have floating-point hardware in their CPU, and hence the default ARMv5 compilation uses software-emulation for floating-point calculations instead of 
+        hardware floating-point instructions to support also these low-end devices.<p>
+        The floating point software-emulation is however several tens of times slower 
+        than real hardware-level floating-point calculations, making 
+        floating-point-intensive applications such as SoundTouch infeasible for low-end 
+        devices.<p>
+        As workaround, the SoundTouch Android compilation builds two separate versions 
+        of the library:<ul>
+        <li>ARMv5 version that compiles SoundTouch using integer algorithms. The integer 
+            algorithm version compromises the sound quality but provides good performance also 
+            with low-end 
+            devices whose CPUs do not have hardware floating-point support</li>
+        <li>ARMv7 version that compiles SoundTouch using hardware floating-point algorithms. 
+            These algorithms provide ideal sound quality yet do not work in simpler CPU 
+            versions.</li>
+    </ul>
+    <p>
+        These two library compilations are defined in file &quot;<b>jni/Application.mk</b>&quot; 
+        and results in automatically building two separate library targets under the &quot;<b>libs</b>&quot; 
+        directory. As far as you include both these compiled library versions into your 
+        application delivery, the Android environment can automatically select the right 
+        library version based on the customer device capabilities.<p>
+        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>
+    <p>The NDK tools build SoundTouch c++ routines into a native binary library, while 
+    Android applications are written in Java language. To call 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 an example how to 
+        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 
+            uses SoundTouch library routines to return the library version string to the main 
+            Android application. The NDK compiles this file along with the SoundTouch 
+            routines into the native library.</li>
+        <li><b>Android-lib/src/net/surina/soundtouch/SoundTouch.java</b>: This file provides 
+            a Java interface class to invoke the native routine implemented in file <b>soundtouch-jni.cpp</b> 
+            for reading the SoundTouch library version string from the Android Java 
+            application code. 
+        </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 behavior into your Android application.</p>
+<hr />
+    <p style="text-align: center"><i>Copyright &copy; Olli Parviainen</i></p>
+    <!--
+$Id: README.html 160 2012-11-08 18:53:01Z oparviai $
+-->
+</body>
+</html>
--- a/source/Android-lib/jni/Android.mk
+++ b/source/Android-lib/jni/Android.mk
@ -0,0 +1,39 @@
+# Copyright (C) 2010 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# $Id: Android.mk 327 2012-03-25 18:26:07Z olli $
+
+LOCAL_PATH := $(call my-dir)
+
+include $(CLEAR_VARS)
+
+# *** Remember: Change -O0 into -O2 in add-applications.mk ***
+
+LOCAL_MODULE    := soundtouch
+LOCAL_SRC_FILES := soundtouch-jni.cpp ../../SoundTouch/AAFilter.cpp \
+                   ../../SoundTouch/FIFOSampleBuffer.cpp ../../SoundTouch/FIRFilter.cpp ../../SoundTouch/cpu_detect_x86.cpp \
+                   ../../SoundTouch/RateTransposer.cpp ../../SoundTouch/SoundTouch.cpp  ../../SoundTouch/TDStretch.cpp
+
+# for native audio
+LOCAL_LDLIBS    += -lgcc 
+# --whole-archive -lgcc 
+# for logging
+LOCAL_LDLIBS    += -llog
+# for native asset manager
+#LOCAL_LDLIBS    += -landroid
+# don't export all symbols
+# added "-marm" switch to use arm instruction set instead of thumb for improved calculation performance.
+LOCAL_CFLAGS += -Wall -fvisibility=hidden -I ../../../include -D ST_NO_EXCEPTION_HANDLING -fdata-sections -ffunction-sections -marm
+
+include $(BUILD_SHARED_LIBRARY)
--- a/source/Android-lib/jni/Application.mk
+++ b/source/Android-lib/jni/Application.mk
@ -0,0 +1,7 @@
+# $Id: Application.mk 222 2011-12-13 21:07:38Z olli $
+#
+# Build both ARMv5TE and ARMv7-A machine code.
+#
+
+APP_ABI := armeabi-v7a armeabi
+APP_OPTIM := release
--- a/source/Android-lib/jni/soundtouch-jni.cpp
+++ b/source/Android-lib/jni/soundtouch-jni.cpp
@ -0,0 +1,43 @@
+////////////////////////////////////////////////////////////////////////////////
+///
+/// Example Interface class for SoundTouch native compilation
+///
+/// Author        : Copyright (c) Olli Parviainen
+/// Author e-mail : oparviai 'at' iki.fi
+/// WWW           : http://www.surina.net
+///
+////////////////////////////////////////////////////////////////////////////////
+//
+// $Id: jni-routines.cpp 222 2011-12-13 21:07:38Z olli $
+//
+////////////////////////////////////////////////////////////////////////////////
+
+#include <jni.h>
+#include <android/log.h>
+//#include <string.h>
+//#include <stdio.h>
+//#include <dlfcn.h>
+
+#include "../../../include/SoundTouch.h"
+//#include "TimeShiftEffect.h"
+
+#define LOGV(...)   __android_log_print((int)ANDROID_LOG_INFO, "SOUNDTOUCH", __VA_ARGS__)
+//#define LOGV(...)
+
+
+#define DLL_PUBLIC __attribute__ ((visibility ("default")))
+
+using namespace soundtouch;
+
+extern "C" DLL_PUBLIC jstring Java_net_surina_soundtouch_getVersionString(JNIEnv *env, jobject thiz)
+{
+    const char *verStr;
+
+    LOGV("JNI call soundtouch.getVersionString");
+
+    // Call example SoundTouch routine
+    verStr = SoundTouch::getVersionString();
+
+    // return version as string
+    return env->NewStringUTF(verStr);
+}
--- a/source/Android-lib/src/net/surina/soundtouch/SoundTouch.java
+++ b/source/Android-lib/src/net/surina/soundtouch/SoundTouch.java
@ -0,0 +1,29 @@
+////////////////////////////////////////////////////////////////////////////////
+///
+/// Example class that invokes native SoundTouch routines through the JNI
+/// interface.
+///
+/// Author        : Copyright (c) Olli Parviainen
+/// Author e-mail : oparviai 'at' iki.fi
+/// WWW           : http://www.surina.net
+///
+////////////////////////////////////////////////////////////////////////////////
+//
+// $Id: jni-routines.cpp 222 2011-12-13 21:07:38Z olli $
+//
+////////////////////////////////////////////////////////////////////////////////
+
+package net.surina.soundtouch;
+
+public final class SoundTouch
+{
+    // Native interface function that returns SoundTouch version string.
+    // This invokes the native c++ routine defined in "soundtouch-jni.cpp".
+    public native final String getVersionString();
+
+    // Load the native library upon startup
+    static
+    {
+        System.loadLibrary("soundtouch");
+    }
+}