
Low-latency Opus codec access: encoding, decoding, packet inspection, repacketization and soft‑clipping, unified C ABI with shared argument validation and embedded synchronous WebAssembly and native modules.
Kotlin Multiplatform bindings for Opus, the low-latency interactive audio codec: encoding, decoding, packet inspection and repacketization on JVM, Android, Kotlin/Native and the web.
opus is included as a Git submodule and compiled from source for every
target. One C ABI, jni/include/opus_kmp.h, feeds
the JNI bridge, the Kotlin/Native cinterop and the WebAssembly build, so every
platform shares the same argument validation, buffer ownership and packet
semantics. The portable floating-point build with runtime CPU dispatch disabled
is used everywhere: one code path across x86, ARM, Android, MinGW and
WebAssembly.
Binding version: 1.0.1-fixed.1.5.2 (Opus 1.5.2).
| Platform | Kotlin target | Native artifact |
|---|---|---|
| JVM | jvm |
opus-kmp-jni-jvm-{linux,darwin}-{x86_64,aarch64}, opus-kmp-jni-jvm-windows-x86_64
|
| Android | android |
opus-kmp AAR with libopus_jni.so for every ABI |
| Android Native |
androidNativeArm64, androidNativeArm32, androidNativeX64, androidNativeX86
|
static archive embedded in the cinterop klib |
| Linux |
linuxX64, linuxArm64
|
static archive embedded in the cinterop klib |
| Windows | mingwX64 |
static archive embedded in the cinterop klib |
| macOS |
macosX64, macosArm64
|
static archive embedded in the cinterop klib |
| Kotlin/JS | js |
embedded WebAssembly module |
| Kotlin/Wasm | wasmJs |
embedded WebAssembly module |
The web targets compile Opus and the C shim to a standalone .wasm module with
Emscripten, embed its bytes into the published klib and instantiate it
synchronously through a small JS bridge. No resource lookup or async
initialization is required at runtime.
The same module is also published to npm as @enaium/opus-kmp for plain
JavaScript/TypeScript web apps. Stage it with
./gradlew :opus-kmp:assembleWasmNpm; it contains opus_wasm.wasm and
opus_kmp_glue.js, whose initOpusKmp() installs the C shim on
globalThis.__opusWeb. Kotlin consumers do not need the npm package.
dependencies {
implementation("cn.enaium.opus:opus-kmp:1.0.1-fixed.1.5.2")
}The Android AAR and the JVM artifacts contain the native libraries. JVM
consumers automatically receive the per-OS/arch JNI artifacts and
NativeLoader extracts the matching one from the classpath.
Opus accepts 8, 12, 16, 24 and 48 kHz, one or two channels, and frame durations of 2.5, 5, 10, 20, 40 or 60 ms. At 48 kHz a 20 ms frame is 960 samples per channel.
import cn.enaium.opus.*
val encoder = OpusEncoder.open(48_000, channels = 1, OpusApplication.AUDIO)
val decoder = OpusDecoder.open(48_000, channels = 1)
try {
encoder.bitrate = 32_000
encoder.complexity = 8
encoder.vbr = true
encoder.inbandFec = true
encoder.packetLossPercent = 10
encoder.dtx = true
while (hasPcm()) {
val pcm = readFrame(encoder.frameSizeSamples(20.0)) // ShortArray, 16-bit
val packet = encoder.encode(pcm)
if (packet.isNotEmpty()) {
sink.write(packet)
speaker.write(decoder.decode(packet))
}
}
// A lost packet: run packet-loss concealment instead of consuming input.
speaker.write(decoder.decode(null, frameSize = 960))
} finally {
encoder.close()
decoder.close()
}encode also accepts an offset, an explicit frame size and a packet-size
budget. The floating-point API uses FloatArray in -1..1:
val packet = encoder.encodeFloat(samples) // FloatArray
val samples = decoder.decodeFloat(packet) // FloatArrayOpusDecoder.decode(null) conceals a lost packet; decodeFec(packet) recovers
the previous frame from the in-band FEC of the following packet.
val bandwidth = OpusPacket.bandwidth(packet) // OpusBandwidth
val frames = OpusPacket.frameCount(packet) // 1..48
val samples = OpusPacket.sampleCount(packet, sampleRate) // per channel
val hasFec = OpusPacket.hasLbrr(packet)
val frameBytes = OpusPacket.frames(packet) // List<ByteArray>OpusPacket.pad and OpusPacket.unpad adjust padding without re-encoding.
OpusRepacketizer combines and splits packets without decoding audio. All
input packets must use the same TOC configuration.
OpusRepacketizer().use { repacketizer ->
repacketizer.cat(first)
repacketizer.cat(second)
val combined = repacketizer.out() // one 40 ms packet
val single = repacketizer.outRange(0, 1) // the first 20 ms frame
}val clipped = Opus.softClip(floats, frameSize = 960, channels = 1)println(Opus.version) // "libopus 1.5.2"
Opus.strerror(-4) // "Invalid packet"
// Every rejected call throws OpusException with the negative Opus code.examples/visual is a Kotlin Multiplatform Dear ImGui application (imgui-kmp +
SDL3). It drives an encoder/decoder pair and plots the input, the decoded output
and the packet-size history through ImPlot. The input source is either a
synthetic speech-like signal or a real microphone captured through audio-io-kmp
(Core Audio, ALSA, WASAPI or Android AudioRecord); mono capture can feed either
one or both Opus channels.
./gradlew :examples:visual:jvmRun
./gradlew :examples:visual:jvmRun --args="--channels 2"
./gradlew :examples:visual:jvmRun --args="--microphone"
# or a standalone native executable:
./gradlew :examples:visual:linkDebugExecutableMacosArm64
OPUS_KMP_CHANNELS=2 ./examples/visual/build/bin/macosArm64/debugExecutable/visual.kexe
OPUS_KMP_MICROPHONE=1 ./examples/visual/build/bin/macosArm64/debugExecutable/visual.kexeThe same UI runs on Android through a thin SDLActivity host. The Android app
module uses the pure-JVM Android path: the common ImGui loop runs on SDL's
dedicated thread while the AARs supply libopus_jni.so, libimgui_jni.so and
libsdl_jni.so for every ABI.
./gradlew :examples:visual:android-app:assembleDebug
adb install -r examples/visual/android/build/outputs/apk/debug/android-app-debug.apk
adb shell am start -n cn.enaium.opus.examples.visual.android/.MainActivityThe app runs in landscape, scales the ImGui font and control widths by the
display density, and asks for RECORD_AUDIO at startup. Choose microphone in
the source combo to switch the visualizer from the synthetic signal to the
device input. Intent extras make automated runs deterministic:
adb shell am start -n cn.enaium.opus.examples.visual.android/.MainActivity \
--ei channels 2 --ez microphone trueHeadless smoke run:
SDL_VIDEO_DRIVER=dummy OPUS_KMP_FRAMES=30 \
./examples/visual/build/bin/macosArm64/debugExecutable/visual.kexe# host targets
./gradlew :opus-kmp:jvmTest :opus-kmp:macosArm64Test
# web (needs emsdk on PATH or in ~/emsdk)
./gradlew :opus-kmp:jsNodeTest :opus-kmp:wasmJsNodeTest
# Android AAR and per-ABI JNI libraries (needs Android NDK 27)
./gradlew :opus-kmp:bundleAndroidMainAar :opus-kmp:buildAndroidJniLibs
# local Maven publication
./gradlew :opus-kmp:publishToMavenLocal
# npm package staging
./gradlew :opus-kmp:assembleWasmNpmThe library uses CMake for every native artifact. Configure it directly when debugging a platform:
cmake -S jni -B build -DBUILD_JNI=ON -DOPUS_DIR=$PWD/opus
cmake --build build --target opus_jni
emcmake cmake -S jni -B build-wasm -DBUILD_WASM=ON -DOPUS_DIR=$PWD/opus
cmake --build build-wasm --target opus_wasm.github/workflows/ci.yml publishes every host artifact to Maven Local, runs
the JVM/native/web tests and builds the visual example headlessly.
.github/workflows/release.yml releases to Maven Central from three runners
(macOS, Linux, Windows) and then publishes the npm package. Disable the npm job
with publish_npm=false when publishing npm from a local Gradle instead. It needs these
repository secrets:
| Secret | Purpose |
|---|---|
MAVEN_CENTRAL_USERNAME / MAVEN_CENTRAL_PASSWORD
|
Sonatype Central Portal user token |
SIGNING_KEY / SIGNING_KEY_ID / SIGNING_PASSWORD
|
PGP signing key, base64-encoded binary ring |
NPM_PUBLISH_KEY |
npm token for @enaium/opus-kmp
|
npm requires semver. A four-component binding version is published with its
fourth component as a prerelease suffix (1.5.2.1 becomes npm 1.5.2-1); a
version that is already valid semver, such as 1.0.1-fixed.1.5.2, is published
unchanged.
This binding is MIT-licensed. Opus itself is BSD-3-Clause; see
opus/COPYING.
Kotlin Multiplatform bindings for Opus, the low-latency interactive audio codec: encoding, decoding, packet inspection and repacketization on JVM, Android, Kotlin/Native and the web.
opus is included as a Git submodule and compiled from source for every
target. One C ABI, jni/include/opus_kmp.h, feeds
the JNI bridge, the Kotlin/Native cinterop and the WebAssembly build, so every
platform shares the same argument validation, buffer ownership and packet
semantics. The portable floating-point build with runtime CPU dispatch disabled
is used everywhere: one code path across x86, ARM, Android, MinGW and
WebAssembly.
Binding version: 1.0.1-fixed.1.5.2 (Opus 1.5.2).
| Platform | Kotlin target | Native artifact |
|---|---|---|
| JVM | jvm |
opus-kmp-jni-jvm-{linux,darwin}-{x86_64,aarch64}, opus-kmp-jni-jvm-windows-x86_64
|
| Android | android |
opus-kmp AAR with libopus_jni.so for every ABI |
| Android Native |
androidNativeArm64, androidNativeArm32, androidNativeX64, androidNativeX86
|
static archive embedded in the cinterop klib |
| Linux |
linuxX64, linuxArm64
|
static archive embedded in the cinterop klib |
| Windows | mingwX64 |
static archive embedded in the cinterop klib |
| macOS |
macosX64, macosArm64
|
static archive embedded in the cinterop klib |
| Kotlin/JS | js |
embedded WebAssembly module |
| Kotlin/Wasm | wasmJs |
embedded WebAssembly module |
The web targets compile Opus and the C shim to a standalone .wasm module with
Emscripten, embed its bytes into the published klib and instantiate it
synchronously through a small JS bridge. No resource lookup or async
initialization is required at runtime.
The same module is also published to npm as @enaium/opus-kmp for plain
JavaScript/TypeScript web apps. Stage it with
./gradlew :opus-kmp:assembleWasmNpm; it contains opus_wasm.wasm and
opus_kmp_glue.js, whose initOpusKmp() installs the C shim on
globalThis.__opusWeb. Kotlin consumers do not need the npm package.
dependencies {
implementation("cn.enaium.opus:opus-kmp:1.0.1-fixed.1.5.2")
}The Android AAR and the JVM artifacts contain the native libraries. JVM
consumers automatically receive the per-OS/arch JNI artifacts and
NativeLoader extracts the matching one from the classpath.
Opus accepts 8, 12, 16, 24 and 48 kHz, one or two channels, and frame durations of 2.5, 5, 10, 20, 40 or 60 ms. At 48 kHz a 20 ms frame is 960 samples per channel.
import cn.enaium.opus.*
val encoder = OpusEncoder.open(48_000, channels = 1, OpusApplication.AUDIO)
val decoder = OpusDecoder.open(48_000, channels = 1)
try {
encoder.bitrate = 32_000
encoder.complexity = 8
encoder.vbr = true
encoder.inbandFec = true
encoder.packetLossPercent = 10
encoder.dtx = true
while (hasPcm()) {
val pcm = readFrame(encoder.frameSizeSamples(20.0)) // ShortArray, 16-bit
val packet = encoder.encode(pcm)
if (packet.isNotEmpty()) {
sink.write(packet)
speaker.write(decoder.decode(packet))
}
}
// A lost packet: run packet-loss concealment instead of consuming input.
speaker.write(decoder.decode(null, frameSize = 960))
} finally {
encoder.close()
decoder.close()
}encode also accepts an offset, an explicit frame size and a packet-size
budget. The floating-point API uses FloatArray in -1..1:
val packet = encoder.encodeFloat(samples) // FloatArray
val samples = decoder.decodeFloat(packet) // FloatArrayOpusDecoder.decode(null) conceals a lost packet; decodeFec(packet) recovers
the previous frame from the in-band FEC of the following packet.
val bandwidth = OpusPacket.bandwidth(packet) // OpusBandwidth
val frames = OpusPacket.frameCount(packet) // 1..48
val samples = OpusPacket.sampleCount(packet, sampleRate) // per channel
val hasFec = OpusPacket.hasLbrr(packet)
val frameBytes = OpusPacket.frames(packet) // List<ByteArray>OpusPacket.pad and OpusPacket.unpad adjust padding without re-encoding.
OpusRepacketizer combines and splits packets without decoding audio. All
input packets must use the same TOC configuration.
OpusRepacketizer().use { repacketizer ->
repacketizer.cat(first)
repacketizer.cat(second)
val combined = repacketizer.out() // one 40 ms packet
val single = repacketizer.outRange(0, 1) // the first 20 ms frame
}val clipped = Opus.softClip(floats, frameSize = 960, channels = 1)println(Opus.version) // "libopus 1.5.2"
Opus.strerror(-4) // "Invalid packet"
// Every rejected call throws OpusException with the negative Opus code.examples/visual is a Kotlin Multiplatform Dear ImGui application (imgui-kmp +
SDL3). It drives an encoder/decoder pair and plots the input, the decoded output
and the packet-size history through ImPlot. The input source is either a
synthetic speech-like signal or a real microphone captured through audio-io-kmp
(Core Audio, ALSA, WASAPI or Android AudioRecord); mono capture can feed either
one or both Opus channels.
./gradlew :examples:visual:jvmRun
./gradlew :examples:visual:jvmRun --args="--channels 2"
./gradlew :examples:visual:jvmRun --args="--microphone"
# or a standalone native executable:
./gradlew :examples:visual:linkDebugExecutableMacosArm64
OPUS_KMP_CHANNELS=2 ./examples/visual/build/bin/macosArm64/debugExecutable/visual.kexe
OPUS_KMP_MICROPHONE=1 ./examples/visual/build/bin/macosArm64/debugExecutable/visual.kexeThe same UI runs on Android through a thin SDLActivity host. The Android app
module uses the pure-JVM Android path: the common ImGui loop runs on SDL's
dedicated thread while the AARs supply libopus_jni.so, libimgui_jni.so and
libsdl_jni.so for every ABI.
./gradlew :examples:visual:android-app:assembleDebug
adb install -r examples/visual/android/build/outputs/apk/debug/android-app-debug.apk
adb shell am start -n cn.enaium.opus.examples.visual.android/.MainActivityThe app runs in landscape, scales the ImGui font and control widths by the
display density, and asks for RECORD_AUDIO at startup. Choose microphone in
the source combo to switch the visualizer from the synthetic signal to the
device input. Intent extras make automated runs deterministic:
adb shell am start -n cn.enaium.opus.examples.visual.android/.MainActivity \
--ei channels 2 --ez microphone trueHeadless smoke run:
SDL_VIDEO_DRIVER=dummy OPUS_KMP_FRAMES=30 \
./examples/visual/build/bin/macosArm64/debugExecutable/visual.kexe# host targets
./gradlew :opus-kmp:jvmTest :opus-kmp:macosArm64Test
# web (needs emsdk on PATH or in ~/emsdk)
./gradlew :opus-kmp:jsNodeTest :opus-kmp:wasmJsNodeTest
# Android AAR and per-ABI JNI libraries (needs Android NDK 27)
./gradlew :opus-kmp:bundleAndroidMainAar :opus-kmp:buildAndroidJniLibs
# local Maven publication
./gradlew :opus-kmp:publishToMavenLocal
# npm package staging
./gradlew :opus-kmp:assembleWasmNpmThe library uses CMake for every native artifact. Configure it directly when debugging a platform:
cmake -S jni -B build -DBUILD_JNI=ON -DOPUS_DIR=$PWD/opus
cmake --build build --target opus_jni
emcmake cmake -S jni -B build-wasm -DBUILD_WASM=ON -DOPUS_DIR=$PWD/opus
cmake --build build-wasm --target opus_wasm.github/workflows/ci.yml publishes every host artifact to Maven Local, runs
the JVM/native/web tests and builds the visual example headlessly.
.github/workflows/release.yml releases to Maven Central from three runners
(macOS, Linux, Windows) and then publishes the npm package. Disable the npm job
with publish_npm=false when publishing npm from a local Gradle instead. It needs these
repository secrets:
| Secret | Purpose |
|---|---|
MAVEN_CENTRAL_USERNAME / MAVEN_CENTRAL_PASSWORD
|
Sonatype Central Portal user token |
SIGNING_KEY / SIGNING_KEY_ID / SIGNING_PASSWORD
|
PGP signing key, base64-encoded binary ring |
NPM_PUBLISH_KEY |
npm token for @enaium/opus-kmp
|
npm requires semver. A four-component binding version is published with its
fourth component as a prerelease suffix (1.5.2.1 becomes npm 1.5.2-1); a
version that is already valid semver, such as 1.0.1-fixed.1.5.2, is published
unchanged.
This binding is MIT-licensed. Opus itself is BSD-3-Clause; see
opus/COPYING.