Prerequisites
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:
- The latest version of the Android SDK
- The latest version of the Android NDK
- The GStreamer SDK for Android is targeted at API version 9 (Android 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 Eclipse IDE. As stated in the Android documentation, developing in Eclipse with ADT is highly recommended and is the fastest way to get started. If you plan to use the Eclipse IDE:
- Install the Android ADT plugin for Eclipse
- Install the Android NDK plugin for Eclipse
Before continuing, make sure you can compile and run the samples included in the Android NDK, and that you understand how the integration 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.
Download and install the SDK
The SDK has two variants: Debug and Release. The Debug variant produces lots of debug output and is useful while developing your application. The Release variant is what you will use to produce the final version of your application, since GStreamer code runs slightly faster and the libraries are smaller.
Get the compressed file below and just unzip it into any folder of your choice (Choose your preferred file format; both files have exactly the same content)
| Debug variant |
|---|
| Release variant |
 | Due to the size of these files, usage of a Download Manager is highly recommended. Take a look at this list if you do not have one installed. If, after downloading, the installer reports itself as corrupt, chances are that the connection ended before the file was complete. A Download Manager will typically re-start the process and fetch the missing parts. |
If you intend to build the tutorials in this same folder, make sure you have writing permissions.
In the process of building GStreamer-enabled Android applications, some tools will need to know where you installed the SDK. You must define an environment variable called GSTREAMER_SDK_ROOT_ANDROID and point it to the folder where you extracted the SDK. 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).
- Point
GSTREAMER_SDK_ROOT_ANDROIDto the folder where you unzipped the SDK.
 | If you plan to use Eclipse and do not want to define this environment variable globally, you can set it inside Eclipse. Go to Window → Preferences → C/C++ → Build → Build Variables and define |
Configure your development environment
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 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.
Building the tutorials
There are a few Android-specific tutorials in the $GSTREAMER_SDK_ROOT_ANDROID\share\gst-sdk\tutorials folder. Each tutorial is a folder containing source code (in Java and C) and the resource files required to build a complete Android application.
The rest of the GStreamer SDK tutorials (basic and playback tutorials) cannot be run on Android without modification.
Android projects with GStreamer support are built like conventional Android NDK projects, so the instructions at the Android NDK home can be followed:
| Note that, on Windows, this procedure requires a working Cygwin shell, as explained in the Android NDK System Requirements. |
For each tutorial, move to its folder and run:
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:
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:
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:
And install on the device with:
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 your device, with the GStreamer SDK logo. If you want to run the 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).
| Windows linkage problems Due to problems related to the standard linker, Google’s Gold Linker 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. If you observe linkage problems, you can replace the linker in your Android NDK with the gold one from this project. Download the |
Creating new projects
Create a normal NDK project, either from the command line as described in the Android NDK 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 …
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:
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:
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 application’s 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 14 lists the plugins you want statically linked into libgstreamer_android.so. Listing only the ones you need makes your application smaller.
Line 15 is required to have internet access from GStreamer, through the souphttpsrc element.
Line 16 defines which GStreamer libraries your application requires.
Finally, line 18 includes the make files which perform the rest of the 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:
Build and run your application as explained in the Building the tutorials section.