# android-opus-codec

**Repository Path**: l6yang/android-opus-codec

## Basic Information

- **Project Name**: android-opus-codec
- **Description**: 音频opus编解码
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: develop
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-03
- **Last Updated**: 2026-04-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# android-opus-codec

Android wrapper around [libopus 1.3.1](https://opus-codec.org/release/stable/2019/04/12/libopus-1_3_1.html) written on C++ and Kotlin.

## 🎯 Limitless Fork - 16KB Page Size Support

This is a fork of [theeasiestway/android-opus-codec](https://github.com/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`:

```groovy
// 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`:

```groovy
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:

```bash
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:
```kotlin
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:
```kotlin
/* 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:
```kotlin
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:
```kotlin
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:
```kotlin
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](https://opus-codec.org/release/stable/2019/04/12/libopus-1_3_1.html) 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.