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 correct version of the [Android NDK] corresponding to the version of
16 [GStreamer binaries] you're using (f.ex., r18b for 1.16.x)
17 - GStreamer for Android is targeted at API version 9 (Android
18 2.3.1, Gingerbread) or higher. Use the SDK Manager tool to make sure
19 you have at least one Android SDK platform installed with API
22 <!-- Optionally, you can use the [Android Studio](https://developer.android.com/studio/index.html). As stated in
23 the Android documentation, *developing in Android Studio is highly
24 recommended and is the fastest way to get started*. -->
26 Before continuing, make sure you can compile and run the samples
27 included in the Android NDK, and that you understand how the integration
28 of C and Java works via the [Java Native Interface] (JNI). Besides the
29 [Android NDK] documentation, you can find some useful [Android JNI tips
32 ## Download and install GStreamer binaries
34 The GStreamer project provides [prebuilt binaries] you should download
35 the latest version and unzip it into any folder of your choice.
37 In the process of building GStreamer-enabled Android applications,
38 some tools will need to know where you installed the GStreamer
39 binaries. You must define an environment variable called
40 `GSTREAMER_ROOT_ANDROID` and point it to the folder where you
41 extracted the GStreamer binaries. This environment variable must be available at
42 build time, so maybe you want to make it available system-wide by
43 adding it to your `~/.profile` file (on Linux and Mac) or to the
44 Environment Variables in the System Properties dialog (on Windows).
46 Point `GSTREAMER_ROOT_ANDROID` to the folder where you unzipped the binaries.
48 > ![information] If you plan to use Android Studio and do not want to define this
49 > environment variable globally, you can set it inside the build.gradle.
51 > ![information] If you plan to use Eclipse, and do not want to define this
52 > environment variable globally, you can set it inside Eclipse. Go to
53 > Window → Preferences → C/C++ → Build → Build Variables and define
54 > `GSTREAMER_ROOT_ANDROID` there.
56 > ![warning] The NDK support in the Gradle build system used by
57 > Android Studio is still in beta, so the recommended way to build
58 > using the GStreamer SDK is still to use "ndk-build".
60 ## Configure your development environment
62 There are two routes to use GStreamer in an Android application: Either
63 writing your GStreamer code in Java or in C.
65 Android applications are mainly written in Java, so adding GStreamer
66 code to them in the same language is a huge advantage. However, this
67 requires using [language bindings] for the GStreamer API which are not
68 complete yet. In the meantime, this documentation will use Java for the
69 User Interface (UI) part and C for the GStreamer code. Both parts
70 interact through [JNI][Java Native Interface].
72 ### Building the tutorials
74 The tutorials code are in the
75 [gst-docs](https://gitlab.freedesktop.org/gstreamer/gst-docs/) in the
76 `examples/tutorials/` folder.
78 There are a few Android-specific tutorials in the `tutorials/`
79 folder. Each tutorial is a folder containing source code (in Java and
80 C) and the resource files required to build a complete Android
83 The rest of the GStreamer tutorials (basic and playback tutorials)
84 cannot be run on Android without modification.
86 Android projects with GStreamer support are built like conventional
87 Android NDK projects, so the instructions at the [Android NDK] home can
91 #### Using Android Studio
93 > ![warning] To be completed!!
98 Make sure you have installed the ADT and NDK plugins listed in the
99 prerequisites section, and that they are both aware of the location of
100 the Android SDK and NDK respectively.
102 Import a tutorial into the Eclipse workspace:
103 File → New → Project… → Android Project from Existing Code, and select
104 the folder called `android-tutorial-1`.
106 After reading in the project and generating some extra files and
107 folders, Eclipse might complain about missing files. **This is normal**,
108 we are not finished yet.
110 Provide native development support by activating the NDK plugin:
111 Right-click on the project in the Project Explorer (this should be the
113 called `com.gst_sdk_tutorials.tutorial_1.Tutorial1`) → Android
114 tools → Add Native Support… Here the NDK plugin asks for a library name.
115 This is irrelevant and any valid file name will do. Accept.
117 Eclipse will still complain about errors in the code. **This is
118 normal**. Some files are missing because they are generated during the
121 Build the project: Project → Build Project. If you bring up the Eclipse
122 Console, you should see some progress messages. Once finished, the
123 missing files will appear and all error messages should be gone. The
124 project is now ready to run. Hit Run → Run.
126 A new application called “Android tutorial 1” should now be available on
127 your device, with the GStreamer logo. If you want to run the
128 tutorial in an Android Virtual Device (AVD), make sure to create the
129 device with support for audio playback and GPU Emulation (to enable
132 #### Using the command line
134 > ![warning] Note that, on Windows, this procedure requires a working Cygwin
135 > shell, as explained in the [Android NDK System Requirements]
137 For each tutorial, move to its folder and run:
139 android update project -p . -s --target X
141 Where `X` is one of the targets available in your system (the ones you
142 installed with the SDK manager). Make sure to use a target with at least
145 To get a list of all available targets in your system issue this
150 The “update project” command generates the `build.xml` file needed by
151 the build system. You only need to perform this action once per project.
153 To build the C part, just call:
157 A few lines in the `Android.mk` file (reviewed later) pull up the
158 necessary machinery to compile the GStreamer bits and generate the
159 Shared Object libraries (.so) that the Java code can use as native
162 Finally, compile the Java code with:
166 And install on the device with:
168 adb install -r bin/Tutorial1-debug.apk
170 The `-r` switch allows the installer to overwrite previous versions.
171 Otherwise, you need to manually uninstall previous versions of your
174 A new application called “Android tutorial 1” should now be available on
175 your device, with the GStreamer logo. If you want to run the
176 tutorial in an Android Virtual Device (AVD), make sure to create the
177 device with support for audio playback and GPU Emulation (to enable
180 > ![warning] Windows linkage problems
182 > Due to problems related to the standard linker, Google’s
183 > <a href="http://en.wikipedia.org/wiki/Gold_(linker)" class="external-link">Gold
184 > Linker</a> is used to build GStreamer applications. Unfortunately,
185 > the Android NDK toolchain for Windows does not include the gold linker
186 > and the standard one has to be used.
188 > If you observe linkage problems, you can replace the linker in your
189 > Android NDK with the gold one from [this project]. Download the
190 > `android-ndk-r8b-ma-windows.7z` file, extract
191 > `\android-ndk-r8b\toolchains\arm-linux-androideabi-4.6\prebuilt\windows\arm-linux-androideabi\bin\ld.exe`
192 > (only this file is needed) and overwrite the one in the same folder in
193 > your Android NDK installation. You might need the free [7-Zip
196 #### Using gradle from the command-line
198 Edit examples/tutorials/android/gradle.properties in order to set gstAndroidRoot to point to the
199 unpacked GStreamer Android binaries.
201 Then, to build and deploy the tutorials to your device, use a command similar to:
204 $ cd examples/tutorials/android
205 $ PATH=~/dev/android/tools/bin:~/dev/android/ndk-bundle:$PATH ANDROID_HOME="$HOME/dev/android/" ./gradlew installDebug
208 To build and deploy a single tutorial:
211 $ cd examples/tutorials/android
212 $ GSTREAMER_ROOT_ANDROID=/path/to/gst-android-1.14/ PATH=~/dev/android/tools/bin:~/dev/android/ndk-bundle:$PATH ANDROID_HOME="$HOME/dev/android/" ./gradlew :android-tutorial-1:installDebug
215 To run the application, you can either directly launch it from the device,
216 or from the command line:
219 $ adb shell am start -n adb shell am start -n org.freedesktop.gstreamer.tutorials.tutorial_1/.Tutorial1
222 To see the GStreamer logs at runtime:
225 $ adb logcat | egrep '(gst)'
228 #### Using Android-studio
230 Edit examples/tutorials/android/gradle.properties in order to set gstAndroidRoot to point to the
231 unpacked GStreamer Android binaries.
233 Launch Android-studio, opening examples/tutorials/android/ as a project.
235 The project should build automatically, once it has done successfully,
236 it should be possible to run the tutorials with Run > Run 'tutorial X', provided
237 a device is attached and USB debugging enabled.
239 The logs can be seen in the logcat tab.
241 ### Creating new projects
243 Create a normal NDK project, either from the command line as described
244 in the [Android NDK][2] home, or use Eclipse: File → New → Project…
245 → Android Application Project, and, once the wizard is complete, right
246 click on the project → Android Tools → Add Native Support …
248 To add GStreamer support you only need to modify the
249 `jni/Android.mk` file. This file describes the native files in your
250 project, and its barebones structure (as auto-generated by Eclipse) is:
254 LOCAL_PATH := $(call my-dir)
256 include $(CLEAR_VARS)
258 LOCAL_MODULE := NativeApplication
259 LOCAL_SRC_FILES := NativeApplication.c
261 include $(BUILD_SHARED_LIBRARY)
263 Where line 5 specifies the name of the `.so` file that will contain your
264 native code and line 6 states all source files that compose your native
265 code, separated by spaces.
267 Adding GStreamer support only requires adding these lines:
269 **Android.mk with GStreamer support**
271 LOCAL_PATH := $(call my-dir)
273 include $(CLEAR_VARS)
275 LOCAL_MODULE := NativeApplication
276 LOCAL_SRC_FILES := NativeApplication.c
277 LOCAL_SHARED_LIBRARIES := gstreamer_android
278 LOCAL_LDLIBS := -landroid
280 include $(BUILD_SHARED_LIBRARY)
282 ifndef GSTREAMER_ROOT
283 ifndef GSTREAMER_ROOT_ANDROID
284 $(error GSTREAMER_ROOT_ANDROID is not defined!)
286 GSTREAMER_ROOT := $(GSTREAMER_ROOT_ANDROID)
289 GSTREAMER_NDK_BUILD_PATH := $(GSTREAMER_ROOT)/share/gst-android/ndk-build/
290 GSTREAMER_PLUGINS := coreelements ogg theora vorbis videoconvert audioconvert audioresample playback glimagesink soup opensles
291 G_IO_MODULES := gnutls
292 GSTREAMER_EXTRA_DEPS := gstreamer-video-1.0
294 include $(GSTREAMER_NDK_BUILD_PATH)/gstreamer.mk
296 Where line 7 specifies an extra library to be included in the project:
297 `libgstreamer_android.so`. This library contains all GStreamer code,
298 tailored for your application’s needs, as shown below.
300 Line 8 specifies additional system libraries, in this case, in order to
301 access android-specific functionality.
303 Lines 12 and 13 simply define some convenient macros.
305 Line 20 lists the plugins you want statically linked into
306 `libgstreamer_android.so`. Listing only the ones you need makes your
309 Line 21 is required to have HTTPS/TLS support from GStreamer, through the
310 `souphttpsrc` element.
312 Line 22 defines which GStreamer libraries your application requires.
314 Finally, line 24 includes the make files which perform the rest of the
317 Listing all desired plugins can be cumbersome, so they have been grouped
318 into categories, which can be used by including the `plugins.mk` file,
321 include $(GSTREAMER_NDK_BUILD_PATH)/plugins.mk
322 GSTREAMER_PLUGINS := $(GSTREAMER_PLUGINS_CORE) $(GSTREAMER_PLUGINS_CODECS) playbin souphttpsrc
324 #### List of categories and included plugins
326 | Category | Included plugins |
327 |--------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
328 | `GSTREAMER_PLUGINS_CORE` | coreelements adder app audioconvert audiorate audioresample audiotestsrc gio pango typefindfunctions videoconvert videorate videoscale videotestsrc volume autodetect videofilter |
329 | `GSTREAMER_PLUGINS_PLAYBACK` | playback |
330 | `GSTREAMER_PLUGINS_VIS` | libvisual goom goom2k1 audiovisualizers |
331 | `GSTREAMER_PLUGINS_EFFECTS` | alpha alphacolor audiofx cairo cutter debug deinterlace dtmf effectv equalizer gdkpixbuf imagefreeze interleave level multifile replaygain shapewipe smpte spectrum videobox videocrop videomixer accurip aiff audiofxbad autoconvert bayer coloreffects debugutilsbad fieldanalysis freeverb frei0r gaudieffects geometrictransform inter interlace ivtc rawparse removesilence segmentclip smooth speed soundtouch videofiltersbad audiomixer compositor webrtcdsp |
332 | `GSTREAMER_PLUGINS_NET` | tcp rtsp rtp rtpmanager soup udp dataurisrc sdp srtp rtspclientsink |
333 | `GSTREAMER_PLUGINS_NET_RESTRICTED` | mms rtmp |
334 | `GSTREAMER_PLUGINS_CODECS` | subparse ogg theora vorbis opus ivorbisdec alaw apetag audioparsers auparse avi dv flac flv flxdec icydemux id3demux isomp4 jpeg matroska mulaw multipart png speex taglib vpx wavenc wavpack wavparse y4menc adpcmdec adpcmenc dashdemux dvbsuboverlay dvdspu hls id3tag kate midi mxf openh264 opusparse pcapparse pnm rfbsrc schro gstsiren smoothstreaming subenc videoparsersbad y4mdec jpegformat gdp rsvg openjpeg spandsp sbc androidmedia |
335 | `GSTREAMER_PLUGINS_CODECS_GPL` | assrender |
336 | `GSTREAMER_PLUGINS_CODECS_RESTRICTED` | asfmux dtsdec faad mpegpsdemux mpegpsmux mpegtsdemux mpegtsmux voaacenc a52dec amrnb amrwbdec asf dvdsub dvdlpcmdec mad mpeg2dec xingmux realmedia x264 lame mpg123 libav |
337 | `GSTREAMER_PLUGINS_SYS` | opensles opengl |
338 | `GSTREAMER_PLUGINS_CAPTURE` | camerabin |
339 | `GSTREAMER_PLUGINS_ENCODING` | encodebin |
340 | `GSTREAMER_PLUGINS_GES` | nle |
342 Build and run your application as explained in the [Building the tutorials] section.
344 [information]: images/icons/emoticons/information.svg
345 [Android SDK]: http://developer.android.com/sdk/index.html
346 [Android NDK]: http://developer.android.com/tools/sdk/ndk/index.html
347 [GStreamer binaries]: https://gstreamer.freedesktop.org/download/#android
348 [Java Native Interface]: http://en.wikipedia.org/wiki/Java_Native_Interface
349 [Android JNI tips here]: http://developer.android.com/guide/practices/jni.html
350 [prebuilt binaries]: https://gstreamer.freedesktop.org/data/pkg/android/
351 [language bindings]: http://en.wikipedia.org/wiki/Language_binding
352 [warning]: images/icons/emoticons/warning.svg
353 [Android NDK System Requirements]: http://developer.android.com/tools/sdk/ndk/index.html#Reqs
354 [this project]: http://code.google.com/p/mingw-and-ndk/downloads/detail?name=android-ndk-r8b-ma-windows.7z&can=2&q=
355 [7-Zip archiving utility]: http://www.7-zip.org/
356 [2]: http://developer.android.com/tools/sdk/ndk/index.html#GetStarted