transmux 0.25.5

//! H.264 / H.265 sequence parameter set (SPS) decode.
//!
//! Decodes the fields needed by the transmux pipeline — profile / level /
//! dimensions / chroma / bit-depth / frame rate — from the raw NAL unit bytes
//! stored in [`AvcSps`](crate::nalu_types::AvcSps) and
//! [`HevcNalUnit`](crate::nalu_types::HevcNalUnit).
//!
//! # Spec citations
//!
//! - **H.264 SPS**: ITU-T H.264 §7.3.2.1.1 (sequence parameter set data).
//! - **H.264 VUI**: ITU-T H.264 §E.1.1 (vui_parameters), §E.2.1 (timing_info
//!   semantics): `num_units_in_tick` and `time_scale` yield frame rate as
//!   `time_scale / (2 × num_units_in_tick)`.
//! - **H.265 SPS + PTL**: ITU-T H.265 §7.3.2.2 (SPS) + §7.3.3 (profile_tier_level).
//! - **Coded dimensions**: see `fixtures/ts/CODEC-ORACLE.md`.
//! - **Emulation prevention**: H.264 §7.3 bullet 1 (leading zero_byte),
//!   §7.4.1 NAL semantics (emulation_prevention_three_byte); H.265 §7.4.2.1.

use crate::bitreader::BitReader;
use crate::error::{Error, Result};
use alloc::string::String;
use alloc::vec::Vec;

// ---------------------------------------------------------------------------
// H.264 helpers
// ---------------------------------------------------------------------------

/// Profiles that require the high-profile SPS branch (§7.3.2.1.1):
/// chroma_format_idc, bit_depth_*_minus8, and optionally scaling lists.
const H264_HIGH_PROFILES: &[u8] = &[100, 110, 122, 244, 44, 83, 86, 118, 128, 138, 139, 134, 135];

pub(crate) fn is_high_profile(profile_idc: u8) -> bool {
    H264_HIGH_PROFILES.contains(&profile_idc)
}

/// Narrow a `read_ue` result to `u8` only after checking it against the
/// field's spec-bounded maximum. A raw `as u8` silently truncates hostile
/// wire values, which then feed dimension/loop arithmetic.
fn ue_to_u8(v: u64, spec_max: u64, field: &'static str) -> Result<u8> {
    if v > spec_max {
        return Err(Error::InvalidValue {
            field,
            value: v,
            reason: "out of spec range",
        });
    }
    u8::try_from(v).map_err(|_| Error::InvalidValue {
        field,
        value: v,
        reason: "does not fit in u8",
    })
}

/// `bit_depth_*_minus8` → bit depth, checked end to end (never a raw
/// `read_ue(..)? as u8 + 8`, which overflowed for hostile values).
fn ue_bit_depth(minus8: u64, spec_max: u64, field: &'static str) -> Result<u8> {
    let minus8 = ue_to_u8(minus8, spec_max, field)?;
    minus8.checked_add(8).ok_or(Error::InvalidValue {
        field,
        value: minus8 as u64,
        reason: "bit depth overflow",
    })
}

/// Computed SubWidthC / SubHeightC from `chroma_format_idc`
/// (ITU-T H.264 Table 6-1).
fn sub_width_c(chroma_format_idc: u8) -> u32 {
    match chroma_format_idc {
        0 => 1,
        1 => 2,
        2 => 2,
        _ => 1,
    }
}

fn sub_height_c(chroma_format_idc: u8) -> u32 {
    match chroma_format_idc {
        0 => 1,
        1 => 2,
        2 => 1,
        _ => 1,
    }
}

// ---------------------------------------------------------------------------
// AvcSpsInfo
// ---------------------------------------------------------------------------

/// Decoded fields from an H.264/AVC sequence parameter set.
#[derive(Debug, Clone, PartialEq)]
pub struct AvcSpsInfo {
    /// `profile_idc` — SPS byte index 1.
    pub profile_idc: u8,
    /// The constraint-flags byte (SPS byte index 2 verbatim):
    /// constraint_set0..5 `[7:2]` + reserved_zero_2bits `[1:0]`.
    pub constraint_flags: u8,
    /// `level_idc` — SPS byte index 3.
    pub level_idc: u8,
    /// `chroma_format_idc` (defaults to 1 for non-high profiles).
    pub chroma_format_idc: u8,
    /// `separate_colour_plane_flag`
    pub separate_colour_plane: bool,
    /// `bit_depth_luma` (= `bit_depth_luma_minus8 + 8`, default 8).
    pub bit_depth_luma: u8,
    /// `bit_depth_chroma` (= `bit_depth_chroma_minus8 + 8`, default 8).
    pub bit_depth_chroma: u8,
    /// `frame_mbs_only_flag`
    pub frame_mbs_only: bool,
    /// Coded width in luma samples (after frame cropping).
    pub width: u32,
    /// Coded height in luma samples (after frame cropping).
    pub height: u32,
    /// `num_units_in_tick` from VUI `timing_info` (ITU-T H.264 §E.1.1).
    ///
    /// Present only when `vui_parameters_present_flag` and
    /// `timing_info_present_flag` are both 1 in the SPS.
    pub num_units_in_tick: Option<u32>,
    /// `time_scale` from VUI `timing_info` (ITU-T H.264 §E.1.1).
    ///
    /// Present only when `vui_parameters_present_flag` and
    /// `timing_info_present_flag` are both 1 in the SPS.
    pub time_scale: Option<u32>,
    /// Frame rate derived from VUI `timing_info` (ITU-T H.264 §E.2.1):
    /// `time_scale / (2 × num_units_in_tick)`.
    ///
    /// `None` when `vui_parameters_present_flag` or `timing_info_present_flag`
    /// is 0, or when `num_units_in_tick` is 0.
    pub fps: Option<f32>,
}

/// Decode an H.264 SPS RBSP.
///
/// `sps_bytes` is the raw NAL unit including the 1-byte NAL header
/// (as returned by [`iter_annexb_nals`](crate::iter_annexb_nals)).
/// The NAL header byte is skipped; decoding starts at the next byte.
pub fn decode_avc_sps(sps_bytes: &[u8]) -> Result<AvcSpsInfo> {
    decode_avc_sps_inner(sps_bytes).map(|(info, _)| info)
}

/// The SPS fields a slice-header parser needs (ITU-T H.264 §7.3.3 reads
/// `frame_num`, `field_pic_flag`, `pic_order_cnt_lsb`, … with widths and
/// presence conditions taken from the SPS).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct AvcSliceSps {
    /// `seq_parameter_set_id`.
    pub sps_id: u8,
    /// `separate_colour_plane_flag` (gates `colour_plane_id`).
    pub separate_colour_plane: bool,
    /// `log2_max_frame_num_minus4 + 4` — the bit width of `frame_num`.
    pub log2_max_frame_num: u8,
    /// `pic_order_cnt_type`.
    pub pic_order_cnt_type: u8,
    /// `log2_max_pic_order_cnt_lsb_minus4 + 4` (POC type 0 only, else 0).
    pub log2_max_poc_lsb: u8,
    /// `delta_pic_order_always_zero_flag` (POC type 1 only, else `false`).
    pub delta_pic_order_always_zero: bool,
    /// `frame_mbs_only_flag` (gates `field_pic_flag`).
    pub frame_mbs_only: bool,
    /// `mb_adaptive_frame_field_flag` (`false` when absent, i.e. when
    /// `frame_mbs_only_flag` is 1 — H.264 §7.3.2.1.1).
    pub mb_adaptive_frame_field: bool,
    /// How to read `pic_struct` out of a picture timing SEI for this SPS, or
    /// `None` when `pic_struct_present_flag` is 0, there is no VUI, the VUI was
    /// truncated, or the NAL and VCL HRD delay lengths disagree (see
    /// `docs/codec/h264-vui-pic-timing.md`).
    pub pic_timing: Option<AvcPicTimingLayout>,
}

/// The part of the H.264 `pic_timing` SEI layout (§D.1.3) that depends on the
/// SPS VUI, for an SPS whose `pic_struct_present_flag` is 1.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct AvcPicTimingLayout {
    /// `(cpb_removal_delay bits, dpb_output_delay bits)` that precede
    /// `pic_struct` when `CpbDpbDelaysPresentFlag` is 1 (a NAL or VCL
    /// `hrd_parameters()` is present), else `None`.
    pub delay_bits: Option<(u8, u8)>,
}

/// Decode only the slice-header-relevant SPS fields ([`AvcSliceSps`]) from an
/// H.264 SPS NAL unit (1-byte NAL header included).
pub fn decode_avc_slice_sps(sps_bytes: &[u8]) -> Result<AvcSliceSps> {
    decode_avc_sps_inner(sps_bytes).map(|(_, s)| s)
}

fn decode_avc_sps_inner(sps_bytes: &[u8]) -> Result<(AvcSpsInfo, AvcSliceSps)> {
    if sps_bytes.len() < 4 {
        return Err(Error::BufferTooShort {
            need: 4,
            have: sps_bytes.len(),
            what: "H.264 SPS header",
        });
    }

    // Byte 0 is the NAL header (nal_ref_idc + nal_unit_type).
    // Byte 1 is profile_idc.
    let profile_idc = sps_bytes[1];
    let constraint_flags = sps_bytes[2];
    let level_idc = sps_bytes[3];

    // Unescape the RBSP: starts after level_idc (byte index 3, i.e. sps_bytes[4]).
    let mut r = BitReader::with_unescape(&sps_bytes[4..], "H.264 SPS")?;

    // seq_parameter_set_id — ue(v)
    // Saturating (not validated): `decode_avc_sps` never rejected these.
    let sps_id = r.read_ue("seq_parameter_set_id")?.min(u8::MAX as u64) as u8;

    // High-profile branch
    let (chroma_format_idc, separate_colour_plane, bit_depth_luma, bit_depth_chroma) =
        if is_high_profile(profile_idc) {
            // H.264 §7.4.2.1: chroma_format_idc shall be 0..=3.
            let chroma_format_idc =
                ue_to_u8(r.read_ue("chroma_format_idc")?, 3, "chroma_format_idc")?;
            let separate_colour_plane = if chroma_format_idc == 3 {
                r.read_flag("separate_colour_plane_flag")?
            } else {
                false
            };
            // H.264 §7.4.2.1: bit_depth_luma_minus8 / bit_depth_chroma_minus8
            // shall be 0..=6 (max bit depth 14).
            let bit_depth_luma = ue_bit_depth(
                r.read_ue("bit_depth_luma_minus8")?,
                6,
                "bit_depth_luma_minus8",
            )?;
            let bit_depth_chroma = ue_bit_depth(
                r.read_ue("bit_depth_chroma_minus8")?,
                6,
                "bit_depth_chroma_minus8",
            )?;
            let _ = r.read_flag("qpprime_y_zero_transform_bypass_flag")?;
            let scaling_matrix_present = r.read_flag("seq_scaling_matrix_present_flag")?;
            if scaling_matrix_present {
                let list_count = if chroma_format_idc != 3 { 8 } else { 12 };
                for _i in 0..list_count {
                    let list_present = r.read_flag("seq_scaling_list_present_flag[i]")?;
                    if list_present {
                        let size: usize = if _i < 6 { 16 } else { 64 };
                        let mut last_scale: i64 = 8;
                        let mut next_scale: i64 = 8;
                        for _j in 0..size {
                            if next_scale != 0 {
                                let delta_scale = r.read_se("delta_scale")?;
                                next_scale = (last_scale + delta_scale + 256) % 256;
                            }
                            if next_scale == 0 {
                                // use default; don't change last_scale
                            } else {
                                last_scale = next_scale;
                            }
                        }
                    }
                }
            }
            (
                chroma_format_idc,
                separate_colour_plane,
                bit_depth_luma,
                bit_depth_chroma,
            )
        } else {
            (1, false, 8, 8)
        };

    // log2_max_frame_num_minus4 — ue(v)
    // §7.4.2.1.1: log2_max_frame_num_minus4 is 0..=12 (clamped, not rejected).
    let log2_max_frame_num = r.read_ue("log2_max_frame_num_minus4")?.min(12) as u8 + 4;
    // pic_order_cnt_type — ue(v)
    let pic_order_cnt_type = r.read_ue("pic_order_cnt_type")?;
    let mut log2_max_poc_lsb = 0u8;
    let mut delta_pic_order_always_zero = false;
    if pic_order_cnt_type == 0 {
        // §7.4.2.1.1: log2_max_pic_order_cnt_lsb_minus4 is 0..=12 (clamped).
        log2_max_poc_lsb = r.read_ue("log2_max_pic_order_cnt_lsb_minus4")?.min(12) as u8 + 4;
    } else if pic_order_cnt_type == 1 {
        delta_pic_order_always_zero = r.read_flag("delta_pic_order_always_zero_flag")?;
        let _ = r.read_se("offset_for_non_ref_pic")?;
        let _ = r.read_se("offset_for_top_to_bottom_field")?;
        let num_ref_frames = r.read_ue("num_ref_frames_in_pic_order_cnt_cycle")?;
        // H.264 §7.4.2.1: num_ref_frames_in_pic_order_cnt_cycle shall be
        // 0..=255. Unbounded, this loop is the ~20-byte-SPS demux hang: a
        // hostile count spins on `read_se` (which used to return Ok(0) at
        // EOF without consuming) for billions of iterations.
        if num_ref_frames > 255 {
            return Err(Error::InvalidValue {
                field: "num_ref_frames_in_pic_order_cnt_cycle",
                value: num_ref_frames,
                reason: "out of range 0..=255 (H.264 §7.4.2.1)",
            });
        }
        for _ in 0..num_ref_frames {
            let _ = r.read_se("offset_for_ref_frame[i]")?;
        }
    }
    // max_num_ref_frames — ue(v)
    let _ = r.read_ue("max_num_ref_frames")?;
    // gaps_in_frame_num_value_allowed_flag — 1 bit
    let _ = r.read_flag("gaps_in_frame_num_value_allowed_flag")?;
    // pic_width_in_mbs_minus1 — ue(v)
    let pic_width_in_mbs_minus1 = r.read_ue("pic_width_in_mbs_minus1")?;
    // pic_height_in_map_units_minus1 — ue(v)
    let pic_height_in_map_units_minus1 = r.read_ue("pic_height_in_map_units_minus1")?;
    // frame_mbs_only_flag — 1 bit
    let frame_mbs_only = r.read_flag("frame_mbs_only_flag")?;

    let mut mb_adaptive_frame_field = false;
    if !frame_mbs_only {
        mb_adaptive_frame_field = r.read_flag("mb_adaptive_frame_field_flag")?;
    }

    // direct_8x8_inference_flag — 1 bit
    let _ = r.read_flag("direct_8x8_inference_flag")?;
    // frame_cropping_flag — 1 bit
    let frame_cropping = r.read_flag("frame_cropping_flag")?;

    let (crop_left, crop_right, crop_top, crop_bottom) = if frame_cropping {
        let cl = r.read_ue("frame_crop_left_offset")?;
        let cr = r.read_ue("frame_crop_right_offset")?;
        let ct = r.read_ue("frame_crop_top_offset")?;
        let cb = r.read_ue("frame_crop_bottom_offset")?;
        (cl, cr, ct, cb)
    } else {
        (0, 0, 0, 0)
    };

    // Compute coded dimensions
    let pic_width_in_mbs = pic_width_in_mbs_minus1 + 1;
    let pic_height_in_map_units = pic_height_in_map_units_minus1 + 1;
    let frame_height_in_mbs = (2 - frame_mbs_only as u64) * pic_height_in_map_units;

    let crop_unit_x = sub_width_c(chroma_format_idc) as u64;
    let crop_unit_y = sub_height_c(chroma_format_idc) as u64 * (2 - frame_mbs_only as u64);

    let width = (pic_width_in_mbs * 16).saturating_sub(crop_unit_x * (crop_left + crop_right));
    let height = (frame_height_in_mbs * 16).saturating_sub(crop_unit_y * (crop_top + crop_bottom));

    // vui_parameters — ITU-T H.264 §E.1.1.  Walk in syntax order to reach
    // timing_info; stop reading after timing_info_present_flag.
    let vui = parse_avc_vui(&mut r);
    let (num_units_in_tick, time_scale, fps) = vui.timing;

    Ok((
        AvcSpsInfo {
            profile_idc,
            constraint_flags,
            level_idc,
            chroma_format_idc,
            separate_colour_plane,
            bit_depth_luma,
            bit_depth_chroma,
            frame_mbs_only,
            width: width as u32,
            height: height as u32,
            num_units_in_tick,
            time_scale,
            fps,
        },
        AvcSliceSps {
            sps_id,
            separate_colour_plane,
            log2_max_frame_num,
            pic_order_cnt_type: pic_order_cnt_type.min(u8::MAX as u64) as u8,
            log2_max_poc_lsb,
            delta_pic_order_always_zero,
            frame_mbs_only,
            mb_adaptive_frame_field,
            pic_timing: vui.pic_timing,
        },
    ))
}

/// What the H.264 VUI walk yields (§E.1.1).
#[derive(Default)]
struct AvcVuiFacts {
    /// `(num_units_in_tick, time_scale, fps)`.
    timing: (Option<u32>, Option<u32>, Option<f32>),
    pic_timing: Option<AvcPicTimingLayout>,
}

/// Walk the H.264 VUI syntax (ITU-T H.264 §E.1.1) in order through
/// `pic_struct_present_flag`, collecting the timing info and the `pic_timing`
/// SEI layout.
///
/// Each result stays at its default when VUI is absent or the bit-reader runs
/// out of data before reaching it (e.g. truncated SPS); a fact read before the
/// truncation is kept. Errors are swallowed because VUI is optional and its
/// absence must not prevent the caller from using the already-decoded
/// mandatory fields.
fn parse_avc_vui(r: &mut BitReader) -> AvcVuiFacts {
    let mut facts = AvcVuiFacts::default();
    let _ = parse_avc_vui_inner(r, &mut facts);
    facts
}

/// Bits of `cpb_removal_delay_length_minus1` / `dpb_output_delay_length_minus1`
/// (H.264 §E.1.2, `u(5)`), and of the other `u(5)` HRD fields.
const HRD_LENGTH_FIELD_BITS: usize = 5;
/// Largest `cpb_cnt_minus1` (H.264 §E.2.2: 0..=31).
const HRD_MAX_CPB_CNT_MINUS1: u64 = 31;

/// Walk one H.264 `hrd_parameters()` (§E.1.2); returns
/// `(cpb_removal_delay_length, dpb_output_delay_length)` in bits.
fn parse_avc_hrd(r: &mut BitReader) -> crate::error::Result<(u8, u8)> {
    let cpb_cnt_minus1 = r.read_ue("cpb_cnt_minus1")?;
    if cpb_cnt_minus1 > HRD_MAX_CPB_CNT_MINUS1 {
        return Err(Error::InvalidValue {
            field: "cpb_cnt_minus1",
            value: cpb_cnt_minus1,
            reason: "out of range 0..=31 (H.264 §E.2.2)",
        });
    }
    let _ = r.read_bits(4, "bit_rate_scale")?;
    let _ = r.read_bits(4, "cpb_size_scale")?;
    for _ in 0..=cpb_cnt_minus1 {
        let _ = r.read_ue("bit_rate_value_minus1")?;
        let _ = r.read_ue("cpb_size_value_minus1")?;
        let _ = r.read_flag("cbr_flag")?;
    }
    let _ = r.read_bits(
        HRD_LENGTH_FIELD_BITS,
        "initial_cpb_removal_delay_length_minus1",
    )?;
    let cpb = r.read_bits(HRD_LENGTH_FIELD_BITS, "cpb_removal_delay_length_minus1")? as u8 + 1;
    let dpb = r.read_bits(HRD_LENGTH_FIELD_BITS, "dpb_output_delay_length_minus1")? as u8 + 1;
    let _ = r.read_bits(HRD_LENGTH_FIELD_BITS, "time_offset_length")?;
    Ok((cpb, dpb))
}

fn parse_avc_vui_inner(r: &mut BitReader, facts: &mut AvcVuiFacts) -> crate::error::Result<()> {
    // vui_parameters_present_flag  u(1)
    let vui_present = r.read_flag("vui_parameters_present_flag")?;
    if !vui_present {
        return Ok(());
    }

    // aspect_ratio_info_present_flag  u(1) — §E.1.1
    let ari_present = r.read_flag("aspect_ratio_info_present_flag")?;
    if ari_present {
        let aspect_ratio_idc = r.read_bits(8, "aspect_ratio_idc")? as u8;
        // Extended_SAR = 255 → sar_width u(16), sar_height u(16)
        if aspect_ratio_idc == 255 {
            let _ = r.read_bits(16, "sar_width")?;
            let _ = r.read_bits(16, "sar_height")?;
        }
    }

    // overscan_info_present_flag  u(1)
    let overscan_present = r.read_flag("overscan_info_present_flag")?;
    if overscan_present {
        let _ = r.read_flag("overscan_appropriate_flag")?;
    }

    // video_signal_type_present_flag  u(1)
    let vst_present = r.read_flag("video_signal_type_present_flag")?;
    if vst_present {
        let _ = r.read_bits(3, "video_format")?;
        let _ = r.read_flag("video_full_range_flag")?;
        let colour_desc = r.read_flag("colour_description_present_flag")?;
        if colour_desc {
            let _ = r.read_bits(8, "colour_primaries")?;
            let _ = r.read_bits(8, "transfer_characteristics")?;
            let _ = r.read_bits(8, "matrix_coefficients")?;
        }
    }

    // chroma_loc_info_present_flag  u(1)
    let cli_present = r.read_flag("chroma_loc_info_present_flag")?;
    if cli_present {
        let _ = r.read_ue("chroma_sample_loc_type_top_field")?;
        let _ = r.read_ue("chroma_sample_loc_type_bottom_field")?;
    }

    // timing_info_present_flag  u(1)
    let timing_present = r.read_flag("timing_info_present_flag")?;
    if timing_present {
        let num_units = r.read_bits(32, "num_units_in_tick")? as u32;
        let ts = r.read_bits(32, "time_scale")? as u32;
        let _ = r.read_flag("fixed_frame_rate_flag")?;
        let fps = if num_units > 0 {
            Some(ts as f32 / (2.0 * num_units as f32))
        } else {
            None
        };
        facts.timing = (Some(num_units), Some(ts), fps);
    }

    // nal_hrd_parameters_present_flag / vcl_hrd_parameters_present_flag
    let nal_hrd = if r.read_flag("nal_hrd_parameters_present_flag")? {
        Some(parse_avc_hrd(r)?)
    } else {
        None
    };
    let vcl_hrd = if r.read_flag("vcl_hrd_parameters_present_flag")? {
        Some(parse_avc_hrd(r)?)
    } else {
        None
    };
    if nal_hrd.is_some() || vcl_hrd.is_some() {
        let _ = r.read_flag("low_delay_hrd_flag")?;
    }
    let pic_struct_present = r.read_flag("pic_struct_present_flag")?;
    if pic_struct_present {
        // CpbDpbDelaysPresentFlag (§E.2.1) is 1 when either HRD is present.
        // When both are, the spec does not say which one sizes the SEI fields;
        // read pic_struct only if they agree.
        let delay_bits = match (nal_hrd, vcl_hrd) {
            (Some(a), Some(b)) if a != b => return Ok(()),
            (Some(a), _) | (None, Some(a)) => Some(a),
            (None, None) => None,
        };
        facts.pic_timing = Some(AvcPicTimingLayout { delay_bits });
    }
    Ok(())
}

// ---------------------------------------------------------------------------
// HevcSpsInfo
// ---------------------------------------------------------------------------

/// Decoded fields from an H.265/HEVC sequence parameter set.
///
/// The `Eq` bound is intentionally absent because `fps` is an `Option<f32>`.
#[derive(Debug, Clone, PartialEq)]
pub struct HevcSpsInfo {
    /// `general_profile_space` (2 bits).
    pub general_profile_space: u8,
    /// `general_tier_flag` (1 bit).
    pub general_tier_flag: bool,
    /// `general_profile_idc` (5 bits).
    pub general_profile_idc: u8,
    /// `general_profile_compatibility_flags` (32 bits).
    pub general_profile_compatibility_flags: u32,
    /// `general_constraint_indicator_flags` (48 bits, i.e. 6 bytes).
    pub general_constraint_indicator_flags: u64,
    /// `general_level_idc` (8 bits).
    pub general_level_idc: u8,
    /// `chroma_format_idc` — ue(v)
    pub chroma_format_idc: u8,
    /// `bit_depth_luma` (= `bit_depth_luma_minus8 + 8`).
    pub bit_depth_luma: u8,
    /// `bit_depth_chroma` (= `bit_depth_chroma_minus8 + 8`).
    pub bit_depth_chroma: u8,
    /// Coded width in luma samples (conformance-window cropped).
    pub width: u32,
    /// Coded height in luma samples (conformance-window cropped).
    pub height: u32,
    /// `vui_num_units_in_tick` from VUI `vui_timing_info` (ITU-T H.265 §E.2.1).
    ///
    /// Present only when `vui_parameters_present_flag` and
    /// `vui_timing_info_present_flag` are both 1 in the SPS.
    pub num_units_in_tick: Option<u32>,
    /// `vui_time_scale` from VUI `vui_timing_info` (ITU-T H.265 §E.2.1).
    ///
    /// Present only when `vui_parameters_present_flag` and
    /// `vui_timing_info_present_flag` are both 1 in the SPS.
    pub time_scale: Option<u32>,
    /// Frame rate derived from VUI `vui_timing_info` (ITU-T H.265 §E.2.1):
    /// `vui_time_scale / vui_num_units_in_tick`.
    ///
    /// Note: unlike H.264, HEVC does **not** divide by 2 — the clock tick rate
    /// directly gives the frame rate.
    ///
    /// `None` when `vui_parameters_present_flag` or `vui_timing_info_present_flag`
    /// is 0, or when `vui_num_units_in_tick` is 0.
    pub fps: Option<f32>,
}

/// Decode an H.265/HEVC SPS RBSP and return the config-relevant fields.
///
/// `sps_bytes` is the full NAL unit including the 2-byte NAL header
/// (`nal_unit_header()` — ITU-T H.265 §7.3.1.2). Decoding starts at byte
/// index 2 (the first byte of `seq_parameter_set_rbsp()`).
///
/// # Spec citations
///
/// - **Syntax**: ITU-T H.265 §7.3.2.2.1 `seq_parameter_set_rbsp()`.
/// - **Semantics**: ITU-T H.265 §7.4.3.2.1 — definitions of
///   `pic_width_in_luma_samples`, `pic_height_in_luma_samples`,
///   `conformance_window_flag` / `conf_win_{left,right,top,bottom}_offset`,
///   and the SubWidthC / SubHeightC multipliers (Table 6-1) used to convert
///   the chroma-sample offsets to luma-sample crop amounts.
/// - **profile_tier_level**: ITU-T H.265 §7.3.3 + §7.4.4.
///
/// # Conformance-window crop
///
/// The returned `width` and `height` are the *display* dimensions after
/// subtracting the conformance-window offsets (§7.4.3.2.1):
///
/// ```text
/// SubWidthC  = 2 for chroma_format_idc 1 (4:2:0) or 2 (4:2:2), 1 otherwise
/// SubHeightC = 2 for chroma_format_idc 1 (4:2:0),               1 otherwise
/// width  = pic_width_in_luma_samples
///            - SubWidthC  * (conf_win_left_offset + conf_win_right_offset)
/// height = pic_height_in_luma_samples
///            - SubHeightC * (conf_win_top_offset  + conf_win_bottom_offset)
/// ```
pub fn decode_hevc_sps(sps_bytes: &[u8]) -> Result<HevcSpsInfo> {
    decode_hevc_sps_inner(sps_bytes).map(|(info, _)| info)
}

/// The interlace-relevant facts of an H.265 SPS (ITU-T H.265 §E.3.1; see
/// `docs/codec/h265-vui-pic-timing.md`).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct HevcInterlaceSps {
    /// `field_seq_flag`: the CVS conveys pictures that represent fields
    /// (inferred `false` when the VUI is absent or truncated before it).
    pub field_seq: bool,
    /// `frame_field_info_present_flag`: picture timing SEIs carry
    /// `pic_struct`. Read from the VUI, else inferred from
    /// `general_progressive_source_flag && general_interlaced_source_flag`.
    pub frame_field_info_present: bool,
}

/// Decode only the interlace facts ([`HevcInterlaceSps`]) from an H.265 SPS
/// NAL unit (2-byte NAL header included).
pub fn decode_hevc_interlace_sps(sps_bytes: &[u8]) -> Result<HevcInterlaceSps> {
    decode_hevc_sps_inner(sps_bytes).map(|(_, i)| i)
}

/// `general_progressive_source_flag` — bit 47 of the 48-bit
/// `general_constraint_indicator_flags` as read MSB-first (H.265 §7.3.3).
const PTL_PROGRESSIVE_SOURCE_BIT: u64 = 1 << 47;
/// `general_interlaced_source_flag` — bit 46 (H.265 §7.3.3).
const PTL_INTERLACED_SOURCE_BIT: u64 = 1 << 46;

fn decode_hevc_sps_inner(sps_bytes: &[u8]) -> Result<(HevcSpsInfo, HevcInterlaceSps)> {
    if sps_bytes.len() < 2 {
        return Err(Error::BufferTooShort {
            need: 2,
            have: sps_bytes.len(),
            what: "HEVC SPS header",
        });
    }

    let mut r = BitReader::with_unescape(&sps_bytes[2..], "HEVC SPS")?;

    // sps_video_parameter_set_id — u(4)
    let _ = r.read_bits(4, "sps_video_parameter_set_id")?;
    // sps_max_sub_layers_minus1 — u(3)
    let sps_max_sub_layers_minus1 = r.read_bits(3, "sps_max_sub_layers_minus1")? as u8;
    // sps_temporal_id_nesting_flag — u(1)
    let _ = r.read_flag("sps_temporal_id_nesting_flag")?;

    // profile_tier_level(1, sps_max_sub_layers_minus1)
    let (
        general_profile_space,
        general_tier_flag,
        general_profile_idc,
        general_profile_compatibility_flags,
        general_constraint_indicator_flags,
        general_level_idc,
    ) = decode_ptl(&mut r, true, sps_max_sub_layers_minus1)?;

    // sps_seq_parameter_set_id — ue(v)
    let _ = r.read_ue("sps_seq_parameter_set_id")?;
    // chroma_format_idc — ue(v)
    // H.265 §7.4.3.2 / Table 6-1: chroma_format_idc shall be 0..=3.
    let chroma_format_idc = ue_to_u8(r.read_ue("chroma_format_idc")?, 3, "chroma_format_idc")?;
    if chroma_format_idc == 3 {
        let _ = r.read_flag("separate_colour_plane_flag")?;
    }
    // pic_width_in_luma_samples — ue(v)
    let pic_width_in_luma_samples = r.read_ue("pic_width_in_luma_samples")?;
    // pic_height_in_luma_samples — ue(v)
    let pic_height_in_luma_samples = r.read_ue("pic_height_in_luma_samples")?;
    // conformance_window_flag — u(1)
    let conformance_window = r.read_flag("conformance_window_flag")?;
    let (conf_win_left, conf_win_right, conf_win_top, conf_win_bottom) = if conformance_window {
        let left = r.read_ue("conf_win_left_offset")?;
        let right = r.read_ue("conf_win_right_offset")?;
        let top = r.read_ue("conf_win_top_offset")?;
        let bottom = r.read_ue("conf_win_bottom_offset")?;
        (left, right, top, bottom)
    } else {
        (0, 0, 0, 0)
    };

    // bit_depth_luma_minus8 — ue(v)
    // H.265 §7.4.3.2: bit_depth_luma/chroma_minus8 shall be 0..=8 (bit depth
    // up to 16 for Main16); checked conversion, never a raw `as u8 + 8`.
    let bit_depth_luma = ue_bit_depth(
        r.read_ue("bit_depth_luma_minus8")?,
        8,
        "bit_depth_luma_minus8",
    )?;
    // bit_depth_chroma_minus8 — ue(v)
    let bit_depth_chroma = ue_bit_depth(
        r.read_ue("bit_depth_chroma_minus8")?,
        8,
        "bit_depth_chroma_minus8",
    )?;

    // Compute cropped dimensions.
    let sub_width_c = match chroma_format_idc {
        1 | 2 => 2,
        3 => 1,
        _ => 1,
    };
    let sub_height_c = match chroma_format_idc {
        1 => 2,
        2 | 3 => 1,
        _ => 1,
    };

    let width = pic_width_in_luma_samples
        .saturating_sub((sub_width_c as u64) * (conf_win_left + conf_win_right));
    let height = pic_height_in_luma_samples
        .saturating_sub((sub_height_c as u64) * (conf_win_top + conf_win_bottom));

    // Walk the remaining HEVC SPS syntax (§7.3.2.2.1) up to and including
    // vui_parameters() in order to reach vui_timing_info.
    // frame_field_info_present_flag defaults to its §E.3.1 inference; the VUI
    // overwrites it when present.
    let mut interlace = HevcInterlaceSps {
        field_seq: false,
        frame_field_info_present: general_constraint_indicator_flags & PTL_PROGRESSIVE_SOURCE_BIT
            != 0
            && general_constraint_indicator_flags & PTL_INTERLACED_SOURCE_BIT != 0,
    };
    let (num_units_in_tick, time_scale, fps) =
        parse_hevc_sps_to_vui_timing(&mut r, sps_max_sub_layers_minus1, &mut interlace);

    Ok((
        HevcSpsInfo {
            general_profile_space,
            general_tier_flag,
            general_profile_idc,
            general_profile_compatibility_flags,
            general_constraint_indicator_flags,
            general_level_idc,
            chroma_format_idc,
            bit_depth_luma,
            bit_depth_chroma,
            width: width as u32,
            height: height as u32,
            num_units_in_tick,
            time_scale,
            fps,
        },
        interlace,
    ))
}

/// Walk the H.265 SPS syntax (ITU-T H.265 §7.3.2.2.1) from
/// `log2_max_pic_order_cnt_lsb_minus4` through `vui_parameters()` (§E.2.1) to
/// extract `vui_num_units_in_tick` and `vui_time_scale`.
///
/// Returns `(num_units_in_tick, time_scale, fps)`.  All three are `None` when
/// VUI is absent, `vui_timing_info_present_flag` is 0, or the bit-reader runs
/// out of data before reaching the timing fields.  Errors are silently swallowed
/// because VUI is optional and its absence must not prevent the caller from using
/// the already-decoded mandatory fields.
fn parse_hevc_sps_to_vui_timing(
    r: &mut BitReader,
    sps_max_sub_layers_minus1: u8,
    interlace: &mut HevcInterlaceSps,
) -> (Option<u32>, Option<u32>, Option<f32>) {
    parse_hevc_sps_to_vui_timing_inner(r, sps_max_sub_layers_minus1, interlace)
        .unwrap_or((None, None, None))
}

/// Largest `num_negative_pics`/`num_positive_pics` (H.265 §7.4.8: at most
/// `sps_max_dec_pic_buffering_minus1`, itself at most `MaxDpbSize - 1` = 15;
/// 16 is a generous bound that still caps hostile input).
const HEVC_MAX_RPS_PICS: u64 = 16;

fn parse_hevc_sps_to_vui_timing_inner(
    r: &mut BitReader,
    sps_max_sub_layers_minus1: u8,
    interlace: &mut HevcInterlaceSps,
) -> crate::error::Result<(Option<u32>, Option<u32>, Option<f32>)> {
    // log2_max_pic_order_cnt_lsb_minus4  ue(v)
    let log2_max_poc_lsb = r.read_ue("log2_max_pic_order_cnt_lsb_minus4")?;

    // sps_sub_layer_ordering_info_present_flag  u(1)
    let sub_layer_ordering = r.read_flag("sps_sub_layer_ordering_info_present_flag")?;
    let start_layer = if sub_layer_ordering {
        0
    } else {
        sps_max_sub_layers_minus1
    };
    for _i in start_layer..=sps_max_sub_layers_minus1 {
        let _ = r.read_ue("sps_max_dec_pic_buffering_minus1")?;
        let _ = r.read_ue("sps_max_num_reorder_pics")?;
        let _ = r.read_ue("sps_max_latency_increase_plus1")?;
    }

    // log2_min_luma_coding_block_size_minus3  ue(v)
    let _ = r.read_ue("log2_min_luma_coding_block_size_minus3")?;
    // log2_diff_max_min_luma_coding_block_size  ue(v)
    let _ = r.read_ue("log2_diff_max_min_luma_coding_block_size")?;
    // log2_min_luma_transform_block_size_minus2  ue(v)
    let _ = r.read_ue("log2_min_luma_transform_block_size_minus2")?;
    // log2_diff_max_min_luma_transform_block_size  ue(v)
    let _ = r.read_ue("log2_diff_max_min_luma_transform_block_size")?;
    // max_transform_hierarchy_depth_inter  ue(v)
    let _ = r.read_ue("max_transform_hierarchy_depth_inter")?;
    // max_transform_hierarchy_depth_intra  ue(v)
    let _ = r.read_ue("max_transform_hierarchy_depth_intra")?;

    // scaling_list_enabled_flag  u(1)
    let scaling_list_enabled = r.read_flag("scaling_list_enabled_flag")?;
    if scaling_list_enabled {
        let sps_scaling_list_data_present = r.read_flag("sps_scaling_list_data_present_flag")?;
        if sps_scaling_list_data_present {
            // scaling_list_data() — §7.3.4
            for size_id in 0u32..4 {
                let matrix_count = if size_id == 3 { 2 } else { 6 };
                for _matrix_id in 0..matrix_count {
                    let pred_mode = r.read_flag("scaling_list_pred_mode_flag")?;
                    if !pred_mode {
                        let _ = r.read_ue("scaling_list_pred_matrix_id_delta")?;
                    } else {
                        let coef_num = core::cmp::min(64u32, 1 << (4 + (size_id << 1)));
                        if size_id > 1 {
                            let _ = r.read_ue("scaling_list_dc_coef_minus8")?;
                        }
                        for _i in 0..coef_num {
                            let _ = r.read_ue("scaling_list_delta_coef")?;
                        }
                    }
                }
            }
        }
    }

    // amp_enabled_flag  u(1)
    let _ = r.read_flag("amp_enabled_flag")?;
    // sample_adaptive_offset_enabled_flag  u(1)
    let _ = r.read_flag("sample_adaptive_offset_enabled_flag")?;

    // pcm_enabled_flag  u(1)
    let pcm_enabled = r.read_flag("pcm_enabled_flag")?;
    if pcm_enabled {
        let _ = r.read_bits(4, "pcm_sample_bit_depth_luma_minus1")?;
        let _ = r.read_bits(4, "pcm_sample_bit_depth_chroma_minus1")?;
        let _ = r.read_ue("log2_min_pcm_luma_coding_block_size_minus3")?;
        let _ = r.read_ue("log2_diff_max_min_pcm_luma_coding_block_size")?;
        let _ = r.read_flag("pcm_loop_filter_disabled_flag")?;
    }

    // num_short_term_ref_pic_sets  ue(v)
    let num_short_term = r.read_ue("num_short_term_ref_pic_sets")?;
    // H.265 §7.4.3.2: num_short_term_ref_pic_sets shall be 0..=64; an
    // unbounded value here is the same CPU-hang class as the AVC POC-cycle
    // loop (the VUI walk swallows this Err, so the SPS decode still returns,
    // just without timing).
    if num_short_term > 64 {
        return Err(Error::InvalidValue {
            field: "num_short_term_ref_pic_sets",
            value: num_short_term,
            reason: "out of range 0..=64 (H.265 §7.4.3.2)",
        });
    }
    // st_ref_pic_set() — §7.3.7, including inter-RPS prediction (7-61/7-62),
    // so the walk can reach the VUI (`field_seq_flag`) on every stream.
    let mut rps_sets: Vec<(Vec<i64>, Vec<i64>)> = Vec::new();
    for i in 0..num_short_term {
        let inter_ref = if i != 0 {
            r.read_flag("inter_ref_pic_set_prediction_flag")?
        } else {
            false
        };
        let set = if inter_ref {
            // delta_idx_minus1 is absent in the SPS (it is only coded in the
            // slice header, stRpsIdx == num_short_term_ref_pic_sets), so
            // RefRpsIdx = stRpsIdx - 1.
            let (ref_s0, ref_s1) = &rps_sets[rps_sets.len() - 1];
            let delta_rps_sign = r.read_flag("delta_rps_sign")?;
            let abs_delta_rps_minus1 = r.read_ue("abs_delta_rps_minus1")?;
            if abs_delta_rps_minus1 >= 1 << 15 {
                return Err(Error::InvalidValue {
                    field: "abs_delta_rps_minus1",
                    value: abs_delta_rps_minus1,
                    reason: "out of range 0..=2^15-1 (H.265 §7.4.8)",
                });
            }
            let magnitude = abs_delta_rps_minus1 as i64 + 1;
            let delta_rps = if delta_rps_sign {
                -magnitude
            } else {
                magnitude
            };
            let num_delta_pocs = ref_s0.len() + ref_s1.len();
            // use_delta_flag[j] for j in 0..=NumDeltaPocs[Ref] (inferred 1
            // when used_by_curr_pic_flag[j] is 1).
            let mut use_delta = Vec::with_capacity(num_delta_pocs + 1);
            for _j in 0..=num_delta_pocs {
                let used_by_curr = r.read_flag("used_by_curr_pic_flag")?;
                use_delta.push(if used_by_curr {
                    true
                } else {
                    r.read_flag("use_delta_flag")?
                });
            }
            let (n0, n1) = (ref_s0.len(), ref_s1.len());
            let mut s0: Vec<i64> = Vec::new();
            let mut s1: Vec<i64> = Vec::new();
            // (7-61)
            for j in (0..n1).rev() {
                let d = ref_s1[j] + delta_rps;
                if d < 0 && use_delta[n0 + j] {
                    s0.push(d);
                }
            }
            if delta_rps < 0 && use_delta[num_delta_pocs] {
                s0.push(delta_rps);
            }
            for j in 0..n0 {
                let d = ref_s0[j] + delta_rps;
                if d < 0 && use_delta[j] {
                    s0.push(d);
                }
            }
            // (7-62)
            for j in (0..n0).rev() {
                let d = ref_s0[j] + delta_rps;
                if d > 0 && use_delta[j] {
                    s1.push(d);
                }
            }
            if delta_rps > 0 && use_delta[num_delta_pocs] {
                s1.push(delta_rps);
            }
            for j in 0..n1 {
                let d = ref_s1[j] + delta_rps;
                if d > 0 && use_delta[n0 + j] {
                    s1.push(d);
                }
            }
            (s0, s1)
        } else {
            let num_negative = r.read_ue("num_negative_pics")?;
            let num_positive = r.read_ue("num_positive_pics")?;
            // §7.4.8: each is at most sps_max_dec_pic_buffering_minus1 (<= 15).
            if num_negative > HEVC_MAX_RPS_PICS || num_positive > HEVC_MAX_RPS_PICS {
                return Err(Error::InvalidValue {
                    field: "num_negative_pics/num_positive_pics",
                    value: num_negative.max(num_positive),
                    reason: "out of range 0..=16 (H.265 §7.4.8)",
                });
            }
            let mut s0 = Vec::new();
            let mut acc = 0i64;
            for _j in 0..num_negative {
                acc -= r.read_ue("delta_poc_s0_minus1")? as i64 + 1;
                let _ = r.read_flag("used_by_curr_pic_s0_flag")?;
                s0.push(acc);
            }
            let mut s1 = Vec::new();
            let mut acc = 0i64;
            for _j in 0..num_positive {
                acc += r.read_ue("delta_poc_s1_minus1")? as i64 + 1;
                let _ = r.read_flag("used_by_curr_pic_s1_flag")?;
                s1.push(acc);
            }
            (s0, s1)
        };
        if set.0.len() > HEVC_MAX_RPS_PICS as usize || set.1.len() > HEVC_MAX_RPS_PICS as usize {
            return Err(Error::InvalidValue {
                field: "NumNegativePics/NumPositivePics",
                value: set.0.len().max(set.1.len()) as u64,
                reason: "derived RPS larger than 16 entries (H.265 §7.4.8)",
            });
        }
        rps_sets.push(set);
    }

    // long_term_ref_pics_present_flag  u(1)
    let ltrp_present = r.read_flag("long_term_ref_pics_present_flag")?;
    if ltrp_present {
        let num_lt = r.read_ue("num_long_term_ref_pics_sps")?;
        // Each entry: lt_ref_pic_poc_lsb_sps u(log2_max_poc_lsb+4)
        //            + used_by_curr_pic_lt_sps_flag u(1)
        let poc_bits = log2_max_poc_lsb + 4;
        for _i in 0..num_lt {
            let _ = r.read_bits(poc_bits as usize, "lt_ref_pic_poc_lsb_sps")?;
            let _ = r.read_flag("used_by_curr_pic_lt_sps_flag")?;
        }
    }

    // sps_temporal_mvp_enabled_flag  u(1)
    let _ = r.read_flag("sps_temporal_mvp_enabled_flag")?;
    // strong_intra_smoothing_enabled_flag  u(1)
    let _ = r.read_flag("strong_intra_smoothing_enabled_flag")?;

    // vui_parameters_present_flag  u(1)
    let vui_present = r.read_flag("vui_parameters_present_flag")?;
    if !vui_present {
        return Ok((None, None, None));
    }

    // vui_parameters() — ITU-T H.265 §E.2.1.  Walk in syntax order to reach
    // vui_timing_info_present_flag; stop after reading vui_time_scale.

    // aspect_ratio_info_present_flag  u(1)
    let ari_present = r.read_flag("aspect_ratio_info_present_flag")?;
    if ari_present {
        let aspect_ratio_idc = r.read_bits(8, "aspect_ratio_idc")? as u8;
        // Extended_SAR = 255 → sar_width u(16), sar_height u(16)
        if aspect_ratio_idc == 255 {
            let _ = r.read_bits(16, "sar_width")?;
            let _ = r.read_bits(16, "sar_height")?;
        }
    }

    // overscan_info_present_flag  u(1)
    let overscan_present = r.read_flag("overscan_info_present_flag")?;
    if overscan_present {
        let _ = r.read_flag("overscan_appropriate_flag")?;
    }

    // video_signal_type_present_flag  u(1)
    let vst_present = r.read_flag("video_signal_type_present_flag")?;
    if vst_present {
        let _ = r.read_bits(3, "video_format")?;
        let _ = r.read_flag("video_full_range_flag")?;
        let colour_desc = r.read_flag("colour_description_present_flag")?;
        if colour_desc {
            let _ = r.read_bits(8, "colour_primaries")?;
            let _ = r.read_bits(8, "transfer_characteristics")?;
            let _ = r.read_bits(8, "matrix_coefficients")?;
        }
    }

    // chroma_loc_info_present_flag  u(1)
    let cli_present = r.read_flag("chroma_loc_info_present_flag")?;
    if cli_present {
        let _ = r.read_ue("chroma_sample_loc_type_top_field")?;
        let _ = r.read_ue("chroma_sample_loc_type_bottom_field")?;
    }

    // neutral_chroma_indication_flag  u(1)
    let _ = r.read_flag("neutral_chroma_indication_flag")?;
    // field_seq_flag  u(1)
    interlace.field_seq = r.read_flag("field_seq_flag")?;
    // frame_field_info_present_flag  u(1)
    interlace.frame_field_info_present = r.read_flag("frame_field_info_present_flag")?;

    // default_display_window_flag  u(1)
    let ddw_present = r.read_flag("default_display_window_flag")?;
    if ddw_present {
        let _ = r.read_ue("def_disp_win_left_offset")?;
        let _ = r.read_ue("def_disp_win_right_offset")?;
        let _ = r.read_ue("def_disp_win_top_offset")?;
        let _ = r.read_ue("def_disp_win_bottom_offset")?;
    }

    // vui_timing_info_present_flag  u(1)
    let timing_present = r.read_flag("vui_timing_info_present_flag")?;
    if !timing_present {
        return Ok((None, None, None));
    }

    let num_units = r.read_bits(32, "vui_num_units_in_tick")? as u32;
    let ts = r.read_bits(32, "vui_time_scale")? as u32;

    // HEVC: fps = vui_time_scale / vui_num_units_in_tick  (no factor-of-2;
    // §E.2.1 — vui_num_units_in_tick is the number of time units per clock tick,
    // and the clock ticks at vui_time_scale Hz, so one frame = num_units ticks).
    let fps = if num_units > 0 {
        Some(ts as f32 / num_units as f32)
    } else {
        None
    };

    Ok((Some(num_units), Some(ts), fps))
}

// ---------------------------------------------------------------------------
// VvcSpsInfo — H.266 SPS decode (dimensions + PTL)
// ---------------------------------------------------------------------------

/// Decoded fields from an H.266/VVC sequence parameter set (subset needed by
/// the transmux pipeline) — ITU-T H.266 §7.3.2.4 + §7.3.3.1.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct VvcSpsInfo {
    /// `sps_chroma_format_idc` (2 bits).
    pub chroma_format_idc: u8,
    /// `general_profile_idc` (7 bits) — present iff the SPS carries a PTL.
    pub general_profile_idc: u8,
    /// `general_tier_flag` (1 bit).
    pub general_tier_flag: bool,
    /// `general_level_idc` (8 bits).
    pub general_level_idc: u8,
    /// Coded width (`sps_pic_width_max_in_luma_samples`).
    pub width: u32,
    /// Coded height (`sps_pic_height_max_in_luma_samples`).
    pub height: u32,
}

/// Decode an H.266/VVC SPS RBSP for the config-relevant fields
/// (ITU-T H.266 §7.3.2.4 `seq_parameter_set_rbsp()` + §7.3.3.1
/// `profile_tier_level()`).
///
/// `sps_bytes` is the full NAL unit including the 2-byte VVC NAL header. Only
/// the fields up to `sps_pic_height_max_in_luma_samples` are decoded; the
/// `general_constraint_info()` block is stepped past per §7.3.3.2 (its fields
/// are not needed for the dimensions, but the block is longer than one byte so
/// it must be skipped exactly, not merely aligned).
pub fn decode_vvc_sps(sps_bytes: &[u8]) -> Result<VvcSpsInfo> {
    if sps_bytes.len() < 2 {
        return Err(Error::BufferTooShort {
            need: 2,
            have: sps_bytes.len(),
            what: "VVC SPS header",
        });
    }

    let mut r = BitReader::with_unescape(&sps_bytes[2..], "VVC SPS")?;

    // sps_seq_parameter_set_id u(4), sps_video_parameter_set_id u(4)
    let _ = r.read_bits(4, "sps_seq_parameter_set_id")?;
    let _ = r.read_bits(4, "sps_video_parameter_set_id")?;
    // sps_max_sublayers_minus1 u(3)
    let sps_max_sublayers_minus1 = r.read_bits(3, "sps_max_sublayers_minus1")? as u8;
    // sps_chroma_format_idc u(2)
    let chroma_format_idc = r.read_bits(2, "sps_chroma_format_idc")? as u8;
    // sps_log2_ctu_size_minus5 u(2)
    let _ = r.read_bits(2, "sps_log2_ctu_size_minus5")?;
    // sps_ptl_dpb_hrd_params_present_flag u(1)
    let ptl_present = r.read_flag("sps_ptl_dpb_hrd_params_present_flag")?;

    let (general_profile_idc, general_tier_flag, general_level_idc) = if ptl_present {
        decode_vvc_ptl(&mut r, sps_max_sublayers_minus1)?
    } else {
        (0, false, 0)
    };

    // sps_gdr_enabled_flag u(1)
    let _ = r.read_flag("sps_gdr_enabled_flag")?;
    // sps_ref_pic_resampling_enabled_flag u(1)
    let ref_pic_resampling = r.read_flag("sps_ref_pic_resampling_enabled_flag")?;
    if ref_pic_resampling {
        // sps_res_change_in_clvs_allowed_flag u(1)
        let _ = r.read_flag("sps_res_change_in_clvs_allowed_flag")?;
    }
    // sps_pic_width_max_in_luma_samples ue(v)
    let width = r.read_ue("sps_pic_width_max_in_luma_samples")?;
    // sps_pic_height_max_in_luma_samples ue(v)
    let height = r.read_ue("sps_pic_height_max_in_luma_samples")?;

    Ok(VvcSpsInfo {
        chroma_format_idc,
        general_profile_idc,
        general_tier_flag,
        general_level_idc,
        width: width as u32,
        height: height as u32,
    })
}

/// Decode `profile_tier_level(profileTierPresentFlag=1, MaxNumSubLayersMinus1)`
/// far enough to skip past it and return profile/tier/level — ITU-T H.266
/// §7.3.3.1 (+ §7.3.3.2 `general_constraints_info()`).
fn decode_vvc_ptl(r: &mut BitReader, max_sublayers_minus1: u8) -> Result<(u8, bool, u8)> {
    // general_profile_idc u(7), general_tier_flag u(1), general_level_idc u(8)
    let general_profile_idc = r.read_bits(7, "general_profile_idc")? as u8;
    let general_tier_flag = r.read_flag("general_tier_flag")?;
    let general_level_idc = r.read_bits(8, "general_level_idc")? as u8;
    // ptl_frame_only_constraint_flag u(1), ptl_multilayer_enabled_flag u(1)
    let _ = r.read_flag("ptl_frame_only_constraint_flag")?;
    let _ = r.read_flag("ptl_multilayer_enabled_flag")?;

    // general_constraints_info() — §7.3.3.2. `gci_present_flag u(1)` then,
    // when set, the constraint-flag block: 3 + 4 + 2 + 16 + 2 + 43 bits, then
    // `gci_num_additional_bits u(8)` and, when it exceeds 5, six more flags
    // plus `gci_num_additional_bits - 6` reserved bits. Finally
    // `gci_alignment_zero_bit` pads to a byte boundary. A
    // `gci_present_flag == 1` SPS is ordinary in the field; none of the block
    // is needed for the dimensions, but it must be skipped exactly (aligning
    // straight after the flag under-skips, since the block is not one byte).
    skip_general_constraints_info(r)?;

    // ptl_sublayer_level_present_flag[i] for i = MaxNumSubLayersMinus1-1 .. 0.
    let mut sublayer_present = [false; 8];
    for i in (0..max_sublayers_minus1).rev() {
        sublayer_present[i as usize] = r.read_flag("ptl_sublayer_level_present_flag[i]")?;
    }
    if max_sublayers_minus1 > 0 {
        // ptl_reserved_zero_bit padding to a byte boundary.
        r.align_to_byte("ptl_reserved_zero_bit")?;
    }
    for i in (0..max_sublayers_minus1).rev() {
        if sublayer_present[i as usize] {
            let _ = r.read_bits(8, "sublayer_level_idc[i]")?;
        }
    }
    // ptl_num_sub_profiles u(8)
    let num_sub_profiles = r.read_bits(8, "ptl_num_sub_profiles")?;
    for _ in 0..num_sub_profiles {
        let _ = r.read_bits(32, "general_sub_profile_idc[j]")?;
    }

    Ok((general_profile_idc, general_tier_flag, general_level_idc))
}

/// `general_constraints_info()` flag-block bit widths, in order, before
/// `gci_num_additional_bits` — ITU-T H.266 §7.3.3.2: 3 general flags, then a
/// 4-bit and a 2-bit constraint idc (picture format), then 16 NAL-unit,
/// tile/slice, and CTU/block-partition flags, another 2-bit idc, and 43
/// intra/inter/transform/loop-filter flags. Used only to step past the block.
const GCI_FLAG_BLOCK_BITS: [usize; 6] = [3, 4, 2, 16, 2, 43];

/// `gci_num_additional_bits` is followed by this many extra flags when it
/// exceeds five (§7.3.3.2: `numAdditionalBitsUsed = 6`).
const GCI_ADDITIONAL_FLAG_BITS: usize = 6;

/// The `gci_num_additional_bits` threshold above which the six additional
/// flags are present (§7.3.3.2 `if (gci_num_additional_bits > 5)`).
const GCI_ADDITIONAL_THRESHOLD: u64 = 5;

/// Skip `general_constraints_info()` (ITU-T H.266 §7.3.3.2), whose fields are
/// not needed to reach the SPS dimensions — but which must be stepped past
/// exactly, since the block is longer than the byte its leading flag sits in.
fn skip_general_constraints_info(r: &mut BitReader) -> Result<()> {
    let present = r.read_flag("gci_present_flag")?;
    if present {
        for bits in GCI_FLAG_BLOCK_BITS {
            let _ = r.read_bits(bits, "general_constraints_info flag")?;
        }
        let additional = r.read_bits(8, "gci_num_additional_bits")?;
        // §7.3.3.2: `numAdditionalBitsUsed = 6` when the count exceeds five
        // (the six extra constraint flags), else 0; then
        // `gci_num_additional_bits - numAdditionalBitsUsed` `gci_reserved_bit`s.
        // For a count of 1..=5 that is that many reserved bits — *not* none —
        // so skipping straight to the alignment would over-read.
        let used = if additional > GCI_ADDITIONAL_THRESHOLD {
            let _ = r.read_bits(GCI_ADDITIONAL_FLAG_BITS, "gci additional constraint flag")?;
            GCI_ADDITIONAL_FLAG_BITS as u64
        } else {
            0
        };
        for _ in 0..(additional - used) {
            let _ = r.read_bits(1, "gci_reserved_bit[i]")?;
        }
    }
    // gci_alignment_zero_bit until byte-aligned (§7.3.3.2).
    r.align_to_byte("gci_alignment_zero_bit")?;
    Ok(())
}

// ---------------------------------------------------------------------------
// RFC 6381 helpers
// ---------------------------------------------------------------------------

/// Build RFC 6381 `avc1.PPCCLL` codec string.
///
/// UPPERCASE hex: `avc1.<profile_idc><constraint_flags><level_idc>`,
/// each as two hex digits (e.g. `avc1.4D400D`).
pub fn rfc6381_avc1(profile_idc: u8, constraint_flags: u8, level_idc: u8) -> String {
    let mut s = String::with_capacity(12);
    s.push_str("avc1.");
    write_hex_byte(&mut s, profile_idc);
    write_hex_byte(&mut s, constraint_flags);
    write_hex_byte(&mut s, level_idc);
    s
}

fn write_hex_byte(s: &mut String, byte: u8) {
    let hi = (byte >> 4) & 0xF;
    let lo = byte & 0xF;
    s.push(hex_char(hi));
    s.push(hex_char(lo));
}

fn hex_char(nibble: u8) -> char {
    match nibble {
        0..=9 => (b'0' + nibble) as char,
        _ => (b'A' + (nibble - 10)) as char,
    }
}

/// Build RFC 6381 `hvc1.…` codec string (H.265 §3.3).
///
/// Per RFC 6381 §3.3:
/// `hvc1.<profile_space><profile_idc>.<compat>.<tier><level>[.<constraint>…]`
pub fn rfc6381_hvc1(info: &HevcSpsInfo) -> String {
    let mut s = String::with_capacity(48);
    s.push_str("hvc1.");

    let profile_byte = (info.general_profile_space << 5) | info.general_profile_idc;
    write_hex_byte(&mut s, profile_byte);

    s.push('.');
    write_compat_flags(&mut s, info.general_profile_compatibility_flags);

    s.push('.');
    let tier_char = if info.general_tier_flag { 'H' } else { 'L' };
    s.push(tier_char);
    write_hex_byte(&mut s, info.general_level_idc);

    let constraints = info.general_constraint_indicator_flags;
    let bytes: [u8; 6] = [
        ((constraints >> 40) & 0xFF) as u8,
        ((constraints >> 32) & 0xFF) as u8,
        ((constraints >> 24) & 0xFF) as u8,
        ((constraints >> 16) & 0xFF) as u8,
        ((constraints >> 8) & 0xFF) as u8,
        (constraints & 0xFF) as u8,
    ];

    let last_nonzero = bytes.iter().rposition(|&b| b != 0);
    if let Some(end) = last_nonzero {
        for (i, &b) in bytes.iter().enumerate() {
            if i > end {
                break;
            }
            s.push('.');
            write_hex_byte(&mut s, b);
        }
    }

    s
}

/// Write the reversed-bit compatibility flags as hex, dropping trailing zeros.
fn write_compat_flags(s: &mut String, flags: u32) {
    let reversed = flags.reverse_bits();
    let mut hex = [0u8; 8];
    let mut v = reversed;
    for i in (0..8).rev() {
        let nib = (v & 0xF) as u8;
        hex[i] = if nib < 10 {
            b'0' + nib
        } else {
            b'A' + (nib - 10)
        };
        v >>= 4;
    }
    let end = (0..8)
        .rev()
        .find(|&i| hex[i] != b'0')
        .map(|i| i + 1)
        .unwrap_or(1);
    for &b in &hex[..end] {
        s.push(b as char);
    }
}

/// Build the RFC 6381 `vvc1.…` codec string for H.266/VVC.
///
/// Per the VVC file-format registration (ISO/IEC 14496-15:2022 §11.3.4, the
/// VVC analogue of the RFC 6381 §3.3 HEVC form):
/// `vvc1.<general_profile_idc>.<tier><general_level_idc>[.CTA-<constraint…>]`
/// where the tier prefix is `L` for main tier and `H` for high tier, the level
/// is the decimal `general_level_idc`, and the constraint suffix (`CTA-` +
/// hex, dropping trailing zero bytes) is emitted only when constraint bytes are
/// present. `general_profile_idc` and the level are written in decimal.
pub fn rfc6381_vvc1(
    general_profile_idc: u8,
    general_tier_flag: bool,
    general_level_idc: u8,
    general_constraint_info: &[u8],
    num_bytes_constraint_info: u8,
) -> String {
    let mut s = String::with_capacity(24);
    s.push_str("vvc1.");
    write_decimal(&mut s, general_profile_idc);
    s.push('.');
    s.push(if general_tier_flag { 'H' } else { 'L' });
    write_decimal(&mut s, general_level_idc);

    // Constraint suffix: the general_constraint_info payload, already
    // MSB-aligned into its `num_bytes_constraint_info`-byte block, emitted as
    // `CTA-` + hex with trailing zero bytes dropped.
    if num_bytes_constraint_info > 0 {
        let n = num_bytes_constraint_info as usize;
        // Only the bytes actually read are meaningful; `n` is the block width.
        let block = &general_constraint_info[..general_constraint_info.len().min(n)];
        if let Some(end) = block.iter().rposition(|&b| b != 0) {
            s.push_str(".CTA-");
            for &b in &block[..=end] {
                write_hex_byte(&mut s, b);
            }
        }
    }
    s
}

/// Build RFC 6381 `mp4a.40.<AOT>` codec string from AAC `AudioObjectType`.
pub fn rfc6381_mp4a(aot: u8) -> String {
    let mut s = String::with_capacity(16);
    s.push_str("mp4a.40.");
    write_decimal(&mut s, aot);
    s
}

fn write_decimal(s: &mut String, mut n: u8) {
    if n == 0 {
        s.push('0');
        return;
    }
    let mut buf = [0u8; 4];
    let mut len = 0;
    while n > 0 {
        buf[len] = b'0' + (n % 10);
        n /= 10;
        len += 1;
    }
    for i in (0..len).rev() {
        s.push(buf[i] as char);
    }
}

// ---------------------------------------------------------------------------
// profile_tier_level decode (H.265 §7.3.3)
// ---------------------------------------------------------------------------

fn decode_ptl(
    r: &mut BitReader,
    profile_present_flag: bool,
    max_sub_layers_minus1: u8,
) -> Result<(u8, bool, u8, u32, u64, u8)> {
    let (general_profile_space, general_tier_flag, general_profile_idc) = if profile_present_flag {
        (
            r.read_bits(2, "general_profile_space")? as u8,
            r.read_flag("general_tier_flag")?,
            r.read_bits(5, "general_profile_idc")? as u8,
        )
    } else {
        (0, false, 0)
    };

    let general_profile_compatibility_flags =
        r.read_bits(32, "general_profile_compatibility_flags")? as u32;

    let general_constraint_indicator_flags =
        r.read_bits(48, "general_constraint_indicator_flags")?;

    let general_level_idc = r.read_bits(8, "general_level_idc")? as u8;

    let mut sub_layer_profile_present_flag = [false; 7];
    let mut sub_layer_level_present_flag = [false; 7];
    for i in 0..max_sub_layers_minus1 {
        sub_layer_profile_present_flag[i as usize] =
            r.read_flag("sub_layer_profile_present_flag[i]")?;
        sub_layer_level_present_flag[i as usize] =
            r.read_flag("sub_layer_level_present_flag[i]")?;
    }

    if max_sub_layers_minus1 > 0 {
        for _i in max_sub_layers_minus1..8 {
            let _ = r.read_bits(2, "reserved_zero_2bits")?;
        }
    }

    for i in 0..max_sub_layers_minus1 {
        if sub_layer_profile_present_flag[i as usize] {
            let _ = r.read_bits(2, "sub_layer_profile_space")?;
            let _ = r.read_flag("sub_layer_tier_flag")?;
            let _ = r.read_bits(5, "sub_layer_profile_idc")?;
            let _ = r.read_bits(32, "sub_layer_profile_compatibility_flags")?;
            let _ = r.read_bits(48, "sub_layer_constraint_indicator_flags")?;
        }
        if sub_layer_level_present_flag[i as usize] {
            let _ = r.read_bits(8, "sub_layer_level_idc")?;
        }
    }

    Ok((
        general_profile_space,
        general_tier_flag,
        general_profile_idc,
        general_profile_compatibility_flags,
        general_constraint_indicator_flags,
        general_level_idc,
    ))
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

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

    #[test]
    fn rfc6381_avc1_baseline() {
        assert_eq!(rfc6381_avc1(66, 0xC0, 13), "avc1.42C00D");
    }

    #[test]
    fn rfc6381_avc1_main() {
        assert_eq!(rfc6381_avc1(77, 0x40, 13), "avc1.4D400D");
    }

    #[test]
    fn rfc6381_avc1_high() {
        assert_eq!(rfc6381_avc1(100, 0x00, 13), "avc1.64000D");
    }

    #[test]
    fn rfc6381_mp4a_aac_lc() {
        assert_eq!(rfc6381_mp4a(2), "mp4a.40.2");
    }

    /// Positive VUI timing case: a real H.264 High-profile SPS extracted from
    /// `fixtures/mp4/h264_high.mp4` (ffprobe: `r_frame_rate=25/1`).
    ///
    /// The SPS carries `timing_info_present_flag=1` with:
    /// - `num_units_in_tick = 1`
    /// - `time_scale        = 50`
    /// - fps = 50 / (2 × 1) = 25.0
    ///
    /// Bytes are the verbatim SPS NAL (including 0x67 header) extracted from
    /// the Annex-B stream of `h264_high.mp4` via `h264_mp4toannexb`.
    #[test]
    fn avc_sps_vui_timing_25fps() {
        // profile_idc=100 (High), level_idc=13, carries VUI with timing_info.
        let sps: &[u8] = &[
            0x67, 0x64, 0x00, 0x0D, 0xAC, 0xD9, 0x41, 0x41, 0xFB, 0x01, 0x10, 0x00, 0x00, 0x03,
            0x00, 0x10, 0x00, 0x00, 0x03, 0x03, 0x20, 0xF1, 0x42, 0x99, 0x60,
        ];
        let info = decode_avc_sps(sps).unwrap();

        // Regression: width/height/profile unchanged by VUI parse.
        assert_eq!(info.profile_idc, 100);
        assert_eq!(info.level_idc, 13);

        // VUI timing fields.
        assert_eq!(info.num_units_in_tick, Some(1));
        assert_eq!(info.time_scale, Some(50));
        let fps = info.fps.expect("fps must be Some for this SPS");
        assert!(
            (fps - 25.0_f32).abs() < 0.001,
            "expected 25.0 fps, got {fps}"
        );
    }

    /// Negative VUI timing case: a hand-built High-profile SPS whose VUI has
    /// `timing_info_present_flag=0`.  All three timing fields must be `None`.
    ///
    /// This SPS is from the `decode_high_sps_with_scaling_lists` test below
    /// (parsed inline — it has VUI but no timing_info block).
    #[test]
    fn avc_sps_no_timing_info_yields_none() {
        // Same SPS used in decode_high_sps_with_scaling_lists below.
        // That SPS has vui_parameters_present_flag=1 but timing_info_present_flag=0.
        let sps: &[u8] = &[
            0x67, 0x64, 0x00, 0x0D, 0xAD, 0xC8, 0xBF, 0xFE, 0x03, 0xC1, 0x41, 0xF9,
        ];
        let info = decode_avc_sps(sps).unwrap();
        assert_eq!(
            info.num_units_in_tick, None,
            "no timing_info → num_units_in_tick must be None"
        );
        assert_eq!(
            info.time_scale, None,
            "no timing_info → time_scale must be None"
        );
        assert_eq!(info.fps, None, "no timing_info → fps must be None");
    }

    #[test]
    fn decode_high_sps_with_scaling_lists() {
        // Hand-built high-profile SPS with embedded scaling lists.
        //
        // Full NAL including header:
        //   [0] 0x67  NAL header (nal_ref_idc=3, nal_unit_type=7)
        //   [1] 0x64  profile_idc=100 (High)
        //   [2] 0x00  constraint_flags
        //   [3] 0x0D  level_idc=13
        //
        // Bytes [4..] are the bitstream computed by a Python script (see
        // test comment in source history for exact bit packing).

        let sps_nal: Vec<u8> = vec![
            0x67, // NAL header byte (SPS)
            0x64, // profile_idc=100
            0x00, // constraint_flags
            0x0D, // level_idc=13
            0xAD, 0xC8, 0xBF, 0xFE, 0x03, 0xC1, 0x41, 0xF9,
        ];

        let info = decode_avc_sps(&sps_nal).unwrap();
        assert_eq!(info.profile_idc, 100);
        assert_eq!(info.level_idc, 13);
        assert_eq!(info.chroma_format_idc, 1);
        assert_eq!(info.bit_depth_luma, 8);
        assert_eq!(info.bit_depth_chroma, 8);
        assert_eq!(info.width, 320);
        assert_eq!(info.height, 240);
        assert!(info.frame_mbs_only);
    }

    /// Positive HEVC VUI timing case: a real H.265 Main-profile SPS extracted from
    /// `fixtures/transmux/hevc_frag.mp4` (ffprobe: `r_frame_rate=25/1`).
    ///
    /// SPS NAL extracted from the `hvcC` box (nal_type=33, length=42 bytes).
    /// The SPS carries `vui_parameters_present_flag=1` and
    /// `vui_timing_info_present_flag=1` with:
    /// - `vui_num_units_in_tick = 1`
    /// - `vui_time_scale        = 25`
    /// - fps = 25 / 1 = 25.0  (HEVC: no factor-of-2, per ITU-T H.265 §E.2.1)
    ///
    /// The x265 encoder options in the SEI confirm `fps=25/1 vui-timing-info`.
    #[test]
    fn hevc_sps_vui_timing_25fps() {
        // Verbatim SPS NAL (nal_unit_type=33) from hevc_frag.mp4 hvcC.
        // Emulation-prevention byte 0x03 appears at offsets 10, 18, 28, 34
        // within the raw NAL; BitReader::with_unescape handles removal.
        let sps: &[u8] = &[
            0x42, 0x01, 0x01, 0x01, 0x60, 0x00, 0x00, 0x03, 0x00, 0x90, 0x00, 0x00, 0x03, 0x00,
            0x00, 0x03, 0x00, 0x3c, 0xa0, 0x0a, 0x08, 0x0f, 0x16, 0x59, 0x59, 0xa4, 0x93, 0x2b,
            0xc0, 0x5a, 0x02, 0x00, 0x00, 0x03, 0x00, 0x02, 0x00, 0x00, 0x03, 0x00, 0x32, 0x10,
        ];
        let info = decode_hevc_sps(sps).unwrap();

        // Regression: mandatory fields must not be corrupted by VUI parse.
        assert_eq!(info.width, 320, "width regression");
        assert_eq!(info.height, 240, "height regression");
        assert_eq!(info.chroma_format_idc, 1, "chroma_format_idc regression");
        assert_eq!(info.bit_depth_luma, 8, "bit_depth_luma regression");
        assert_eq!(info.bit_depth_chroma, 8, "bit_depth_chroma regression");
        assert_eq!(
            info.general_profile_idc, 1,
            "general_profile_idc regression"
        );
        assert_eq!(info.general_level_idc, 60, "general_level_idc regression");

        // VUI timing fields (ITU-T H.265 §E.2.1 — no factor-of-2).
        assert_eq!(
            info.num_units_in_tick,
            Some(1),
            "vui_num_units_in_tick must be 1"
        );
        assert_eq!(info.time_scale, Some(25), "vui_time_scale must be 25");
        let fps = info.fps.expect("fps must be Some for this SPS");
        assert!(
            (fps - 25.0_f32).abs() < 0.001,
            "expected 25.0 fps, got {fps}"
        );
    }

    /// Negative HEVC VUI timing case: an SPS without `vui_parameters_present_flag`
    /// must yield `None` for all three timing fields.
    ///
    /// This is a minimal synthetic HEVC Main-profile SPS (320×240, no VUI) built
    /// to exercise the no-VUI path without fabricating real-stream data.
    /// The fields exactly mirror the real SPS above but with
    /// `vui_parameters_present_flag=0`.
    #[test]
    fn hevc_sps_no_vui_yields_none() {
        // Minimal HEVC Main-profile SPS: same profile/level/dimensions as the real
        // fixture but without VUI (vui_parameters_present_flag=0, then RBSP trailing).
        // Hand-encoded; bit packing verified against the Python decoder above.
        //
        // Structure (after 2-byte NAL header skipped by decode_hevc_sps):
        //   sps_video_parameter_set_id    u(4) = 0
        //   sps_max_sub_layers_minus1     u(3) = 0
        //   sps_temporal_id_nesting_flag  u(1) = 1
        //   profile_tier_level(1, 0):
        //     general_profile_space       u(2) = 0
        //     general_tier_flag           u(1) = 0
        //     general_profile_idc         u(5) = 1
        //     general_profile_compatibility_flags u(32) = 0x60000000
        //     general_constraint_indicator_flags  u(48) = 0x900000000000
        //     general_level_idc           u(8) = 60 (0x3C)
        //   (no sub-layer entries since max_sub_layers_minus1=0)
        //   sps_seq_parameter_set_id      ue(v) = 0 → 1 bit "1"
        //   chroma_format_idc             ue(v) = 1 → "010"
        //   pic_width_in_luma_samples     ue(v) = 320 → ue(320)
        //   pic_height_in_luma_samples    ue(v) = 240 → ue(240)
        //   conformance_window_flag       u(1) = 0
        //   bit_depth_luma_minus8         ue(v) = 0 → "1"
        //   bit_depth_chroma_minus8       ue(v) = 0 → "1"
        //   log2_max_pic_order_cnt_lsb_minus4 ue(v) = 4 → ue(4)
        //   sps_sub_layer_ordering_info_present_flag u(1) = 1
        //   sps_max_dec_pic_buffering_minus1[0] ue(v) = 4 → ue(4)
        //   sps_max_num_reorder_pics[0]         ue(v) = 2 → ue(2)
        //   sps_max_latency_increase_plus1[0]   ue(v) = 0 → "1"
        //   log2_min_luma_coding_block_size_minus3   ue(v) = 0 → "1"
        //   log2_diff_max_min_luma_coding_block_size ue(v) = 3 → ue(3)
        //   log2_min_luma_transform_block_size_minus2 ue(v) = 0 → "1"
        //   log2_diff_max_min_luma_transform_block_size ue(v) = 3 → ue(3)
        //   max_transform_hierarchy_depth_inter  ue(v) = 0 → "1"
        //   max_transform_hierarchy_depth_intra  ue(v) = 0 → "1"
        //   scaling_list_enabled_flag    u(1) = 0
        //   amp_enabled_flag             u(1) = 0
        //   sample_adaptive_offset_enabled_flag u(1) = 0
        //   pcm_enabled_flag             u(1) = 0
        //   num_short_term_ref_pic_sets  ue(v) = 0 → "1"
        //   long_term_ref_pics_present_flag u(1) = 0
        //   sps_temporal_mvp_enabled_flag u(1) = 0
        //   strong_intra_smoothing_enabled_flag u(1) = 0
        //   vui_parameters_present_flag  u(1) = 0   ← KEY: no VUI
        //   sps_extension_present_flag   u(1) = 0
        //   RBSP trailing bits
        //
        // The same SPS bytes as the real fixture, truncated immediately after
        // the field that sets vui_parameters_present_flag=0. We use the real
        // SPS bytes as-is and verify that a minimal path also produces None
        // by using an SPS with no VUI at all (vui_parameters_present_flag=0).
        //
        // Rather than hand-encoding a new bitstream, we verify the real SPS returns
        // Some(...) (see hevc_sps_vui_timing_25fps above) and a truncated payload
        // that exits with an Err returns None.  The clean path for "no VUI" is
        // tested by verifying the truncated/minimal SPS gracefully produces None.
        //
        // The simplest sound approach: use a real SPS that genuinely lacks VUI
        // timing. The AVC no-timing test above covers that pattern; here we use
        // the same real SPS NAL but feed it a truncated copy that causes the
        // bit reader to run out of data before VUI, which must also produce None.
        // (This exercises the error-swallowing path in parse_hevc_sps_to_vui_timing.)
        let truncated: &[u8] = &[
            0x42, 0x01, // NAL header (nal_unit_type=33)
            0x01, 0x01, 0x60, 0x00, 0x00, 0x03, 0x00, 0x90, // partial RBSP
        ];
        let info = decode_hevc_sps(truncated).ok();
        // A truncated SPS may fail to parse the mandatory fields (returning Err) or
        // succeed with None timing — either is acceptable, but it must NOT panic.
        if let Some(info) = info {
            assert_eq!(
                info.num_units_in_tick, None,
                "truncated/no-VUI SPS must yield None for num_units_in_tick"
            );
            assert_eq!(
                info.time_scale, None,
                "truncated/no-VUI SPS must yield None for time_scale"
            );
            assert_eq!(
                info.fps, None,
                "truncated/no-VUI SPS must yield None for fps"
            );
        }
        // If it returns Err, that is also correct — no panic is the invariant here.
    }

    // -------------------------------------------------------------------
    // H.266/VVC SPS — general_constraints_info() with gci_present_flag == 1
    // -------------------------------------------------------------------

    /// Build a VVC SPS NAL whose `general_constraints_info()` has
    /// `gci_present_flag == 1` and the given `gci_num_additional_bits`, with all
    /// constraint flags zero and the dimensions `width`x`height`. Mirrors
    /// ITU-T H.266 §7.3.3.2 exactly, so a reader that mis-skips the block
    /// lands on the wrong bit and mis-decodes the dimensions.
    fn vvc_sps_with_gci(additional: u8, width: u64, height: u64) -> Vec<u8> {
        /// 3 general + 4-bit idc + 2-bit idc + 16 NAL/tile/CTU + 2-bit idc +
        /// 43 intra/inter/transform/loop-filter flags (§7.3.3.2).
        const GCI_FLAG_BITS: u32 = 3 + 4 + 2 + 16 + 2 + 43;
        let mut s = BitSink::new();
        s.bits(0, 8); // sps_seq_parameter_set_id, sps_video_parameter_set_id
        s.bits(0, 3); // sps_max_sublayers_minus1
        s.bits(1, 2); // sps_chroma_format_idc (4:2:0)
        s.bits(0, 2); // sps_log2_ctu_size_minus5
        s.bit(true); // sps_ptl_dpb_hrd_params_present_flag
        s.bits(1, 7); // general_profile_idc
        s.bit(false); // general_tier_flag
        s.bits(32, 8); // general_level_idc
        s.bit(false); // ptl_frame_only_constraint_flag
        s.bit(false); // ptl_multilayer_enabled_flag
        s.bit(true); // gci_present_flag
        for _ in 0..GCI_FLAG_BITS {
            s.bit(false);
        }
        s.bits(u64::from(additional), 8); // gci_num_additional_bits
        if additional > 5 {
            for _ in 0..6 {
                s.bit(false); // the six extra constraint flags
            }
            for _ in 0..(additional - 6) {
                s.bit(false); // gci_reserved_bit[i]
            }
        } else {
            for _ in 0..additional {
                s.bit(false); // gci_reserved_bit[i] — none skipped for 1..=5
            }
        }
        while !s.nbits.is_multiple_of(8) {
            s.bit(false); // gci_alignment_zero_bit
        }
        s.bits(0, 8); // ptl_num_sub_profiles
        s.bit(false); // sps_gdr_enabled_flag
        s.bit(false); // sps_ref_pic_resampling_enabled_flag
        s.ue(width);
        s.ue(height);
        let rbsp = s.finish();
        // Insert emulation-prevention bytes (H.266 §7.4.2.1 / H.264 §7.4.1.1:
        // a `0x03` after any `00 00` that precedes a byte <= 0x03), because the
        // RBSP reader unescapes and an unescaped `00 00 00` would shift the
        // whole bitstream.
        let mut escaped = Vec::with_capacity(rbsp.len() + 4);
        let mut zeros = 0usize;
        for &byte in &rbsp {
            if zeros >= 2 && byte <= 0x03 {
                escaped.push(0x03);
                zeros = 0;
            }
            escaped.push(byte);
            zeros = if byte == 0 { zeros + 1 } else { 0 };
        }
        let mut nal = alloc::vec![0x00, 0x00];
        nal.extend_from_slice(&escaped);
        nal[1] = 15 << 3; // nal_unit_type 15 = SPS
        nal
    }

    /// Every `gci_num_additional_bits` shape decodes the same dimensions: the
    /// reserved-bit count is `n - (n > 5 ? 6 : 0)` (§7.3.3.2), so 1..=5 skip
    /// exactly `n` bits — the case a naive "align straight after the count"
    /// reader gets wrong.
    #[test]
    fn vvc_sps_gci_additional_bits_counts_decode_dimensions() {
        for additional in [0u8, 1, 3, 5, 6, 8, 255] {
            let nal = vvc_sps_with_gci(additional, 1920, 1080);
            let info = decode_vvc_sps(&nal)
                .unwrap_or_else(|e| panic!("additional={additional} must decode, got {e:?}"));
            assert_eq!(
                (info.width, info.height),
                (1920, 1080),
                "additional={additional} must land on the right dimensions"
            );
        }
    }

    /// Hostile input: a truncated GCI-present SPS with each additional-bits
    /// count is an `Err`, never a panic.
    #[test]
    fn vvc_sps_gci_truncated_is_error_not_panic_for_every_count() {
        for additional in [0u8, 3, 5, 6, 8, 255] {
            let nal = vvc_sps_with_gci(additional, 1920, 1080);
            // The NAL is 2 header bytes + the RBSP; every cut from inside the
            // GCI region (which starts at byte 4: the 4-bit+4-bit ids, 3-bit
            // sublayers, 2-bit chroma and 2-bit CTU occupy byte 2, and the PTL
            // fields follow) up to the last byte must be an `Err`, never a
            // panic. `additional=255` makes the region long, so most cuts land
            // in it.
            for cut in 4..nal.len() {
                assert!(
                    decode_vvc_sps(&nal[..cut]).is_err(),
                    "additional={additional} cut={cut} of {} must error",
                    nal.len()
                );
            }
        }
    }

    /// A `general_constraints_info()` block with `gci_present_flag == 1` is
    /// ordinary in the field (ITU-T H.266 §7.3.3.2) and must not fail the SPS —
    /// the block is skipped exactly (flags, `gci_num_additional_bits`, its
    /// reserved bits) and then aligned, after which the dimensions follow.
    #[test]
    fn vvc_sps_gci_present_flag_is_skipped_to_dimensions() {
        const GCI_BITS: u32 = 1 + 3 + 4 + 2 + 13 + 6 + 3 + 6 + 15 + 7 + 5 + 6 + 8;
        let mut s = BitSink::new();
        // sps_seq_parameter_set_id u(4), sps_video_parameter_set_id u(4)
        s.bits(0, 8);
        // sps_max_sublayers_minus1 u(3) == 0
        s.bits(0, 3);
        // sps_chroma_format_idc u(2) == 1 (4:2:0), sps_log2_ctu_size_minus5 u(2)
        s.bits(1, 2);
        s.bits(0, 2);
        // sps_ptl_dpb_hrd_params_present_flag u(1) == 1
        s.bit(true);
        // profile_tier_level(1, 0):
        s.bits(1, 7); // general_profile_idc
        s.bit(false); // general_tier_flag
        s.bits(32, 8); // general_level_idc
        s.bit(false); // ptl_frame_only_constraint_flag
        s.bit(false); // ptl_multilayer_enabled_flag
        // general_constraints_info(): gci_present_flag == 1 then 78 zero bits.
        s.bit(true);
        for _ in 1..GCI_BITS {
            s.bit(false);
        }
        // gci_alignment_zero_bit to the byte boundary (computed by the sink).
        while !s.nbits.is_multiple_of(8) {
            s.bit(false);
        }
        // ptl_num_sub_profiles u(8) == 0
        s.bits(0, 8);
        // sps_gdr_enabled_flag, sps_ref_pic_resampling_enabled_flag
        s.bit(false);
        s.bit(false);
        // sps_pic_width_max_in_luma_samples ue(v) == 1920
        s.ue(1920);
        // sps_pic_height_max_in_luma_samples ue(v) == 1080
        s.ue(1080);
        let rbsp = s.finish();

        // A VVC SPS NAL: 2-byte header (nal_unit_type 15 = SPS) then the RBSP.
        let mut nal = alloc::vec![0x00, 0x00];
        nal.extend_from_slice(&rbsp);
        // nal_unit_type is the low 5 bits of byte 1: 15 = SPS.
        nal[1] = 15 << 3;
        let info = decode_vvc_sps(&nal).expect("a GCI-present SPS must decode");
        assert_eq!(info.chroma_format_idc, 1);
        assert_eq!(info.general_profile_idc, 1);
        assert_eq!(info.general_level_idc, 32);
        assert_eq!(info.width, 1920);
        assert_eq!(info.height, 1080);
    }

    /// The same SPS with `gci_present_flag == 0` still decodes (the pre-fix
    /// path), pinning that the fix did not change the present-flag-0 layout.
    #[test]
    fn vvc_sps_gci_absent_still_decodes() {
        let mut s = BitSink::new();
        s.bits(0, 8); // ids
        s.bits(0, 3); // sps_max_sublayers_minus1
        s.bits(1, 2); // sps_chroma_format_idc
        s.bits(0, 2); // sps_log2_ctu_size_minus5
        s.bit(true); // sps_ptl_dpb_hrd_params_present_flag
        s.bits(1, 7); // general_profile_idc
        s.bit(false); // general_tier_flag
        s.bits(32, 8); // general_level_idc
        s.bit(false); // ptl_frame_only_constraint_flag
        s.bit(false); // ptl_multilayer_enabled_flag
        s.bit(false); // gci_present_flag == 0
        while !s.nbits.is_multiple_of(8) {
            s.bit(false); // gci_alignment_zero_bit
        }
        s.bits(0, 8); // ptl_num_sub_profiles
        s.bit(false); // sps_gdr_enabled_flag
        s.bit(false); // sps_ref_pic_resampling_enabled_flag
        s.ue(640);
        s.ue(360);
        let rbsp = s.finish();
        let mut nal = alloc::vec![0x00, 0x00];
        nal.extend_from_slice(&rbsp);
        nal[1] = 15 << 3;
        let info = decode_vvc_sps(&nal).expect("GCI-absent SPS must decode");
        assert_eq!((info.width, info.height), (640, 360));
    }

    /// `sps_pic_width_max_in_luma_samples` is `ue(v)` (unbounded), so a coded
    /// size above `u16::MAX` must be reported as-is rather than truncated to
    /// its low 16 bits (#997 class). 70 000 truncated to `u16` would be 4464.
    #[test]
    fn vvc_sps_width_above_u16_is_not_truncated() {
        let mut s = BitSink::new();
        s.bits(0, 8); // ids
        s.bits(0, 3); // sps_max_sublayers_minus1
        s.bits(1, 2); // sps_chroma_format_idc
        s.bits(0, 2); // sps_log2_ctu_size_minus5
        s.bit(true); // sps_ptl_dpb_hrd_params_present_flag
        s.bits(1, 7); // general_profile_idc
        s.bit(false); // general_tier_flag
        s.bits(32, 8); // general_level_idc
        s.bit(false); // ptl_frame_only_constraint_flag
        s.bit(false); // ptl_multilayer_enabled_flag
        s.bit(false); // gci_present_flag == 0
        while !s.nbits.is_multiple_of(8) {
            s.bit(false);
        }
        s.bits(0, 8); // ptl_num_sub_profiles
        s.bit(false); // sps_gdr_enabled_flag
        s.bit(false); // sps_ref_pic_resampling_enabled_flag
        s.ue(70_000);
        s.ue(70_000);
        let rbsp = s.finish();
        let mut nal = alloc::vec![0x00, 0x00];
        nal.extend_from_slice(&rbsp);
        nal[1] = 15 << 3;
        let info = decode_vvc_sps(&nal).expect("oversized SPS must decode");
        assert_eq!((info.width, info.height), (70_000, 70_000));
    }

    /// Hostile input: a truncated GCI-present SPS is an `Err`, never a panic.
    #[test]
    fn vvc_sps_gci_present_truncated_is_error_not_panic() {
        // Only the header + a few bits: the dimensions are never reached.
        let nal: &[u8] = &[0x00, 0x78, 0x00, 0x40];
        assert!(decode_vvc_sps(nal).is_err());
        // A two-byte header alone (the minimum for the reader to start).
        assert!(decode_vvc_sps(&[0x00, 0x78]).is_err());
    }

    // -------------------------------------------------------------------
    // Hostile SPS field bounds (P0 batch B, item 5)
    // -------------------------------------------------------------------

    use alloc::vec;
    use alloc::vec::Vec;

    /// Minimal MSB-first bit writer for hand-built SPS RBSPs in these tests.
    struct BitSink {
        bytes: Vec<u8>,
        cur: u8,
        nbits: u32,
    }

    impl BitSink {
        fn new() -> Self {
            Self {
                bytes: Vec::new(),
                cur: 0,
                nbits: 0,
            }
        }
        fn bit(&mut self, b: bool) {
            if b {
                self.cur |= 1 << (7 - self.nbits);
            }
            self.nbits += 1;
            if self.nbits == 8 {
                self.bytes.push(self.cur);
                self.cur = 0;
                self.nbits = 0;
            }
        }
        fn bits(&mut self, v: u64, n: u32) {
            for i in (0..n).rev() {
                self.bit((v >> i) & 1 == 1);
            }
        }
        /// `ue(v)` encoder — the exact inverse of `BitReader::read_ue`
        /// (H.264 §9.1).
        fn ue(&mut self, v: u64) {
            let code = v + 1;
            let len = 64 - code.leading_zeros();
            for _ in 0..len - 1 {
                self.bit(false);
            }
            self.bits(code, len);
        }
        /// Write a value with exactly 32 leading zero bits (ue value
        /// `0xFFFF_FFFF`): past every spec bound above, yet inside the
        /// reader's ≤32-zero cap — so these tests exercise the *SPS-level*
        /// checks, not the bitreader cap.
        fn ue_huge(&mut self) {
            for _ in 0..32 {
                self.bit(false);
            }
            self.bit(true);
            for _ in 0..32 {
                self.bit(false);
            }
        }
        fn finish(mut self) -> Vec<u8> {
            if self.nbits > 0 {
                self.bytes.push(self.cur);
            }
            self.bytes
        }
    }

    /// `num_ref_frames_in_pic_order_cnt_cycle = 2^32-1` as the last field of
    /// an otherwise-plausible SPS must return `Err` promptly. Pre-fix this
    /// test would never finish: the loop spun ~4.3 billion times on a
    /// `read_se` that returned `Ok(0)` at EOF without consuming anything —
    /// exactly the permanent demux hang from the field reports.
    #[test]
    fn avc_sps_huge_poc_cycle_count_is_rejected() {
        let mut nal = vec![0x67u8, 66, 0x00, 30]; // nal hdr, profile 66 (no high branch)
        let mut s = BitSink::new();
        s.ue(0); // seq_parameter_set_id
        s.ue(0); // log2_max_frame_num_minus4
        s.ue(1); // pic_order_cnt_type = 1
        s.bit(false); // delta_pic_order_always_zero_flag
        s.bit(true); // offset_for_non_ref_pic se(0)
        s.bit(true); // offset_for_top_to_bottom_field se(0)
        s.ue_huge(); // num_ref_frames_in_pic_order_cnt_cycle = 2^32-1 > 255
        nal.extend(s.finish());

        let err =
            decode_avc_sps(&nal).expect_err("H.264 §7.4.2.1 bounds the cycle count to 0..=255");
        assert!(
            matches!(
                err,
                Error::InvalidValue {
                    field: "num_ref_frames_in_pic_order_cnt_cycle",
                    ..
                }
            ),
            "{err:?}"
        );
    }

    /// `chroma_format_idc > 3` (H.264 §7.4.2.1) must be `Err`, not a silently
    /// truncated `as u8`.
    #[test]
    fn avc_sps_chroma_format_idc_above_3_is_rejected() {
        let mut nal = vec![0x67u8, 100, 0x00, 30]; // High profile → chroma branch
        let mut s = BitSink::new();
        s.ue(0); // seq_parameter_set_id
        s.ue(4); // chroma_format_idc — out of range
        nal.extend(s.finish());

        let err = decode_avc_sps(&nal).expect_err("chroma_format_idc shall be 0..=3");
        assert!(
            matches!(
                err,
                Error::InvalidValue {
                    field: "chroma_format_idc",
                    ..
                }
            ),
            "{err:?}"
        );
    }

    /// `bit_depth_luma_minus8 > 6` (H.264 §7.4.2.1) must be `Err`; pre-fix it
    /// was `as u8 + 8`, which overflowed (debug panic / release wrap) for
    /// values ≥ 248 and mis-computed the bit depth for anything > 6.
    #[test]
    fn avc_sps_bit_depth_minus8_above_6_is_rejected() {
        let mut nal = vec![0x67u8, 100, 0x00, 30];
        let mut s = BitSink::new();
        s.ue(0); // seq_parameter_set_id
        s.ue(1); // chroma_format_idc
        s.ue(7); // bit_depth_luma_minus8 — out of range (max 6)
        nal.extend(s.finish());

        let err = decode_avc_sps(&nal).expect_err("bit_depth_luma_minus8 shall be 0..=6");
        assert!(
            matches!(
                err,
                Error::InvalidValue {
                    field: "bit_depth_luma_minus8",
                    ..
                }
            ),
            "{err:?}"
        );
    }

    /// HEVC analogue: `num_short_term_ref_pic_sets = 2^32-1` (H.265 §7.4.3.2
    /// bounds it to 0..=64). Pre-fix the VUI walk looped ~4.3 billion times
    /// on EOF `Ok(0)` reads; post-fix the bound makes the error-swallowing
    /// wrapper return promptly with no timing.
    #[test]
    fn hevc_sps_huge_short_term_ref_pic_set_count_terminates_promptly() {
        let mut nal = vec![0x42u8, 0x01]; // NAL header (nal_unit_type=33)
        let mut s = BitSink::new();
        s.bits(0, 4); // sps_video_parameter_set_id u(4)
        s.bits(0, 3); // sps_max_sub_layers_minus1 u(3) = 0
        s.bit(false); // sps_temporal_id_nesting_flag
        // profile_tier_level(1, 0): general_* only.
        s.bits(0, 2); // general_profile_space
        s.bit(false); // general_tier_flag
        s.bits(1, 5); // general_profile_idc
        s.bits(0, 32); // general_profile_compatibility_flags
        s.bits(0xE0_00_00_00_00_00, 48); // general_constraint_indicator_flags
        s.bits(93, 8); // general_level_idc
        s.ue(0); // sps_seq_parameter_set_id
        s.ue(1); // chroma_format_idc
        s.ue(16); // pic_width_in_luma_samples
        s.ue(16); // pic_height_in_luma_samples
        s.bit(false); // conformance_window_flag
        s.ue(2); // bit_depth_luma_minus8 (10-bit)
        s.ue(2); // bit_depth_chroma_minus8
        // parse_hevc_sps_to_vui_timing_inner resumes here:
        s.ue(3); // log2_max_pic_order_cnt_lsb_minus4
        s.bit(false); // sps_sub_layer_ordering_info_present_flag
        s.ue(0); // sps_max_dec_pic_buffering_minus1[0]
        s.ue(0); // sps_max_num_reorder_pics[0]
        s.ue(0); // sps_max_latency_increase_plus1[0]
        s.ue(0); // log2_min_luma_coding_block_size_minus3
        s.ue(3); // log2_diff_max_min_luma_coding_block_size
        s.ue(0); // log2_min_luma_transform_block_size_minus2
        s.ue(3); // log2_diff_max_min_luma_transform_block_size
        s.ue(1); // max_transform_hierarchy_depth_inter
        s.ue(1); // max_transform_hierarchy_depth_intra
        s.bit(false); // scaling_list_enabled_flag
        s.bit(false); // amp_enabled_flag
        s.bit(false); // sample_adaptive_offset_enabled_flag
        s.bit(false); // pcm_enabled_flag
        s.ue_huge(); // num_short_term_ref_pic_sets = 2^32-1 > 64
        nal.extend(s.finish());

        let info = decode_hevc_sps(&nal)
            .expect("mandatory fields parse; the bounded VUI walk error is swallowed");
        assert_eq!(info.fps, None);
    }

    // -------------------------------------------------------------------
    // Interlace facts (#1162 R3): spec-built synthetic streams. Every field
    // is written per the transcribed syntax in docs/codec/h26{4,5}-vui-pic-
    // timing.md, so a mis-walk of any preceding element shifts the bits the
    // assertions read.
    // -------------------------------------------------------------------

    use crate::interlace::{PicStruct, SourceScanType, avc_facts, hevc_facts};
    use crate::slice_header::AvcParamSets;

    /// Build an HEVC SPS NAL whose RPS section exercises inter-RPS prediction
    /// (so the VUI is only reachable with the exact (7-61)/(7-62) counts) and
    /// whose VUI carries `field_seq`/`frame_field_info_present`.
    fn hevc_interlace_sps(field_seq: bool, ffi: bool, vui: bool, ptl_bits: u64) -> Vec<u8> {
        let mut nal = vec![0x42u8, 0x01];
        let mut s = BitSink::new();
        s.bits(0, 4); // sps_video_parameter_set_id
        s.bits(0, 3); // sps_max_sub_layers_minus1
        s.bit(true); // sps_temporal_id_nesting_flag
        s.bits(0, 2); // general_profile_space
        s.bit(false); // general_tier_flag
        s.bits(1, 5); // general_profile_idc
        s.bits(0, 32); // general_profile_compatibility_flags
        s.bits(ptl_bits, 48); // general_constraint_indicator_flags
        s.bits(93, 8); // general_level_idc
        s.ue(0); // sps_seq_parameter_set_id
        s.ue(1); // chroma_format_idc
        s.ue(16); // pic_width_in_luma_samples
        s.ue(16); // pic_height_in_luma_samples
        s.bit(false); // conformance_window_flag
        s.ue(0); // bit_depth_luma_minus8
        s.ue(0); // bit_depth_chroma_minus8
        s.ue(3); // log2_max_pic_order_cnt_lsb_minus4
        s.bit(false); // sps_sub_layer_ordering_info_present_flag
        s.ue(0);
        s.ue(0);
        s.ue(0); // sps_max_dec_pic_buffering/num_reorder/latency
        s.ue(0);
        s.ue(3);
        s.ue(0);
        s.ue(3); // coding/transform block sizes
        s.ue(1);
        s.ue(1); // max_transform_hierarchy_depth_inter/intra
        s.bit(false); // scaling_list_enabled_flag
        s.bit(false); // amp_enabled_flag
        s.bit(false); // sample_adaptive_offset_enabled_flag
        s.bit(false); // pcm_enabled_flag
        s.ue(3); // num_short_term_ref_pic_sets
        // set 0: explicit, DeltaPocS0 = [-1], DeltaPocS1 = [+2]
        s.ue(1); // num_negative_pics
        s.ue(1); // num_positive_pics
        s.ue(0); // delta_poc_s0_minus1 -> -1
        s.bit(true); // used_by_curr_pic_s0_flag
        s.ue(1); // delta_poc_s1_minus1 -> +2
        s.bit(true); // used_by_curr_pic_s1_flag
        // set 1: inter from set 0 (NumDeltaPocs = 2 -> 3 flag groups),
        // deltaRps = -3. Candidates: s1[0] -> -1 (j = 1, dropped below),
        // deltaRps entry (j = 2) -> -3, s0[0] -> -4 (j = 0): derives
        // S0 = [-3, -4], S1 = [] (2 entries).
        s.bit(true); // inter_ref_pic_set_prediction_flag
        s.bit(true); // delta_rps_sign
        s.ue(2); // abs_delta_rps_minus1
        s.bit(true); // used_by_curr_pic_flag[0]
        s.bit(false); // used_by_curr_pic_flag[1]
        s.bit(false); // use_delta_flag[1] = 0: -1 is not kept
        s.bit(true); // used_by_curr_pic_flag[2]
        // set 2: inter from set 1 (NumDeltaPocs = 2 -> 3 flags)
        s.bit(true); // inter_ref_pic_set_prediction_flag
        s.bit(false); // delta_rps_sign
        s.ue(0); // abs_delta_rps_minus1
        for _ in 0..3 {
            s.bit(true); // used_by_curr_pic_flag[j]
        }
        s.bit(false); // long_term_ref_pics_present_flag
        s.bit(false); // sps_temporal_mvp_enabled_flag
        s.bit(false); // strong_intra_smoothing_enabled_flag
        s.bit(vui); // vui_parameters_present_flag
        if vui {
            s.bit(false); // aspect_ratio_info_present_flag
            s.bit(false); // overscan_info_present_flag
            s.bit(false); // video_signal_type_present_flag
            s.bit(false); // chroma_loc_info_present_flag
            s.bit(false); // neutral_chroma_indication_flag
            s.bit(field_seq); // field_seq_flag
            s.bit(ffi); // frame_field_info_present_flag
            s.bit(false); // default_display_window_flag
            s.bit(false); // vui_timing_info_present_flag
            s.bit(false); // bitstream_restriction_flag
        }
        s.bit(true); // rbsp_stop_one_bit
        nal.extend(s.finish());
        nal
    }

    #[test]
    fn hevc_field_seq_is_read_past_inter_rps_prediction() {
        let sps = hevc_interlace_sps(true, true, true, 0);
        let i = decode_hevc_interlace_sps(&sps).expect("parses");
        assert!(i.field_seq, "field_seq_flag read through 3 st_ref_pic_sets");
        assert!(i.frame_field_info_present);
        let frames = decode_hevc_interlace_sps(&hevc_interlace_sps(false, false, true, 0)).unwrap();
        assert_eq!(
            (frames.field_seq, frames.frame_field_info_present),
            (false, false)
        );
        // The pre-existing decoder agrees and still parses.
        assert!(decode_hevc_sps(&sps).is_ok());
    }

    #[test]
    fn hevc_frame_field_info_is_inferred_from_ptl_when_vui_absent() {
        // general_progressive_source_flag = general_interlaced_source_flag = 1
        // (§E.3.1 inference), no VUI.
        let both = decode_hevc_interlace_sps(&hevc_interlace_sps(
            false,
            false,
            false,
            0xC0_00_00_00_00_00,
        ))
        .unwrap();
        assert!(both.frame_field_info_present && !both.field_seq);
        let one = decode_hevc_interlace_sps(&hevc_interlace_sps(
            false,
            false,
            false,
            0x80_00_00_00_00_00,
        ))
        .unwrap();
        assert!(!one.frame_field_info_present);
    }

    fn hevc_nal(nal_type: u8, body: &[u8]) -> Vec<u8> {
        let mut v = vec![nal_type << 1, 0x01];
        v.extend_from_slice(body);
        v
    }

    /// A HEVC prefix SEI carrying a `pic_timing` with the given
    /// `pic_struct`/`source_scan_type`/`duplicate_flag` (§D.2.3).
    fn hevc_pic_timing_sei(pic_struct: u64, scan: u64) -> Vec<u8> {
        let mut p = BitSink::new();
        p.bits(pic_struct, 4);
        p.bits(scan, 2);
        p.bit(false); // duplicate_flag
        let payload = p.finish(); // one byte (7 bits + pad)
        let mut body = vec![1u8, payload.len() as u8]; // payloadType 1, size
        body.extend_from_slice(&payload);
        body.push(0x80); // rbsp_trailing_bits
        hevc_nal(39, &body)
    }

    #[test]
    fn hevc_pic_struct_and_scan_type_are_read_from_prefix_sei() {
        let sps = hevc_interlace_sps(true, true, true, 0);
        let vcl = hevc_nal(1, &[0x80]);
        for (code, want, bottom_first) in [
            (1u64, PicStruct::TopField, Some(false)),
            (2, PicStruct::BottomField, Some(true)),
            (10, PicStruct::BottomPairedWithPreviousTop, Some(true)),
            (11, PicStruct::TopPairedWithNextBottom, Some(false)),
        ] {
            let sei = hevc_pic_timing_sei(code, 0);
            let f = hevc_facts(&sps, &[sei.as_slice(), vcl.as_slice()]).expect("facts");
            assert!(f.field_pic);
            assert_eq!(f.fields, 1);
            assert_eq!(f.pic_struct, Some(want));
            assert_eq!(f.bottom_field_first, bottom_first);
            assert_eq!(f.source_scan_type, Some(SourceScanType::Interlaced));
        }
        // source_scan_type 3 (reserved) reads as unknown (§D.3.3).
        let sei = hevc_pic_timing_sei(1, 3);
        let f = hevc_facts(&sps, &[sei.as_slice(), vcl.as_slice()]).unwrap();
        assert_eq!(f.source_scan_type, Some(SourceScanType::Unknown));
        // Reserved pic_struct (13) is reported as None, not guessed.
        let sei = hevc_pic_timing_sei(13, 0);
        let f = hevc_facts(&sps, &[sei.as_slice(), vcl.as_slice()]).unwrap();
        assert_eq!(f.pic_struct, None);
        // A SEI-less picture of a field sequence is still a field, parity unknown.
        let f = hevc_facts(&sps, &[vcl.as_slice()]).unwrap();
        assert!(f.field_pic);
        assert_eq!((f.pic_struct, f.bottom_field_first), (None, None));
        // No VCL NAL at all: not a picture.
        assert!(hevc_facts(&sps, &[sei.as_slice()]).is_none());
        // frame_field_info_present = 0: the SEI is not interpreted.
        let sps0 = hevc_interlace_sps(false, false, true, 0);
        let sei = hevc_pic_timing_sei(4, 0);
        let f = hevc_facts(&sps0, &[sei.as_slice(), vcl.as_slice()]).unwrap();
        assert!(!f.field_pic);
        assert_eq!(f.pic_struct, None);
    }

    /// Build an H.264 SPS (profile 66, `pic_order_cnt_type` 2 so slice headers
    /// carry no POC syntax). `hrd`: optional `(cpb_removal_delay_length_minus1,
    /// dpb_output_delay_length_minus1)` for the NAL HRD, `vcl` likewise.
    fn avc_interlace_sps(
        mbaff: bool,
        pic_struct_present: bool,
        nal_hrd: Option<(u64, u64)>,
        vcl_hrd: Option<(u64, u64)>,
    ) -> Vec<u8> {
        fn hrd(s: &mut BitSink, (cpb, dpb): (u64, u64)) {
            s.ue(1); // cpb_cnt_minus1 (two schedules, so the loop must iterate)
            s.bits(0, 4); // bit_rate_scale
            s.bits(0, 4); // cpb_size_scale
            for _ in 0..2 {
                s.ue(7); // bit_rate_value_minus1
                s.ue(9); // cpb_size_value_minus1
                s.bit(true); // cbr_flag
            }
            s.bits(22, 5); // initial_cpb_removal_delay_length_minus1
            s.bits(cpb, 5); // cpb_removal_delay_length_minus1
            s.bits(dpb, 5); // dpb_output_delay_length_minus1
            s.bits(24, 5); // time_offset_length
        }
        let mut nal = vec![0x67u8, 66, 0x00, 30];
        let mut s = BitSink::new();
        s.ue(0); // seq_parameter_set_id
        s.ue(0); // log2_max_frame_num_minus4 -> frame_num is 4 bits
        s.ue(2); // pic_order_cnt_type
        s.ue(1); // max_num_ref_frames
        s.bit(false); // gaps_in_frame_num_value_allowed_flag
        s.ue(3); // pic_width_in_mbs_minus1
        s.ue(1); // pic_height_in_map_units_minus1
        s.bit(false); // frame_mbs_only_flag
        s.bit(mbaff); // mb_adaptive_frame_field_flag
        s.bit(true); // direct_8x8_inference_flag
        s.bit(false); // frame_cropping_flag
        s.bit(true); // vui_parameters_present_flag
        s.bit(false); // aspect_ratio_info_present_flag
        s.bit(false); // overscan_info_present_flag
        s.bit(false); // video_signal_type_present_flag
        s.bit(false); // chroma_loc_info_present_flag
        s.bit(true); // timing_info_present_flag
        s.bits(1, 32); // num_units_in_tick
        s.bits(50, 32); // time_scale
        s.bit(true); // fixed_frame_rate_flag
        s.bit(nal_hrd.is_some()); // nal_hrd_parameters_present_flag
        if let Some(h) = nal_hrd {
            hrd(&mut s, h);
        }
        s.bit(vcl_hrd.is_some()); // vcl_hrd_parameters_present_flag
        if let Some(h) = vcl_hrd {
            hrd(&mut s, h);
        }
        if nal_hrd.is_some() || vcl_hrd.is_some() {
            s.bit(false); // low_delay_hrd_flag
        }
        s.bit(pic_struct_present); // pic_struct_present_flag
        s.bit(false); // bitstream_restriction_flag
        s.bit(true); // rbsp_stop_one_bit
        nal.extend(s.finish());
        nal
    }

    fn avc_pps() -> Vec<u8> {
        let mut s = BitSink::new();
        s.ue(0); // pic_parameter_set_id
        s.ue(0); // seq_parameter_set_id
        s.bit(false); // entropy_coding_mode_flag
        s.bit(false); // bottom_field_pic_order_in_frame_present_flag
        s.ue(0); // num_slice_groups_minus1
        s.ue(0);
        s.ue(0); // num_ref_idx_l0/l1_default_active_minus1
        s.bit(false); // weighted_pred_flag
        s.bits(0, 2); // weighted_bipred_idc
        s.ue(0); // pic_init_qp_minus26 se(0)
        s.ue(0); // pic_init_qs_minus26
        s.ue(0); // chroma_qp_index_offset
        s.bit(false); // deblocking_filter_control_present_flag
        s.bit(false); // constrained_intra_pred_flag
        s.bit(false); // redundant_pic_cnt_present_flag
        s.bit(true);
        let mut nal = vec![0x68u8];
        nal.extend(s.finish());
        nal
    }

    /// An I slice (type 7), `frame_num` 0, as a frame or as a top/bottom field.
    fn avc_slice(field: Option<bool>) -> Vec<u8> {
        let mut s = BitSink::new();
        s.ue(0); // first_mb_in_slice
        s.ue(7); // slice_type (I)
        s.ue(0); // pic_parameter_set_id
        s.bits(0, 4); // frame_num
        match field {
            None => s.bit(false), // field_pic_flag
            Some(bottom) => {
                s.bit(true); // field_pic_flag
                s.bit(bottom); // bottom_field_flag
            }
        }
        s.bits(0, 8); // slice data stand-in (never parsed)
        let mut nal = vec![0x61u8]; // nal_ref_idc 3, type 1
        nal.extend(s.finish());
        nal
    }

    /// An H.264 `pic_timing` SEI NAL: `cpb`/`dpb` delay bit lengths, then
    /// `pic_struct` (§D.1.3), then a zero clock-timestamp-flag tail.
    fn avc_pic_timing_sei(delays: Option<(u32, u32)>, pic_struct: u64) -> Vec<u8> {
        let mut p = BitSink::new();
        if let Some((cpb, dpb)) = delays {
            p.bits(0x15555 & ((1 << cpb) - 1), cpb); // cpb_removal_delay
            p.bits(0x2AAAA & ((1 << dpb) - 1), dpb); // dpb_output_delay
        }
        p.bits(pic_struct, 4);
        p.bits(0, 3); // clock_timestamp_flag[0..] = 0
        let payload = p.finish();
        let mut nal = vec![0x06u8, 1, payload.len() as u8];
        nal.extend_from_slice(&payload);
        nal.push(0x80);
        nal
    }

    fn avc_ps(sps: &[u8]) -> AvcParamSets {
        let mut ps = AvcParamSets::new();
        ps.observe_nal(sps);
        ps.observe_nal(&avc_pps());
        ps
    }

    #[test]
    fn avc_sps_scan_flags_and_pic_timing_layout() {
        let paff = decode_avc_slice_sps(&avc_interlace_sps(false, false, None, None)).unwrap();
        assert!(!paff.frame_mbs_only && !paff.mb_adaptive_frame_field);
        assert_eq!(paff.pic_timing, None, "pic_struct_present_flag = 0");
        let mbaff = decode_avc_slice_sps(&avc_interlace_sps(true, true, None, None)).unwrap();
        assert!(mbaff.mb_adaptive_frame_field);
        assert_eq!(
            mbaff.pic_timing,
            Some(AvcPicTimingLayout { delay_bits: None })
        );
        let hrd = decode_avc_slice_sps(&avc_interlace_sps(true, true, Some((4, 3)), None)).unwrap();
        assert_eq!(
            hrd.pic_timing,
            Some(AvcPicTimingLayout {
                delay_bits: Some((5, 4))
            })
        );
        let both = decode_avc_slice_sps(&avc_interlace_sps(true, true, Some((4, 3)), Some((4, 3))))
            .unwrap();
        assert_eq!(both.pic_timing, hrd.pic_timing);
        // NAL and VCL disagree: the spec names no winner, so no pic_struct.
        let clash =
            decode_avc_slice_sps(&avc_interlace_sps(true, true, Some((4, 3)), Some((6, 3))))
                .unwrap();
        assert_eq!(clash.pic_timing, None);
    }

    #[test]
    fn avc_pic_struct_is_read_after_the_hrd_delays() {
        let sps = avc_interlace_sps(true, true, Some((4, 3)), None);
        let ps = avc_ps(&sps);
        let frame = avc_slice(None);
        let sei = avc_pic_timing_sei(Some((5, 4)), 4);
        let f = avc_facts(&ps, &[sei.as_slice(), frame.as_slice()]).expect("facts");
        assert!(!f.field_pic);
        assert_eq!(f.fields, 0);
        assert_eq!(f.pic_struct, Some(PicStruct::BottomTop));
        assert_eq!(f.bottom_field_first, Some(true));
        // Reserved pic_struct (9 is HEVC-only) is None for H.264.
        let sei = avc_pic_timing_sei(Some((5, 4)), 9);
        let f = avc_facts(&ps, &[sei.as_slice(), frame.as_slice()]).unwrap();
        assert_eq!(f.pic_struct, None);
        // No HRD: pic_struct is the first field of the payload.
        let sps = avc_interlace_sps(false, true, None, None);
        let ps = avc_ps(&sps);
        let sei = avc_pic_timing_sei(None, 3);
        let f = avc_facts(&ps, &[sei.as_slice(), frame.as_slice()]).unwrap();
        assert_eq!(f.pic_struct, Some(PicStruct::TopBottom));
        assert_eq!(f.bottom_field_first, Some(false));
    }

    #[test]
    fn avc_field_pair_parity_comes_from_the_first_slice() {
        let ps = avc_ps(&avc_interlace_sps(false, false, None, None));
        let (top, bottom) = (avc_slice(Some(false)), avc_slice(Some(true)));
        let pair = avc_facts(&ps, &[top.as_slice(), bottom.as_slice()]).unwrap();
        assert_eq!(
            (pair.field_pic, pair.fields, pair.bottom_field_first),
            (true, 2, Some(false))
        );
        let pair = avc_facts(&ps, &[bottom.as_slice(), top.as_slice()]).unwrap();
        assert_eq!(
            (pair.field_pic, pair.fields, pair.bottom_field_first),
            (true, 2, Some(true))
        );
        let lone = avc_facts(&ps, &[bottom.as_slice()]).unwrap();
        assert_eq!((lone.fields, lone.bottom_field_first), (1, Some(true)));
        // Two slices of the SAME field are one picture, not a pair.
        let same = avc_facts(&ps, &[top.as_slice(), top.as_slice()]).unwrap();
        assert_eq!(same.fields, 1);
        // Unknown PPS: no facts.
        assert!(avc_facts(&AvcParamSets::new(), &[top.as_slice()]).is_none());
    }
}