oxideav_opus/
toc.rs

1//! Opus packet TOC byte parser.
2//!
3//! Implements the Table-of-Contents header described in RFC 6716 §3.1.
4//! The first byte of every well-formed Opus packet contains:
5//!
6//! ```text
7//!                              0
8//!                              0 1 2 3 4 5 6 7
9//!                             +-+-+-+-+-+-+-+-+
10//!                             | config  |s| c |
11//!                             +-+-+-+-+-+-+-+-+
12//! ```
13//!
14//! * `config` — five bits (bit 0 is the MSB per RFC 6716 numbering),
15//!   selecting one of 32 (mode, bandwidth, frame-size) tuples per
16//!   Table 2.
17//! * `s` — one bit: 0 = mono, 1 = stereo per Table 3 (informal —
18//!   described in prose immediately after Table 2 in the RFC).
19//! * `c` — two bits: code 0..3, the frame-packing code per Table 4
20//!   (also described in the prose at the end of §3.1).
21//!
22//! Only the TOC byte interpretation is implemented here. Frame
23//! packing per §3.2 and the SILK / CELT inner decoders are out of
24//! scope for round 1.
25
26use core::fmt;
27
28use crate::Error;
29
30/// Operating mode selected by the `config` field of the TOC byte.
31///
32/// Per RFC 6716 §3.1 Table 2 the 32 configurations cluster into
33/// three operating modes: a SILK-only LP mode, a Hybrid SILK+CELT
34/// mode, and a CELT-only MDCT mode.
35#[derive(Debug, Clone, Copy, PartialEq, Eq)]
36pub enum Mode {
37    /// LP (SILK) only — used at low bitrates up to WB.
38    SilkOnly,
39    /// Hybrid SILK + CELT — used for SWB / FB speech at medium
40    /// bitrates.
41    Hybrid,
42    /// CELT (MDCT) only — used for very low delay and music
43    /// transmission.
44    CeltOnly,
45}
46
47/// Audio bandwidth selected by the `config` field of the TOC byte.
48///
49/// The five bandwidths per RFC 6716 §2:
50///
51/// * NB — narrowband, 4 kHz effective, 8 kHz sample rate equivalent.
52/// * MB — medium band, 6 kHz effective.
53/// * WB — wideband, 8 kHz effective.
54/// * SWB — super-wideband, 12 kHz effective.
55/// * FB — fullband, 20 kHz effective.
56#[derive(Debug, Clone, Copy, PartialEq, Eq)]
57pub enum Bandwidth {
58    Nb,
59    Mb,
60    Wb,
61    Swb,
62    Fb,
63}
64
65/// Channel mapping signalled by the `s` bit of the TOC byte.
66#[derive(Debug, Clone, Copy, PartialEq, Eq)]
67pub enum ChannelMapping {
68    /// `s = 0` — one channel.
69    Mono,
70    /// `s = 1` — two channels.
71    Stereo,
72}
73
74/// Frame-packing code signalled by the `c` field of the TOC byte
75/// (RFC 6716 §3.1, immediately after Table 2).
76#[derive(Debug, Clone, Copy, PartialEq, Eq)]
77pub enum FrameCountCode {
78    /// Code 0 — exactly one frame in the packet.
79    One,
80    /// Code 1 — exactly two frames, both compressed to the same size.
81    TwoEqual,
82    /// Code 2 — exactly two frames with independent compressed sizes.
83    TwoUnequal,
84    /// Code 3 — arbitrary frame count, encoded in a following byte.
85    Arbitrary,
86}
87
88/// Decoded interpretation of a single Opus packet TOC byte.
89///
90/// This does not consume any bytes beyond the TOC byte itself — frame
91/// packing (the second byte for code 3, the length sequence for
92/// code 2, etc.) is the §3.2 layer and lives elsewhere.
93#[derive(Debug, Clone, Copy, PartialEq, Eq)]
94pub struct OpusTocByte {
95    /// Raw `config` value (0..31).
96    pub config: u8,
97    /// Operating mode selected by `config`.
98    pub mode: Mode,
99    /// Audio bandwidth selected by `config`.
100    pub bandwidth: Bandwidth,
101    /// Per-frame duration in tenths of a millisecond.
102    ///
103    /// Encoded in tenths because RFC 6716 allows 2.5 ms (= 25) which
104    /// is not representable in whole milliseconds. The legal values
105    /// per Table 2 are 25, 50, 100, 200, 400, 600.
106    pub frame_size_tenths_ms: u16,
107    /// Channel mapping signalled by `s`.
108    pub channels: ChannelMapping,
109    /// Frame-packing code signalled by `c`.
110    pub frame_count_code: FrameCountCode,
111}
112
113impl OpusTocByte {
114    /// Parse the TOC byte from the front of an Opus packet.
115    ///
116    /// Returns [`Error::EmptyPacket`] if `packet` is empty (RFC 6716
117    /// §3.1 requirement R1). Any non-empty packet has a syntactically
118    /// valid TOC byte by construction (every five-bit `config` value
119    /// is assigned, every `s` and `c` value is assigned), so the only
120    /// failure mode is the empty-packet case.
121    pub fn parse(packet: &[u8]) -> Result<Self, Error> {
122        let first = *packet.first().ok_or(Error::EmptyPacket)?;
123        Ok(Self::from_byte(first))
124    }
125
126    /// Decode an isolated TOC byte. Total function — every `u8` is a
127    /// valid TOC byte.
128    pub fn from_byte(byte: u8) -> Self {
129        // RFC 6716 §3.1 numbers bit 0 as the most significant bit.
130        // In u8 terms (bit 7 = MSB): config is the top 5 bits,
131        // s is bit 2 (counted from LSB), c is the low 2 bits.
132        let config = byte >> 3;
133        let s = (byte >> 2) & 0x01;
134        let c = byte & 0x03;
135
136        let (mode, bandwidth, frame_size_tenths_ms) = decode_config(config);
137        let channels = if s == 0 {
138            ChannelMapping::Mono
139        } else {
140            ChannelMapping::Stereo
141        };
142        let frame_count_code = match c {
143            0 => FrameCountCode::One,
144            1 => FrameCountCode::TwoEqual,
145            2 => FrameCountCode::TwoUnequal,
146            3 => FrameCountCode::Arbitrary,
147            _ => unreachable!("c is masked to 2 bits"),
148        };
149
150        Self {
151            config,
152            mode,
153            bandwidth,
154            frame_size_tenths_ms,
155            channels,
156            frame_count_code,
157        }
158    }
159
160    /// Compose the TOC byte for a `(mode, bandwidth, frame size)`
161    /// triple plus the channel flag and frame-count code — the inverse
162    /// of [`Self::from_byte`] (RFC 6716 §3.1).
163    ///
164    /// Returns [`Error::MalformedPacket`] when the triple does not
165    /// correspond to any Table-2 `config` row (e.g. SILK-only SWB, or
166    /// a CELT-only 40 ms frame).
167    pub fn compose_byte(
168        mode: Mode,
169        bandwidth: Bandwidth,
170        frame_size_tenths_ms: u16,
171        stereo: bool,
172        frame_count_code: FrameCountCode,
173    ) -> Result<u8, Error> {
174        // Table 2 is small; find the config row by exhaustive match
175        // against the decode mapping (correct by construction).
176        let config = (0u8..32)
177            .find(|&c| decode_config(c) == (mode, bandwidth, frame_size_tenths_ms))
178            .ok_or(Error::MalformedPacket)?;
179        let s = u8::from(stereo);
180        let c = match frame_count_code {
181            FrameCountCode::One => 0u8,
182            FrameCountCode::TwoEqual => 1,
183            FrameCountCode::TwoUnequal => 2,
184            FrameCountCode::Arbitrary => 3,
185        };
186        Ok((config << 3) | (s << 2) | c)
187    }
188
189    /// Minimum and maximum frame count the TOC byte implies *without*
190    /// consulting subsequent bytes. Codes 0/1/2 have a known frame
191    /// count; code 3 needs the §3.2.5 frame-count byte to resolve and
192    /// returns the legal `(1, 48)` range here.
193    pub fn frame_count_range(self) -> (u8, u8) {
194        match self.frame_count_code {
195            FrameCountCode::One => (1, 1),
196            FrameCountCode::TwoEqual | FrameCountCode::TwoUnequal => (2, 2),
197            // RFC 6716 §3.2.5: the M field is 1..48 inclusive (R5).
198            FrameCountCode::Arbitrary => (1, 48),
199        }
200    }
201}
202
203impl fmt::Display for Mode {
204    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
205        f.write_str(match self {
206            Mode::SilkOnly => "SILK-only",
207            Mode::Hybrid => "Hybrid",
208            Mode::CeltOnly => "CELT-only",
209        })
210    }
211}
212
213impl fmt::Display for Bandwidth {
214    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
215        f.write_str(match self {
216            Bandwidth::Nb => "NB",
217            Bandwidth::Mb => "MB",
218            Bandwidth::Wb => "WB",
219            Bandwidth::Swb => "SWB",
220            Bandwidth::Fb => "FB",
221        })
222    }
223}
224
225/// Map a five-bit `config` value to the `(mode, bandwidth,
226/// frame-size)` triple per RFC 6716 §3.1 Table 2.
227///
228/// The configuration numbers in each range correspond to the choices
229/// of frame size in the same order — e.g. for SILK-only NB
230/// (configs 0..=3) the frame sizes 10, 20, 40, 60 ms correspond to
231/// configs 0, 1, 2, 3 respectively.
232fn decode_config(config: u8) -> (Mode, Bandwidth, u16) {
233    debug_assert!(config < 32);
234    match config {
235        // SILK-only — 10, 20, 40, 60 ms.
236        0 => (Mode::SilkOnly, Bandwidth::Nb, 100),
237        1 => (Mode::SilkOnly, Bandwidth::Nb, 200),
238        2 => (Mode::SilkOnly, Bandwidth::Nb, 400),
239        3 => (Mode::SilkOnly, Bandwidth::Nb, 600),
240        4 => (Mode::SilkOnly, Bandwidth::Mb, 100),
241        5 => (Mode::SilkOnly, Bandwidth::Mb, 200),
242        6 => (Mode::SilkOnly, Bandwidth::Mb, 400),
243        7 => (Mode::SilkOnly, Bandwidth::Mb, 600),
244        8 => (Mode::SilkOnly, Bandwidth::Wb, 100),
245        9 => (Mode::SilkOnly, Bandwidth::Wb, 200),
246        10 => (Mode::SilkOnly, Bandwidth::Wb, 400),
247        11 => (Mode::SilkOnly, Bandwidth::Wb, 600),
248        // Hybrid — 10, 20 ms.
249        12 => (Mode::Hybrid, Bandwidth::Swb, 100),
250        13 => (Mode::Hybrid, Bandwidth::Swb, 200),
251        14 => (Mode::Hybrid, Bandwidth::Fb, 100),
252        15 => (Mode::Hybrid, Bandwidth::Fb, 200),
253        // CELT-only — 2.5, 5, 10, 20 ms.
254        16 => (Mode::CeltOnly, Bandwidth::Nb, 25),
255        17 => (Mode::CeltOnly, Bandwidth::Nb, 50),
256        18 => (Mode::CeltOnly, Bandwidth::Nb, 100),
257        19 => (Mode::CeltOnly, Bandwidth::Nb, 200),
258        20 => (Mode::CeltOnly, Bandwidth::Wb, 25),
259        21 => (Mode::CeltOnly, Bandwidth::Wb, 50),
260        22 => (Mode::CeltOnly, Bandwidth::Wb, 100),
261        23 => (Mode::CeltOnly, Bandwidth::Wb, 200),
262        24 => (Mode::CeltOnly, Bandwidth::Swb, 25),
263        25 => (Mode::CeltOnly, Bandwidth::Swb, 50),
264        26 => (Mode::CeltOnly, Bandwidth::Swb, 100),
265        27 => (Mode::CeltOnly, Bandwidth::Swb, 200),
266        28 => (Mode::CeltOnly, Bandwidth::Fb, 25),
267        29 => (Mode::CeltOnly, Bandwidth::Fb, 50),
268        30 => (Mode::CeltOnly, Bandwidth::Fb, 100),
269        31 => (Mode::CeltOnly, Bandwidth::Fb, 200),
270        _ => unreachable!("config is masked to 5 bits"),
271    }
272}
273
274#[cfg(test)]
275mod tests {
276    use super::*;
277
278    /// Every five-bit `config` produces the correct (mode, bandwidth,
279    /// frame-size) triple per RFC 6716 §3.1 Table 2.
280    ///
281    /// We assemble the TOC byte as `config<<3 | 0<<2 | 0` (mono,
282    /// code 0) so the parser sees exactly the `config` we expect.
283    #[test]
284    fn table2_all_32_configs() {
285        // Independently encoded expected triples mirroring Table 2.
286        let expected: [(Mode, Bandwidth, u16); 32] = [
287            (Mode::SilkOnly, Bandwidth::Nb, 100),
288            (Mode::SilkOnly, Bandwidth::Nb, 200),
289            (Mode::SilkOnly, Bandwidth::Nb, 400),
290            (Mode::SilkOnly, Bandwidth::Nb, 600),
291            (Mode::SilkOnly, Bandwidth::Mb, 100),
292            (Mode::SilkOnly, Bandwidth::Mb, 200),
293            (Mode::SilkOnly, Bandwidth::Mb, 400),
294            (Mode::SilkOnly, Bandwidth::Mb, 600),
295            (Mode::SilkOnly, Bandwidth::Wb, 100),
296            (Mode::SilkOnly, Bandwidth::Wb, 200),
297            (Mode::SilkOnly, Bandwidth::Wb, 400),
298            (Mode::SilkOnly, Bandwidth::Wb, 600),
299            (Mode::Hybrid, Bandwidth::Swb, 100),
300            (Mode::Hybrid, Bandwidth::Swb, 200),
301            (Mode::Hybrid, Bandwidth::Fb, 100),
302            (Mode::Hybrid, Bandwidth::Fb, 200),
303            (Mode::CeltOnly, Bandwidth::Nb, 25),
304            (Mode::CeltOnly, Bandwidth::Nb, 50),
305            (Mode::CeltOnly, Bandwidth::Nb, 100),
306            (Mode::CeltOnly, Bandwidth::Nb, 200),
307            (Mode::CeltOnly, Bandwidth::Wb, 25),
308            (Mode::CeltOnly, Bandwidth::Wb, 50),
309            (Mode::CeltOnly, Bandwidth::Wb, 100),
310            (Mode::CeltOnly, Bandwidth::Wb, 200),
311            (Mode::CeltOnly, Bandwidth::Swb, 25),
312            (Mode::CeltOnly, Bandwidth::Swb, 50),
313            (Mode::CeltOnly, Bandwidth::Swb, 100),
314            (Mode::CeltOnly, Bandwidth::Swb, 200),
315            (Mode::CeltOnly, Bandwidth::Fb, 25),
316            (Mode::CeltOnly, Bandwidth::Fb, 50),
317            (Mode::CeltOnly, Bandwidth::Fb, 100),
318            (Mode::CeltOnly, Bandwidth::Fb, 200),
319        ];
320        for (config, &(mode, bw, dur)) in expected.iter().enumerate() {
321            let toc = OpusTocByte::from_byte((config as u8) << 3);
322            assert_eq!(toc.config, config as u8, "config field");
323            assert_eq!(toc.mode, mode, "config {config}: mode");
324            assert_eq!(toc.bandwidth, bw, "config {config}: bandwidth");
325            assert_eq!(
326                toc.frame_size_tenths_ms, dur,
327                "config {config}: frame-size (tenths of ms)"
328            );
329        }
330    }
331
332    /// The `s` bit (bit position 5 from the MSB / bit 2 from the
333    /// LSB) toggles mono vs. stereo independently of `config` and
334    /// `c`. We sweep `config` and `c` and verify each `s` polarity.
335    #[test]
336    fn stereo_bit_independent_of_config_and_code() {
337        for config in 0u8..32 {
338            for code in 0u8..4 {
339                let mono = OpusTocByte::from_byte((config << 3) | code);
340                let stereo = OpusTocByte::from_byte((config << 3) | (1 << 2) | code);
341                assert_eq!(mono.channels, ChannelMapping::Mono);
342                assert_eq!(stereo.channels, ChannelMapping::Stereo);
343                // Toggling `s` must not bleed into the other fields.
344                assert_eq!(mono.config, stereo.config);
345                assert_eq!(mono.mode, stereo.mode);
346                assert_eq!(mono.bandwidth, stereo.bandwidth);
347                assert_eq!(mono.frame_size_tenths_ms, stereo.frame_size_tenths_ms);
348                assert_eq!(mono.frame_count_code, stereo.frame_count_code);
349            }
350        }
351    }
352
353    /// The `c` two-bit field selects the frame-packing code per the
354    /// four cases enumerated immediately after Table 2.
355    #[test]
356    fn frame_count_codes() {
357        let cases = [
358            (0u8, FrameCountCode::One, (1u8, 1u8)),
359            (1, FrameCountCode::TwoEqual, (2, 2)),
360            (2, FrameCountCode::TwoUnequal, (2, 2)),
361            (3, FrameCountCode::Arbitrary, (1, 48)),
362        ];
363        for (c, expected_code, range) in cases {
364            let toc = OpusTocByte::from_byte(c);
365            assert_eq!(toc.frame_count_code, expected_code, "c={c}");
366            assert_eq!(toc.frame_count_range(), range, "c={c} frame-count range");
367        }
368    }
369
370    /// Empty packet rejection per RFC 6716 §3.1 R1.
371    #[test]
372    fn parse_empty_rejects() {
373        assert_eq!(OpusTocByte::parse(&[]), Err(Error::EmptyPacket));
374    }
375
376    /// A spot-check parse against a hand-assembled packet:
377    /// config=13 (Hybrid SWB 20 ms), s=1 (stereo), c=2 (two
378    /// unequal frames). Bit layout: `01101 1 10` = 0x6E.
379    #[test]
380    fn parse_known_byte() {
381        let toc = OpusTocByte::parse(&[0x6E, 0x00, 0x00]).unwrap();
382        assert_eq!(toc.config, 13);
383        assert_eq!(toc.mode, Mode::Hybrid);
384        assert_eq!(toc.bandwidth, Bandwidth::Swb);
385        assert_eq!(toc.frame_size_tenths_ms, 200);
386        assert_eq!(toc.channels, ChannelMapping::Stereo);
387        assert_eq!(toc.frame_count_code, FrameCountCode::TwoUnequal);
388        // And a second spot-check at the opposite corner: config=31
389        // (CELT FB 20 ms), mono, code 0.
390        let toc2 = OpusTocByte::from_byte(0xF8);
391        assert_eq!(toc2.config, 31);
392        assert_eq!(toc2.mode, Mode::CeltOnly);
393        assert_eq!(toc2.bandwidth, Bandwidth::Fb);
394        assert_eq!(toc2.frame_size_tenths_ms, 200);
395        assert_eq!(toc2.channels, ChannelMapping::Mono);
396        assert_eq!(toc2.frame_count_code, FrameCountCode::One);
397    }
398}
oxideav_opus/toc.rs

oxideav_opus/
toc.rs
