android-opus-codec

Android wrapper around libopus 1.3.1 written on C++ and Kotlin.

🎯 Limitless Fork - 16KB Page Size Support

This is a fork of theeasiestway/android-opus-codec with Android 15+ compatibility for devices using 16KB memory pages.

What's Different?

Branch: feat/16kb-page-size-support

• ✅ All native libraries compiled with -Wl,-z,max-page-size=16384 linker flag
• ✅ Automated compileOpusLibraries Gradle task for building from source
• ✅ Fixed-point mode compilation for optimal mobile performance
• ✅ Custom fixed_generic.h shim for libopusenc compatibility
• ✅ Precompiled binaries removed (all libraries built fresh with correct alignment)
• ✅ Updated to target Android API 33 with flexible page size support

Why This Fork?

Starting November 1, 2025, Google Play requires all apps targeting Android 15+ to support 16KB page sizes. The original library's precompiled binaries use 4KB alignment and will fail this requirement. This fork compiles all libraries from source with proper 16KB alignment.

Integration

Add to your project's settings.gradle:

// Clone opus library with 16KB page size support
def opusDir = new File(rootDir, 'opus')
def opusRepoUrl = 'https://github.com/limitless-ai-inc/android-opus-codec.git'
def opusBranch = 'feat/16kb-page-size-support'

if (!opusDir.exists()) {
    println "Cloning opus library with 16KB support..."
    def cloneResult = "git clone -b ${opusBranch} ${opusRepoUrl} ${opusDir.absolutePath}".execute()
    cloneResult.waitFor()
    if (cloneResult.exitValue() != 0) {
        throw new GradleException("Failed to clone opus library: ${cloneResult.err.text}")
    }
}

include ':opus'
project(':opus').projectDir = new File(rootDir, 'opus/opus')

Then add the dependency in your app/build.gradle:

dependencies {
    implementation project(':opus')
}

That's it! The libraries will automatically compile with 16KB page size support during your build.

Requirements

• Android NDK 27.1.12297006 (or compatible version with 16KB support)
• Gradle 7.0+
• Android API 33+ (for flexible page size support)

Verification

You can verify the libraries have correct 16KB alignment using:

llvm-readelf -l path/to/libopus.so | grep LOAD
# Should show alignment of 0x4000 (16KB)

---

Supported features:

1. Encoding PCM audio into Opus.
2. Decoding Opus audio into PCM.
3. Sample rate of input audio from 8000Hz to 48000Hz.
4. Different frame sizes.
5. Mono or stereo input audio.
6. Input in bytes or shorts.
7. Output in bytes or shorts.
8. Convert from bytes to shorts and vice versa.
9. Bitrate setting.
10. Complexity setting.

Supported ABIs:

armeabi-v7a, arm64-v8a, x86, x86_64

How to use

Init encoder and decoder:

val SAMPLE_RATE = Constants.SampleRate._48000()       // samlpe rate of the input audio
val CHANNELS = Constants.Channels.stereo()            // type of the input audio mono or stereo 
val APPLICATION = Constants.Application.audio()       // coding mode of the encoder
var FRAME_SIZE = Constants.FrameSize._120()           // default frame size for 48000Hz

val codec = Opus()                                    // getting Codec instance
codec.encoderInit(SAMPLE_RATE, CHANNELS, APPLICATION) // init encoder
codec.decoderInit(SAMPLE_RATE, CHANNELS)              // init decoder

Setup the encoder:

/* this step is optional because the encoder can use default values */
val COMPLEXITY = Constants.Complexity.instance(10)    // encoder's algorithmic complexity 
val BITRATE = Constants.Bitrate.max()                 // encoder's bitrate
codec.encoderSetComplexity(COMPLEXITY)                // complexity setup
codec.encoderSetBitrate(BITRATE)                      // bitrate setup

Encoding:

val frame = ...                                       // get a chunk of audio from some source as an array of bytes or shorts
val encoded = codec.encode(frame, FRAME_SIZE)         // encode the audio chunk into Opus
if (encoded != null) Log.d("Opus", "encoded chunk size: ${encoded.size}")

Decoding:

val decoded = codec.decode(encoded, FRAME_SIZE)       // decode a chunk of audio into PCM
if (decoded != null) Log.d("Opus", "decoded chunk size: ${decoded.size}")

Releasing resources when the app closes:

codec.encoderRelease()
codec.decoderRelease()

Project structure

Project consists of two modules:

• app - here you can find a sample app that demonsrates ecoding, decoding and converting procedures by capturing an audio from device's mic and play it from a loud speaker. I recommend to check this app using a headphones, otherwise there may be echo in a hight levels of volume.
• opus - here you can find a C++ class that interacts with libopus 1.3.1 and JNI wrapper for interacting with it from Java/Kotlin layer.

Integration Method:

This fork uses source integration instead of precompiled AAR to ensure proper 16KB page alignment. When you include the :opus module in your project, Gradle will automatically compile the native libraries with correct alignment during your build.

Original AAR approach (not recommended for Android 15+):

• opus.aar - The original project provides a precompiled AAR with 4KB aligned binaries. This will not work on Android 15+ devices with 16KB pages. Use the source integration method above instead.