How to integrate libaom into Android NDK?

Integrating the libaom library into an Android NDK project allows developers to encode and decode AV1 video natively within their applications. This process involves setting up the Android NDK environment, fetching the libaom source code, configuring the build system using CMake, and compiling the library into shared or static objects (.so or .a). By following this workflow, you can leverage high-efficiency AV1 video compression directly inside your Android applications for better performance and reduced bandwidth usage.

Prerequisites and Environment Setup

Before starting the integration, ensure you have the necessary tools installed via the Android Studio SDK Manager:

• Android NDK: The Native Development Kit required to compile C/C++ code for Android.
• CMake: The build tool used by both Android Studio and libaom.
• Ninja: A build system that speeds up the compilation process (highly recommended).
• Git and Python: Required to clone the repository and run libaom’s build scripts.

Step 1: Fetch the libaom Source Code

Clone the official AOMedia Video 1 (libaom) repository from the Alliance for Open Media Git server into your project’s native source directory (typically app/src/main/cpp/).

git clone https://aomedia.googlesource.com/aom
cd aom

It is often safest to checkout a specific stable release tag rather than building directly from the master branch to ensure build stability.

Step 2: Configure CMake for Cross-Compilation

Libaom uses CMake, which integrates cleanly with the Android NDK’s toolchain file. You need to pass specific flags to CMake to ensure it cross-compiles for Android architectures (such as arm64-v8a or armeabi-v7a).

Create a build directory outside the source tree and run the CMake configuration command, pointing it to your NDK toolchain:

mkdir build_android && cd build_android

cmake ../aom \
  -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake \
  -DANDROID_ABI="arm64-v8a" \
  -DANDROID_PLATFORM=android-21 \
  -DENABLE_DOCS=OFF \
  -DENABLE_EXAMPLES=OFF \
  -DENABLE_TESTS=OFF \
  -DCONFIG_RUNTIME_CPU_DETECT=1 \
  -AOM_TARGET_CPU=arm64

• CONFIG_RUNTIME_CPU_DETECT: Crucial for Android, as it allows the library to optimize performance based on the specific ARM features available on the user’s device at runtime.
• ENABLE_EXAMPLES/TESTS/DOCS: Disabling these reduces build times and keeps the final binary size minimal.

Step 3: Compile the Library

Once CMake successfully generates the build files, compile the library using Make or Ninja:

cmake --build .

This generates the static library files (like libaom.a) inside your build directory.

Step 4: Link libaom in your Android Project

To use the compiled library in your Android application, update your project’s primary CMakeLists.txt file (located in app/src/main/cpp/CMakeLists.txt) to include and link libaom as a prebuilt library.

cmake_minimum_required(VERSION 3.10.2)

project("native-av1-app")

# Add the prebuilt libaom static library
add_library(libaom STATIC IMPORTED)
set_target_properties(libaom PROPERTIES
    IMPORTED_LOCATION "${CMAKE_CURRENT_SOURCE_DIR}/path_to_compiled_lib/libaom.a")

# Include libaom headers
include_directories("${CMAKE_CURRENT_SOURCE_DIR}/aom")

# Define your project's native native-lib
add_library(native-lib SHARED native-lib.cpp)

# Link libaom to your native library
target_link_libraries(native-lib libaom log)

Step 5: Configure build.gradle

Ensure your app-level build.gradle file is configured to compile for the corresponding ABIs you targeted during the libaom build phase:

android {
    defaultConfig {
        externalNativeBuild {
            cmake {
                abiFilters "arm64-v8a"
            }
        }
    }
    externalNativeBuild {
        cmake {
            path "src/main/cpp/CMakeLists.txt"
        }
    }
}

After syncing your project with the Gradle files, you can begin calling libaom APIs within your native-lib.cpp file and exposing them to your Java or Kotlin code via JNI.