oxideav-opus 0.0.9

Opus audio codec for oxideav — SILK + CELT decode (mono/stereo), CELT-only full-band encode, SILK-only encode (NB/MB/WB, mono+stereo, 10/20/40/60 ms)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116

#![allow(
    dead_code,
    clippy::needless_range_loop,
    clippy::excessive_precision,
    clippy::too_many_arguments
)]

//! Opus audio codec (RFC 6716 bitstream, RFC 7845 in-Ogg mapping).
//!
//! Decoder scope (see `decoder` module docs for the nitty-gritty):
//!
//! * `OpusHead` identification-packet parsing (RFC 7845 §5.1).
//! * Full TOC byte + framing code 0/1/2/3 packet parser (RFC 6716 §3).
//! * CELT-only frames at any bandwidth (NB/WB/SWB/FB), mono + stereo,
//!   2.5/5/10/20 ms — full §4.3 pipeline (range decode, coarse+fine+
//!   final band energy, bit allocation, PVQ shape, anti-collapse,
//!   IMDCT with overlap-add, comb post-filter).
//! * SILK-only frames at NB/MB/WB, mono + stereo, 10/20/40/60 ms —
//!   §4.2 pipeline (NLSF → LPC, LTP for voiced, excitation, synthesis,
//!   stereo MS→LR unmix, 8/12/16 → 48 kHz upsample).
//! * Silence / DTX frames (0 / 1-byte packets) produce correct-length
//!   silence output.
//!
//! Additional decoder modes:
//!
//! * Hybrid (SILK+CELT) frames (§4.4) — SILK WB body + CELT high band
//!   with a start_band offset (17 for FB, 14 for SWB), summed.
//! * SILK LBRR redundancy — flags are parsed and the redundancy
//!   bodies decode-and-discard via a scratch SILK state so the range
//!   coder stays aligned; loss-free output is unaffected.
//! * Channel mapping family 1 (Vorbis surround) and family 2
//!   (ambisonics) via the `MultistreamDecoder`.
//!
//! Encoder scope — see `encoder` module docs. Today the module exposes:
//!
//! * `OpusEncoder` — CELT-only Fullband mono/stereo 20 ms at 48 kHz.
//! * `SilkEncoder` — SILK-only Narrowband mono 20 ms (config 1),
//!   accepting 8 kHz or 48 kHz input. Round-trips through our own
//!   decoder at ≥ 20 dB SNR on speech-like signals.
//! * `HybridEncoder` — SILK-WB low band + CELT high band, mono
//!   20 ms, SWB (config 13) or FB (config 15). Single shared range-
//!   coded bitstream per RFC 6716 §4.4.

pub mod decoder;
pub mod encoder;
pub mod header;
pub mod silk;
pub mod toc;

use oxideav_core::{CodecCapabilities, CodecId, CodecParameters, CodecTag, Result};
use oxideav_core::{CodecInfo, CodecRegistry, Decoder, Encoder};

pub const CODEC_ID_STR: &str = "opus";

pub fn register_codecs(reg: &mut CodecRegistry) {
    let caps = CodecCapabilities::audio("opus_sw")
        .with_lossy(true)
        .with_max_channels(2)
        .with_max_sample_rate(48_000);
    // AVI / WAVEFORMATEX tags — Opus in AVI is non-standard but a few
    // third-party muxers have stamped these wFormatTag values on Opus
    // streams.
    reg.register(
        CodecInfo::new(CodecId::new(CODEC_ID_STR))
            .capabilities(caps)
            .decoder(make_decoder)
            .encoder(make_encoder)
            .tags([
                CodecTag::wave_format(0x4F70),
                CodecTag::wave_format(0x704F),
                CodecTag::wave_format(0x7075),
            ]),
    );
}

/// Unified registration entry point — installs Opus into the codec
/// sub-registry of the supplied [`oxideav_core::RuntimeContext`].
pub fn register(ctx: &mut oxideav_core::RuntimeContext) {
    register_codecs(&mut ctx.codecs);
}

oxideav_core::register!("opus", register);

fn make_decoder(params: &CodecParameters) -> Result<Box<dyn Decoder>> {
    decoder::make_decoder(params)
}

fn make_encoder(params: &CodecParameters) -> Result<Box<dyn Encoder>> {
    encoder::make_encoder(params)
}

pub use decoder::MultistreamOpusDecoder;
pub use header::{parse_opus_head, OpusHead};
pub use toc::{
    parse_packet, parse_self_delimited_packet, OpusBandwidth, OpusMode, OpusPacket, Toc,
};

#[cfg(test)]
mod register_tests {
    use super::*;

    #[test]
    fn register_via_runtime_context_installs_codec_factory() {
        let mut ctx = oxideav_core::RuntimeContext::new();
        register(&mut ctx);
        let id = CodecId::new(CODEC_ID_STR);
        assert!(
            ctx.codecs.has_decoder(&id),
            "decoder factory not installed via RuntimeContext"
        );
        assert!(
            ctx.codecs.has_encoder(&id),
            "encoder factory not installed via RuntimeContext"
        );
    }
}