Compile VLC Player for Android on Mac OS X Snow Leopard

In this post, I will outline the steps necessary to compile the VLC Player for Android devices. As a pre-requisite, please see my post about installing Eclipse Indigo for Android Development on Mac OS X Snow Leopard.

Prepare Your System for VLC Compilation:

1. Download the latest Apple Xcode development tool suite. Xcode is required by MacPorts below. (I downloaded Xcode 4.0.2 and iOS SDK 4.3)
   • Update: For the latest Xcode 4.5.1 (which I installed from the Mac App Store), after you install it, you will need to manually install the “Command Line Tools” which are required by Macports. To do so: go to Xcode->Preferences, Downloads, and click on “Install” for “Command Line Tools”.
   • (You will need to create a free Apple account, if you don’t already have one. This can be the same as your iTunes account.)
   • Double-click on the downloaded “xcode_4.0.2_and_ios_sdk_4.3.dmg” to mount the disk image.
   • It will show up on your desktop as a new drive “Xcode and iOS SDK”. Open the drive (if it doesn’t automatically open), launch the “Xcode and iOS SDK.mpkg” file, and follow the installation wizard instructions.
2. Download the latest MacPorts which is an open-source utility to make it easy to download, install, and upgrade open-source software such as subversion, wget, etc. We will need it to set up the environment for VLC android compilation. (I downloaded “MacPorts-2.0.0-10.6-SnowLeopard.dmg”)
   • Look under “Mac OS X Package (.pkg) Installer” section for the dmg installable image for Snow Leopard.
   • Double-click on the downloaded “MacPorts-2.0.0-10.6-SnowLeopard.dmg” to mount the disk image.
   • It will show up on your desktop as a new drive “MacPorts-2.0.0”. Open the drive (if it doesn’t automatically open), launch the “MacPorts-2.0.0.pkg” file, and follow the installation wizard instructions.

   Periodically, you can run this command in a Terminal to update MacPorts and the programs which it has installed.

   sudo port -v selfupdate
   sudo port -v upgrade outdated

   To see the programs installed and managed by MacPorts, run this command in a Terminal:

   sudo port installed
3. Open up a new Terminal and use MacPorts to install the following utilities:
   sudo port install wget
   sudo port install autoconf
   sudo port install libtool
   sudo port install pkgconfig
   sudo port install subversion

   The first installation, wget, will take a long time so just have patience.
   Note: After installing programs using MacPorts, you will want to re-start the Terminal before using these command line tools.

Install Subversion Eclipse Plugin (Subclipse)

Optionally, add support for subversion in Eclipse:

1. Install the subversion JavaHL bindings which is required by the Eclipse subversion plugin.
   sudo port install subversion-javahlbindings
   • Updated Note: Macports’ latest subversion-javahlbindings 1.7.x works fine with Eclipse Juno.
   • Note: Macports’ recent upgrade of subversion-javahlbindings to version 1.7.1 (from 1.6.17) broke Subclipse compatibility with Eclipse Indigo. If you use Eclipse Indigo, you will want to install the JavaHL 1.6.x bindings from Collabnet Website instead.
2. Run Eclipse.
3. Go to Eclipse menu Help->Install New Software…
4. Input “http://subclipse.tigris.org/update_1.8.x” into the “Work with” field and the table will be updated with installation packages available at that location. (You can check what is the latest subclipse here.)
5. Check just the “Subclipse” package and click Next, Next, accept the license, Finish.
   • Note: If the first Next button freezes Eclipse with a message saying that it is “Calculating requirements…”, then it may be that one or more Eclipse update sites are unreachable. If you encounter this, you may need to force quit Eclipse (canceling doesn’t seem to unfreeze it). Restart Eclipse, repeat these steps, but uncheck the “Contact all update sites during install to find required software” before clicking on the first Next button.
6. If the Security Warning dialog about the “unsigned content” appears, click Ok to accept.
7. Click on “Restart Now” to restart Eclipse.

Download and Compile VLC

We will download and install VLC android according to the VideoLan website’s VLC Android Compile directions. I will repeat the relevant instructions below with my additional notes. Please double-check the instructions below against the VideoLan website because the VideoLan instructions are updated continually.

1. Get the VLC source using Git. Run the following on a newly opened Terminal in the directory (ex: “~/projects”) where you want to download VLC android to:
   git clone git://git.videolan.org/vlc/vlc-android.git

   This operation will take a long time. By default, it will create a subdirectory called “vlc-android”. If you don’t like that, then add the custom subdirectory name as an additional argument to the end of the “git clone” command. Alternatively, you can always rename the “vlc-android” subdirectory afterwards.

2. Configure 3rd party modules for android compilation:
   cd vlc-android/extras/contrib
   ./bootstrap -t arm-eabi -d android

   This step will create the following files: config.mak, distro.mak (softlink to src/Distributions/android.mak), Makefile (softlink to contrib.mak), toolchain.cmake. Also, the following directories are created: build (softlink to hosts/arm-eabi), build-src, hosts.

   • Hint: It looks like you can edit “distro.mak” to enable/disable 3rd party module compilation by editing the “all” target to include/exclude projects.
3. Retrieve 3rd party modules from the internet (which uses the wget and subversion that we had installed with MacPorts) and compile them for Android. Under the same “vlc-android/extras/contrib” directory, run:
   make

   Some things to watch for:

   • With the VLC version I got, the make command failed with an error:
     RTSPServerSupportingHTTPStreaming.cpp:69: error: invalid conversion from 'long unsigned int*' to 'const time_t*'

     I fixed it by modifying the “./build-src/live/liveMedia/RTSPServerSupportingHTTPStreaming.cpp” file (you will need to chmod it first to make it modifiable) and inserting an explicit cast “(const time_t*)” in the call to gmtime: “gmtime((const time_t*)&sb.st_mtime)”.

   • The make will retrieve the 3rd party module source code under the “./build-src” subdirectory and will generate the library files under the “./hosts/arm-eabi/lib” subdirectory. The corresponding library headers can be found under the “./hosts/arm-eabi/include” subdirectory.
4. Configure the main VLC codebase for Android compilation:
   • First before you do anything else, go back to the original root “vlc-android” git clone directory. The VideoLan website neglects to include this step. Assuming that you created “vlc-android” under your home directory, run these commands:
     cd ~/vlc-android
     ./bootstrap

     This step will create these files: ABOUT-NLS, aclocal.m4, config.h.in, configure, Makefile.in. And will create a directory, autom4te.cache, and add these files to the autotools directory: compile, config.guess, config.sub, depcomp, install-sh, ltmain.sh, missing. Additionally, the Makefile.in file is added to directories: bin, compat, doc, all subdirectories under libs, m4, modules (including most subdirectories of), share, src, test. Finally, directories m4 and po got other miscellaneous files.

   • Create our own build directory and prepare it to hold the compiled VLC classes:
     mkdir build
     cd build
     ../extras/package/android/configure.sh

     This step will create a bunch of files and directories under the “build” directory. The most important files are:

     • config.h – contains directives to customize the build; the variable CONFIGURE_LINE will reflect the enable/disable directives from configure.sh.
     • Makefile – builds the Android-compatible static .a library files for enabled modules

     Hint: Before running “../extras/package/android/configure.sh”, you can edit it to enable/disable modules. Search for “–enable” or “–disable” and adjust accordingly. When enabling/disabling 3rd party libraries, please make sure that your changes here matches the changes you made to “distro.mak” earlier.

5. Compile VLC and configure Android JNI generation:
   • Run this command to compile the VLC source code (it will take a long time before completing).
     ./compile -k

     This program uses GNU libtool to compile the VLC source and prepare it to generate a shareable library (or dynamically-linked library). As a result, besides the standard object .o files and static library .a files, you will see .libs and .dep subdirectories and .la, .lo, and .Plo files required by libtool. Most of these files will be created under the build directory’s src and modules subdirectories.

   • Create the NDK makefile and build the VLC JNI library for Android by running these commands:
     cd ../extras/package/android
     VLC_BUILD_DIR=../../../build make

     Things to note:

     • Under the “vlc-android/extras/package/android/vlc-android” directory, you will see the following new subdirectories: bin, gen (contains auto-generated Android java sources like R.java), libs (contains libvlcjni.so which is the VLC shared library), and obj. In addition, you will see the following new files: local.properties, jni/Android.mk (NDK makefile) and jni/libvlcjni.h (declare VLC plugins). (Android.mk and libvlcjni.h should only contain the enabled modules matching your changes to “distro.mak” earlier.)
     • If you did not name your “build” directory as “vlc-android/build”, then you will need to adjust the value for VLC_BUILD_DIR in the command above accordingly. If you ran the above command with the wrong VLC_BUILD_DIR, run the following commands to cleanup before re-running the make again:
       make clean
       rm vlc-android/jni/Android.mk

       The “make clean” deletes the bin, libs, and obj subdirectories but neglects to delete jni/Android.mk which makes use of the VLC_BUILD_DIR variable.

Compile and Deploy the Android VLC Player

1. Launch Eclipse.
2. Create a new project by doing the following:
   • Select menu File->New->Project…
   • Select Android->Android Project. Click Next.
   • Click on “Create project from existing source”.
   • Press the Browse… button and locate the “vlc-android/extras/package/android/vlc-android” directory.
   • Update “Project name” field to “vlc-android” (or whatever you want). Press the Finish button.
3. The new “vlc-android” project will be created and will appear under the Eclipse Package Explorer left-most pane. The Eclipse ADT plugin will automatically compile the newly-imported vlc-android project and prepare it for deployment. Hopefully you don’t see any errors.
4. Deploy the VLC Player to an Android device:
   • Connect your Android device to your Mac. You can double-check that the Android device is recognized by opening up a Terminal and running the follow ADB command:
     adb devices

     You should see your Android device listed with a 12 alphanumeric characters long identifier.

   • Locate “vlc-android” project under the Eclipse Package Explorer pane.
   • Right-click on “vlc-android” project and select “Run As”->”1 Android Application”. Eclipse ADT will deploy the VLC Player to your Android device and launch it.
   • If you have more than one Android device connected or you have created an emulator (VLC Player cannot run under an emulator), you will need to configure Eclipse ADT to allow you to manually select the Android device to deploy to:
     • Right-click on “vlc-android” project and select “Run As”->”Run Configurations…”.
     • “Android Applications”->”vlc-android” should already be selected.
     • Click on Target tab and check the Manual radio button.
     • Hit Apply and Close buttons.

Using the Android VLC Player

1. Before running the VLC Player, you will need to prepare some movies for it to play.
   • You can download some Android compatible movie trailers here. If you create your own sample movie files, I recommend making sure the video encoding, video resolution, audio encoding, audio sample rate are supported by your Android device.
   • Copy the video files to your SD card under a directory called “movies”. You can remove the SD card from the Android device and stick it into your computer to copy the movies over. Or you can use ADB to copy the video files to the Android device over USB like so:
     adb shell
     cd sdcard
     mkdir movies
     exit
     
     adb push movie1.mp4 /sdcard/movies
     adb push movie2.mp4 /sdcard/movies
     ...
   • Launch VLC Player on your Android device. You will get a notice that it is alpha software; just click ok.
   • You will get the main VLC page with the message “No Media Files”. Fix that by doing the following on the Android device:
     • Touch the menu button and select Preferences.
     • Tap on Directories, on “sdcard”, and on the checkbox to the left of “movies”.
     • Touch return three times to get back to the main VLC page.
     • A list containing the movies and their preview images should appear.
   • Select a movie to play it.

Modifying VLC Source and Re-compiling the Android VLC Player

If you wish to modify VLC source code without having to redo the long compilation from scratch, below are some hints. Suppose that you wish to rebuild after modifying the “vlc-android/modules/video_filter/rotate.c” file:

1. Force the rebuild of the object files related to “rotate.c” by doing the following under the “vlc-android/build” directory:
   cd build
   find . -name "*rotate*.*" -print | xargs rm
   ./compile -k
   ./compile -k

   The “./compile -k” is run twice because the first time, the libtool will error out because the dependency file .Plo will be missing. However, libtool generates the missing .Plo file all the same. The second time will succeed. (For cases where the .Plo file is not required by libtool, the first run will succeed.)

2. Rebuild the Android NDK JNI related files by doing the following:
   cd ../extras/package/android
   make clean
   VLC_BUILD_DIR=../../../build make
3. In Eclipse, right-click on the “vlc-android” project and select Refresh.
   • Note:If the “vlc-android” project starts throwing a bunch of “Cannot resolve type” class errors, you will need to tell Eclipse that it is okay to rebuild class files which have been modified externally (by our script commands above). To do so, enable the ”Rebuild class files modified by others” option under menu “Eclipse->Preferences–>Java–>Compiler–>Building–>Output folder”.
4. Use Eclipse to re-deploy VLC Player to your Android device.
   • Note: I have seen instances where the re-deploy does not update the VLC Player on the Android and there are no error messages from Eclipse. If I suspect that, then I will manually uninstall VLC Player (on Android, tap “Settings->Applications->Manage applications->VLC media player->Uninstall”) from the Android device and then do a fresh deployment from Eclipse. As a shortcut, you can do this by opening a Terminal and running the following commands:
     adb uninstall org.videolan.vlc.android
     cd vlc-android/extras/package/android/vlc-android/bin
     adb install vlc-android.apk

Tips for Developing and Debugging with Android

• To run the ndk-build script directly, you can do the following:
  cd vlc-android/extras/package/android/vlc-android/jni
  $ANDROID_NDK/ndk-build -B V=1

  The “-B” flag indicates a rebuild and the “V=1” flag enables verbose output.

• VLC Player and other applications (including your own) may output debug traces to the adb logger (called logcat). (Under native C code, use msg_Dbg and msg_Err statements. Under Java, use the android.util.Log class.) Under Elipse, you can display the logger debug traces in real-time by going to menu “Window->Show View->Other…->Android->LogCat”. (Note: Under Eclipse, the filter only works on the Message text field.) Alternatively, you can open up a Terminal and run “adb logcat”.
• Check CPU usage on the Android by opening a Terminal and running “adb shell top -m 5”.
• Show the library dependencies by opening a Terminal and running “otool -L libvlcjni.so”. (The otool utility is the Mac OS X equivalent of the Linux ldd or readelf utilities.)

That’s it. Hope that you have fun developing with Android.