ruopus Documentation

ruopus is a pure-Rust implementation of the Opus audio codec (RFC 6716) with first-class Python/NumPy interop. PCM crosses the Rust/Python boundary as NumPy arrays shaped (frames, channels), moved out of Rust without an extra copy. The GIL is released for all encode/decode operations.

Features

Encoding:

  • Three encode paths: automatic mode selection (SILK/hybrid/CELT), forced CELT, forced SILK, or hybrid

  • Full encoder control: complexity, bitrate (CBR/VBR), DTX, in-band FEC, bandwidth, signal hint, application profile

  • Ogg Opus output: single-call convenience for writing complete Ogg Opus files

Decoding:

  • float32 and int16 output: decode_packet / decode_packet_i16

  • Packet loss concealment: decode_lost extrapolates the last pitch period

  • In-band FEC recovery: decode_fec reconstructs a lost frame from its successor

  • Ogg Opus input: demuxing, pre-skip removal, end trimming, and output gain

Packet Introspection:

  • TOC parsing: mode, bandwidth, frame size, channel count from the single header byte

  • Packet parsing: frame extraction for standard and self-delimited framing (RFC 6716 §3 and Appendix B)

Advanced:

  • Multistream decoding: surround layouts via MultistreamDecoder (RFC 7845)

  • Low-level layers: direct access to SILK, LPC arithmetic, and CELT codecs below the packet layer

Quick Examples

Encode and Decode

import numpy as np
import ruopus

enc = ruopus.OpusEncoder(2, bitrate=64_000)          # stereo, 64 kbps
dec = ruopus.OpusDecoder(2)

frame = np.zeros((960, 2), dtype=np.float32)         # 20 ms stereo at 48 kHz
packet = enc.encode_auto(frame)                      # -> bytes
pcm    = dec.decode_packet(packet)                   # -> (960, 2) float32

Ogg Opus Round-Trip

import numpy as np
import ruopus

samples = np.random.randn(48_000 * 5).astype(np.float32)   # 5 s mono
ogg_bytes = ruopus.encode_ogg_opus(samples, channels=1, bitrate=96_000)

pcm, head = ruopus.decode_ogg_opus(ogg_bytes)
print(f"Decoded {pcm.shape[0] / 48_000:.2f} s, {head.channel_count}-ch")

Packet Inspection

import ruopus

pkt = ruopus.Packet(raw_bytes)
print(f"mode={pkt.toc.mode}, bw={pkt.toc.bandwidth}, frames={len(pkt)}")

Installation

pip install ruopus

Build from source (requires a Rust toolchain and maturin):

git clone https://github.com/jmg049/ruopus
cd ruopus
pip install maturin
maturin develop --release

Contents

User Guide

API Reference

Indices and Tables