Module decoder 

Top-level Opus packet → PCM orchestration — RFC 6716 §3 / §4.

This module is the keystone that turns a raw Opus packet (a TOC byte plus one or more §3.2-packed Opus frames) into interleaved 48 kHz PCM samples. It sits above every per-stage SILK / CELT decoder in the crate and wires the §3.1 TOC parse, the §3.2 frame packing (crate::frames::OpusPacket), and the §4.2 / §4.3 per-frame mode dispatch (crate::framing::OpusFrameRouting) into one OpusDecoder::decode_packet call.

What this module owns

• The packet → frame split (delegated to OpusPacket::parse).
• The §4.5 multi-frame loop: every Opus frame in a code-1 / code-2 / code-3 packet is decoded in order and its PCM appended to the output, so a 60 ms code-3 packet of three 20 ms frames yields one contiguous PCM buffer.
• The §3.2.1 DTX / lost-frame marker handling: a zero-length frame slice contributes one Opus-frame worth of silence (the §4.6 PLC “fill with silence” floor — a real concealment model is a separate milestone).
• The 48 kHz output sample-count accounting (RFC 7845 §5.1: the Opus decoder always emits 48 kHz regardless of the internal SILK / CELT sample rate).
• The per-frame routing seam: each Opus frame is dispatched to [Self::decode_silk_only_frame], [Self::decode_celt_only_frame], or [Self::decode_hybrid_frame] based on its OpusFrameRouting.

What this module does not own

• The §4.1 range-coder primitive (crate::range_decoder).
• The per-stage SILK / CELT decode (the silk_* / celt_* modules).
• Any container parsing (Ogg / RTP framing live in their own crates; this module consumes a bare Opus packet).

Status of the per-frame audio decode

The packet-level orchestration (TOC → framing → routing → 48 kHz PCM buffer layout) is complete and total over all 32 §3.1 configs and all four §3.2 frame-count codes. The per-frame audio decode is wired incrementally:

• Mono SILK-only frames run the full §4.2 decode → PCM path: the §4.2.3 header bits, the §4.2.5 LBRR / §4.2.6 regular SILK frame loop (1 / 2 / 3 SILK frames per §4.2.2), each frame decoded in Table-5 order via crate::silk_decode::decode_silk_frame with the inter-frame state threaded across them, then the §4.2.7.9 LTP / LPC synthesis (crate::silk_synthesis::synthesize_silk_frame) and the §4.2.9 (non-normative) resample to 48 kHz. The carried §4.2.7.9 synthesis histories persist across the packet’s Opus frames; the emitted PCM is real audio (FrameDecodeStatus::SilkParamsDecoded).
• Stereo SILK-only frames run the full §4.2 interleaved decode → PCM path: the §4.2.3 two-channel header bits, the §4.2.5 / §4.2.6 mid/side interleave (mid frame then side frame per 20 ms interval, the side frame skipped when the §4.2.7.2 mid-only flag is set), each channel’s §4.2.7.9 synthesis with its own carried history, then the §4.2.8 mid/side → left/right unmixing (crate::silk_stereo::stereo_ms_to_lr) and the §4.2.9 resample, emitting interleaved L/R PCM (FrameDecodeStatus::SilkStereoDecoded). The §4.2.7.1 mono→stereo weight reset and the §4.5.2 SILK state reset are applied across packets.
• CELT-only / Hybrid frames emit silence of the correct length flagged FrameDecodeStatus::LayerNotWired (CELT is gated on the §4.3.2.1 coarse-energy Laplace decode).

Either way the multi-frame packet loop and the RFC 7845 §5.1 48 kHz sample-count accounting are exercised end-to-end.

Structs

DecodedAudio

Decoded audio for one Opus packet: interleaved 48 kHz PCM plus the per-frame outcomes.

FecRecovered

The result of an in-band FEC recovery for one lost packet (OpusDecoder::decode_packet_fec).

FrameOutcome

The result of decoding one Opus frame: how many per-channel samples it contributed and why.

OpusDecoder

Stateful Opus packet → PCM decoder.

Enums

FecDecodeStatus

Why an in-band FEC (OpusDecoder::decode_packet_fec) recovery produced the samples it did (RFC 6716 §2.1.7 / §4.2.5).

FrameDecodeStatus

Why a given Opus frame produced the samples it did.

Constants

OUTPUT_SAMPLES_PER_MS

Output samples per millisecond per channel at OUTPUT_SAMPLE_RATE_HZ.

OUTPUT_SAMPLE_RATE_HZ

Output sample rate of the Opus decoder, in Hz. Per RFC 7845 §5.1 the decoder always emits 48 kHz regardless of the internal SILK / CELT sample rate; the per-layer resamplers upsample to this rate.

Functions

channel_count

Convenience: the channel count for a ChannelMapping.

output_samples_per_channel

Number of 48 kHz output samples (per channel) an Opus frame of the given duration produces.