GstreamerAndroid_InstallInstructions

Contents

  1. Building GStreamer with the NDK
    1. Things you will need
    2. Obtaining the bundle
    3. Building
    4. Installing
    5. Current Status
    6. Suported Devices
  2. Build GStreamer as a part of Android
    1. Development Environment Setup
    2. Get Android source
    3. Build the unmodified tree
    4. Build the modified tree
    5. Rooting your Nexus S
    6. Backup your system partition
  3. Installing our bundle on the Nexus S
    1. Common issues
  4. People

There are two ways of building GStreamer for/on Android. You can build GStreamer as an Native application APK or as a part of Android itself. The former will enable you to use GStreamer as a support library for your own native application development; the latter enables you to use GStreamer on Android as a media backend for the OS. Providing services to the rest of the system by replacing (in part) the native media framework.

Building GStreamer with the NDK

This is a work in progress and although most of GStreamer can be built and installed on a real device, there is still a lot of work to do.

Things you will need

$NDK_HOME/platforms/android-9/arch-arm/usr/lib/libaudioflinger.so
$NDK_HOME/platforms/android-9/arch-arm/usr/lib/libbinder.so
$NDK_HOME/platforms/android-9/arch-arm/usr/lib/libcutils.so
$NDK_HOME/platforms/android-9/arch-arm/usr/lib/libhardware.so
$NDK_HOME/platforms/android-9/arch-arm/usr/lib/libmediaplayerservice.so
$NDK_HOME/platforms/android-9/arch-arm/usr/lib/libmedia.so
$NDK_HOME/platforms/android-9/arch-arm/usr/lib/libpixelflinger.so
$NDK_HOME/platforms/android-9/arch-arm/usr/lib/libsurfaceflinger_client.so
$NDK_HOME/platforms/android-9/arch-arm/usr/lib/libsurfaceflinger.so
$NDK_HOME/platforms/android-9/arch-arm/usr/lib/libui.so
$NDK_HOME/platforms/android-9/arch-arm/usr/lib/libutils.so

Obtaining the bundle

You can get a ready to build bundle issuing: 

    git clone git://git.collabora.co.uk/git/android/gstreamer-0.10_ndk_bundle.git

Look here for git viewer.

We also have a preliminary WIP ICS port here: 

    http://cgit.collabora.com/git/android/gstreamer_ndk_bundle.git/

Feel free to try it out and help us getting it ready!

Then, from within the just created gstreamer[-0.10|-1.0]_ndk_bundle directory: 

    git submodule update --init

Building

This is fairly easy. We are providing an small helper script called setup.sh. Run it to get an APK ready to install on your device. Rember you need ndk-build, java and ant on your PATH.

Currently the module is configured to build for the honeycomb target. If you want to e.g. build for GingerBread/IcecreamSandwich you need to make the two changes below:

(Example using Gingerbread as target):

Installing

Again, we are providing a helper script named install_bundle.sh, run it with your device connected to get the NDK bundle installed on your system

Current Status

Surfaceflingersink and Audioflingersink have problems we are ironing out ATM (AudioFlingerSink should be working on Gingerbread/Honeycomb/ICS. SurfaceFlingerSink should work for you on Gingerbread). Other than that you can play around with the bundle's executables using adb shell run-as com.android.freedesktop.gstreamer. Keep in mind you will need to export LD_LIBRARY_PATH, GST_PLUGIN_PATH and GST_REGISTRY so they match the bundle's install environment. Heres an example with gst-inspect to get you going: 

GST_REGISTRY=/data/data/com.android.freedesktop.gstreamer/cache/registry.bin GST_PLUGIN_PATH=/data/data/com.android.freedesktop.gstreamer/lib  LD_LIBRARY_PATH=/data/data/com.android.freedesktop.gstreamer/lib run-as com.android.freedesktop.gstreamer /data/data/com.android.freedesktop.gstreamer/bin/gst-inspect

Suported Devices

Most of the testing work has been perfomed using a Sammsung Nexus S and a LG P500 (Gingerbread), a Samsung Galaxy Tab 10.1 (Honeycomb) and the Galaxy Nexus (Icecream Sandwich). Again, please feel free to try with other devices and report back your results.

Build GStreamer as a part of Android

Development Environment Setup

Although we provide full instructions here to build our GStreamer/Android bundle you can use this document as a generic reference if need be:

* Instructions for downloading & building the Android source tree

Get Android source

You will first need to get Android's source code as described in the above link. We are basing this initial pre-release in Android 2.3.2 so to get it you would issue: 

    repo init -u git://android.git.kernel.org/platform/manifest.git -b android-2.3.2_r1

And then: 

    repo sync

The future plan is to target android-release (currently 2.3.3_r1) for the NexusS crespo build but all current tests had been conducted running our bundle on the Nexus S with 2.3.2 installed.

You can also use the Google android git servers as an alternative to the kernel.org git servers.

Android can be built on Debian/Sid amd64 against Sun's Java 6 JDK. For setting up the needed default symbolic links after installing it you should issue this command as root: 

    update-java-alternatives -s java-1.6.0-sun

Ubuntu/Debian doesn't have packages for the X11 libraries, this situation can be worked around issuing: 

    ln -s /usr/lib32/libX11.so.6 /usr/lib32/libX11.so

Build the unmodified tree

You need to try this procedure first to ensure your development environment is correctly setup. These commands came straight from android's building instructions: 

    cd $ANDROID_SOURCE_DIR
    source build/envsetup.sh
    lunch (pick a target) (This is going to be 'full_crespo-userdebug' for the image you can try on the Nexus S, and 'generic-eng' to try in the emulator)
    make [showcommands]

Now, if you are going to be trying out our bundle in your phone, it would be the right time to root your phone and backup your system partition.

Once you make sure this procedure works you can continue with the instructions to build our modified tree.

Don't skip this step, even if you are not going to try the build on your phone, otherwise you will get into trouble in the next steps.

Build the modified tree

You should first get Androgenizer

build it and put it somewhere in your PATH.

Get this local manifest for 2.3.2_r1 and put it in your $ANDROID_SOURCE_DIR/.repo

After you have downloaded the needed local_manifest.xml and moved it to $ANDROID_SOURCE/.repo/ all you have to do is: 

    repo sync

To get our sources and GStreamer hooks to your base android tree.

A word of caution here, repo has the tendency to leave your checked out stuff in 'no branch'. If this happens (and its almost sure it will) you will have the weirdests errors at building and/or trying to run the stuff on the phone. You can make sure the sync went well with the repo branch command. The output should match the revisions for each of the modules on the local_manifest.xml you downloaded. If this is not the case, got to each module and issue git checkout <branch> where branch is the revision prop on each module's entry in the file. As far as we know this is a bug in repo.

Get config.sub and put it in $ANDROID_SOURCE_DIR/external/gstreamer_aggregate/ , then issue the following commands to build the whole system: 

    cd $ANDROID_SOURCE_DIR/external/gstreamer_aggregate/
    for i in *; do if [ -d $i ]; then echo $i; cp config.sub $i; fi; done
    cp config.sub gst-openmax/build-aux/
    cd $ANDROID_SOURCE_DIR
    source build/envsetup.sh
    lunch (pick a target)
    make libmad-configure libid3tag-configure libogg-configure libx264-configure libfaad-configure
    make libmad libid3tag libogg libx264 libfaad libvorbisidec
    make gstreamer-aggregate-configure
    make

Rooting your Nexus S

To be able to install our bundle to your Nexus S you will need to root it first, we don't encourage nor support this procedure but for the sake of completeness we show you our instructions on how to do it:

From the build tree do: 

    . build/envsetup.sh
    lunch full_crespo-userdebug
    make

The trick is selecting the userdebug variant. It sets the ro.debuggable property to 1 in the boot image so that adb root will give you root access.

Once everything is built, reboot your phone in fastboot mode

Flash the newly built recovery and boot images: 

    fastboot flash recovery out/target/product/crespo/recovery.img
    fastboot flash boot out/target/product/crespo/boot.img
    [reboot]

Now get root: 

    adb root
    adb shell

Backup your system partition

We can't stress this enough. PLEASE backup your system partition so we don't have to feel guilty about you borking your phone without a way back ;). It basically goes this way:

Root your Nexus S

Issue adb shell and figure out where your /system partition is on the disc* (mount command should tell you that)

Then, still under your adb shell, dd it to somewhere you can write to: 

    dd if=/device/descriptor/of/your/system/partition of=/data/system_backup.img
    exit
    adb pull /data/system_backup.img

That will leave your system_backup.img file wherever on your path you issued the last command. Keep it somewhere safe for any future need.

Installing our bundle on the Nexus S

'You will need to have a rooted phone to be able to perform this step.'

Once you have everything built you can use this install.sh script to install the modified files on the phone. Gets the script, put it on your $ANDROID_SOURCE directory and issue: 

    sh install.sh

Here is the complete procedure: 

    cd $ANDROID_SOURCE
    move the install.sh here
    sh install.sh
    adb reboot
    enjoy \o/

If you see any errors while the script is pushing files to the phone run it again, it takes a few seconds before the /sys filesystem gets mounted and some times the wait() time on the script is not enough to account for the delay.

To get h264 decoding working, you need to put http://people.collabora.co.uk/~twi/gst-openmax.conf in /system. 

    wget http://people.collabora.co.uk/~twi/gst-openmax.conf
    adb push gst-openmax.conf /system

This procedure should be pretty phone-agnostic but currently please keep in mind (and we can't stress this enough) our test had been conducted on the Nexus S.

You can actually perform a manual push of the files too, just keep an eye on the target paths. Here is the manual procedure: 

    cd $ANDROID_SOURCE
    adb root
    adb remount
    adb push [SOME_FILE_YOU_WANT_TO_PUSH_TO_THE_PHONE] [SOME_PATH_ON_THE_PHONE]

Common issues

Weird internal dependency issues or random files not being built

Please double check you are not using ccache nor any kind of distributed/simultaneous make (-jX). We have seen problems with both.

C compiler cannot create executable files

Don't use ccache when configuring. You may have to add or remove the $(PWD) prefix before libgcc.a in the makefile.

/usr/include/gnu/stubs.h:7:27: error: gnu/stubs-32.h: No such file or directory

You need to install 32bit compat development files if you are on a 64bit platform.

For ubuntu these packages should be installed: ia32-libs lib32z1-dev lib32bz2-dev git-core gnupg flex bison gperf build-essential zip curl zlib1g-dev libc6-dev g++-multilib lib32ncurses5-dev x11proto-core-dev libx11-dev lib32readline5-dev lib32z-dev libgl1-mesa-dev On Fedora follow these instructions.

Invalid configuration `arm-linux-androideabi'

You need a config.sub with this configuration. Make sure you have followed these initial steps from Build the modified tree section:

Get config.sub and put it in $ANDROID_SOURCE_DIR/external/gstreamer_aggregate/ , then issue the following commands to build the whole system: 

    cd $ANDROID_SOURCE_DIR/external/gstreamer_aggregate/
    for i in *; do if [ -d $i ]; then echo $i; cp config.sub $i; fi; done
    cp config.sub gst-openmax/build-aux/

GST_FORMAT_TYPE undefined

Check that gstenumtypes.h is generated properly (eg, not empty). Remove it if so, and it'll be regenerated.

glib-mkenums or glib-genmarshal not found

A host glib can be used. Some distros like to withhold various parts of software you install so you may have to get the -dev version too.

Emulator / No space on /system to copy GStreamer

If you are trying this on the emulator run it with -partition-size 512 (or at least about 5 MB more than it currently has).

Getting a warning containing "too many libraries when loading *.so"

Bionic imposes a hard limit on the number of shared objects you can load at run time. There are a few ways to work around this issue:

If your pipeline is complex enough so it makes you hit the limit no matter what. Then you have two alternitives:

autovideosink not found when using gst-launch with playbin2

Set playbin2's video-sink property to surfaceflingersink.

Got an error at 'make' about you trying to change API?

Please run 

    make update-api

This problem was caused by some leftover changes we had in frameworks/base but they have been removed now.

And then run 'make' normally. This error comes from a leftover of our work in frameworks/base and should be gone soon.

What to do if the system refuses to boot after pushing our stuff

You will have to use the backup iso for 2.3.2_r1 you made in Backup your system partition it should allow you to get your system back to a working state. You basically dd it to the /system partition on your Nexus S, reboot et voila! your phone is booting again. If you want to repeat the customization procedure after you have overriden your /system with this backup you should make sure follow the steps for the android branch you are using because that's what you just pushed to the phone.

People

People historically and/or currently involved in this port, in no particular order (You can find us on Freenode's #gstreamer channel):

People from Collabora:

Commnity and people from other companies: