Metadata-Version: 2.4
Name: ruopus
Version: 0.1.1
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Rust
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Multimedia :: Sound/Audio :: Conversion
Classifier: Typing :: Typed
Requires-Dist: maturin>=1.14.1
Requires-Dist: numpy>=1.22
Requires-Dist: sphinx>=7.0.0 ; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=2.0.0 ; extra == 'docs'
Requires-Dist: myst-parser>=2.0.0 ; extra == 'docs'
Requires-Dist: pytest>=7.4.0 ; extra == 'test'
Requires-Dist: numpy>=1.22 ; extra == 'test'
Provides-Extra: docs
Provides-Extra: test
License-File: LICENSE
Summary: A pure-Rust implementation of the Opus audio codec (RFC 6716) - fast, with first-class NumPy interop.
Keywords: opus,audio,codec,rfc6716,rust,numpy
Author-email: "Jack Geraghty (jmg049)" <jgeraghty049@gmail.com>
Maintainer-email: "Jack Geraghty (jmg049)" <jgeraghty049@gmail.com>
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Bug Reports, https://github.com/jmg049/ruopus/issues
Project-URL: Documentation, https://docs.rs/ruopus
Project-URL: Homepage, https://github.com/jmg049/ruopus
Project-URL: Repository, https://github.com/jmg049/ruopus

# ruopus

[![Crates.io](https://img.shields.io/crates/v/ruopus.svg)](https://crates.io/crates/ruopus)
[![docs.rs](https://img.shields.io/docsrs/ruopus)](https://docs.rs/ruopus)
[![PyPI](https://img.shields.io/pypi/v/ruopus.svg)](https://pypi.org/project/ruopus/)
[![MSRV](https://img.shields.io/badge/rustc-1.85%2B-orange.svg)](https://blog.rust-lang.org/2025/02/20/Rust-1.85.0.html)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

A pure-Rust implementation of the [Opus audio codec](https://opus-codec.org/)
([RFC 6716](https://www.rfc-editor.org/rfc/rfc6716)): decoder and encoder, with
no C and no FFI.

**Pure Rust. `unsafe` only in a few SIMD kernels, every one checked under
[Miri](https://github.com/rust-lang/miri). Runs on stable Rust**

> The decoder passes the official Opus conformance vectors, and the encoder produces standard Opus that libopus and ffmpeg decode.

Python bindings are available on [PyPI](https://pypi.org/project/ruopus/).


## Overview

`ruopus` is a from-scratch Rust implementation of Opus. It links no
`libopus`, needs no C toolchain, and exposes plain `&[u8]`/`&[i16]`/`&[f32]`
interfaces, so it embeds under any audio stack.

- Pure Rust, no FFI. Builds on `wasm32`. The decoder is `no_std` + `alloc`
  (build with `default-features = false, features = ["libm"]`); the encoder
  currently needs `std`.
- `unsafe` is denied by default. The only exceptions are a few `std::arch` SIMD
  hot loops, each carrying a `// SAFETY:` note ([`docs/unsafe.md`](docs/unsafe.md))
  and checked for undefined behaviour by Miri on both the SSE2 and AVX2 paths
  (`tools/miri.sh`). No `portable_simd`, no inline asm.
- Zero required dependencies. The default build adds one optional FFT crate for
  faster decoding; `default-features = false` is fully dependency-free.

## Use

```toml
[dependencies]
ruopus = "0.1"
```

```rust
use ruopus::{OpusDecoder, OpusEncoder};

// Decode Opus packets to interleaved f32 PCM.
let mut dec = OpusDecoder::new(2); // channels
let pcm = dec.decode_packet(&packet)?;

// Encode 48 kHz PCM (one 20 ms frame is 960 samples per channel, interleaved).
let mut enc = OpusEncoder::new(1);
enc.set_bitrate(Some(24_000));
let packet = enc.encode_auto(&pcm_960, 4000)?;
```

```rust
// Whole Ogg Opus files.
let (pcm, head) = ruopus::decode_ogg_opus(&bytes)?;
let ogg = ruopus::encode_ogg_opus(&pcm, 2, 96_000);
```

## Python

Install from [PyPI](https://pypi.org/project/ruopus/):

```sh
pip install ruopus
```

The bindings wrap `OpusDecoder` and `OpusEncoder` with NumPy interop — decoded
PCM is returned as a `(frames, channels) float32` array; the encoder accepts the
same shape or a flat interleaved array.

```python
import numpy as np
import ruopus

# Decode
dec = ruopus.OpusDecoder(channels=2, sample_rate=48_000)
pcm = dec.decode_packet(packet)          # ndarray (frames, 2), float32

# Encode
enc = ruopus.OpusEncoder(channels=2, bitrate=64_000)
frame = np.zeros((960, 2), dtype=np.float32)   # 20 ms at 48 kHz
packet = enc.encode(frame)               # bytes
```

## Performance

Measured against libopus 1.6.1 (SIMD-enabled C) on identical data, one core,
pinned to a single performance core: `cargo bench --bench vs_libopus --features
std`. Figures are x realtime; "ratio" is ruopus divided by libopus.

**Decode**

| Mode | ruopus | libopus | ratio |
|------|-------------|---------|-------|
| SILK wideband 16 kb/s | 2095x | 1171x | 1.79x |
| hybrid fullband 32 kb/s | 1199x | 850x | 1.41x |
| CELT fullband 64 kb/s | 1389x | 1566x | 0.89x |

Speech decode (SILK, hybrid) is faster than SIMD libopus. CELT trails on the
MDCT, where libopus's SIMD wins.

**Encode** (matched complexity)

| Mode | ruopus | libopus | ratio |
|------|-------------|---------|-------|
| SILK wideband 16 kb/s | 734x | 740x | 0.99x |
| hybrid fullband 32 kb/s | 560x | 562x | 1.00x |
| CELT fullband 64 kb/s | 1088x | 1092x | 1.00x |

At matched complexity, encode is at parity with libopus across all modes.
Against libopus at its default complexity it runs 1.6 to 3.2x faster (it does
not yet spend cycles on delayed-decision NSQ or warped noise shaping).

## Conformance

Passes the official Opus conformance criterion: all twelve
[RFC 8251 test vectors](https://opus-codec.org/testvectors/) score 99.2 to 100%
on opus_compare, with per-packet final ranges bit-exact. Fetch the vectors with
`tools/fetch-testvectors.sh` (about 121 MB, not committed); the conformance
tests skip cleanly without them.

## License

MIT, see [LICENSE](LICENSE). The Opus format is royalty-free; see the
[Opus IPR statements](https://datatracker.ietf.org/ipr/search/?rfc=6716&submit=rfc).

