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 the build.gradle.
50 > ![information] If you plan to use Eclipse, and do not want to define this
51 > environment variable globally, you can set it inside Eclipse. Go to
52 > Window → Preferences → C/C++ → Build → Build Variables and define
53 > `GSTREAMER_ROOT_ANDROID` there.
55 > ![warning] The NDK support in the Gradle build system used by
56 > Android Studio is still in beta, so the recommended way to build
57 > using the GStreamer SDK is still to use "ndk-build".
59 ## Configure your development environment
61 There are two routes to use GStreamer in an Android application: Either
62 writing your GStreamer code in Java or in C.
64 Android applications are mainly written in Java, so adding GStreamer
65 code to them in the same language is a huge advantage. However, this
66 requires using [language bindings] for the GStreamer API which are not
67 complete yet. In the meantime, this documentation will use Java for the
68 User Interface (UI) part and C for the GStreamer code. Both parts
69 interact through [JNI][Java Native Interface].
71 ### Building the tutorials
73 The tutorials code are in the
74 [gst-docs](https://cgit.freedesktop.org/gstreamer/gst-docs/) in the
75 `examples/tutorials/` folder.
77 There are a few Android-specific tutorials in the `tutorials/`
78 folder. Each tutorial is a folder containing source code (in Java and
79 C) and the resource files required to build a complete Android
82 The rest of the GStreamer tutorials (basic and playback tutorials)
83 cannot be run on Android without modification.
85 Android projects with GStreamer support are built like conventional
86 Android NDK projects, so the instructions at the [Android NDK] home can
90 #### Using Android Studio
92 > ![warning] To be completed!!
97 Make sure you have installed the ADT and NDK plugins listed in the
98 prerequisites section, and that they are both aware of the location of
99 the Android SDK and NDK respectively.
101 Import a tutorial into the Eclipse workspace:
102 File → New → Project… → Android Project from Existing Code, and select
103 the folder called `android-tutorial-1`.
105 After reading in the project and generating some extra files and
106 folders, Eclipse might complain about missing files. **This is normal**,
107 we are not finished yet.
109 Provide native development support by activating the NDK plugin:
110 Right-click on the project in the Project Explorer (this should be the
112 called `com.gst_sdk_tutorials.tutorial_1.Tutorial1`) → Android
113 tools → Add Native Support… Here the NDK plugin asks for a library name.
114 This is irrelevant and any valid file name will do. Accept.
116 Eclipse will still complain about errors in the code. **This is
117 normal**. Some files are missing because they are generated during the
120 Build the project: Project → Build Project. If you bring up the Eclipse
121 Console, you should see some progress messages. Once finished, the
122 missing files will appear and all error messages should be gone. The
123 project is now ready to run. Hit Run → Run.
125 A new application called “Android tutorial 1” should now be available on
126 your device, with the GStreamer logo. If you want to run the
127 tutorial in an Android Virtual Device (AVD), make sure to create the
128 device with support for audio playback and GPU Emulation (to enable
131 #### Using the command line
133 > ![warning] Note that, on Windows, this procedure requires a working Cygwin
134 > shell, as explained in the [Android NDK System Requirements]
136 For each tutorial, move to its folder and run:
138 android update project -p . -s --target X
140 Where `X` is one of the targets available in your system (the ones you
141 installed with the SDK manager). Make sure to use a target with at least
144 To get a list of all available targets in your system issue this
149 The “update project” command generates the `build.xml` file needed by
150 the build system. You only need to perform this action once per project.
152 To build the C part, just call:
156 A few lines in the `Android.mk` file (reviewed later) pull up the
157 necessary machinery to compile the GStreamer bits and generate the
158 Shared Object libraries (.so) that the Java code can use as native
161 Finally, compile the Java code with:
165 And install on the device with:
167 adb install -r bin/Tutorial1-debug.apk
169 The `-r` switch allows the installer to overwrite previous versions.
170 Otherwise, you need to manually uninstall previous versions of your
173 A new application called “Android tutorial 1” should now be available on
174 your device, with the GStreamer logo. If you want to run the
175 tutorial in an Android Virtual Device (AVD), make sure to create the
176 device with support for audio playback and GPU Emulation (to enable
179 > ![warning] Windows linkage problems
181 > Due to problems related to the standard linker, Google’s
182 > <a href="http://en.wikipedia.org/wiki/Gold_(linker)" class="external-link">Gold
183 > Linker</a> is used to build GStreamer applications. Unfortunately,
184 > the Android NDK toolchain for Windows does not include the gold linker
185 > and the standard one has to be used.
187 > If you observe linkage problems, you can replace the linker in your
188 > Android NDK with the gold one from [this project]. Download the
189 > `android-ndk-r8b-ma-windows.7z` file, extract
190 > `\android-ndk-r8b\toolchains\arm-linux-androideabi-4.6\prebuilt\windows\arm-linux-androideabi\bin\ld.exe`
191 > (only this file is needed) and overwrite the one in the same folder in
192 > your Android NDK installation. You might need the free [7-Zip
195 ### Creating new projects
197 Create a normal NDK project, either from the command line as described
198 in the [Android NDK][2] home, or use Eclipse: File → New → Project…
199 → Android Application Project, and, once the wizard is complete, right
200 click on the project → Android Tools → Add Native Support …
202 To add GStreamer support you only need to modify the
203 `jni/Android.mk` file. This file describes the native files in your
204 project, and its barebones structure (as auto-generated by Eclipse) is:
208 LOCAL_PATH := $(call my-dir)
210 include $(CLEAR_VARS)
212 LOCAL_MODULE := NativeApplication
213 LOCAL_SRC_FILES := NativeApplication.c
215 include $(BUILD_SHARED_LIBRARY)
217 Where line 5 specifies the name of the `.so` file that will contain your
218 native code and line 6 states all source files that compose your native
219 code, separated by spaces.
221 Adding GStreamer support only requires adding these lines:
223 **Android.mk with GStreamer support**
225 LOCAL_PATH := $(call my-dir)
227 include $(CLEAR_VARS)
229 LOCAL_MODULE := NativeApplication
230 LOCAL_SRC_FILES := NativeApplication.c
231 LOCAL_SHARED_LIBRARIES := gstreamer_android
232 LOCAL_LDLIBS := -landroid
234 include $(BUILD_SHARED_LIBRARY)
236 ifndef GSTREAMER_ROOT
237 ifndef GSTREAMER_ROOT_ANDROID
238 $(error GSTREAMER_ROOT_ANDROID is not defined!)
240 GSTREAMER_ROOT := $(GSTREAMER_ROOT_ANDROID)
243 GSTREAMER_NDK_BUILD_PATH := $(GSTREAMER_ROOT)/share/gst-android/ndk-build/
244 GSTREAMER_PLUGINS := coreelements ogg theora vorbis videoconvert audioconvert audioresample playback glimagesink soup opensles
245 G_IO_MODULES := gnutls
246 GSTREAMER_EXTRA_DEPS := gstreamer-video-1.0
248 include $(GSTREAMER_NDK_BUILD_PATH)/gstreamer.mk
250 Where line 7 specifies an extra library to be included in the project:
251 `libgstreamer_android.so`. This library contains all GStreamer code,
252 tailored for your application’s needs, as shown below.
254 Line 8 specifies additional system libraries, in this case, in order to
255 access android-specific functionality.
257 Lines 12 and 13 simply define some convenient macros.
259 Line 20 lists the plugins you want statically linked into
260 `libgstreamer_android.so`. Listing only the ones you need makes your
263 Line 21 is required to have HTTPS/TLS support from GStreamer, through the
264 `souphttpsrc` element.
266 Line 22 defines which GStreamer libraries your application requires.
268 Finally, line 24 includes the make files which perform the rest of the
271 Listing all desired plugins can be cumbersome, so they have been grouped
272 into categories, which can be used by including the `plugins.mk` file,
275 include $(GSTREAMER_NDK_BUILD_PATH)/plugins.mk
276 GSTREAMER_PLUGINS := $(GSTREAMER_PLUGINS_CORE) $(GSTREAMER_PLUGINS_CODECS) playbin souphttpsrc
278 #### List of categories and included plugins
280 | Category | Included plugins |
281 |--------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
282 | `GSTREAMER_PLUGINS_CORE` | coreelements adder app audioconvert audiorate audioresample audiotestsrc gio pango typefindfunctions videoconvert videorate videoscale videotestsrc volume autodetect videofilter |
283 | `GSTREAMER_PLUGINS_PLAYBACK` | playback |
284 | `GSTREAMER_PLUGINS_VIS` | libvisual goom goom2k1 audiovisualizers |
285 | `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 |
286 | `GSTREAMER_PLUGINS_NET` | tcp rtsp rtp rtpmanager soup udp dataurisrc sdp srtp rtspclientsink |
287 | `GSTREAMER_PLUGINS_NET_RESTRICTED` | mms rtmp |
288 | `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 |
289 | `GSTREAMER_PLUGINS_CODECS_GPL` | assrender |
290 | `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 |
291 | `GSTREAMER_PLUGINS_SYS` | opensles opengl |
292 | `GSTREAMER_PLUGINS_CAPTURE` | camerabin |
293 | `GSTREAMER_PLUGINS_ENCODING` | encodebin |
294 | `GSTREAMER_PLUGINS_GES` | nle |
296 Build and run your application as explained in the [Building the tutorials] section.
298 [information]: images/icons/emoticons/information.png
299 [Android SDK]: http://developer.android.com/sdk/index.html
300 [Android NDK]: http://developer.android.com/tools/sdk/ndk/index.html
301 [Java Native Interface]: http://en.wikipedia.org/wiki/Java_Native_Interface
302 [Android JNI tips here]: http://developer.android.com/guide/practices/jni.html
303 [prebuilt binaries]: https://gstreamer.freedesktop.org/data/pkg/android/
304 [language bindings]: http://en.wikipedia.org/wiki/Language_binding
305 [warning]: images/icons/emoticons/warning.png
306 [Android NDK System Requirements]: http://developer.android.com/tools/sdk/ndk/index.html#Reqs
307 [this project]: http://code.google.com/p/mingw-and-ndk/downloads/detail?name=android-ndk-r8b-ma-windows.7z&can=2&q=
308 [7-Zip archiving utility]: http://www.7-zip.org/
309 [2]: http://developer.android.com/tools/sdk/ndk/index.html#GetStarted