Kickstart Your GStreamer on Android Development in 6 Easy Steps

So you want to do some free-fashioned GStreamer developent on Android?

You are not alone. Android development – when using the stock SDK’s high level multimedia API – is geared towards a particular set of standard use cases. As a result it is kind of limiting, especially if you want to go beyond what is considered a regular use case. From this, you can easily assume there have been others like you who have gotten their feet wet in these revolving waters.

The GStreamer project and other third parties have already done a lot of GStreamer development on Android; this work can be reused to make the road to that incredible application you have in mind a bit less rocky. There are many pieces that need to be put together to assemble a working development environment; the good thing is you don’t need to do this by yourself anymore (barring additional modifications to the stock system).

I’m going to assume that if you have decided to try GStreamer on Android, you are already familiar with what this wonderful multimedia framework has to offer; you are already sold, so to speak. This article won’t include an introduction to GStreamer nor a primer on multimedia development concepts; the idea is to get you set up with an adequate environment to build, install, and run a community-provided, sample GStreamer application on your device. This will set you up to explore GStreamer for your own application.

First, some generic disclaimers:

  • All of the command line examples use Linux, so they will need to be adapted for other platforms.
  • This short guide doesn’t cover generic Android development or application development, it uses a sample Android application that has already been developed.

Step 1: Get The Required Materials

  • Android SDKGet the Android SDK and install it wherever you decide to do so. The SDK is mostly self contained, so you can put it anywhere your development user account has access.
  • Cerbero – This utility will perform most of the heavy lifting needed for bootstrapping. Clone the linked repository using Git into a directory that is usable by your user account.
  • Sample Applications Clone the linked repository using Git into a directory that is usable by your user account.

Make sure you can use adb (a utility provided by the SDK) with your device; this is usually quite simple. Install the SDK and make sure adb is in your PATH. You will also need to enable USB debugging on your device and “Install APKs from unknown sources.” Both of these are handled through the settings menu; sometimes these options are hidden under a special “developer” section. It depends largely on the device vendor and Android version, a bit more on the former. To find out how to perform this step on your particular device, use your favorite search engine to find a guide for your device/carrier/Android version; there are myriad of pages on the web with working instructions.

Once you are have set up the SDK, you can issue the following command to see devices that are hooked up via USB to your development machine. If you see your device listed, you are good to go:

adb devices

Note: You might think going for the bundled Android-studio version of the SDK and associated IDE and tools is a good idea, but for what we are doing it would be overkill, trust me.

Step 2: Bootstrap the Android Development Environment

You can get away without using Cerbero by simply downloading the pre-built binaries for your platform, but if you ever need to modify GStreamer itself, you will benefit from learning to perform this step up front.

Go to the directory where you put Cerbero and issue the following set of chained commands:

./cerbero-uninstalled -c config/cross-android.cbc bootstrap && 
./cerbero-uninstalled -c config/cross-android.cbc package gstreamer-1.0 && 
echo $?

Cerbero will download the required Android NDK for you as long as you have a working Internet connection. If you are greeted by a “0” in your terminal after everything is done you are good to go!

Step 3: Get GStreamer-for-Android Ready for Development

Cerbero will package two versions of GStreamer-for-Android after the previous step is completed. These are left in compressed tar balls on your Cerbero tree:

gstreamer-1.0-android-arm-1.7.0-runtime.tar.bz2
 gstreamer-1.0-android-arm-1.7.0.tar.bz2

The exact names you see might be different, but it’s important to remember that, for our approach (building an installable GStreamer application), all you need is the non-runtime version. The other package is used when using GStreamer as a system component on Android. That topic is beyond the scope of this guide.

Extract gstreamer-1.0-android-arm-1.7.0.tar.bz2 somewhere you’d use it from. I chose to unpack it in:

~/devel/gstreamer/gstreamer-android-root

After the unpacking is done, you should set the GSTREAMER_ROOT_ANDROID environment variable to point to this location:

export GSTREAMER_ROOT_ANDROID=/home/reynaldo/devel/gstreamer/gstreamer-android-root

Step 4: Let’s Build the Application!

Remember that we cloned gst-sdk-tutorials back in step one; we are going to use them now. The tutorials are simple test applications for Android that have various levels of complexity and usefulness. The code is quite easy to read, so if you feel like taking a look at how things work under the hood after you get your first applications built, please feel free to do so; you won’t regret it.

As I’m sure no one is particularly excited about trying yet another “Hello world” application, we are going to go for android-tutorial-5. This is a “full blown” (sic) multimedia player that will play some video for you. Amazing, isn’t it?

Go to the directory where you cloned the gst-sdk-tutorials and change to the directory for android-tutorial-5:

cd gst-sdk/tutorials/android-tutorial-5

The application needs some bootstrapping of its own; you need to select your target Android API level among other things. You can build with Android API level 9, which is the lowest level GStreamer supports. In my case, I’m going to target the Android version on my device, 6.0, so API level 23 it is. The easiest way to find out which level you need is to take a look at the API level table for each Android platform version.

Now, check that your desired API level is supported by your Android SDK. If it shows with this following command, you are all set:

android list

Note: the command above prints a clear string that represents the target Android platform version for a given API level in the “Name:” field, but this is also used to identify targets of differing hardware characteristics so it might get confusing.

If your API level isn’t supported, fire up the SDK manager and install the missing bits; you do that with this command:

android

Then, re-check that the API level you want is ready to be used and proceed. Remember, do all these steps while in the android-tutorial-5 directory.
Now, run the following command, adjusting it to match your chosen API level:

android update project -p . -s --target "android-23"
 ndk-build
 ant debug

The last step builds the application in debugging mode, which is exactly what we want for our first try. Our next step is to install it and try it out!

Step 5: Install the GStreamer App on Your Android Device

Still in the same directory, you will see that two debugging versions of the application were built and are stored in the bin sub-directory:

ls ./bin
 ./bin/Tutorial5-debug-unaligned.apk
 ./bin/Tutorial5-debug.apk

We are going to install the plain debug version (the unaligned version belongs to a previous step in the process which performs an optimization that Dalvik needs). To proceed, run the following command:

adb install ./bin/Tutorial5-debug.apk

Once the above command completes, you have successfully installed your custom-built GStreamer Android application! Pat yourself on the back, you are proving this guide to be useful!

Step 6: Run the Application

The rest is quite simple; the application should now be listed among the apps in your launcher. The icon sports the classic rendition of the GStreamer flag logo with a number 5 in front. Once you have found it, launch it. You will be greeted by a fairly standard set of playback controls and should see messages about buffering. You can hit play, pause, etc. The functionality should be self-explanatory, as long as it works.

In the unlikely case your application fails to start or to perform playback as expected, you can get some hints on what’s going on using adb again with the command:

adb logcat

Expand on This Work

For a more complete testing application, you might want to take a look at gst-launch-remote. This application provides a simple, remotely-controlled interface that enables you to run arbitrary GStreamer pipelines on your device (certain limitations apply).

You’ve just gone through what most GStreamer developers had to face at the start of their journey into Android. This is a bit of an understatement to be honest. In reality, the GStreamer community had to do a lot of work to get to this stage; things as simple as audio rendering were quite a hassle, let alone video. We had to not only develop a custom video output sink for this to happen (eglglessink: now part of the generic GStreamer GL sink), but also had to spend considerable time fiddling with bits to hook this up to the windowing system in Android. Even more importantly, getting access to the HW accelerated codec engine was a major struggle.

Now that you have your first GStreamer-on-Android application running, your exploration won’t be as crippled by the underlaying system as it would have been in the past. In a future article, I plan to show you how to work with a customized GStreamer tree to make modifications to your own GStreamer environment. It should be fun, so keep checking back here for more guides!

In the meantime, if something didn’t work, or you feel like there’s something that needs fixing, don’t hesitate to report your thoughts and issues directly to the GStreamer community using Bugzilla or the GStreamer Development/ GStreamer for Android mailing lists.

Happy hacking!

Author: Reynaldo Verdejo

Husband, Dad, and Multimedia FOSS developer by trade in between. His work is primarily found in GStreamer and FFmpeg, but he has also contributed to an assorted list of free and open source software during his more than a decade-long software development career.