pure Rust opus implementation
  • Rust 99.6%
  • Shell 0.2%
  • C 0.1%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
8bit-Wraith ecefb7290b
Merge pull request #1 from 8b-is/copilot/port-fixed-point-dsp-backend
Complete CELT fixed-point DSP backend with tests and example decoder
2026-01-21 01:13:13 -05:00
.github/workflows Add DRED vector validation plumbing 2026-01-17 19:40:22 +08:00
ctests Add C/Rust comparisons for MDCT and synthesis 2026-01-18 01:01:09 +08:00
docs Add CELT fixed-point decoder example and documentation 2026-01-21 01:37:22 +00:00
examples Add CELT fixed-point decoder example and documentation 2026-01-21 01:37:22 +00:00
fuzz Document fuzzing and fix cargo-fuzz workspace 2026-01-17 23:43:44 +08:00
mousiki-deep-plc-weights Align deep PLC weights features and parsing 2026-01-17 00:30:24 +08:00
mousiki-dred-weights Align deep PLC weights features and parsing 2026-01-17 00:30:24 +08:00
opus-c@b5dc74f26f Align SILK range and gate DRED APIs 2026-01-03 23:26:45 +08:00
scripts Add DRED vector validation plumbing 2026-01-17 19:40:22 +08:00
src Port FIXED_POINT variants for vq and math functions 2026-01-21 01:29:31 +00:00
testdata port fuzz test 2025-09-23 15:49:55 +08:00
tests Add CELT fixed-point integration tests 2026-01-21 01:35:24 +00:00
.gitignore Add DRED vector validation plumbing 2026-01-17 19:40:22 +08:00
.gitmodules Pin opus-c to v1.5.2 (#190) 2026-01-02 23:39:33 +08:00
AGENTS.md Implement deep PLC output and update test strategy 2026-01-16 22:05:31 +08:00
Cargo.toml Document fuzzing and fix cargo-fuzz workspace 2026-01-17 23:43:44 +08:00
CLAUDE.md stereo fade 2026-01-11 23:31:15 +08:00
Dockerfile.opus-fuzz Document fuzzing status and Docker setup 2026-01-18 00:15:08 +08:00
FUZZING_PLAN.md Document fuzzing and fix cargo-fuzz workspace 2026-01-17 23:43:44 +08:00
FUZZING_STATUS.md Fix CELT synthesis output span and add fuzz regression 2026-01-18 02:04:17 +08:00
LICENSE add LICENSE 2025-09-23 16:50:21 +08:00
PORTING_STATUS.md Document fuzzing plan 2026-01-17 19:54:52 +08:00
README.md Document fuzzing and fix cargo-fuzz workspace 2026-01-17 23:43:44 +08:00
rustfmt.toml reformat (#4) 2025-06-17 10:23:41 +08:00

mousiki

A Rust port of the Xiph opus-c reference implementation. The core crate is #![no_std] and uses alloc (some APIs allocate).

Current coverage (high level)

  • Opus decode path mirrors opus_decode_native, including SILK/CELT/Hybrid, PLC/FEC, final-range reporting, and packet parsing; multistream decode and projection front-ends are wired.
  • Opus encode front-end supports SILK-only 10/20/40/60 ms packets (plus repacketized

    60 ms frames), CELT-only multiframe packing, and hybrid single-frame 10/20 ms payloads.

  • Repacketizer, packet helpers, extension padding, mapping/projection matrices, and tonality analysis are available.

Known gaps

  • Full encoder parity (hybrid multiframe, full CELT/HYBRID packing, remaining CTLs) is still pending.
  • Fixed-point decode backend, SIMD back-ends, and optional DRED/Deep PLC paths are not complete.
  • See PORTING_STATUS.md for detailed status.

Quick start

Run the examples

  • Decode Ogg Opus (SILK-only path used by decoder::Decoder) to a PCM file:
cargo run --example decode -- testdata/tiny.ogg output_mono.pcm
  • Play directly (requires an audio output device; uses cpal):
cargo run --example playback -- testdata/tiny.ogg

Run the tests

  • Full test suite:
cargo test --all-features
  • Decode integration test (ported from opus-c/tests/test_opus_decode.c):
cargo test --all-features --test test_opus_decode
  • Opt-in to the fuzz-heavy decode section (longer runtime), or to strict final-range checks:
TEST_OPUS_FUZZ=1 cargo test --all-features --test test_opus_decode
TEST_OPUS_STRICT_FINAL_RANGE=1 cargo test --all-features --test test_opus_decode
  • DRED vector validation (optional; vectors are distributed separately):
# Fetch vectors into testdata/dred_vectors (requires DRED_VECTORS_URL).
./scripts/fetch_dred_vectors.sh --url <vector-archive-url>

# Run the vector checks (uses DRED_VECTORS_PATH or testdata/dred_vectors).
# If deep_plc_weights is disabled, set DNN_BLOB or pass --dnn-blob.
DRED_VECTORS_PATH=testdata/dred_vectors cargo test --all-features --test dred_vectors

Fuzzing (manual/on-demand)

Fuzzing uses cargo-fuzz and is not part of CI by default.

cargo install cargo-fuzz
rustup toolchain install nightly
rustup run nightly cargo fuzz run decode_fuzzer

Seed corpus lives in fuzz/corpus/decode_fuzzer/.

Use in your code

The snippet below uses the lightweight decoder::Decoder (SILK-only, single-frame) to decode a single Opus packet into i16 PCM (mono, 48 kHz):

use mousiki::decoder::Decoder;

// `packet` is a single Opus SILK-only, mono packet (already decontainerized; not an Ogg page).
let packet: &[u8] = /* your Opus packet */;

// Output buffer (20 ms -> 960 samples, each sample is 2 bytes for i16)
let mut pcm_bytes = [0u8; 1920];

let mut decoder = Decoder::new();
let (_bandwidth, stereo) = decoder.decode(packet, &mut pcm_bytes)?;
assert!(!stereo, "mono only for now");
// `pcm_bytes` now contains 48 kHz i16 little-endian PCM data

For f32 output, use decode_float32 and a buffer of length 960 for a 20 ms frame:

use mousiki::decoder::Decoder;

let packet: &[u8] = /* your Opus packet */;
let mut pcm_f32 = [0.0f32; 960];

let mut decoder = Decoder::new();
let (_bandwidth, stereo) = decoder.decode_float32(packet, &mut pcm_f32)?;
assert!(!stereo);

Tip: If you need the full Opus API surface (stereo, CELT/Hybrid, multistream), use opus_decoder instead of decoder::Decoder. For Ogg input, see the oggreader example to extract raw Opus packets.

Compatibility and roadmap

  • Target environments: no_std + alloc, constrained memory, real-time systems.
  • The decoder::Decoder path remains SILK-only and single-frame; the full Opus API surface is exposed via opus_decoder/opus_encoder.
  • For detailed porting milestones, see PORTING_STATUS.md.

License and acknowledgements

  • License: MIT (see LICENSE).
  • Thanks to the upstream pion/opus (Go) implementation and the community.