gstreamer/sdk-installing-for-android-development.md

301 lines
16 KiB
Markdown
Raw Normal View History

2016-05-27 16:32:59 +00:00
# Installing for Android development
2016-05-27 16:32:59 +00:00
![information] All versions starting from 2.3.1 Gingerbread are supported
2016-05-16 14:30:34 +00:00
## Prerequisites
2016-05-16 14:30:34 +00:00
The development machine is where you will develop your Android
application, which then you will deploy on the target machine, which
should obviously be an Android device.
The development machine can either be a Linux, Mac OS X or Windows, and
needs to have installed:
2016-05-27 16:32:59 +00:00
- The latest version of the [Android SDK]
- The latest version of the [Android NDK]
2016-06-17 22:21:42 +00:00
- GStreamer for Android is targeted at API version 9 (Android
2016-05-16 14:30:34 +00:00
2.3.1, Gingerbread) or higher. Use the SDK Manager tool to make sure
you have at least one Android SDK platform installed with API
version 9 or higher.
<!-- Optionally, you can use the [Android Studio](https://developer.android.com/studio/index.html). As stated in
2016-05-27 16:32:59 +00:00
the Android documentation, *developing in Android Studio is highly
recommended and is the fastest way to get started*. -->
2016-05-16 14:30:34 +00:00
Before continuing, make sure you can compile and run the samples
included in the Android NDK, and that you understand how the integration
2016-05-27 16:32:59 +00:00
of C and Java works via the [Java Native Interface] (JNI). Besides the
[Android NDK] documentation, you can find some useful [Android JNI tips
here].
2016-05-16 14:30:34 +00:00
2016-06-17 22:21:42 +00:00
## Download and install GStreamer binaries
2016-05-16 14:30:34 +00:00
2016-05-27 16:32:59 +00:00
The GStreamer project provides [prebuilt binaries] you should download
the latest version and unzip it into any folder of your choice.
2016-06-17 22:21:42 +00:00
In the process of building GStreamer-enabled Android applications,
some tools will need to know where you installed the GStreamer
binaries. You must define an environment variable called
`GSTREAMER_ROOT_ANDROID` and point it to the folder where you
extracted the GStreamer binaries. This environment variable must be available at
build time, so maybe you want to make it available system-wide by
adding it to your `~/.profile` file (on Linux and Mac) or to the
Environment Variables in the System Properties dialog (on Windows).
2016-05-16 14:30:34 +00:00
2016-06-17 22:21:42 +00:00
Point `GSTREAMER_ROOT_ANDROID` to the folder where you unzipped the binaries.
2016-05-16 14:30:34 +00:00
2016-05-27 16:32:59 +00:00
> ![information] If you plan to use Android Studio and do not want to define this
2016-09-15 19:45:01 +00:00
> environment variable globally, you can set it inside the build.gradle.
> ![information] If you plan to use Eclipse, and do not want to define this
2016-05-27 16:32:59 +00:00
> environment variable globally, you can set it inside Eclipse. Go to
> Window → Preferences → C/C++ → Build → Build Variables and define
2016-06-17 22:21:42 +00:00
> `GSTREAMER_ROOT_ANDROID` there.
2016-05-16 14:30:34 +00:00
2016-09-15 19:45:01 +00:00
> ![warning] The NDK support in the Gradle build system used by
> Android Studio is still in beta, so the recommended way to build
> using the GStreamer SDK is still to use "ndk-build".
## Configure your development environment
2016-05-16 14:30:34 +00:00
There are two routes to use GStreamer in an Android application: Either
writing your GStreamer code in Java or in C.
Android applications are mainly written in Java, so adding GStreamer
code to them in the same language is a huge advantage. However, this
2016-05-27 16:32:59 +00:00
requires using [language bindings] for the GStreamer API which are not
complete yet. In the meantime, this documentation will use Java for the
User Interface (UI) part and C for the GStreamer code. Both parts
interact through [JNI][Java Native Interface].
2016-05-16 14:30:34 +00:00
### Building the tutorials
There are a few Android-specific tutorials in the
2016-09-15 19:45:01 +00:00
`$GSTREAMER_ROOT_ANDROID/share/gst-sdk/tutorials` folder. Each
2016-05-16 14:30:34 +00:00
tutorial is a folder containing source code (in Java and C) and the
resource files required to build a complete Android application.
2016-06-17 22:21:42 +00:00
The rest of the GStreamer tutorials (basic and playback tutorials)
2016-05-16 14:30:34 +00:00
cannot be run on Android without modification.
Android projects with GStreamer support are built like conventional
2016-05-27 16:32:59 +00:00
Android NDK projects, so the instructions at the [Android NDK] home can
be followed:
2016-05-16 14:30:34 +00:00
<!--
2016-09-15 19:45:01 +00:00
#### Using Android Studio
> ![warning] To be completed!!
-->
2016-09-15 19:45:01 +00:00
#### Using Eclipse
2016-05-16 14:30:34 +00:00
Make sure you have installed the ADT and NDK plugins listed in the
prerequisites section, and that they are both aware of the location of
the Android SDK and NDK respectively.
Import a tutorial into the Eclipse workspace:
2016-05-27 16:32:59 +00:00
File  New  Project…  Android Project from Existing Code, and select
the folder called `android-tutorial-1`.
2016-05-16 14:30:34 +00:00
After reading in the project and generating some extra files and
folders, Eclipse might complain about missing files. **This is normal**,
2016-05-16 14:30:34 +00:00
we are not finished yet.
Provide native development support by activating the NDK plugin:
Right-click on the project in the Project Explorer (this should be the
2016-05-27 16:32:59 +00:00
top-most folder,
called `com.gst_sdk_tutorials.tutorial_1.Tutorial1`)  Android
2016-05-16 14:30:34 +00:00
tools  Add Native Support… Here the NDK plugin asks for a library name.
This is irrelevant and any valid file name will do. Accept.
Eclipse will still complain about errors in the code. **This is
normal**. Some files are missing because they are generated during the
first build run.
Build the project: Project  Build Project. If you bring up the Eclipse
Console, you should see some progress messages. Once finished, the
missing files will appear and all error messages should be gone. The
project is now ready to run. Hit Run  Run.
A new application called “Android tutorial 1” should now be available on
2016-06-17 22:21:42 +00:00
your device, with the GStreamer logo. If you want to run the
2016-05-16 14:30:34 +00:00
tutorial in an Android Virtual Device (AVD), make sure to create the
device with support for audio playback and GPU Emulation (to enable
OpenGL ES).
#### Using the command line
2016-05-16 14:30:34 +00:00
2016-05-27 16:32:59 +00:00
> ![warning] Note that, on Windows, this procedure requires a working Cygwin
> shell, as explained in the [Android NDK System Requirements]
2016-05-16 14:30:34 +00:00
For each tutorial, move to its folder and run:
2016-05-27 16:32:59 +00:00
android update project -p . -s --target X
2016-05-16 14:30:34 +00:00
Where `X` is one of the targets available in your system (the ones you
installed with the SDK manager). Make sure to use a target with at least
API level 9.
To get a list of all available targets in your system issue this
command:
2016-05-27 16:32:59 +00:00
android list
2016-05-16 14:30:34 +00:00
The “update project” command generates the `build.xml` file needed by
the build system. You only need to perform this action once per project.
To build the C part, just call:
2016-05-27 16:32:59 +00:00
ndk-build
2016-05-16 14:30:34 +00:00
A few lines in the `Android.mk` file (reviewed later) pull up the
necessary machinery to compile the GStreamer bits and generate the
Shared Object libraries (.so) that the Java code can use as native
methods.
Finally, compile the Java code with:
2016-05-27 16:32:59 +00:00
ant debug
2016-05-16 14:30:34 +00:00
And install on the device with:
2016-05-27 16:32:59 +00:00
adb install -r bin/Tutorial1-debug.apk
2016-05-16 14:30:34 +00:00
The `-r` switch allows the installer to overwrite previous versions.
Otherwise, you need to manually uninstall previous versions of your
application.
A new application called “Android tutorial 1” should now be available on
2016-06-17 22:21:42 +00:00
your device, with the GStreamer logo. If you want to run the
2016-05-16 14:30:34 +00:00
tutorial in an Android Virtual Device (AVD), make sure to create the
device with support for audio playback and GPU Emulation (to enable
OpenGL ES).
2016-05-27 16:32:59 +00:00
> ![warning] Windows linkage problems
>
2016-05-27 16:32:59 +00:00
> Due to problems related to the standard linker, Googles
> <a href="http://en.wikipedia.org/wiki/Gold_(linker)" class="external-link">Gold
> Linker</a> is used to build GStreamer applications.  Unfortunately,
> the Android NDK toolchain for Windows does not include the gold linker
> and the standard one has to be used.
>
2016-05-27 16:32:59 +00:00
> If you observe linkage problems, you can replace the linker in your
> Android NDK with the gold one from [this project]. Download the
> `android-ndk-r8b-ma-windows.7z` file, extract
> `\android-ndk-r8b\toolchains\arm-linux-androideabi-4.6\prebuilt\windows\arm-linux-androideabi\bin\ld.exe`
> (only this file is needed) and overwrite the one in the same folder in
> your Android NDK installation. You might need the free [7-Zip
> archiving utility]
2016-05-16 14:30:34 +00:00
### Creating new projects
Create a normal NDK project, either from the command line as described
2016-05-27 16:32:59 +00:00
in the [Android NDK][2] home, or use Eclipse: File → New → Project…
 Android Application Project, and, once the wizard is complete, right
click on the project → Android Tools → Add Native Support …
2016-05-16 14:30:34 +00:00
To add GStreamer support you only need to modify the
`jni/Android.mk` file. This file describes the native files in your
project, and its barebones structure (as auto-generated by Eclipse) is:
**Android.mk**
2016-05-27 16:32:59 +00:00
LOCAL_PATH := $(call my-dir)
2016-05-16 14:30:34 +00:00
2016-05-27 16:32:59 +00:00
include $(CLEAR_VARS)
2016-05-16 14:30:34 +00:00
2016-05-27 16:32:59 +00:00
LOCAL_MODULE := NativeApplication
LOCAL_SRC_FILES := NativeApplication.c
2016-05-16 14:30:34 +00:00
2016-05-27 16:32:59 +00:00
include $(BUILD_SHARED_LIBRARY)
2016-05-16 14:30:34 +00:00
Where line 5 specifies the name of the `.so` file that will contain your
native code and line 6 states all source files that compose your native
code, separated by spaces.
Adding GStreamer support only requires adding these lines:
**Android.mk with GStreamer support**
2016-05-27 16:32:59 +00:00
LOCAL_PATH := $(call my-dir)
2016-05-16 14:30:34 +00:00
2016-05-27 16:32:59 +00:00
include $(CLEAR_VARS)
2016-05-16 14:30:34 +00:00
2016-05-27 16:32:59 +00:00
LOCAL_MODULE := NativeApplication
LOCAL_SRC_FILES := NativeApplication.c
LOCAL_SHARED_LIBRARIES := gstreamer_android
LOCAL_LDLIBS := -landroid
2016-05-16 14:30:34 +00:00
2016-05-27 16:32:59 +00:00
include $(BUILD_SHARED_LIBRARY)
2016-05-16 14:30:34 +00:00
ifndef GSTREAMER_ROOT
ifndef GSTREAMER_ROOT_ANDROID
$(error GSTREAMER_ROOT_ANDROID is not defined!)
endif
GSTREAMER_ROOT := $(GSTREAMER_ROOT_ANDROID)
endif
2016-06-17 22:21:42 +00:00
GSTREAMER_NDK_BUILD_PATH := $(GSTREAMER_ROOT)/share/gst-android/ndk-build/
GSTREAMER_PLUGINS := coreelements ogg theora vorbis videoconvert audioconvert audioresample playback glimagesink soup opensles
2016-05-27 16:32:59 +00:00
G_IO_MODULES := gnutls
GSTREAMER_EXTRA_DEPS := gstreamer-video-1.0
2016-05-16 14:30:34 +00:00
include $(GSTREAMER_NDK_BUILD_PATH)/gstreamer.mk
2016-05-16 14:30:34 +00:00
Where line 7 specifies an extra library to be included in the project:
`libgstreamer_android.so`. This library contains all GStreamer code,
tailored for your applications needs, as shown below.
Line 8 specifies additional system libraries, in this case, in order to
access android-specific functionality.
Lines 12 and 13 simply define some convenient macros.
Line 20 lists the plugins you want statically linked into
2016-05-16 14:30:34 +00:00
`libgstreamer_android.so`. Listing only the ones you need makes your
application smaller.
Line 21 is required to have HTTPS/TLS support from GStreamer, through the
2016-05-16 14:30:34 +00:00
`souphttpsrc` element.
Line 22 defines which GStreamer libraries your application requires.
2016-05-16 14:30:34 +00:00
Finally, line 24 includes the make files which perform the rest of the
2016-05-16 14:30:34 +00:00
magic.
Listing all desired plugins can be cumbersome, so they have been grouped
into categories, which can be used by including the `plugins.mk` file,
and used as follows:
2016-05-27 16:32:59 +00:00
include $(GSTREAMER_NDK_BUILD_PATH)/plugins.mk
GSTREAMER_PLUGINS := $(GSTREAMER_PLUGINS_CORE) $(GSTREAMER_PLUGINS_CODECS) playbin souphttpsrc
#### List of categories and included plugins
2016-05-16 14:30:34 +00:00
2016-05-27 16:32:59 +00:00
| Category | Included plugins |
|--------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `GSTREAMER_PLUGINS_CORE` | coreelements coreindexers adder app audioconvert audiorate audioresample audiotestsrc videoconvert gdp gio pango typefindfunctions videorate videoscale videotestsrc volume autodetect videofilter |
2016-05-27 16:32:59 +00:00
| `GSTREAMER_PLUGINS_PLAYBACK` | decodebin playbin |
| `GSTREAMER_PLUGINS_CODECS` | subparse ogg theora vorbis alaw annodex apetag audioparsers auparse avi flac flv flxdec icydemux id3demux isomp4 jpeg matroska mulaw multipart png speex taglib wavenc wavpack wavparse y4menc adpcmdec adpcmenc aiff cdxaparse dtmf dvbsuboverlay dvdspu fragmented hdvparse id3tag ivfparse jp2k kate mve mxf nsf nuvdemux opus pcapparse pnm schro siren subenc tta videoparsersbad vmnc vp8 y4mdec |
| `GSTREAMER_PLUGINS_VIS` | libvisual goom goom2k1 audiovisualizers |
| `GSTREAMER_PLUGINS_EFFECTS` | alpha alphacolor audiofx cutter debug deinterlace effectv equalizer gdkpixbuf imagefreeze interleave level multifile replaygain shapewipe smpte spectrum videobox videocrop videomixer autoconvert bayer coloreffects faceoverlay fieldanalysis freeverb frei0r gaudieffects geometrictransform interlace jp2kdecimator liveadder rawparse removesilence scaletempoplugin segmentclip smooth speed stereo videofiltersbad videomeasure videosignal |
| `GSTREAMER_PLUGINS_NET` | rtsp rtp rtpmanager souphttpsrc udp dataurisrc rtpmux rtpvp8 sdpelem |
| `GSTREAMER_PLUGINS_CODECS_GPL` | assrender |
| `GSTREAMER_PLUGINS_SYS` | glimagesink opensles amc |
2016-05-16 14:30:34 +00:00
2016-06-05 21:32:50 +00:00
Build and run your application as explained in the [Building the tutorial](sdk-installing-for-android-development.md#building-the-tutorials) section.
2016-05-27 16:32:59 +00:00
[information]: images/icons/emoticons/information.png
[Android SDK]: http://developer.android.com/sdk/index.html
[Android NDK]: http://developer.android.com/tools/sdk/ndk/index.html
[Java Native Interface]: http://en.wikipedia.org/wiki/Java_Native_Interface
[Android JNI tips here]: http://developer.android.com/guide/practices/jni.html
[prebuilt binaries]: https://gstreamer.freedesktop.org/data/pkg/android/
[language bindings]: http://en.wikipedia.org/wiki/Language_binding
[warning]: images/icons/emoticons/warning.png
[Android NDK System Requirements]: http://developer.android.com/tools/sdk/ndk/index.html#Reqs
[this project]: http://code.google.com/p/mingw-and-ndk/downloads/detail?name=android-ndk-r8b-ma-windows.7z&can=2&q=
[7-Zip archiving utility]: http://www.7-zip.org/
[2]: http://developer.android.com/tools/sdk/ndk/index.html#GetStarted