oxideav-opus 0.0.12

//! SILK per-frame header decoding — RFC 6716 §4.2.7.1 through §4.2.7.5.1.
//!
//! Each regular SILK frame begins with a fixed prefix of side-information
//! symbols that drive the subsequent gain / LSF / LTP / excitation
//! stages. This module parses that prefix:
//!
//! * §4.2.7.1 — Stereo prediction weights (mid-channel of a stereo frame
//!   only). Three range-coded indices `n`, `(i0, i1)`, `(i2, i3)` are
//!   combined into a pair of Q13 prediction weights `(w0_Q13, w1_Q13)`
//!   per the formulas at the end of §4.2.7.1.
//! * §4.2.7.2 — Mid-only flag (mid-channel of a stereo frame, when the
//!   side channel is not otherwise required).
//! * §4.2.7.3 — Frame-type symbol, which jointly carries the signal type
//!   ([`SignalType`]) and the quantization-offset type
//!   ([`QuantizationOffsetType`]) per Table 10.
//! * §4.2.7.5.1 — Normalized LSF stage-1 codebook index `I1` (0..32),
//!   PDF chosen from Table 14 by `(bandwidth, signal_type)`.
//!
//! All symbols are read from a [`RangeDecoder`] using the §4.1.3.3
//! inverse-CDF primitive. The PDFs in Tables 6, 8, 9, and 14 are
//! transcribed verbatim from RFC 6716.
//!
//! Higher-level SILK stages (subframe gains, LSF stage-2 residual, LTP
//! parameters, LCG seed, excitation) are out of scope for round 4 — the
//! goal here is to land the entry point onto the SILK frame body and
//! the four structural decisions that everything downstream branches
//! on.

use crate::range_decoder::RangeDecoder;
use crate::toc::Bandwidth;
use crate::Error;

/// Decoded stereo prediction weights for one mid-channel SILK frame
/// (RFC 6716 §4.2.7.1).
///
/// Both weights are in Q13 fixed-point. By construction
/// `w0_Q13, w1_Q13 ∈ [-13732 - 0.1*(13732 - 10050), 13732 + ...]`,
/// i.e. roughly `[-14_100, +14_100]` after the interpolation step.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct StereoPredictionWeights {
    /// First weight, Q13. The decoded formula:
    /// `w0 = w_Q13[wi0] + (((w_Q13[wi0+1] - w_Q13[wi0])*6554) >> 16)*(2*i1+1) - w1`.
    pub w0_q13: i32,
    /// Second weight, Q13. The decoded formula:
    /// `w1 = w_Q13[wi1] + (((w_Q13[wi1+1] - w_Q13[wi1])*6554) >> 16)*(2*i3+1)`.
    pub w1_q13: i32,
}

/// Signal type carried by the §4.2.7.3 frame-type symbol (Table 10).
///
/// Drives downstream LSF stage-1 PDF selection (§4.2.7.5.1) and the
/// gain MSB PDF (§4.2.7.4).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SignalType {
    /// Frame-type 0 or 1 (Table 10).
    Inactive,
    /// Frame-type 2 or 3 (Table 10).
    Unvoiced,
    /// Frame-type 4 or 5 (Table 10).
    Voiced,
}

/// Quantization-offset type carried by the §4.2.7.3 frame-type symbol
/// (Table 10).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum QuantizationOffsetType {
    /// Even frame-type values (0, 2, 4).
    Low,
    /// Odd frame-type values (1, 3, 5).
    High,
}

/// Whether the current SILK frame is an LBRR frame or a regular SILK
/// frame, and the VAD state of the corresponding time interval.
///
/// Drives which §4.2.7.3 PDF is used (Table 9) and whether the
/// mid-only flag (§4.2.7.2) appears.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FrameKind {
    /// Regular SILK frame whose VAD flag is unset for this time
    /// interval. Frame-type symbol uses the "Inactive" PDF in Table 9.
    /// Decoded value is always 0 or 1.
    RegularInactive,
    /// Regular SILK frame whose VAD flag is set for this time
    /// interval. Frame-type symbol uses the "Active" PDF in Table 9.
    /// Decoded value lies in `2..=5`.
    RegularActive,
    /// LBRR frame. Per §4.2.7.3, LBRR frames also use the "Active"
    /// PDF, since every LBRR frame is itself an active-coded frame.
    Lbrr,
}

/// Configuration for the mid-only flag (§4.2.7.2).
///
/// The mid-only flag is present only on a mid-channel SILK frame of a
/// stereo Opus frame when the corresponding side channel is not
/// otherwise required. The caller decides whether this applies and
/// passes the result via [`SilkFrameHeaderConfig::has_mid_only_flag`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct SilkFrameHeaderConfig {
    /// True if this is the mid-channel SILK frame of a stereo Opus
    /// frame. The stereo prediction weights (§4.2.7.1) are decoded
    /// only when this is true.
    pub stereo_mid_channel: bool,
    /// True if this is a stereo Opus frame at all. When the stereo
    /// bit of the TOC byte is 0, neither the stereo prediction
    /// weights nor the mid-only flag is present.
    pub stereo: bool,
    /// True if the §4.2.7.2 mid-only flag should be decoded. Per
    /// §4.2.7.2, this happens when (a) we are on the mid channel of
    /// a stereo Opus frame, AND (b) the side channel of this time
    /// interval is not otherwise required (regular frame with side
    /// VAD == 0, or LBRR frame with side LBRR == 0).
    pub has_mid_only_flag: bool,
    /// Frame kind for the current SILK frame (regular vs LBRR; if
    /// regular, the VAD state). Drives the §4.2.7.3 PDF selection.
    pub kind: FrameKind,
    /// Audio bandwidth of the SILK signal. Drives the §4.2.7.5.1 PDF
    /// selection (NB / MB share a row in Table 14, WB has its own).
    /// SWB and FB SILK do not exist; the caller passes the SILK-layer
    /// bandwidth post-§4.2.2 split.
    pub bandwidth: Bandwidth,
}

/// SILK frame header — the prefix of side-information that drives the
/// rest of the SILK frame decoder. RFC 6716 §4.2.7.1 through §4.2.7.5.1.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct SilkFrameHeader {
    /// Stereo prediction weights (§4.2.7.1) if this is a mid-channel
    /// SILK frame of a stereo Opus frame; `None` otherwise.
    pub stereo_pred: Option<StereoPredictionWeights>,
    /// Mid-only flag (§4.2.7.2): `Some(true)` means the side channel
    /// of this time interval is skipped; `Some(false)` means the side
    /// channel is coded normally; `None` means the flag was not
    /// present.
    pub mid_only_flag: Option<bool>,
    /// Raw §4.2.7.3 frame-type symbol value in `0..=5` (per Table 10).
    pub frame_type: u8,
    /// Decoded signal type (§4.2.7.3, Table 10).
    pub signal_type: SignalType,
    /// Decoded quantization-offset type (§4.2.7.3, Table 10).
    pub qoff_type: QuantizationOffsetType,
    /// Normalized LSF stage-1 codebook index `I1` (§4.2.7.5.1), in
    /// `0..32`.
    pub lsf_stage1: u8,
}

/// Table 6 stage-1 PDF (25 symbols) — `silk_stereo_pred_joint_iCDF`
/// equivalent expressed as an inverse-CDF for the §4.1.3.3 primitive.
///
/// The PDF as stated in RFC 6716 Table 6:
///
/// ```text
/// {7, 2, 1, 1, 1, 10, 24, 8, 1, 1, 3, 23, 92, 23, 3, 1, 1,
///  8, 24, 10, 1, 1, 1, 2, 7}/256
/// ```
///
/// Cumulative `fh[k]` running sum:
/// `[7,9,10,11,12,22,46,54,55,56,59,82,174,197,200,201,202,210,234,
///   244,245,246,247,249,256]`.
/// `icdf[k] = 256 - fh[k]`, terminated by 0:
const STEREO_STAGE1_ICDF: &[u8] = &[
    249, 247, 246, 245, 244, 234, 210, 202, 201, 200, 197, 174, 82, 59, 56, 55, 54, 46, 22, 12, 11,
    10, 9, 7, 0,
];

/// Table 6 stage-2 PDF — `{85, 86, 85}/256`. Cumulative `fh = [85, 171,
/// 256]`. `icdf = [171, 85, 0]`.
const STEREO_STAGE2_ICDF: &[u8] = &[171, 85, 0];

/// Table 6 stage-3 PDF — `{51, 51, 52, 51, 51}/256`. Cumulative
/// `fh = [51, 102, 154, 205, 256]`. `icdf = [205, 154, 102, 51, 0]`.
const STEREO_STAGE3_ICDF: &[u8] = &[205, 154, 102, 51, 0];

/// Table 7 — 16-entry weight table indexed by `wi0` / `wi1 + 1` in the
/// `w0_Q13` / `w1_Q13` computation of §4.2.7.1.
///
/// Last entry is included even though `wi*` only ranges over 0..=14, so
/// that the linear interpolation `w_Q13[wi+1] - w_Q13[wi]` is always
/// defined.
const STEREO_WEIGHT_Q13: [i32; 16] = [
    -13732, -10050, -8266, -7526, -6500, -5000, -2950, -820, 820, 2950, 5000, 6500, 7526, 8266,
    10050, 13732,
];

/// Table 8 mid-only flag PDF `{192, 64}/256`. Cumulative `fh = [192,
/// 256]`. `icdf = [64, 0]`.
const MID_ONLY_ICDF: &[u8] = &[64, 0];

/// Table 9 inactive frame-type PDF `{26, 230, 0, 0, 0, 0}/256` — only
/// indices 0 and 1 ever decode. Cumulative `fh = [26, 256]`. `icdf =
/// [230, 0]`.
const FRAME_TYPE_INACTIVE_ICDF: &[u8] = &[230, 0];

/// Table 9 active frame-type PDF `{0, 0, 24, 74, 148, 10}/256` —
/// indices 2..=5. Cumulative `fh = [0, 0, 24, 98, 246, 256]`. The
/// §4.1.3.3 primitive needs the leading zero-mass cells to be
/// representable; `icdf = [256, 256, 232, 158, 10, 0]` but 256 is not a
/// valid `u8`. Instead, the §4.1.3.3 formulation handles the
/// degenerate "this cell has probability zero" case naturally: the
/// `s * icdf[k]` product equals `rng` when `icdf[k] == ft`, and
/// `val < rng` always holds — so the search just falls through. We
/// approximate the leading-256 entries with their wraparound `0u8`
/// representation, since the §4.1.3.3 primitive compares `val >= next`
/// where `next = s * icdf[k]`; for `icdf[k] = 0` this gives `next = 0`
/// and the loop returns at this index. That is the WRONG behaviour
/// for a leading zero-probability cell. The clean solution is to use
/// a different `ftb` that excludes the zero-probability cells, which
/// gives us a tight inverse-CDF: the active PDF "really" has support
/// over {2, 3, 4, 5}, so transcribe it as a 4-entry table indexed
/// `0..=3` and add the +2 offset in the caller. Cumulative
/// `fh = [24, 98, 246, 256]`. `icdf = [232, 158, 10, 0]`.
const FRAME_TYPE_ACTIVE_ICDF: &[u8] = &[232, 158, 10, 0];

/// Table 14 LSF stage-1 PDF for NB/MB inactive-or-unvoiced. Sum of
/// the 32 cells is 256 by construction. Build cumulative `fh` then
/// `icdf = 256 - fh` with a trailing zero.
const LSF_STAGE1_NB_MB_INACTIVE_PDF: [u8; 32] = [
    44, 34, 30, 19, 21, 12, 11, 3, 3, 2, 16, 2, 2, 1, 5, 2, 1, 3, 3, 1, 1, 2, 2, 2, 3, 1, 9, 9, 2,
    7, 2, 1,
];

/// Table 14 LSF stage-1 PDF for NB/MB voiced.
const LSF_STAGE1_NB_MB_VOICED_PDF: [u8; 32] = [
    1, 10, 1, 8, 3, 8, 8, 14, 13, 14, 1, 14, 12, 13, 11, 11, 12, 11, 10, 10, 11, 8, 9, 8, 7, 8, 1,
    1, 6, 1, 6, 5,
];

/// Table 14 LSF stage-1 PDF for WB inactive-or-unvoiced.
const LSF_STAGE1_WB_INACTIVE_PDF: [u8; 32] = [
    31, 21, 3, 17, 1, 8, 17, 4, 1, 18, 16, 4, 2, 3, 1, 10, 1, 3, 16, 11, 16, 2, 2, 3, 2, 11, 1, 4,
    9, 8, 7, 3,
];

/// Table 14 LSF stage-1 PDF for WB voiced.
const LSF_STAGE1_WB_VOICED_PDF: [u8; 32] = [
    1, 4, 16, 5, 18, 11, 5, 14, 15, 1, 3, 12, 13, 14, 14, 6, 14, 12, 2, 6, 1, 12, 12, 11, 10, 3,
    10, 5, 1, 1, 1, 3,
];

/// Convert a 32-cell length-256 PDF into an iCDF (`256 - fh[k]`) with
/// a trailing zero — the format consumed by [`RangeDecoder::dec_icdf`].
const fn pdf_to_icdf32(pdf: &[u8; 32]) -> [u8; 33] {
    let mut icdf = [0u8; 33];
    let mut acc: u32 = 0;
    let mut k = 0;
    while k < 32 {
        acc += pdf[k] as u32;
        // `256 - acc` fits in u8 as long as acc <= 256, which it is
        // for any well-formed Table-14 row (sum = 256).
        icdf[k] = (256 - acc) as u8;
        k += 1;
    }
    // trailing zero terminator
    icdf[32] = 0;
    icdf
}

/// LSF stage-1 iCDFs derived from the four PDF rows in Table 14.
const LSF_STAGE1_ICDF_NB_MB_INACTIVE: [u8; 33] = pdf_to_icdf32(&LSF_STAGE1_NB_MB_INACTIVE_PDF);
const LSF_STAGE1_ICDF_NB_MB_VOICED: [u8; 33] = pdf_to_icdf32(&LSF_STAGE1_NB_MB_VOICED_PDF);
const LSF_STAGE1_ICDF_WB_INACTIVE: [u8; 33] = pdf_to_icdf32(&LSF_STAGE1_WB_INACTIVE_PDF);
const LSF_STAGE1_ICDF_WB_VOICED: [u8; 33] = pdf_to_icdf32(&LSF_STAGE1_WB_VOICED_PDF);

impl SilkFrameHeader {
    /// Decode the §4.2.7.1–§4.2.7.5.1 header prefix from `rd`.
    ///
    /// The caller is responsible for telling us, via `cfg`, whether
    /// the stereo prediction weights and the mid-only flag are
    /// present, and whether the current frame is regular-inactive,
    /// regular-active, or LBRR. The function does not consult the
    /// §3.1 TOC byte or the §4.2.3/§4.2.4 packet-level header bits.
    pub fn decode(rd: &mut RangeDecoder<'_>, cfg: SilkFrameHeaderConfig) -> Result<Self, Error> {
        // -------- §4.2.7.1 Stereo Prediction Weights --------
        let stereo_pred = if cfg.stereo && cfg.stereo_mid_channel {
            Some(Self::decode_stereo_pred(rd))
        } else {
            None
        };

        // -------- §4.2.7.2 Mid-Only Flag --------
        // Per §4.2.7.2 the flag is present iff (stereo Opus frame) AND
        // (mid channel) AND (side channel not otherwise required). We
        // gate strictly on the caller's `has_mid_only_flag` to keep
        // the LBRR / VAD logic out of the SILK frame decoder.
        let mid_only_flag = if cfg.has_mid_only_flag {
            // Table 8: P(0) = 192/256 = 3/4, P(1) = 64/256 = 1/4.
            // dec_icdf returns the symbol index; index 0 => flag = 0,
            // index 1 => flag = 1 ("mid only").
            let v = rd.dec_icdf(MID_ONLY_ICDF, 8);
            Some(v == 1)
        } else {
            None
        };

        // -------- §4.2.7.3 Frame Type --------
        let frame_type_raw = match cfg.kind {
            FrameKind::RegularInactive => {
                // Inactive PDF — only indices 0 and 1 ever decode.
                rd.dec_icdf(FRAME_TYPE_INACTIVE_ICDF, 8) as u8
            }
            FrameKind::RegularActive | FrameKind::Lbrr => {
                // Active PDF — indices 2..=5. We use a 4-entry iCDF
                // covering the support and shift by +2.
                let k = rd.dec_icdf(FRAME_TYPE_ACTIVE_ICDF, 8) as u8;
                k + 2
            }
        };
        if frame_type_raw > 5 {
            // Should not happen for well-formed PDFs; defend anyway.
            return Err(Error::MalformedPacket);
        }
        let (signal_type, qoff_type) = frame_type_to_signal_qoff(frame_type_raw);

        // -------- §4.2.7.5.1 LSF Stage-1 --------
        let lsf_icdf: &[u8] = match (cfg.bandwidth, signal_type) {
            (Bandwidth::Nb | Bandwidth::Mb, SignalType::Inactive | SignalType::Unvoiced) => {
                &LSF_STAGE1_ICDF_NB_MB_INACTIVE
            }
            (Bandwidth::Nb | Bandwidth::Mb, SignalType::Voiced) => &LSF_STAGE1_ICDF_NB_MB_VOICED,
            (Bandwidth::Wb, SignalType::Inactive | SignalType::Unvoiced) => {
                &LSF_STAGE1_ICDF_WB_INACTIVE
            }
            (Bandwidth::Wb, SignalType::Voiced) => &LSF_STAGE1_ICDF_WB_VOICED,
            // §2 — SILK does not operate on SWB or FB. Hybrid mode
            // splits the signal so that the SILK layer always sees
            // NB / MB / WB only. Reject anything else.
            _ => return Err(Error::MalformedPacket),
        };
        let lsf_stage1 = rd.dec_icdf(lsf_icdf, 8) as u8;
        if lsf_stage1 >= 32 {
            return Err(Error::MalformedPacket);
        }

        if rd.has_error() {
            return Err(Error::MalformedPacket);
        }

        Ok(Self {
            stereo_pred,
            mid_only_flag,
            frame_type: frame_type_raw,
            signal_type,
            qoff_type,
            lsf_stage1,
        })
    }

    /// Internal: decode the five sub-symbols of §4.2.7.1 (`n`, `i0`,
    /// `i1`, `i2`, `i3`) and compose them into `(w0_Q13, w1_Q13)`.
    ///
    /// Reads order is exactly the one stated in §4.2.7.1: "let i0
    /// and i1 be indices decoded with the stage-2 and stage-3 PDFs in
    /// Table 6, respectively, and let i2 and i3 be two more indices
    /// decoded with the stage-2 and stage-3 PDFs, all in that order."
    fn decode_stereo_pred(rd: &mut RangeDecoder<'_>) -> StereoPredictionWeights {
        let n = rd.dec_icdf(STEREO_STAGE1_ICDF, 8) as i32;
        let i0 = rd.dec_icdf(STEREO_STAGE2_ICDF, 8) as i32;
        let i1 = rd.dec_icdf(STEREO_STAGE3_ICDF, 8) as i32;
        let i2 = rd.dec_icdf(STEREO_STAGE2_ICDF, 8) as i32;
        let i3 = rd.dec_icdf(STEREO_STAGE3_ICDF, 8) as i32;

        // §4.2.7.1: wi0 = i0 + 3*(n/5), wi1 = i2 + 3*(n%5); both fall
        // in 0..=14.
        let wi0 = (i0 + 3 * (n / 5)) as usize;
        let wi1 = (i2 + 3 * (n % 5)) as usize;
        // Defensive clamp: the spec guarantees wi* <= 14 for any
        // (n, i0, i2) tuple, but we still saturate to keep the
        // STEREO_WEIGHT_Q13[wi+1] lookup in-bounds even on a
        // pathologically corrupt frame.
        let wi0 = wi0.min(14);
        let wi1 = wi1.min(14);

        // w1 first (w0 depends on w1):
        //   w1 = w_Q13[wi1] + (((w_Q13[wi1+1] - w_Q13[wi1])*6554) >> 16)*(2*i3+1)
        let step1: i32 =
            (((STEREO_WEIGHT_Q13[wi1 + 1] - STEREO_WEIGHT_Q13[wi1]) * 6554) >> 16) * (2 * i3 + 1);
        let w1_q13 = STEREO_WEIGHT_Q13[wi1] + step1;
        //   w0 = w_Q13[wi0] + (((w_Q13[wi0+1] - w_Q13[wi0])*6554) >> 16)*(2*i1+1) - w1
        let step0: i32 =
            (((STEREO_WEIGHT_Q13[wi0 + 1] - STEREO_WEIGHT_Q13[wi0]) * 6554) >> 16) * (2 * i1 + 1);
        let w0_q13 = STEREO_WEIGHT_Q13[wi0] + step0 - w1_q13;
        StereoPredictionWeights { w0_q13, w1_q13 }
    }
}

/// Map a frame-type symbol (0..=5) to `(signal_type, qoff_type)` per
/// RFC 6716 §4.2.7.3 Table 10.
fn frame_type_to_signal_qoff(frame_type: u8) -> (SignalType, QuantizationOffsetType) {
    let signal = match frame_type {
        0 | 1 => SignalType::Inactive,
        2 | 3 => SignalType::Unvoiced,
        4 | 5 => SignalType::Voiced,
        _ => SignalType::Inactive, // unreachable in practice; defensive
    };
    let qoff = if frame_type % 2 == 0 {
        QuantizationOffsetType::Low
    } else {
        QuantizationOffsetType::High
    };
    (signal, qoff)
}

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

    // --- Table 6 / 7 / 8 / 9 / 14 PDF→iCDF transcription self-checks.
    //
    // These tests do not exercise the range decoder; they confirm
    // the constant tables match the RFC by checking that each PDF row
    // sums to 256 and that consecutive iCDF cells are strictly
    // monotonically decreasing (a §4.1.3.3 precondition).

    #[test]
    fn stereo_stage1_pdf_sums_to_256() {
        let pdf = [
            7, 2, 1, 1, 1, 10, 24, 8, 1, 1, 3, 23, 92, 23, 3, 1, 1, 8, 24, 10, 1, 1, 1, 2, 7,
        ];
        let sum: u32 = pdf.iter().sum();
        assert_eq!(sum, 256);
        assert_eq!(STEREO_STAGE1_ICDF.len(), pdf.len());
        // iCDF strictly monotone decreasing then terminator zero.
        for w in STEREO_STAGE1_ICDF.windows(2) {
            assert!(w[0] > w[1] || (w[0] == 0 && w[1] == 0));
        }
        assert_eq!(*STEREO_STAGE1_ICDF.last().unwrap(), 0);
    }

    #[test]
    fn stereo_stage2_pdf_self_check() {
        assert_eq!(STEREO_STAGE2_ICDF, &[171u8, 85, 0]);
        assert_eq!(STEREO_STAGE3_ICDF, &[205u8, 154, 102, 51, 0]);
    }

    #[test]
    fn mid_only_pdf_self_check() {
        assert_eq!(MID_ONLY_ICDF, &[64u8, 0]);
    }

    #[test]
    fn lsf_stage1_nb_mb_inactive_sums_to_256() {
        let s: u32 = LSF_STAGE1_NB_MB_INACTIVE_PDF
            .iter()
            .map(|&x| x as u32)
            .sum();
        assert_eq!(s, 256);
    }

    #[test]
    fn lsf_stage1_nb_mb_voiced_sums_to_256() {
        let s: u32 = LSF_STAGE1_NB_MB_VOICED_PDF.iter().map(|&x| x as u32).sum();
        assert_eq!(s, 256);
    }

    #[test]
    fn lsf_stage1_wb_inactive_sums_to_256() {
        let s: u32 = LSF_STAGE1_WB_INACTIVE_PDF.iter().map(|&x| x as u32).sum();
        assert_eq!(s, 256);
    }

    #[test]
    fn lsf_stage1_wb_voiced_sums_to_256() {
        let s: u32 = LSF_STAGE1_WB_VOICED_PDF.iter().map(|&x| x as u32).sum();
        assert_eq!(s, 256);
    }

    #[test]
    fn lsf_stage1_icdf_terminator_is_zero() {
        for icdf in [
            &LSF_STAGE1_ICDF_NB_MB_INACTIVE,
            &LSF_STAGE1_ICDF_NB_MB_VOICED,
            &LSF_STAGE1_ICDF_WB_INACTIVE,
            &LSF_STAGE1_ICDF_WB_VOICED,
        ] {
            assert_eq!(icdf[32], 0, "iCDF must terminate with zero");
            assert_eq!(icdf.len(), 33);
            // Strictly decreasing.
            for w in icdf.windows(2) {
                assert!(
                    w[0] >= w[1],
                    "iCDF must be monotone non-increasing: {:?} -> {:?}",
                    w[0],
                    w[1]
                );
            }
        }
    }

    #[test]
    fn stereo_weight_table_is_symmetric() {
        // Table 7 is symmetric around the middle: w[15-k] == -w[k]
        // for k in 0..=7.
        for k in 0..8 {
            assert_eq!(STEREO_WEIGHT_Q13[15 - k], -STEREO_WEIGHT_Q13[k]);
        }
        assert_eq!(STEREO_WEIGHT_Q13[0], -13732);
        assert_eq!(STEREO_WEIGHT_Q13[15], 13732);
    }

    // --- Table 10 frame-type mapping --------

    #[test]
    fn frame_type_to_signal_qoff_table10() {
        let expected = [
            (0, SignalType::Inactive, QuantizationOffsetType::Low),
            (1, SignalType::Inactive, QuantizationOffsetType::High),
            (2, SignalType::Unvoiced, QuantizationOffsetType::Low),
            (3, SignalType::Unvoiced, QuantizationOffsetType::High),
            (4, SignalType::Voiced, QuantizationOffsetType::Low),
            (5, SignalType::Voiced, QuantizationOffsetType::High),
        ];
        for (ft, sig, q) in expected {
            assert_eq!(frame_type_to_signal_qoff(ft), (sig, q));
        }
    }

    // --- End-to-end: decode against a hand-crafted RangeDecoder.
    //
    // We can't easily construct an arbitrary byte sequence that
    // produces a specific symbol pattern without an encoder, but we
    // CAN check round-trip behaviour: every decoded value must
    // satisfy the spec's range bounds, and the function must not
    // latch the corrupt-frame flag for a non-corrupt input.

    fn mono_inactive_cfg(bw: Bandwidth) -> SilkFrameHeaderConfig {
        SilkFrameHeaderConfig {
            stereo_mid_channel: false,
            stereo: false,
            has_mid_only_flag: false,
            kind: FrameKind::RegularInactive,
            bandwidth: bw,
        }
    }

    fn mono_active_cfg(bw: Bandwidth) -> SilkFrameHeaderConfig {
        SilkFrameHeaderConfig {
            stereo_mid_channel: false,
            stereo: false,
            has_mid_only_flag: false,
            kind: FrameKind::RegularActive,
            bandwidth: bw,
        }
    }

    fn stereo_mid_active_cfg(bw: Bandwidth) -> SilkFrameHeaderConfig {
        SilkFrameHeaderConfig {
            stereo_mid_channel: true,
            stereo: true,
            has_mid_only_flag: true,
            kind: FrameKind::RegularActive,
            bandwidth: bw,
        }
    }

    #[test]
    fn mono_inactive_nb_decode_basic() {
        // A long-enough buffer so the range decoder doesn't immediately
        // start zero-extending past EOF.
        let buf = [
            0x55, 0xAA, 0x33, 0xCC, 0x7F, 0x80, 0x12, 0x34, 0x56, 0x78, 0x9A, 0xBC, 0xDE, 0xF0,
            0x12, 0x34,
        ];
        let mut rd = RangeDecoder::new(&buf);
        let hdr = SilkFrameHeader::decode(&mut rd, mono_inactive_cfg(Bandwidth::Nb))
            .expect("decode must succeed");
        // No stereo content.
        assert!(hdr.stereo_pred.is_none());
        assert!(hdr.mid_only_flag.is_none());
        // Inactive frame: ft must be 0 or 1.
        assert!(hdr.frame_type <= 1, "ft={}", hdr.frame_type);
        assert_eq!(hdr.signal_type, SignalType::Inactive);
        assert!(hdr.lsf_stage1 < 32);
    }

    #[test]
    fn mono_active_wb_decode_basic() {
        let buf = [
            0x12, 0x34, 0x56, 0x78, 0x9A, 0xBC, 0xDE, 0xF0, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66,
            0x77, 0x88,
        ];
        let mut rd = RangeDecoder::new(&buf);
        let hdr = SilkFrameHeader::decode(&mut rd, mono_active_cfg(Bandwidth::Wb))
            .expect("decode must succeed");
        assert!(hdr.stereo_pred.is_none());
        assert!(hdr.mid_only_flag.is_none());
        // Active frame: ft must be 2, 3, 4, or 5.
        assert!((2..=5).contains(&hdr.frame_type), "ft={}", hdr.frame_type);
        assert!(matches!(
            hdr.signal_type,
            SignalType::Unvoiced | SignalType::Voiced
        ));
        assert!(hdr.lsf_stage1 < 32);
    }

    #[test]
    fn stereo_mid_active_includes_pred_and_mid_only() {
        let buf = [
            0xC3, 0x18, 0x42, 0x7F, 0x55, 0xAA, 0x33, 0xCC, 0x77, 0x33, 0x11, 0xAA, 0xDE, 0xAD,
            0xBE, 0xEF, 0x10, 0x32, 0x54, 0x76, 0x98, 0xBA, 0xDC, 0xFE,
        ];
        let mut rd = RangeDecoder::new(&buf);
        let hdr = SilkFrameHeader::decode(&mut rd, stereo_mid_active_cfg(Bandwidth::Mb))
            .expect("decode must succeed");
        let pred = hdr.stereo_pred.expect("stereo prediction must be present");
        // w1 is one interpolated Table-7 entry (~±14_100 after the
        // §4.2.7.1 interpolation step). w0 then subtracts w1 from
        // another interpolated entry, so |w0| can reach ~ 28_000.
        assert!(
            (-30_000..=30_000).contains(&pred.w0_q13),
            "w0={}",
            pred.w0_q13
        );
        assert!(
            (-15_000..=15_000).contains(&pred.w1_q13),
            "w1={}",
            pred.w1_q13
        );
        assert!(hdr.mid_only_flag.is_some());
        assert!((2..=5).contains(&hdr.frame_type), "ft={}", hdr.frame_type);
        assert!(hdr.lsf_stage1 < 32);
    }

    #[test]
    fn stereo_side_no_prediction() {
        // Side-channel SILK frame: NOT mid channel, so no stereo pred
        // weights and no mid-only flag.
        let cfg = SilkFrameHeaderConfig {
            stereo_mid_channel: false,
            stereo: true,
            has_mid_only_flag: false,
            kind: FrameKind::RegularActive,
            bandwidth: Bandwidth::Wb,
        };
        let buf = [
            0x37, 0x91, 0xC4, 0x18, 0xA2, 0x5D, 0x6E, 0xFF, 0x77, 0x33, 0x11, 0xAA,
        ];
        let mut rd = RangeDecoder::new(&buf);
        let hdr = SilkFrameHeader::decode(&mut rd, cfg).expect("decode must succeed");
        assert!(hdr.stereo_pred.is_none());
        assert!(hdr.mid_only_flag.is_none());
    }

    #[test]
    fn lbrr_frame_uses_active_pdf() {
        // LBRR frames decode the frame-type symbol from the "Active"
        // PDF irrespective of the (regular) VAD state.
        let cfg = SilkFrameHeaderConfig {
            stereo_mid_channel: false,
            stereo: false,
            has_mid_only_flag: false,
            kind: FrameKind::Lbrr,
            bandwidth: Bandwidth::Nb,
        };
        let buf = [
            0x55, 0xAA, 0x33, 0xCC, 0x7F, 0x80, 0x12, 0x34, 0x56, 0x78, 0x9A, 0xBC,
        ];
        let mut rd = RangeDecoder::new(&buf);
        let hdr = SilkFrameHeader::decode(&mut rd, cfg).expect("decode must succeed");
        assert!(
            (2..=5).contains(&hdr.frame_type),
            "lbrr ft must be active: {}",
            hdr.frame_type
        );
    }

    #[test]
    fn pdf_to_icdf_terminates_and_decreases() {
        // The const helper must produce a strictly-decreasing iCDF
        // with a trailing zero, for any well-formed length-32
        // length-256-sum PDF.
        let pdf = [8u8; 32]; // uniform 32-way: sum = 256.
        let icdf = pdf_to_icdf32(&pdf);
        assert_eq!(icdf[32], 0);
        for w in icdf.windows(2) {
            assert!(w[0] >= w[1]);
        }
        // 256 - 8 = 248 (first cumulative-fh subtraction).
        assert_eq!(icdf[0], 248);
        // After all 32 cells: 256 - 32*8 = 0; uniform PDF sums to ft.
        assert_eq!(icdf[31], 0);
    }

    #[test]
    fn stereo_pred_wi_clamped_in_bounds() {
        // Even in the pathological case where rd.has_error() is set,
        // the wi0/wi1 clamps in decode_stereo_pred ensure we never
        // index past STEREO_WEIGHT_Q13[15]. We can't directly inject
        // n=24, but the clamp `.min(14)` is exercised by inspection;
        // exercise it indirectly by running many random buffers.
        for seed in 0..32u8 {
            let buf = [
                seed,
                seed.wrapping_mul(3),
                seed.wrapping_add(7),
                seed ^ 0xA5,
                seed.wrapping_mul(11),
                seed.wrapping_add(13),
                seed ^ 0x5A,
                seed.wrapping_mul(17),
                seed.wrapping_add(19),
                seed ^ 0xC3,
                seed.wrapping_mul(23),
                seed.wrapping_add(29),
                seed ^ 0x3C,
                seed.wrapping_mul(31),
                seed.wrapping_add(37),
                seed ^ 0x55,
            ];
            let mut rd = RangeDecoder::new(&buf);
            let pred = SilkFrameHeader::decode_stereo_pred(&mut rd);
            // w1 is one interpolated table entry (~±14k); w0 is one
            // interpolated entry MINUS w1 (~±28k worst case).
            assert!(
                (-30_000..=30_000).contains(&pred.w0_q13),
                "seed={seed}, w0={}",
                pred.w0_q13
            );
            assert!(
                (-15_000..=15_000).contains(&pred.w1_q13),
                "seed={seed}, w1={}",
                pred.w1_q13
            );
        }
    }
}