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 There are a few Android-specific tutorials in the
74 `$GSTREAMER_ROOT_ANDROID/share/gst-sdk/tutorials` folder. Each
75 tutorial is a folder containing source code (in Java and C) and the
76 resource files required to build a complete Android application.
78 The rest of the GStreamer tutorials (basic and playback tutorials)
79 cannot be run on Android without modification.
81 Android projects with GStreamer support are built like conventional
82 Android NDK projects, so the instructions at the [Android NDK] home can
86 #### Using Android Studio
88 > ![warning] To be completed!!
93 Make sure you have installed the ADT and NDK plugins listed in the
94 prerequisites section, and that they are both aware of the location of
95 the Android SDK and NDK respectively.
97 Import a tutorial into the Eclipse workspace:
98 File → New → Project… → Android Project from Existing Code, and select
99 the folder called `android-tutorial-1`.
101 After reading in the project and generating some extra files and
102 folders, Eclipse might complain about missing files. **This is normal**,
103 we are not finished yet.
105 Provide native development support by activating the NDK plugin:
106 Right-click on the project in the Project Explorer (this should be the
108 called `com.gst_sdk_tutorials.tutorial_1.Tutorial1`) → Android
109 tools → Add Native Support… Here the NDK plugin asks for a library name.
110 This is irrelevant and any valid file name will do. Accept.
112 Eclipse will still complain about errors in the code. **This is
113 normal**. Some files are missing because they are generated during the
116 Build the project: Project → Build Project. If you bring up the Eclipse
117 Console, you should see some progress messages. Once finished, the
118 missing files will appear and all error messages should be gone. The
119 project is now ready to run. Hit Run → Run.
121 A new application called “Android tutorial 1” should now be available on
122 your device, with the GStreamer logo. If you want to run the
123 tutorial in an Android Virtual Device (AVD), make sure to create the
124 device with support for audio playback and GPU Emulation (to enable
127 #### Using the command line
129 > ![warning] Note that, on Windows, this procedure requires a working Cygwin
130 > shell, as explained in the [Android NDK System Requirements]
132 For each tutorial, move to its folder and run:
134 android update project -p . -s --target X
136 Where `X` is one of the targets available in your system (the ones you
137 installed with the SDK manager). Make sure to use a target with at least
140 To get a list of all available targets in your system issue this
145 The “update project” command generates the `build.xml` file needed by
146 the build system. You only need to perform this action once per project.
148 To build the C part, just call:
152 A few lines in the `Android.mk` file (reviewed later) pull up the
153 necessary machinery to compile the GStreamer bits and generate the
154 Shared Object libraries (.so) that the Java code can use as native
157 Finally, compile the Java code with:
161 And install on the device with:
163 adb install -r bin/Tutorial1-debug.apk
165 The `-r` switch allows the installer to overwrite previous versions.
166 Otherwise, you need to manually uninstall previous versions of your
169 A new application called “Android tutorial 1” should now be available on
170 your device, with the GStreamer logo. If you want to run the
171 tutorial in an Android Virtual Device (AVD), make sure to create the
172 device with support for audio playback and GPU Emulation (to enable
175 > ![warning] Windows linkage problems
177 > Due to problems related to the standard linker, Google’s
178 > <a href="http://en.wikipedia.org/wiki/Gold_(linker)" class="external-link">Gold
179 > Linker</a> is used to build GStreamer applications. Unfortunately,
180 > the Android NDK toolchain for Windows does not include the gold linker
181 > and the standard one has to be used.
183 > If you observe linkage problems, you can replace the linker in your
184 > Android NDK with the gold one from [this project]. Download the
185 > `android-ndk-r8b-ma-windows.7z` file, extract
186 > `\android-ndk-r8b\toolchains\arm-linux-androideabi-4.6\prebuilt\windows\arm-linux-androideabi\bin\ld.exe`
187 > (only this file is needed) and overwrite the one in the same folder in
188 > your Android NDK installation. You might need the free [7-Zip
191 ### Creating new projects
193 Create a normal NDK project, either from the command line as described
194 in the [Android NDK][2] home, or use Eclipse: File → New → Project…
195 → Android Application Project, and, once the wizard is complete, right
196 click on the project → Android Tools → Add Native Support …
198 To add GStreamer support you only need to modify the
199 `jni/Android.mk` file. This file describes the native files in your
200 project, and its barebones structure (as auto-generated by Eclipse) is:
204 LOCAL_PATH := $(call my-dir)
206 include $(CLEAR_VARS)
208 LOCAL_MODULE := NativeApplication
209 LOCAL_SRC_FILES := NativeApplication.c
211 include $(BUILD_SHARED_LIBRARY)
213 Where line 5 specifies the name of the `.so` file that will contain your
214 native code and line 6 states all source files that compose your native
215 code, separated by spaces.
217 Adding GStreamer support only requires adding these lines:
219 **Android.mk with GStreamer support**
221 LOCAL_PATH := $(call my-dir)
223 include $(CLEAR_VARS)
225 LOCAL_MODULE := NativeApplication
226 LOCAL_SRC_FILES := NativeApplication.c
227 LOCAL_SHARED_LIBRARIES := gstreamer_android
228 LOCAL_LDLIBS := -landroid
230 include $(BUILD_SHARED_LIBRARY)
232 ifndef GSTREAMER_ROOT
233 ifndef GSTREAMER_ROOT_ANDROID
234 $(error GSTREAMER_ROOT_ANDROID is not defined!)
236 GSTREAMER_ROOT := $(GSTREAMER_ROOT_ANDROID)
239 GSTREAMER_NDK_BUILD_PATH := $(GSTREAMER_ROOT)/share/gst-android/ndk-build/
240 GSTREAMER_PLUGINS := coreelements ogg theora vorbis videoconvert audioconvert audioresample playback glimagesink soup opensles
241 G_IO_MODULES := gnutls
242 GSTREAMER_EXTRA_DEPS := gstreamer-video-1.0
244 include $(GSTREAMER_NDK_BUILD_PATH)/gstreamer.mk
246 Where line 7 specifies an extra library to be included in the project:
247 `libgstreamer_android.so`. This library contains all GStreamer code,
248 tailored for your application’s needs, as shown below.
250 Line 8 specifies additional system libraries, in this case, in order to
251 access android-specific functionality.
253 Lines 12 and 13 simply define some convenient macros.
255 Line 20 lists the plugins you want statically linked into
256 `libgstreamer_android.so`. Listing only the ones you need makes your
259 Line 21 is required to have HTTPS/TLS support from GStreamer, through the
260 `souphttpsrc` element.
262 Line 22 defines which GStreamer libraries your application requires.
264 Finally, line 24 includes the make files which perform the rest of the
267 Listing all desired plugins can be cumbersome, so they have been grouped
268 into categories, which can be used by including the `plugins.mk` file,
271 include $(GSTREAMER_NDK_BUILD_PATH)/plugins.mk
272 GSTREAMER_PLUGINS := $(GSTREAMER_PLUGINS_CORE) $(GSTREAMER_PLUGINS_CODECS) playbin souphttpsrc
274 #### List of categories and included plugins
276 | Category | Included plugins |
277 |--------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
278 | `GSTREAMER_PLUGINS_CORE` | coreelements coreindexers adder app audioconvert audiorate audioresample audiotestsrc videoconvert gdp gio pango typefindfunctions videorate videoscale videotestsrc volume autodetect videofilter |
279 | `GSTREAMER_PLUGINS_PLAYBACK` | decodebin playbin |
280 | `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 |
281 | `GSTREAMER_PLUGINS_VIS` | libvisual goom goom2k1 audiovisualizers |
282 | `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 |
283 | `GSTREAMER_PLUGINS_NET` | rtsp rtp rtpmanager souphttpsrc udp dataurisrc rtpmux rtpvp8 sdpelem |
284 | `GSTREAMER_PLUGINS_CODECS_GPL` | assrender |
285 | `GSTREAMER_PLUGINS_SYS` | glimagesink opensles amc |
287 Build and run your application as explained in the [Building the tutorial](sdk-installing-for-android-development.md#building-the-tutorials) section.
289 [information]: images/icons/emoticons/information.png
290 [Android SDK]: http://developer.android.com/sdk/index.html
291 [Android NDK]: http://developer.android.com/tools/sdk/ndk/index.html
292 [Java Native Interface]: http://en.wikipedia.org/wiki/Java_Native_Interface
293 [Android JNI tips here]: http://developer.android.com/guide/practices/jni.html
294 [prebuilt binaries]: https://gstreamer.freedesktop.org/data/pkg/android/
295 [language bindings]: http://en.wikipedia.org/wiki/Language_binding
296 [warning]: images/icons/emoticons/warning.png
297 [Android NDK System Requirements]: http://developer.android.com/tools/sdk/ndk/index.html#Reqs
298 [this project]: http://code.google.com/p/mingw-and-ndk/downloads/detail?name=android-ndk-r8b-ma-windows.7z&can=2&q=
299 [7-Zip archiving utility]: http://www.7-zip.org/
300 [2]: http://developer.android.com/tools/sdk/ndk/index.html#GetStarted