1 # Installing for Android development
3 ![information] All versions starting from 2.3.1 Gingerbread are supported
7 The development machine is where you will develop your Android
8 application, which then you will deploy on the target machine, which
9 should obviously be an Android device.
11 The development machine can either be a Linux, Mac OS X or Windows, and
12 needs to have installed:
14 - The latest version of the [Android SDK]
15 - The latest version of the [Android NDK]
16 - GStreamer for Android is targeted at API version 9 (Android
17 2.3.1, Gingerbread) or higher. Use the SDK Manager tool to make sure
18 you have at least one Android SDK platform installed with API
21 Optionally, you can use the [Android Studio] (https://developer.android.com/studio/index.html). As stated in
22 the Android documentation, *developing in Android Studio is highly
23 recommended and is the fastest way to get started*.
25 Before continuing, make sure you can compile and run the samples
26 included in the Android NDK, and that you understand how the integration
27 of C and Java works via the [Java Native Interface] (JNI). Besides the
28 [Android NDK] documentation, you can find some useful [Android JNI tips
31 ## Download and install GStreamer binaries
33 The GStreamer project provides [prebuilt binaries] you should download
34 the latest version and unzip it into any folder of your choice.
36 In the process of building GStreamer-enabled Android applications,
37 some tools will need to know where you installed the GStreamer
38 binaries. You must define an environment variable called
39 `GSTREAMER_ROOT_ANDROID` and point it to the folder where you
40 extracted the GStreamer binaries. This environment variable must be available at
41 build time, so maybe you want to make it available system-wide by
42 adding it to your `~/.profile` file (on Linux and Mac) or to the
43 Environment Variables in the System Properties dialog (on Windows).
45 Point `GSTREAMER_ROOT_ANDROID` to the folder where you unzipped the binaries.
47 > ![information] If you plan to use Android Studio and do not want to define this
48 > environment variable globally, you can set it inside Eclipse. Go to
49 > Window → Preferences → C/C++ → Build → Build Variables and define
50 > `GSTREAMER_ROOT_ANDROID` there.
52 ## Configure your development environment
54 There are two routes to use GStreamer in an Android application: Either
55 writing your GStreamer code in Java or in C.
57 Android applications are mainly written in Java, so adding GStreamer
58 code to them in the same language is a huge advantage. However, this
59 requires using [language bindings] for the GStreamer API which are not
60 complete yet. In the meantime, this documentation will use Java for the
61 User Interface (UI) part and C for the GStreamer code. Both parts
62 interact through [JNI][Java Native Interface].
64 ### Building the tutorials
66 There are a few Android-specific tutorials in the
67 `$GSTREAMER_ROOT_ANDROID\share\gst-sdk\tutorials` folder. Each
68 tutorial is a folder containing source code (in Java and C) and the
69 resource files required to build a complete Android application.
71 The rest of the GStreamer tutorials (basic and playback tutorials)
72 cannot be run on Android without modification.
74 Android projects with GStreamer support are built like conventional
75 Android NDK projects, so the instructions at the [Android NDK] home can
80 Make sure you have installed the ADT and NDK plugins listed in the
81 prerequisites section, and that they are both aware of the location of
82 the Android SDK and NDK respectively.
84 Import a tutorial into the Eclipse workspace:
85 File → New → Project… → Android Project from Existing Code, and select
86 the folder called `android-tutorial-1`.
88 After reading in the project and generating some extra files and
89 folders, Eclipse might complain about missing files. **This is normal**,
90 we are not finished yet.
92 Provide native development support by activating the NDK plugin:
93 Right-click on the project in the Project Explorer (this should be the
95 called `com.gst_sdk_tutorials.tutorial_1.Tutorial1`) → Android
96 tools → Add Native Support… Here the NDK plugin asks for a library name.
97 This is irrelevant and any valid file name will do. Accept.
99 Eclipse will still complain about errors in the code. **This is
100 normal**. Some files are missing because they are generated during the
103 Build the project: Project → Build Project. If you bring up the Eclipse
104 Console, you should see some progress messages. Once finished, the
105 missing files will appear and all error messages should be gone. The
106 project is now ready to run. Hit Run → Run.
108 A new application called “Android tutorial 1” should now be available on
109 your device, with the GStreamer logo. If you want to run the
110 tutorial in an Android Virtual Device (AVD), make sure to create the
111 device with support for audio playback and GPU Emulation (to enable
114 #### Using the command line
116 > ![warning] Note that, on Windows, this procedure requires a working Cygwin
117 > shell, as explained in the [Android NDK System Requirements]
119 For each tutorial, move to its folder and run:
121 android update project -p . -s --target X
123 Where `X` is one of the targets available in your system (the ones you
124 installed with the SDK manager). Make sure to use a target with at least
127 To get a list of all available targets in your system issue this
132 The “update project” command generates the `build.xml` file needed by
133 the build system. You only need to perform this action once per project.
135 To build the C part, just call:
139 A few lines in the `Android.mk` file (reviewed later) pull up the
140 necessary machinery to compile the GStreamer bits and generate the
141 Shared Object libraries (.so) that the Java code can use as native
144 Finally, compile the Java code with:
148 And install on the device with:
150 adb install -r bin/Tutorial1-debug.apk
152 The `-r` switch allows the installer to overwrite previous versions.
153 Otherwise, you need to manually uninstall previous versions of your
156 A new application called “Android tutorial 1” should now be available on
157 your device, with the GStreamer logo. If you want to run the
158 tutorial in an Android Virtual Device (AVD), make sure to create the
159 device with support for audio playback and GPU Emulation (to enable
162 > ![warning] Windows linkage problems
164 > Due to problems related to the standard linker, Google’s
165 > <a href="http://en.wikipedia.org/wiki/Gold_(linker)" class="external-link">Gold
166 > Linker</a> is used to build GStreamer applications. Unfortunately,
167 > the Android NDK toolchain for Windows does not include the gold linker
168 > and the standard one has to be used.
170 > If you observe linkage problems, you can replace the linker in your
171 > Android NDK with the gold one from [this project]. Download the
172 > `android-ndk-r8b-ma-windows.7z` file, extract
173 > `\android-ndk-r8b\toolchains\arm-linux-androideabi-4.6\prebuilt\windows\arm-linux-androideabi\bin\ld.exe`
174 > (only this file is needed) and overwrite the one in the same folder in
175 > your Android NDK installation. You might need the free [7-Zip
178 ### Creating new projects
180 Create a normal NDK project, either from the command line as described
181 in the [Android NDK][2] home, or use Eclipse: File → New → Project…
182 → Android Application Project, and, once the wizard is complete, right
183 click on the project → Android Tools → Add Native Support …
185 To add GStreamer support you only need to modify the
186 `jni/Android.mk` file. This file describes the native files in your
187 project, and its barebones structure (as auto-generated by Eclipse) is:
191 LOCAL_PATH := $(call my-dir)
193 include $(CLEAR_VARS)
195 LOCAL_MODULE := NativeApplication
196 LOCAL_SRC_FILES := NativeApplication.c
198 include $(BUILD_SHARED_LIBRARY)
200 Where line 5 specifies the name of the `.so` file that will contain your
201 native code and line 6 states all source files that compose your native
202 code, separated by spaces.
204 Adding GStreamer support only requires adding these lines:
206 **Android.mk with GStreamer support**
208 LOCAL_PATH := $(call my-dir)
210 include $(CLEAR_VARS)
212 LOCAL_MODULE := NativeApplication
213 LOCAL_SRC_FILES := NativeApplication.c
214 LOCAL_SHARED_LIBRARIES := gstreamer_android
215 LOCAL_LDLIBS := -landroid
217 include $(BUILD_SHARED_LIBRARY)
219 ifndef GSTREAMER_ROOT
220 ifndef GSTREAMER_ROOT_ANDROID
221 $(error GSTREAMER_ROOT_ANDROID is not defined!)
223 GSTREAMER_ROOT := $(GSTREAMER_ROOT_ANDROID)
226 GSTREAMER_NDK_BUILD_PATH := $(GSTREAMER_ROOT)/share/gst-android/ndk-build/
227 GSTREAMER_PLUGINS := coreelements ogg theora vorbis videoconvert audioconvert audioresample playback glimagesink soup opensles
228 G_IO_MODULES := gnutls
229 GSTREAMER_EXTRA_DEPS := gstreamer-video-1.0
231 include $(GSTREAMER_NDK_BUILD_PATH)/gstreamer.mk
233 Where line 7 specifies an extra library to be included in the project:
234 `libgstreamer_android.so`. This library contains all GStreamer code,
235 tailored for your application’s needs, as shown below.
237 Line 8 specifies additional system libraries, in this case, in order to
238 access android-specific functionality.
240 Lines 12 and 13 simply define some convenient macros.
242 Line 20 lists the plugins you want statically linked into
243 `libgstreamer_android.so`. Listing only the ones you need makes your
246 Line 21 is required to have HTTPS/TLS support from GStreamer, through the
247 `souphttpsrc` element.
249 Line 22 defines which GStreamer libraries your application requires.
251 Finally, line 24 includes the make files which perform the rest of the
254 Listing all desired plugins can be cumbersome, so they have been grouped
255 into categories, which can be used by including the `plugins.mk` file,
258 include $(GSTREAMER_NDK_BUILD_PATH)/plugins.mk
259 GSTREAMER_PLUGINS := $(GSTREAMER_PLUGINS_CORE) $(GSTREAMER_PLUGINS_CODECS) playbin souphttpsrc
261 #### List of categories and included plugins
263 | Category | Included plugins |
264 |--------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
265 | `GSTREAMER_PLUGINS_CORE` | coreelements coreindexers adder app audioconvert audiorate audioresample audiotestsrc ffmpegcolorspace gdp gio pango typefindfunctions videorate videoscale videotestsrc volume autodetect videofilter |
266 | `GSTREAMER_PLUGINS_PLAYBACK` | decodebin playbin |
267 | `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 |
268 | `GSTREAMER_PLUGINS_VIS` | libvisual goom goom2k1 audiovisualizers |
269 | `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 |
270 | `GSTREAMER_PLUGINS_NET` | rtsp rtp rtpmanager souphttpsrc udp dataurisrc rtpmux rtpvp8 sdpelem |
271 | `GSTREAMER_PLUGINS_CODECS_GPL` | assrender |
272 | `GSTREAMER_PLUGINS_SYS` | glimagesink opensles amc |
274 Build and run your application as explained in the [Building the tutorial](sdk-installing-for-android-development.md#building-the-tutorials) section.
276 [information]: images/icons/emoticons/information.png
277 [Android SDK]: http://developer.android.com/sdk/index.html
278 [Android NDK]: http://developer.android.com/tools/sdk/ndk/index.html
279 [Java Native Interface]: http://en.wikipedia.org/wiki/Java_Native_Interface
280 [Android JNI tips here]: http://developer.android.com/guide/practices/jni.html
281 [prebuilt binaries]: https://gstreamer.freedesktop.org/data/pkg/android/
282 [language bindings]: http://en.wikipedia.org/wiki/Language_binding
283 [warning]: images/icons/emoticons/warning.png
284 [Android NDK System Requirements]: http://developer.android.com/tools/sdk/ndk/index.html#Reqs
285 [this project]: http://code.google.com/p/mingw-and-ndk/downloads/detail?name=android-ndk-r8b-ma-windows.7z&can=2&q=
286 [7-Zip archiving utility]: http://www.7-zip.org/
287 [2]: http://developer.android.com/tools/sdk/ndk/index.html#GetStarted