pq/libfreemkv
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v1.0.0-rc.1

Browse Source 
CSS keyless decrypt (Stevenson), AACS 1.0/2.0/2.1, MPEG-2 DVD, multi-OS SCSI, multipass recovery, mux highway, audit hardening
This commit is contained in:
Matthew Jackson
2026-06-21 21:06:07 -07:00
parent e8bb6225ac
commit 5941c059c6
53 changed files with 7439 additions and 2340 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/mux/codec/h264.rs
+664 -65
View File
@@ -24,9 +24,17 @@ pub struct H264Parser {
// occurrence whose body DIFFERS from the codecPrivate copy must therefore be
// emitted IN-BAND at each point it appears so it overrides the re-applied
// avcC set; otherwise those frames decode against the wrong parameter set.
// (Same defect class as the HEVC PPS-redefinition bug.)
// (Same defect class as the HEVC PPS-redefinition bug — fixed identically.)
sps: Option<Vec<u8>>,
pps: Option<Vec<u8>>,
// Currently-ACTIVE body of each type (most recent the bitstream defined),
// distinct from the fixed `sps`/`pps` codecPrivate copy. See the HEVC
// parser for the full rationale: the strip/emit decision must be made
// against the active set, and the active set must be re-asserted in-band at
// every keyframe that doesn't carry it, or a streaming decoder reverts to
// the stale avcC copy after a mid-title redefinition.
cur_sps: Option<Vec<u8>>,
cur_pps: Option<Vec<u8>>,
}
impl Default for H264Parser {
@@ -41,37 +49,80 @@ impl H264Parser {
Self {
sps: None,
pps: None,
cur_sps: None,
cur_pps: None,
}
}
}
/// Handle an SPS/PPS NAL (mirrors the HEVC fix):
/// - First of its type → seeds codecPrivate (`first`); stripped from frame data
/// (the player gets it from avcC).
/// - Identical to the codecPrivate copy → stripped (the player re-applies it
/// from avcC at each keyframe; BD streams repeat param sets at every IDR).
/// - DIFFERENT body from the codecPrivate copy (a mid-title redefinition of the
/// same id) → emitted IN-BAND (length-prefixed) at EVERY occurrence so it
/// overrides the avcC copy the player re-applies at each keyframe.
fn handle_param_set(first: &mut Option<Vec<u8>>, nal: &[u8], frame_data: &mut Vec<u8>) {
match first {
None => {
first.replace(nal.to_vec()); // seeds codecPrivate; stripped here
}
Some(f) if f.as_slice() == nal => {} // == codecPrivate → player has it
Some(_) => {
// Differs from codecPrivate → emit in-band so it wins at this AU.
// A NAL longer than u32::MAX cannot be length-prefixed in the
// 4-byte field; skip it rather than emit a truncated length over
// the full body (mis-framed NALU). Unreachable in practice — no
// real access unit is >4 GiB.
let Ok(len) = u32::try_from(nal.len()) else {
return;
};
frame_data.extend_from_slice(&len.to_be_bytes());
frame_data.extend_from_slice(nal);
}
/// Append `nal` to `out` as a 4-byte big-endian length prefix + body. A NAL
/// longer than `u32::MAX` can't be length-prefixed in the 4-byte field, so it
/// is skipped rather than mis-framed. Unreachable in practice (no AU > 4 GiB).
fn push_length_prefixed(out: &mut Vec<u8>, nal: &[u8]) {
let Ok(len) = u32::try_from(nal.len()) else {
return;
};
out.extend_from_slice(&len.to_be_bytes());
out.extend_from_slice(nal);
}
/// Handle an SPS/PPS NAL (mirrors the HEVC fix). The strip/emit decision is
/// made against the currently-ACTIVE set `cur`, NOT the codecPrivate copy
/// `first`: a streaming MKV decoder applies avcC once at init and thereafter
/// updates a parameter set only from an in-band NAL, so a switch BACK to the
/// first-seen body (== codecPrivate) is still a change the decoder must be told
/// about. Stripping on `== first` silently dropped that revert.
///
/// - First of its type → seeds codecPrivate; stripped (decoder gets it from avcC).
/// - Equal to the active set `cur` → redundant; stripped.
/// - Different from `cur` (a change in EITHER direction) → emitted in-band and
/// `cur` updated.
///
/// Returns `true` when the NAL was emitted in-band into `frame_data`.
fn handle_param_set(
first: &mut Option<Vec<u8>>,
cur: &mut Option<Vec<u8>>,
nal: &[u8],
frame_data: &mut Vec<u8>,
) -> bool {
let is_first = first.is_none();
if is_first {
first.replace(nal.to_vec()); // seeds codecPrivate; stripped here
}
let changed = cur.as_deref() != Some(nal);
if changed {
*cur = Some(nal.to_vec());
}
if is_first || !changed {
return false;
}
push_length_prefixed(frame_data, nal);
true
}
/// Append the active parameter set `cur` to `prefix` (length-prefixed) so every
/// keyframe is SELF-CONTAINED: it carries the active SPS/PPS in-band ahead of
/// its slices. Skipped only when this access unit ALREADY carried the NAL in-band
/// (`emitted` — avoids a duplicate) or no active set exists yet.
///
/// Unconditional (not only when the active set differs from codecPrivate): a
/// streaming decoder applies the avcC param sets once at init, then relies on
/// in-band repetition. Some sources stop repeating a param set at later IDRs even
/// though its body is unchanged; if the decoder then drops it (a reset event),
/// nothing re-sends it and every subsequent slice fails (param-set id out of
/// range) until the next genuine change. Re-asserting at EVERY keyframe — what
/// compliant muxers do at every IDR — makes streaming decode self-healing.
/// Re-sending an identical param set is benign; cost is a few bytes per keyframe.
/// This strictly supersets the change-only re-assert, so the param-set-revert
/// fix is unaffected.
fn reassert_active(prefix: &mut Vec<u8>, cur: &Option<Vec<u8>>, emitted: bool) {
if emitted {
return;
}
let Some(active) = cur.as_deref() else {
return;
};
push_length_prefixed(prefix, active);
}
impl CodecParser for H264Parser {
@@ -90,6 +141,9 @@ impl CodecParser for H264Parser {
// Annex B (start-code prefixed) NALUs to length-prefixed NALUs (MKV with
// AVCDecoderConfigurationRecord expects a 4-byte length prefix per NAL).
let mut keyframe = false;
// Did this access unit already carry each param-set type in-band?
let mut emitted_sps = false;
let mut emitted_pps = false;
// Pre-size: output is ~input bytes plus a few 4-byte NAL length prefixes.
// The unsized Vec growth chain otherwise reallocs several times per
// frame in the mux hot path (mirrors the HEVC parser).
@@ -99,10 +153,16 @@ impl CodecParser for H264Parser {
let nal_type = nal[0] & 0x1F;
match nal_type {
// Param sets: seed avcC, strip if identical, emit in-band if a
// mid-title redefinition differs from the avcC copy.
NAL_SPS => handle_param_set(&mut self.sps, nal, &mut frame_data),
NAL_PPS => handle_param_set(&mut self.pps, nal, &mut frame_data),
// Param sets: seed avcC, strip if unchanged vs the active set,
// emit in-band on any change (incl. reverting to the avcC copy).
NAL_SPS => {
emitted_sps |=
handle_param_set(&mut self.sps, &mut self.cur_sps, nal, &mut frame_data)
}
NAL_PPS => {
emitted_pps |=
handle_param_set(&mut self.pps, &mut self.cur_pps, nal, &mut frame_data)
}
// Access unit delimiters: drop. Intentional and spec-correct —
// Matroska H.264 frame data omits AUDs (the container delimits
// access units), so keeping them in-band is redundant. Mirrors
@@ -128,6 +188,20 @@ impl CodecParser for H264Parser {
return Vec::new();
}
// Every keyframe is self-contained: re-assert the active SPS/PPS in-band
// ahead of the slices (even when unchanged vs codecPrivate) so a decoder
// that dropped the set at a reset recovers, and a stale avcC re-apply
// can't revert it. Skipped per-type only when this AU already carried it.
if keyframe {
let mut prefix = Vec::new();
reassert_active(&mut prefix, &self.cur_sps, emitted_sps);
reassert_active(&mut prefix, &self.cur_pps, emitted_pps);
if !prefix.is_empty() {
prefix.extend_from_slice(&frame_data);
frame_data = prefix;
}
}
vec![Frame {
pts_ns,
keyframe,
@@ -165,6 +239,7 @@ impl CodecParser for H264Parser {
// numOfPictureParameterSets = 1
// pictureParameterSetLength = pps.len()
// pictureParameterSetNALUnit = pps
// [High Profile extension per ISO 14496-15 §5.3.3.1.2, when applicable]
let mut record = vec![
1, // configurationVersion
@@ -182,10 +257,175 @@ impl CodecParser for H264Parser {
record.push(pps.len() as u8);
record.extend_from_slice(pps);
// ISO 14496-15 §5.3.3.1.2: for High-Profile and related profiles
// (profile_idc 100, 110, 122, 144) the record has 4 trailing extension
// bytes carrying chroma_format_idc and bit depths. Older parsers expect
// the record to END after the PPS for Baseline/Main/Extended — do NOT
// append for those (strict parsers reject the extra bytes).
let profile_idc = sps[1];
const HIGH_PROFILES: [u8; 4] = [100, 110, 122, 144];
if HIGH_PROFILES.contains(&profile_idc) {
if let Some((chroma_fmt, depth_luma, depth_chroma)) = parse_sps_high_profile_ext(sps) {
// byte 0: 111111xx — reserved(6) + chroma_format_idc(2)
record.push(0xFC | (chroma_fmt & 0x03));
// byte 1: 11111xxx — reserved(5) + bit_depth_luma_minus8(3)
record.push(0xF8 | (depth_luma & 0x07));
// byte 2: 11111xxx — reserved(5) + bit_depth_chroma_minus8(3)
record.push(0xF8 | (depth_chroma & 0x07));
// byte 3: num_of_sequence_parameter_set_ext (0 = none)
record.push(0x00);
}
}
Some(record)
}
}
/// Parse `(chroma_format_idc, bit_depth_luma_minus8, bit_depth_chroma_minus8)` from
/// a High-Profile SPS NAL (profile_idc ∈ {100, 110, 122, 144}).
///
/// SPS RBSP layout (ITU-T H.264 §7.3.2.1.1) up to the fields we need:
/// byte 0 NAL header (already known to be type 7)
/// byte 1 profile_idc
/// byte 2 constraint_set_flags / reserved
/// byte 3 level_idc
/// ue(v) seq_parameter_set_id
/// — High-profile branch —
/// ue(v) chroma_format_idc
/// if chroma_format_idc == 3: u(1) separate_colour_plane_flag
/// ue(v) bit_depth_luma_minus8
/// ue(v) bit_depth_chroma_minus8
///
/// RBSP emulation-prevention bytes (0x00 0x00 0x03 → 0x00 0x00) are removed
/// before bit-parsing so the bit reader sees clean RBSP data.
///
/// Returns `None` if the SPS is too short or malformed (Exp-Golomb code
/// overflows 32 bits, leading-zero count > 31, etc.). The caller silently
/// omits the extension in that case.
fn parse_sps_high_profile_ext(sps: &[u8]) -> Option<(u8, u8, u8)> {
// Strip emulation-prevention bytes: 00 00 03 xx → 00 00 xx (drop the 03).
// We skip byte 0 (NAL header) and start the RBSP from byte 1.
let rbsp: Vec<u8> = {
let raw = &sps[1..]; // skip NAL header byte
let mut out = Vec::with_capacity(raw.len());
let mut i = 0;
while i < raw.len() {
if i + 2 < raw.len() && raw[i] == 0x00 && raw[i + 1] == 0x00 && raw[i + 2] == 0x03 {
out.push(0x00);
out.push(0x00);
i += 3; // skip the 0x03 emulation-prevention byte
} else {
out.push(raw[i]);
i += 1;
}
}
out
};
// RBSP layout after stripping the NAL header byte:
// [0] profile_idc (already checked by caller)
// [1] constraint flags
// [2] level_idc
// [3..] seq_parameter_set_id ue(v), then High-Profile fields
if rbsp.len() < 4 {
return None;
}
// Bit reader over rbsp[3..] (skip profile/flags/level, already known).
let mut reader = SpsReader::new(&rbsp[3..]);
// seq_parameter_set_id — skip
reader.read_ue()?;
// chroma_format_idc
let chroma_format_idc = reader.read_ue()?;
// separate_colour_plane_flag (only when chroma_format_idc == 3)
if chroma_format_idc == 3 {
reader.read_bits(1)?; // skip separate_colour_plane_flag
}
// bit_depth_luma_minus8
let bit_depth_luma_minus8 = reader.read_ue()?;
// bit_depth_chroma_minus8
let bit_depth_chroma_minus8 = reader.read_ue()?;
// Clamp to the 2- and 3-bit fields in the avcC extension bytes.
// Valid H.264 values are 0..=6; the spec guarantees ≤ 6, so no real
// content should be truncated. Out-of-spec values are clamped rather
// than rejected so a corrupt-but-decodable SPS still produces a
// reasonable avcC.
Some((
(chroma_format_idc & 0x03) as u8,
(bit_depth_luma_minus8 & 0x07) as u8,
(bit_depth_chroma_minus8 & 0x07) as u8,
))
}
/// Minimal Exp-Golomb / fixed-width bit reader over a byte slice, for SPS parsing.
struct SpsReader<'a> {
data: &'a [u8],
/// Current byte index.
byte: usize,
/// Number of bits remaining in data[byte] (0 means fully consumed, advance).
bits_left: u8,
}
impl<'a> SpsReader<'a> {
fn new(data: &'a [u8]) -> Self {
Self {
data,
byte: 0,
bits_left: if data.is_empty() { 0 } else { 8 },
}
}
/// Read one bit. Returns `None` when the slice is exhausted.
fn read_bit(&mut self) -> Option<u8> {
if self.bits_left == 0 {
self.byte += 1;
if self.byte >= self.data.len() {
return None;
}
self.bits_left = 8;
}
self.bits_left -= 1;
Some((self.data[self.byte] >> self.bits_left) & 1)
}
/// Read `n` bits (n ≤ 32) as a u32, MSB first. Returns `None` on
/// end-of-data.
fn read_bits(&mut self, n: u8) -> Option<u32> {
let mut val = 0u32;
for _ in 0..n {
val = (val << 1) | (self.read_bit()? as u32);
}
Some(val)
}
/// Read one Exp-Golomb coded unsigned integer ue(v). Leading-zero count
/// must not exceed 31 (a 63-bit code would overflow u32). Returns `None`
/// on end-of-data or overflow.
fn read_ue(&mut self) -> Option<u32> {
let mut leading_zeros = 0u8;
loop {
let bit = self.read_bit()?;
if bit == 1 {
break;
}
leading_zeros += 1;
if leading_zeros > 31 {
return None; // malformed / non-conforming SPS
}
}
if leading_zeros == 0 {
return Some(0);
}
let suffix = self.read_bits(leading_zeros)?;
Some((1u32 << leading_zeros) - 1 + suffix)
}
}
/// Iterator over NAL units in Annex B byte stream.
/// Finds start codes (00 00 01 or 00 00 00 01) and yields the data between them.
struct NalIterator<'a> {
@@ -301,6 +541,112 @@ mod tests {
assert_eq!(frames.len(), 1);
}
// Length-prefixed NAL bodies out of frame_data, and the H.264 PPS (type 8)
// payloads among them.
fn h264_nals_in(frame: &[u8]) -> Vec<Vec<u8>> {
let mut out = Vec::new();
let mut i = 0;
while i + 4 <= frame.len() {
let len =
u32::from_be_bytes([frame[i], frame[i + 1], frame[i + 2], frame[i + 3]]) as usize;
i += 4;
if i + len > frame.len() {
break;
}
out.push(frame[i..i + len].to_vec());
i += len;
}
out
}
fn h264_pps_bodies(nals: &[Vec<u8>]) -> Vec<Vec<u8>> {
nals.iter()
.filter(|n| !n.is_empty() && n[0] & 0x1F == 8)
.map(|n| n[1..].to_vec())
.collect()
}
fn h264_nal(t: u8, body: &[u8]) -> Vec<u8> {
let mut v = vec![0x00, 0x00, 0x01, t];
v.extend_from_slice(body);
v
}
/// Regression (Fight Club bug, H.264 variant): PPS id 0 = body A (→ avcC),
/// redefined to B, then switched BACK to A. A streaming decoder is on B; the
/// revert to A == avcC must still be emitted in-band or the A-segment
/// decodes against B.
#[test]
fn h264_emits_switch_back_to_codecprivate_pps() {
let a = [0xA1u8, 0xA2];
let b = [0xB1u8, 0xB2, 0xB3];
let mut p = H264Parser::new();
// AU1: SPS (seed avcC) + PPS-A (seed) + IDR.
p.parse(&make_pes(
[
h264_nal(0x67, &[0x42, 0x00, 0x1E, 0xAB]),
h264_nal(0x68, &a),
h264_nal(0x65, &[1]),
]
.concat(),
Some(0),
));
// AU2 IDR: redefine PPS to B → emitted in-band.
let f2 = p.parse(&make_pes(
[h264_nal(0x68, &b), h264_nal(0x65, &[2])].concat(),
Some(1),
));
assert!(
h264_pps_bodies(&h264_nals_in(&f2[0].data))
.iter()
.any(|x| x == &b),
"AU2 must carry redefined PPS-B in-band"
);
// AU3 IDR: back to A (== avcC) — must be emitted in-band (active was B).
let f3 = p.parse(&make_pes(
[h264_nal(0x68, &a), h264_nal(0x65, &[3])].concat(),
Some(2),
));
assert!(
h264_pps_bodies(&h264_nals_in(&f3[0].data))
.iter()
.any(|x| x == &a),
"switch back to avcC PPS-A must be emitted in-band"
);
}
/// Regression: a bare IDR keyframe (source omits the PPS) after a mid-title
/// redefinition must re-assert the active PPS in-band.
#[test]
fn h264_reasserts_active_pps_at_bare_keyframe() {
let a = [0xA1u8, 0xA2];
let b = [0xB1u8, 0xB2, 0xB3];
let mut p = H264Parser::new();
p.parse(&make_pes(
[
h264_nal(0x67, &[0x42, 0x00, 0x1E, 0xAB]),
h264_nal(0x68, &a),
h264_nal(0x65, &[1]),
]
.concat(),
Some(0),
));
// Redefine to B at a keyframe.
p.parse(&make_pes(
[h264_nal(0x68, &b), h264_nal(0x65, &[2])].concat(),
Some(1),
));
// Bare IDR (no PPS): active B must be re-asserted; stale A must not be.
let f3 = p.parse(&make_pes(h264_nal(0x65, &[3]), Some(2)));
let got = h264_pps_bodies(&h264_nals_in(&f3[0].data));
assert!(
got.iter().any(|x| x == &b),
"bare keyframe must re-assert active PPS-B"
);
assert!(
!got.iter().any(|x| x == &a),
"must not re-assert stale avcC PPS-A"
);
}
#[test]
fn codec_private_none_before_sps_pps() {
let parser = H264Parser::new();
@@ -390,14 +736,14 @@ mod tests {
}
}
// --- SPS/PPS/AUD are stripped from frame data ---
// --- AUD is stripped; SPS/PPS seed avcC and re-assert at the keyframe ---
#[test]
fn sps_pps_aud_stripped_from_frame_data() {
fn aud_stripped_param_sets_reasserted_at_keyframe() {
let mut parser = H264Parser::new();
let mut data = Vec::new();
// AUD (type 9)
// AUD (type 9) — always dropped
data.extend_from_slice(&[0x00, 0x00, 0x01]);
data.push(0x09);
data.push(0xF0);
@@ -409,7 +755,7 @@ mod tests {
data.extend_from_slice(&[0x00, 0x00, 0x01]);
data.push(0x68);
data.extend_from_slice(&[0xCE, 0x01]);
// IDR (type 5) - only this should appear in frame data
// IDR (type 5)
data.extend_from_slice(&[0x00, 0x00, 0x01]);
data.push(0x65);
data.extend_from_slice(&[0x88, 0x00]);
@@ -418,12 +764,25 @@ mod tests {
let frames = parser.parse(&pes);
assert_eq!(frames.len(), 1);
// Frame data should only contain the IDR NAL (length-prefixed)
// SPS/PPS seed avcC...
assert!(parser.codec_private().is_some(), "SPS/PPS seed avcC");
// ...and because this is a keyframe, the active SPS/PPS are re-asserted
// in-band ahead of the IDR so the keyframe is self-contained. AUD (9) is
// always dropped. Frame data = SPS(7), PPS(8), IDR(5).
let fd = &frames[0].data;
let length = u32::from_be_bytes([fd[0], fd[1], fd[2], fd[3]]);
// IDR NAL is 0x65, 0x88 (trailing 0x00 is stripped as potential start code prefix)
assert_eq!(length, 2);
assert_eq!(fd[4], 0x65); // IDR NAL type byte
let mut types = Vec::new();
let mut o = 0;
while o + 4 <= fd.len() {
let len = u32::from_be_bytes([fd[o], fd[o + 1], fd[o + 2], fd[o + 3]]) as usize;
o += 4;
types.push(fd[o] & 0x1F);
o += len;
}
assert_eq!(
types,
vec![7, 8, 5],
"keyframe: SPS+PPS re-asserted ahead of IDR, AUD dropped"
);
}
// --- PTS conversion ---
@@ -496,11 +855,12 @@ mod tests {
}
#[test]
fn first_param_sets_stripped_redefinition_emitted_inline() {
fn keyframes_self_contained_and_redefinition_emitted() {
let mut parser = H264Parser::new();
// AU 1: SPS(id0,bodyA) + PPS(id0,bodyA) + IDR. Both param sets are the
// first of their type → seed avcC, stripped from frame data.
// AU 1: SPS(id0,bodyA) + PPS(id0,bodyA) + IDR. The param sets seed avcC,
// and because this is a keyframe the active SPS/PPS are re-asserted
// in-band ahead of the IDR (self-contained keyframe). Frame = SPS,PPS,IDR.
let mut au1 = Vec::new();
au1.extend_from_slice(&[0x00, 0x00, 0x01]);
au1.extend_from_slice(&[0x67, 0x42, 0x00, 0x1E, 0xAA]); // SPS body A
@@ -510,16 +870,15 @@ mod tests {
au1.extend_from_slice(&[0x65, 0x10, 0x20]); // IDR
let f1 = parser.parse(&make_pes(au1, Some(0)));
assert_eq!(f1.len(), 1);
// Frame 1 carries only the IDR — param sets stripped (in avcC).
assert_eq!(
frame_nal_types(&f1[0].data),
vec![5],
"AU1: only IDR in-band"
vec![7, 8, 5],
"AU1 keyframe: SPS+PPS re-asserted ahead of IDR"
);
// AU 2: SPS identical to avcC, PPS REDEFINED (same id, different body) +
// IDR. The identical SPS is stripped; the redefined PPS must be emitted
// in-band so it overrides the avcC copy at this keyframe.
// AU 2: SPS identical to avcC (re-asserted unchanged at the keyframe),
// PPS REDEFINED (same id, different body) → emitted in-band as a change.
// Frame = SPS(re-asserted), PPS(redefined), IDR.
let mut au2 = Vec::new();
au2.extend_from_slice(&[0x00, 0x00, 0x01]);
au2.extend_from_slice(&[0x67, 0x42, 0x00, 0x1E, 0xAA]); // SPS == body A
@@ -530,19 +889,32 @@ mod tests {
let f2 = parser.parse(&make_pes(au2, Some(90000)));
assert_eq!(f2.len(), 1);
let types = frame_nal_types(&f2[0].data);
assert!(
types.contains(&8),
"redefined PPS (type 8) must be emitted in-band, got {types:?}"
assert_eq!(types, vec![7, 8, 5], "got {types:?}");
// Confirm the in-band PPS is the REDEFINED body B (0x22), not avcC's A.
let mut o = 0;
let mut pps_body = None;
while o + 4 <= f2[0].data.len() {
let len = u32::from_be_bytes([
f2[0].data[o],
f2[0].data[o + 1],
f2[0].data[o + 2],
f2[0].data[o + 3],
]) as usize;
o += 4;
if f2[0].data[o] & 0x1F == 8 {
pps_body = Some(f2[0].data[o + 1]);
}
o += len;
}
assert_eq!(
pps_body,
Some(0x22),
"in-band PPS must be the redefined body B"
);
assert!(
!types.contains(&7),
"identical SPS (type 7) must stay stripped, got {types:?}"
);
assert!(types.contains(&5), "IDR (type 5) present, got {types:?}");
}
#[test]
fn repeated_identical_param_sets_stay_stripped() {
fn repeated_identical_param_sets_reasserted_each_keyframe() {
let mut parser = H264Parser::new();
let mut au = Vec::new();
au.extend_from_slice(&[0x00, 0x00, 0x01]);
@@ -551,13 +923,16 @@ mod tests {
au.extend_from_slice(&[0x68, 0x11]);
au.extend_from_slice(&[0x00, 0x00, 0x01]);
au.extend_from_slice(&[0x65, 0x10]);
// Two identical AUs.
// Two identical AUs. Each is a keyframe, so each re-asserts the active
// SPS/PPS in-band (self-contained keyframe) even though the bodies are
// unchanged — a decoder that dropped them at a reset recovers at every
// IDR. Frame = SPS, PPS, IDR.
parser.parse(&make_pes(au.clone(), Some(0)));
let f = parser.parse(&make_pes(au, Some(90000)));
assert_eq!(
frame_nal_types(&f[0].data),
vec![5],
"repeated identical SPS/PPS stay in avcC, not duplicated in-band"
vec![7, 8, 5],
"each keyframe re-asserts the active SPS/PPS in-band"
);
}
@@ -592,12 +967,16 @@ mod tests {
fn avcc_exact_length_fields_and_payload() {
// The AVCDecoderConfigurationRecord must encode SPS length and PPS length
// as 16-bit big-endian fields, followed by the verbatim NAL bodies.
// Uses a Main-Profile SPS (profile_idc=0x4D=77) so no High-Profile
// extension bytes are appended — the test validates the fixed-header
// layout only. High-Profile extension is covered by
// avcc_high_profile_appends_extension_bytes.
// SPS = 0x67,profile,compat,level + 2 payload bytes (6 bytes total).
// PPS = 0x68 + 2 payload bytes (3 bytes total).
let mut parser = H264Parser::new();
let mut data = Vec::new();
data.extend_from_slice(&[0x00, 0x00, 0x01]);
data.extend_from_slice(&[0x67, 0x64, 0x00, 0x28, 0xAB, 0xCD]); // SPS, 6 bytes
data.extend_from_slice(&[0x67, 0x4D, 0x00, 0x28, 0xAB, 0xCD]); // SPS, 6 bytes, Main Profile (77)
data.extend_from_slice(&[0x00, 0x00, 0x01]);
data.extend_from_slice(&[0x68, 0xEE, 0x3C]); // PPS, 3 bytes
// A slice so a frame is produced (not required for codec_private though).
@@ -607,7 +986,7 @@ mod tests {
let cp = parser.codec_private().expect("avcC");
// Fixed header.
assert_eq!(cp[0], 1, "configurationVersion");
assert_eq!(cp[1], 0x64, "AVCProfileIndication = SPS[1]");
assert_eq!(cp[1], 0x4D, "AVCProfileIndication = SPS[1]");
assert_eq!(cp[2], 0x00, "profile_compatibility = SPS[2]");
assert_eq!(cp[3], 0x28, "AVCLevelIndication = SPS[3]");
assert_eq!(cp[4], 0xFF, "lengthSizeMinusOne nibble (4-byte prefix)");
@@ -615,14 +994,14 @@ mod tests {
// sequenceParameterSetLength (16-bit BE) = 6.
assert_eq!(u16::from_be_bytes([cp[6], cp[7]]), 6, "SPS length field");
// SPS body follows verbatim.
assert_eq!(&cp[8..14], &[0x67, 0x64, 0x00, 0x28, 0xAB, 0xCD]);
assert_eq!(&cp[8..14], &[0x67, 0x4D, 0x00, 0x28, 0xAB, 0xCD]);
// numPPS = 1.
assert_eq!(cp[14], 1, "numPPS");
// pictureParameterSetLength (16-bit BE) = 3.
assert_eq!(u16::from_be_bytes([cp[15], cp[16]]), 3, "PPS length field");
// PPS body verbatim.
assert_eq!(&cp[17..20], &[0x68, 0xEE, 0x3C]);
// Record length is exactly the sum of its parts — no extra/missing bytes.
// Record length is exactly the sum of its parts — no extension bytes for Main Profile.
assert_eq!(cp.len(), 20);
}
@@ -806,4 +1185,224 @@ mod tests {
"oversized SPS must not produce a truncated avcC"
);
}
// --- High Profile avcC extension (ISO 14496-15 §5.3.3.1.2) ---
/// Build a minimal High-Profile SPS RBSP with the fields needed for the
/// avcC extension. The SPS bytes (NAL-header included) are:
/// [0x67] NAL header (type=7, ref_idc=3)
/// [profile_idc] [constraint_flags] [level_idc]
/// ue(v) seq_parameter_set_id = 0 → 1 bit: 0b1
/// ue(v) chroma_format_idc → depends on value
/// if chroma_format_idc==3: u(1) separate_colour_plane_flag
/// ue(v) bit_depth_luma_minus8
/// ue(v) bit_depth_chroma_minus8
///
/// All ue(v) values <= 6 fit within 3 leading zeros + 3 suffix bits (7 bits
/// total): prefix = leading_zeros + stop-1 bit, suffix = leading_zeros bits.
/// For small values (0..=2), the unary prefix + code is short enough to
/// pack manually with a simple bit-packing helper.
fn build_high_profile_sps(
profile_idc: u8,
chroma_format_idc: u32,
bit_depth_luma_minus8: u32,
bit_depth_chroma_minus8: u32,
) -> Vec<u8> {
// Bit-pack the ue(v) fields into a byte buffer after the fixed header.
// We append bits MSB-first into a growing Vec<u8>.
struct BitWriter {
buf: Vec<u8>,
cur: u8,
bits: u8, // bits accumulated in `cur` (0..8)
}
impl BitWriter {
fn new() -> Self {
Self {
buf: Vec::new(),
cur: 0,
bits: 0,
}
}
fn push_bit(&mut self, bit: u8) {
self.cur = (self.cur << 1) | (bit & 1);
self.bits += 1;
if self.bits == 8 {
self.buf.push(self.cur);
self.cur = 0;
self.bits = 0;
}
}
fn write_ue(&mut self, val: u32) {
// Exp-Golomb encode: find k such that 2^k - 1 <= val, then
// k leading zeros + 1 stop + k-bit suffix.
if val == 0 {
self.push_bit(1);
return;
}
let code = val + 1; // code = val + 1, k = floor(log2(code))
let k = 31 - code.leading_zeros();
for _ in 0..k {
self.push_bit(0);
} // k leading zeros
self.push_bit(1); // stop bit
for i in (0..k).rev() {
self.push_bit(((code >> i) & 1) as u8);
}
}
fn finish(mut self) -> Vec<u8> {
// Flush partial byte (padding with zeros on the right — RBSP
// trailing bits pattern, sufficient for our test payload).
if self.bits > 0 {
self.cur <<= 8 - self.bits;
self.buf.push(self.cur);
}
self.buf
}
}
let mut w = BitWriter::new();
w.write_ue(0); // seq_parameter_set_id = 0
w.write_ue(chroma_format_idc);
if chroma_format_idc == 3 {
w.push_bit(0); // separate_colour_plane_flag = 0
}
w.write_ue(bit_depth_luma_minus8);
w.write_ue(bit_depth_chroma_minus8);
let payload = w.finish();
let mut sps = vec![
0x67, // NAL header (type=7)
profile_idc,
0x00, // constraint flags
0x28, // level_idc = 4.0
];
sps.extend_from_slice(&payload);
sps
}
fn feed_sps_pps(parser: &mut H264Parser, sps_bytes: &[u8]) {
// Feed a PES containing: custom SPS + a minimal PPS + an IDR slice.
let mut data = Vec::new();
data.extend_from_slice(&[0x00, 0x00, 0x01]);
data.extend_from_slice(sps_bytes);
data.extend_from_slice(&[0x00, 0x00, 0x01, 0x68, 0xCE, 0x01]); // PPS
data.extend_from_slice(&[0x00, 0x00, 0x01, 0x65, 0x88]); // IDR
parser.parse(&make_pes(data, Some(0)));
}
/// ISO 14496-15 §5.3.3.1.2 regression: a High-Profile SPS (profile_idc=100)
/// must produce an avcC with the 4 extension bytes (chroma_format_idc,
/// bit_depth_luma_minus8, bit_depth_chroma_minus8, num_sps_ext=0).
#[test]
fn avcc_high_profile_appends_extension_bytes() {
// profile_idc=100 (High), chroma_format_idc=1 (4:2:0), depths both 0.
let sps = build_high_profile_sps(100, 1, 0, 0);
let mut parser = H264Parser::new();
feed_sps_pps(&mut parser, &sps);
let cp = parser.codec_private().expect("avcC must be present");
// Walk to the end of the fixed record to locate the extension bytes.
// Fixed header: 6 bytes. SPS length field: 2 bytes. SPS body. numPPS: 1.
// PPS length: 2. PPS body (0x68, 0xCE, 0x01 = 3 bytes).
// Fixed tail offset = 6 + 2 + sps.len() + 1 + 2 + 3 = sps.len() + 14.
let ext_off = sps.len() + 14;
assert!(
cp.len() == ext_off + 4,
"High-Profile avcC must have exactly 4 extension bytes (len={}, expected {})",
cp.len(),
ext_off + 4
);
// Byte 0: 111111xx — upper 6 bits reserved (0b111111), lower 2 = chroma_format_idc=1.
assert_eq!(
cp[ext_off] & 0xFC,
0xFC,
"extension byte 0: reserved bits must be 111111xx"
);
assert_eq!(cp[ext_off] & 0x03, 1, "chroma_format_idc must be 1 (4:2:0)");
// Byte 1: 11111xxx — upper 5 bits reserved, lower 3 = bit_depth_luma_minus8=0.
assert_eq!(
cp[ext_off + 1] & 0xF8,
0xF8,
"extension byte 1: reserved bits must be 11111xxx"
);
assert_eq!(cp[ext_off + 1] & 0x07, 0, "bit_depth_luma_minus8 must be 0");
// Byte 2: 11111xxx — upper 5 bits reserved, lower 3 = bit_depth_chroma_minus8=0.
assert_eq!(
cp[ext_off + 2] & 0xF8,
0xF8,
"extension byte 2: reserved bits must be 11111xxx"
);
assert_eq!(
cp[ext_off + 2] & 0x07,
0,
"bit_depth_chroma_minus8 must be 0"
);
// Byte 3: num_of_sequence_parameter_set_ext = 0.
assert_eq!(
cp[ext_off + 3],
0,
"num_of_sequence_parameter_set_ext must be 0"
);
}
/// ISO 14496-15 §5.3.3.1.2 regression: a High-Profile SPS with non-zero
/// chroma_format_idc and bit depths carries those values correctly in the
/// extension bytes.
#[test]
fn avcc_high_profile_extension_carries_correct_values() {
// profile_idc=100, chroma_format_idc=3 (4:4:4), depth_luma=2, depth_chroma=2.
let sps = build_high_profile_sps(100, 3, 2, 2);
let mut parser = H264Parser::new();
feed_sps_pps(&mut parser, &sps);
let cp = parser.codec_private().expect("avcC");
let ext_off = sps.len() + 14;
assert_eq!(cp[ext_off] & 0x03, 3, "chroma_format_idc must be 3 (4:4:4)");
assert_eq!(cp[ext_off + 1] & 0x07, 2, "bit_depth_luma_minus8 must be 2");
assert_eq!(
cp[ext_off + 2] & 0x07,
2,
"bit_depth_chroma_minus8 must be 2"
);
assert_eq!(
cp[ext_off + 3],
0,
"num_of_sequence_parameter_set_ext must be 0"
);
}
/// ISO 14496-15 §5.3.3.1.2 regression: a Main-Profile SPS (profile_idc=77)
/// must NOT have the extension bytes — strict parsers reject trailing bytes
/// for Baseline/Main/Extended profiles.
#[test]
fn avcc_main_profile_no_extension_bytes() {
// profile_idc=77 (Main). No High-Profile branch in the SPS RBSP,
// so we build a simpler SPS: NAL header + profile/compat/level + a
// ue(v) seq_parameter_set_id=0 + remaining RBSP (can be trivial).
let sps = vec![
0x67, // NAL header (type=7)
77, // profile_idc = Main
0x40, // constraint flags
0x28, // level_idc
// seq_parameter_set_id=0 → ue(v) = 0b1 (1 bit). Pack into a byte:
// bit pattern: 1000_0000 (stop bit in MSB, rest don't-care)
0x80,
];
let mut parser = H264Parser::new();
feed_sps_pps(&mut parser, &sps);
let cp = parser.codec_private().expect("avcC must be present");
// Fixed record: 6 + 2 + sps.len() + 1 + 2 + 3 = sps.len() + 14.
let expected_len = sps.len() + 14;
assert_eq!(
cp.len(),
expected_len,
"Main-Profile avcC must NOT have extension bytes (len={}, expected {})",
cp.len(),
expected_len
);
}
}
src/mux/codec/hevc.rs
+644 -79
View File
@@ -19,6 +19,13 @@ const _NAL_UNSPEC62_DV_RPU: u8 = 62;
// IRAP types (keyframes): BLA, IDR, CRA
const NAL_BLA_W_LP: u8 = 16;
const NAL_RSV_IRAP_VCL23: u8 = 23;
// CRA_NUT (Clean Random Access). A CRA at a splice carries RASL leading
// pictures that reference frames from BEFORE the splice; on linear decode of a
// concatenated title those references are gone ("Could not find ref with POC
// N"). The HEVC spec remedy is to rewrite the splice CRA as a BLA (Broken Link
// Access): a decoder then sets NoRaslOutput and discards the RASL cleanly with
// no error. See `mark_clip_boundary` / the IRAP arm in `parse`.
const NAL_CRA_NUT: u8 = 21;
/// HEVC (H.265) Annex B → MKV codec parser: extracts VPS/SPS/PPS for the hvcC
/// codecPrivate, detects IRAP keyframes, and converts each PES access unit into
@@ -36,6 +43,39 @@ pub struct HevcParser {
vps: Option<Vec<u8>>,
sps: Option<Vec<u8>>,
pps: Option<Vec<u8>>,
// The currently-ACTIVE parameter-set body of each type — the most recent
// one the bitstream defined, which the decoder must use until the next
// redefinition. Distinct from the `vps/sps/pps` codecPrivate copy above
// (which is fixed to the FIRST one seen). When a stream redefines a param
// set mid-title (e.g. PPS id 0 body changes partway through, then the
// source STOPS repeating it at later IRAPs and relies on the decoder
// retaining it), a raw decode is fine — but an hvcC/MKV decode is NOT: a
// player re-applies the codecPrivate set at EVERY keyframe (ffmpeg's
// hvcC→Annex-B insertion), reverting id 0 to the stale FIRST body. We must
// therefore re-emit the active set IN-BAND at every keyframe whenever it
// differs from the codecPrivate copy and the access unit didn't already
// carry it. See `parse`.
cur_vps: Option<Vec<u8>>,
cur_sps: Option<Vec<u8>>,
cur_pps: Option<Vec<u8>>,
// Splice-aware CRA→BLA rewrite (non-seamless BD clip boundaries).
//
// When a BD title concatenates clips at a NON-SEAMLESS join (MPLS
// connection_condition 0x01), the next clip opens with a CRA whose RASL
// leading pictures reference frames from before the splice — gone after
// concatenation. The caller (the code that crosses the join) sets this flag
// via `mark_clip_boundary`; the parser then rewrites the FIRST CRA it sees
// at/after that point from CRA_NUT (21) to BLA_W_LP (16) so a linear decoder
// sets NoRaslOutput and discards the dangling RASL with no error. The flag
// is consumed (cleared) by that first CRA so only ONE CRA per boundary is
// touched — never a mid-stream CRA, never an IDR, never a non-CRA NAL.
//
// SAFETY: defaults to `false` and is ONLY ever set through
// `mark_clip_boundary`, which the caller invokes ONLY for a non-seamless
// (0x01) join. A stream with no boundary marker (single-clip title, any
// seamless-joined UHD/BD) never has this set, so the rewrite branch is never
// reached and output is byte-identical to a parser without this field.
pending_clip_boundary: bool,
}
impl Default for HevcParser {
@@ -51,40 +91,115 @@ impl HevcParser {
vps: None,
sps: None,
pps: None,
cur_vps: None,
cur_sps: None,
cur_pps: None,
pending_clip_boundary: false,
}
}
/// Mark that the NEXT IRAP this parser sees begins a NON-SEAMLESS BD clip
/// (MPLS connection_condition 0x01). The first CRA at/after this point is
/// rewritten CRA_NUT (21) → BLA_W_LP (16) so a linear decoder sets
/// NoRaslOutput and discards the now-dangling RASL leading pictures with no
/// "could not find ref" error.
///
/// MUST be called ONLY when MPLS reports the join as non-seamless. It is a
/// no-op for the rewrite unless a CRA actually follows: an IDR/IDR_W_RADL
/// boundary needs no fix (it carries no cross-splice references), and the
/// flag is cleared by the first IRAP-class CRA it reaches.
///
/// SAFETY: never call this for a seamless join (0x05/0x06) or within a
/// single-clip title — doing so could convert a legitimate mid-content CRA
/// to BLA. The default (never called) path leaves output byte-identical.
pub fn mark_clip_boundary(&mut self) {
self.pending_clip_boundary = true;
}
}
/// Handle a VPS/SPS/PPS NAL.
/// Handle a VPS/SPS/PPS NAL. Decides whether to strip it (the decoder already
/// has the value) or emit it in-band, and tracks the currently-active body.
///
/// - First of its type → seeds codecPrivate (`first`); stripped from frame data
/// (the player gets it from hvcC).
/// - Identical to the codecPrivate copy → stripped (the player already re-applies
/// it from hvcC at each keyframe; BD streams repeat param sets at every IRAP).
/// - DIFFERENT body from the codecPrivate copy (a mid-title redefinition of the
/// same id) → emitted IN-BAND (length-prefixed) at EVERY occurrence, so it
/// overrides the hvcC copy the player re-applies at each keyframe. Emitting it
/// only once is not enough — the next keyframe's hvcC re-insertion would revert
/// it. This matches what a conforming muxer produces and fixes mid-title
/// PPS-id-0 redefinition.
fn handle_param_set(first: &mut Option<Vec<u8>>, nal: &[u8], frame_data: &mut Vec<u8>) {
match first {
None => {
first.replace(nal.to_vec()); // seeds codecPrivate; stripped here
}
Some(f) if f.as_slice() == nal => {} // == codecPrivate → player has it
Some(_) => {
// Differs from codecPrivate → emit in-band so it wins at this AU.
// A NAL longer than u32::MAX can't be length-prefixed in the 4-byte
// field; skip it rather than mis-frame the output. Unreachable in
// practice (no real access unit is >4 GiB).
let Ok(len) = u32::try_from(nal.len()) else {
return;
};
frame_data.extend_from_slice(&len.to_be_bytes());
frame_data.extend_from_slice(nal);
}
/// The decision MUST be made against the currently-active set (`cur`), NOT the
/// codecPrivate copy (`first`). The two player behaviours for hvcC-in-MKV
/// diverge exactly here:
///
/// - A *seek-capable / Annex-B* player (e.g. ffmpeg's `hevc_mp4toannexb`)
/// re-applies the hvcC sets at every keyframe. `reassert_active` handles it.
/// - A *streaming* decode (ffmpeg decoding the MKV directly — what most
/// integrity checkers do) applies hvcC ONCE at init and thereafter updates a
/// parameter set ONLY from an in-band NAL.
///
/// So when a title redefines a set mid-stream (id 0 body A → B) and later
/// switches BACK to A (== codecPrivate), the change to A must STILL be emitted
/// in-band: the streaming decoder is sitting on B and will never revert
/// otherwise, decoding the whole A-segment against B → CABAC/cu_qp_delta
/// desync. Stripping on `== first` (the old behaviour) dropped exactly that
/// revert and corrupted every "switch back to the first body" segment.
///
/// Rules:
/// - First of its type → seeds codecPrivate; stripped (the decoder gets it from
/// hvcC at init).
/// - Equal to the active set `cur` → redundant; stripped.
/// - Different from `cur` (a change, in EITHER direction) → emitted in-band and
/// `cur` updated.
///
/// Returns `true` when the NAL was emitted in-band into `frame_data`.
fn handle_param_set(
first: &mut Option<Vec<u8>>,
cur: &mut Option<Vec<u8>>,
nal: &[u8],
frame_data: &mut Vec<u8>,
) -> bool {
let is_first = first.is_none();
if is_first {
first.replace(nal.to_vec()); // seeds codecPrivate; stripped here
}
let changed = cur.as_deref() != Some(nal);
if changed {
*cur = Some(nal.to_vec());
}
// Strip the seeding occurrence (decoder gets it from hvcC) and any NAL that
// doesn't change the active set. Emit only a genuine change.
if is_first || !changed {
return false;
}
// A NAL longer than u32::MAX can't be length-prefixed in the 4-byte field;
// skip it rather than mis-frame the output. Unreachable in practice (no
// real access unit is >4 GiB).
let Ok(len) = u32::try_from(nal.len()) else {
return false;
};
frame_data.extend_from_slice(&len.to_be_bytes());
frame_data.extend_from_slice(nal);
true
}
/// Append the active parameter set `cur` to `prefix` (length-prefixed) so every
/// keyframe is SELF-CONTAINED: it carries the active VPS/SPS/PPS in-band ahead
/// of its slices. Skipped only when this access unit ALREADY carried the NAL
/// in-band (`emitted` — avoids a duplicate) or no active set exists yet.
///
/// Why unconditional (not only when the active set differs from codecPrivate):
/// a streaming decoder applies the hvcC param sets once at init, then relies on
/// in-band repetition. Some sources stop repeating a param set at later IRAPs
/// even though its body is unchanged; if the decoder then drops it (a CRA reset
/// or SPS event), nothing re-sends it and every subsequent slice fails with
/// "PPS id out of range" until the next genuine change (observed as a ~24 min
/// corrupt band on one dual-layer UHD title). Re-asserting the active set at
/// EVERY keyframe — what compliant muxers (mkvmerge) do at every IRAP — makes
/// streaming decode self-healing. Re-sending an identical param set is benign
/// (decoders expect it at IRAPs); cost is a few hundred bytes per keyframe.
/// This strictly supersets the earlier change-only re-assert, so the
/// param-set-revert fix is unaffected.
fn reassert_active(prefix: &mut Vec<u8>, cur: &Option<Vec<u8>>, emitted: bool) {
if emitted {
return;
}
let Some(active) = cur.as_deref() else {
return;
};
push_length_prefixed(prefix, active);
}
/// Append `nal` to `out` as a 4-byte big-endian length prefix followed by the
@@ -114,6 +229,12 @@ impl CodecParser for HevcParser {
let pts_ns = pes.pts.or(pes.dts).map(pts_to_ns).unwrap_or(0);
let data = &pes.data;
let mut keyframe = false;
// Track whether THIS access unit already carried each param-set type
// in-band (a redefinition vs codecPrivate). Used after the scan to
// re-assert the active set at a keyframe the source left bare.
let mut emitted_vps = false;
let mut emitted_sps = false;
let mut emitted_pps = false;
// Pre-size: output is ~input bytes with a few 4-byte length
// prefixes added. UHD frames are 150-300 KB; the unsized Vec
// growth chain otherwise reallocs 5-7× per frame.
@@ -145,13 +266,28 @@ impl CodecParser for HevcParser {
match nal_type {
NAL_VPS => {
handle_param_set(&mut self.vps, &data[nal_start..end], &mut frame_data)
emitted_vps |= handle_param_set(
&mut self.vps,
&mut self.cur_vps,
&data[nal_start..end],
&mut frame_data,
)
}
NAL_SPS => {
handle_param_set(&mut self.sps, &data[nal_start..end], &mut frame_data)
emitted_sps |= handle_param_set(
&mut self.sps,
&mut self.cur_sps,
&data[nal_start..end],
&mut frame_data,
)
}
NAL_PPS => {
handle_param_set(&mut self.pps, &data[nal_start..end], &mut frame_data)
emitted_pps |= handle_param_set(
&mut self.pps,
&mut self.cur_pps,
&data[nal_start..end],
&mut frame_data,
)
}
// Drop Access Unit Delimiters. This is intentional and
// spec-correct: Matroska HEVC frame data omits AUDs
@@ -160,7 +296,32 @@ impl CodecParser for HevcParser {
NAL_AUD => {}
t if (NAL_BLA_W_LP..=NAL_RSV_IRAP_VCL23).contains(&t) => {
keyframe = true;
push_length_prefixed(&mut frame_data, &data[nal_start..end]);
// Splice-aware CRA→BLA rewrite. At the FIRST CRA
// following a non-seamless clip boundary (flag set
// via `mark_clip_boundary`), rewrite CRA_NUT (21) →
// BLA_W_LP (16) so a linear decoder sets NoRaslOutput
// and drops the dangling RASL with no error. The flag
// is consumed here so exactly ONE CRA per boundary is
// touched. A non-CRA IRAP (IDR, BLA) clears the flag
// too (the boundary is handled — IDR carries no
// cross-splice refs) but is NOT modified. Default
// path (flag never set) is unreachable → byte-
// identical output.
if self.pending_clip_boundary && t == NAL_CRA_NUT {
// First CRA after a non-seamless boundary: rewrite
// its header type to BLA_W_LP. NAL type is bits 1-6
// of byte 0: byte = (byte & 0x81) | (type << 1).
self.pending_clip_boundary = false;
let mut rewritten = data[nal_start..end].to_vec();
rewritten[0] = (rewritten[0] & 0x81) | (NAL_BLA_W_LP << 1);
push_length_prefixed(&mut frame_data, &rewritten);
} else {
// Any IRAP clears a pending boundary (it's been
// reached and handled — an IDR needs no rewrite),
// but only a CRA is modified.
self.pending_clip_boundary = false;
push_length_prefixed(&mut frame_data, &data[nal_start..end]);
}
}
_ => {
// All other NAL types (slices, SEI, DV RPU, etc.) pass through
@@ -178,6 +339,27 @@ impl CodecParser for HevcParser {
return Vec::new();
}
// A player re-applies the hvcC (codecPrivate) parameter sets at every
// keyframe. If the active set was redefined mid-title and the source
// stopped repeating that redefinition at later IRAPs (relying on the
// decoder to retain it — valid for a raw bitstream), the hvcC
// re-insertion would silently revert to the stale FIRST body and every
// frame in the segment decodes against the wrong parameter set
// (CABAC/cu_qp_delta desync). Re-assert the active set in-band, ahead
// of this AU's slices, so it wins. Re-asserted at EVERY keyframe (even
// when active == codecPrivate) so each keyframe is self-contained and a
// decoder that dropped the set (CRA reset / SPS event) self-heals.
if keyframe {
let mut prefix = Vec::new();
reassert_active(&mut prefix, &self.cur_vps, emitted_vps);
reassert_active(&mut prefix, &self.cur_sps, emitted_sps);
reassert_active(&mut prefix, &self.cur_pps, emitted_pps);
if !prefix.is_empty() {
prefix.extend_from_slice(&frame_data);
frame_data = prefix;
}
}
vec![Frame {
pts_ns,
keyframe,
@@ -208,38 +390,35 @@ impl CodecParser for HevcParser {
// Minimal HEVCDecoderConfigurationRecord header.
//
// The stored SPS NAL is [2-byte HEVC NAL header][SPS RBSP...].
// The RBSP begins at sps[2]; profile_tier_level() begins one byte
// later, after sps_video_parameter_set_id u(4) +
// sps_max_sub_layers_minus1 u(3) + sps_temporal_id_nesting_flag u(1)
// (= sps[2], a full byte). So the profile_tier_level fields are:
// sps[3] general_profile_space u(2)+tier u(1)+profile_idc u(5)
// sps[4..8] general_profile_compatibility_flags u(32)
// sps[8..14] general_constraint_indicator_flags 48 bits
// sps[14] general_level_idc u(8)
// (Byte-aligned read; emulation-prevention bytes within the first
// 15 SPS bytes are not handled — extremely rare and matches the
// pre-existing simplification.)
// profile_tier_level fields must be read off the
// emulation-prevention-STRIPPED RBSP — a `00 00 03` sequence in the
// first ~15 SPS bytes would otherwise shift every raw byte index and
// corrupt the PTL (profile/compat/constraint/level). We strip first
// (same as parse_sps_chroma) and index into the cleaned RBSP:
// rbsp[0] sps_vps_id u(4)+max_sub_layers u(3)+temporal_nesting u(1)
// rbsp[1] general_profile_space u(2)+tier u(1)+profile_idc u(5)
// rbsp[2..6] general_profile_compatibility_flags u(32)
// rbsp[6..12] general_constraint_indicator_flags 48 bits
// rbsp[12] general_level_idc u(8)
let ptl: Vec<u8> = if sps.len() > 2 {
strip_emulation_prevention(&sps[2..])
} else {
Vec::new()
};
let ptl_at = |i: usize| -> u8 { ptl.get(i).copied().unwrap_or(0) };
record.push(1); // configurationVersion
// general_profile_space + general_tier_flag + general_profile_idc
record.push(if sps.len() > 3 { sps[3] } else { 0 });
// general_profile_compatibility_flags (4 bytes) — SPS bytes 4..8
if sps.len() > 7 {
record.extend_from_slice(&sps[4..8]);
} else {
let target = record.len() + 4;
record.extend_from_slice(&sps[sps.len().min(4)..sps.len().min(8)]);
record.resize(target, 0u8); // zero-pad the missing bytes in place
record.push(ptl_at(1));
// general_profile_compatibility_flags (4 bytes) — RBSP bytes 2..6
for i in 2..6 {
record.push(ptl_at(i));
}
// general_constraint_indicator_flags (6 bytes) — SPS bytes 8..14
if sps.len() > 13 {
record.extend_from_slice(&sps[8..14]);
} else {
let target = record.len() + 6;
record.extend_from_slice(&sps[sps.len().min(8)..sps.len().min(14)]);
record.resize(target, 0u8); // zero-pad the missing bytes in place
// general_constraint_indicator_flags (6 bytes) — RBSP bytes 6..12
for i in 6..12 {
record.push(ptl_at(i));
}
// general_level_idc — SPS byte 14
record.push(if sps.len() > 14 { sps[14] } else { 0 });
// general_level_idc — RBSP byte 12
record.push(ptl_at(12));
// min_spatial_segmentation_idc (4 + 12 bits)
record.extend_from_slice(&[0xF0, 0x00]);
// parallelismType (6 + 2 bits)
@@ -553,6 +732,171 @@ mod tests {
);
}
/// Regression (Fight Club UHD banded corruption): a stream redefines PPS
/// id 0 mid-title, then a later keyframe arrives WITHOUT repeating it (the
/// source relies on the decoder retaining the redefinition — valid for a
/// raw bitstream). An hvcC player re-applies the FIRST (codecPrivate) PPS
/// at every keyframe, so the active redefinition must be re-asserted
/// in-band at that bare keyframe or the whole segment decodes against the
/// wrong parameter set.
#[test]
fn reasserts_active_pps_at_bare_keyframe() {
fn nal(t: u8, body: &[u8]) -> Vec<u8> {
let mut v = vec![0x00, 0x00, 0x01];
v.extend_from_slice(&hevc_nal_header(t));
v.extend_from_slice(body);
v
}
// Split length-prefixed frame_data back into NAL bodies.
fn nals_in(frame: &[u8]) -> Vec<Vec<u8>> {
let mut out = Vec::new();
let mut i = 0;
while i + 4 <= frame.len() {
let len = u32::from_be_bytes([frame[i], frame[i + 1], frame[i + 2], frame[i + 3]])
as usize;
i += 4;
if i + len > frame.len() {
break;
}
out.push(frame[i..i + len].to_vec());
i += len;
}
out
}
let pps_of = |nals: &[Vec<u8>]| -> Vec<Vec<u8>> {
nals.iter()
.filter(|n| n.len() >= 2 && (n[0] >> 1) & 0x3F == 34)
.map(|n| n[2..].to_vec())
.collect()
};
let sps_body = [
0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D,
];
let pps_a = [0xA1u8, 0xA2];
let pps_b = [0xB1u8, 0xB2, 0xB3];
let mut parser = HevcParser::new();
// AU1: seeds codecPrivate with VPS/SPS/PPS-A (all stripped in-band).
let au1 = [
nal(32, &[0xAA]),
nal(33, &sps_body),
nal(34, &pps_a),
nal(19, &[0x10]),
]
.concat();
parser.parse(&make_pes(au1, Some(0)));
// AU2: keyframe redefines PPS id 0 to body B → emitted in-band.
let au2 = [nal(34, &pps_b), nal(19, &[0x11])].concat();
let f2 = parser.parse(&make_pes(au2, Some(3600)));
assert!(
pps_of(&nals_in(&f2[0].data)).iter().any(|b| b == &pps_b),
"AU2 must carry the redefined PPS-B in-band"
);
// AU3: BARE keyframe, source omits the PPS. The active set (B) must be
// re-asserted, and the stale codecPrivate A must NOT be injected.
let au3 = nal(19, &[0x12]);
let f3 = parser.parse(&make_pes(au3, Some(7200)));
let got = pps_of(&nals_in(&f3[0].data));
assert!(
got.iter().any(|b| b == &pps_b),
"bare keyframe must re-assert the active PPS-B in-band, got {got:?}"
);
assert!(
!got.iter().any(|b| b == &pps_a),
"must not re-assert the stale codecPrivate PPS-A"
);
// AU4: switch the active set BACK to A (== codecPrivate) via an in-band
// redefinition (a real change from B → emitted).
let au4 = [nal(34, &pps_a), nal(19, &[0x13])].concat();
parser.parse(&make_pes(au4, Some(10800)));
// AU5: BARE keyframe, source omits the PPS, and the active set now
// EQUALS codecPrivate. It must STILL be re-asserted in-band — every
// keyframe is self-contained: a decoder that dropped PPS id 0 at a CRA
// reset can only recover from an in-band copy, and there is no genuine
// change here to trigger the emit path.
let au5 = nal(19, &[0x14]);
let f5 = parser.parse(&make_pes(au5, Some(14400)));
assert!(
pps_of(&nals_in(&f5[0].data)).iter().any(|b| b == &pps_a),
"bare keyframe must re-assert the active PPS even when == codecPrivate"
);
}
/// Regression (Fight Club UHD, the real bug): id 0 is body A (→ hvcC), then
/// redefined to B, then the title switches BACK to A. A streaming decoder
/// (hvcC at init, in-band updates only) is sitting on B; the switch back to
/// A must be emitted IN-BAND even though A == codecPrivate, or the whole
/// A-segment decodes against B (cu_qp_delta desync). Stripping on `== hvcC`
/// dropped this revert.
#[test]
fn emits_switch_back_to_codecprivate_pps() {
fn nal(t: u8, body: &[u8]) -> Vec<u8> {
let mut v = vec![0x00, 0x00, 0x01];
v.extend_from_slice(&hevc_nal_header(t));
v.extend_from_slice(body);
v
}
fn nals_in(frame: &[u8]) -> Vec<Vec<u8>> {
let mut out = Vec::new();
let mut i = 0;
while i + 4 <= frame.len() {
let len = u32::from_be_bytes([frame[i], frame[i + 1], frame[i + 2], frame[i + 3]])
as usize;
i += 4;
if i + len > frame.len() {
break;
}
out.push(frame[i..i + len].to_vec());
i += len;
}
out
}
let pps_body = |nals: &[Vec<u8>]| -> Vec<Vec<u8>> {
nals.iter()
.filter(|n| n.len() >= 2 && (n[0] >> 1) & 0x3F == 34)
.map(|n| n[2..].to_vec())
.collect()
};
let sps = [
0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D,
];
let a = [0xA1u8, 0xA2];
let b = [0xB1u8, 0xB2, 0xB3];
let mut parser = HevcParser::new();
// AU1: seeds codecPrivate with PPS-A.
parser.parse(&make_pes(
[nal(32, &[0xAA]), nal(33, &sps), nal(34, &a), nal(19, &[1])].concat(),
Some(0),
));
// AU2 keyframe: redefine to B → emitted in-band.
parser.parse(&make_pes([nal(34, &b), nal(19, &[2])].concat(), Some(3600)));
// AU3 keyframe: source sends A again (== codecPrivate). Must be emitted
// in-band because the active set was B.
let f3 = parser.parse(&make_pes([nal(34, &a), nal(19, &[3])].concat(), Some(7200)));
assert!(
pps_body(&nals_in(&f3[0].data)).iter().any(|p| p == &a),
"switch back to codecPrivate PPS-A must be emitted in-band"
);
// AU4 keyframe: A again, now == active AND == codecPrivate. Under the
// self-contained-keyframe rule it is STILL re-asserted in-band so a
// decoder that dropped PPS id 0 at this IRAP recovers. handle_param_set
// strips the source copy (== active), then reassert_active prepends the
// active set unconditionally.
let f4 = parser.parse(&make_pes(
[nal(34, &a), nal(19, &[4])].concat(),
Some(10800),
));
assert!(
pps_body(&nals_in(&f4[0].data)).iter().any(|p| p == &a),
"active PPS must be re-asserted at every keyframe (self-contained), even when == codecPrivate"
);
}
#[test]
fn hvcc_profile_tier_level_offsets() {
// The hvcC fixed header must read profile_tier_level from the SPS
@@ -751,6 +1095,204 @@ mod tests {
assert!(frames[0].keyframe, "type 23 should be keyframe");
}
// --- splice-aware CRA→BLA rewrite (non-seamless clip boundary) ---
/// Split length-prefixed frame_data into NAL bodies (4-byte BE length + NAL).
fn nals_of(frame: &[u8]) -> Vec<Vec<u8>> {
let mut out = Vec::new();
let mut i = 0;
while i + 4 <= frame.len() {
let len =
u32::from_be_bytes([frame[i], frame[i + 1], frame[i + 2], frame[i + 3]]) as usize;
i += 4;
if i + len > frame.len() {
break;
}
out.push(frame[i..i + len].to_vec());
i += len;
}
out
}
fn nal_type_of(nal: &[u8]) -> u8 {
(nal[0] >> 1) & 0x3F
}
/// Build a standalone CRA (type 21) access unit.
fn cra_au(payload: &[u8]) -> Vec<u8> {
let mut d = vec![0x00, 0x00, 0x01];
d.extend_from_slice(&hevc_nal_header(21));
d.extend_from_slice(payload);
d
}
/// Test 1: a CRA at a MARKED non-seamless boundary is rewritten to BLA_W_LP.
#[test]
fn cra_at_marked_boundary_rewritten_to_bla() {
let mut parser = HevcParser::new();
parser.mark_clip_boundary();
let frames = parser.parse(&make_pes(cra_au(&[0x10, 0x20, 0x30]), Some(0)));
assert_eq!(frames.len(), 1);
assert!(frames[0].keyframe, "rewritten BLA is still a keyframe");
let nals = nals_of(&frames[0].data);
assert_eq!(nals.len(), 1);
assert_eq!(
nal_type_of(&nals[0]),
NAL_BLA_W_LP,
"marked-boundary CRA must be rewritten to BLA_W_LP (16)"
);
// The forbidden_zero_bit + layer-id-high (bit 0) and the rest of byte 0,
// and all payload bytes, are otherwise untouched.
assert_eq!(nals[0][0] & 0x81, hevc_nal_header(21)[0] & 0x81);
assert_eq!(&nals[0][2..], &[0x10, 0x20, 0x30]);
// The flag is one-shot: a SECOND CRA (no new marker) is left as CRA.
let f2 = parser.parse(&make_pes(cra_au(&[0x40]), Some(90000)));
assert_eq!(
nal_type_of(&nals_of(&f2[0].data)[0]),
NAL_CRA_NUT,
"only the first CRA after a boundary is rewritten"
);
}
/// Test 2: a CRA with NO boundary marker is left unchanged (CRA stays CRA).
#[test]
fn cra_without_boundary_unchanged() {
let mut parser = HevcParser::new();
let frames = parser.parse(&make_pes(cra_au(&[0x10, 0x20]), Some(0)));
let nals = nals_of(&frames[0].data);
assert_eq!(
nal_type_of(&nals[0]),
NAL_CRA_NUT,
"an unmarked CRA must remain a CRA"
);
}
/// Test 3: non-CRA NALs are never rewritten even when a boundary IS marked.
/// IDR (19), RASL (8/9), VPS/SPS/PPS, and a trailing slice all pass through
/// unmodified; the IDR clears the pending boundary so no later CRA is wrongly
/// converted.
#[test]
fn non_cra_nals_never_rewritten_at_boundary() {
// IDR boundary: marker set, but the first IRAP is an IDR → no rewrite,
// and the marker is consumed so a later CRA is untouched.
let mut parser = HevcParser::new();
parser.mark_clip_boundary();
let mut idr = vec![0x00, 0x00, 0x01];
idr.extend_from_slice(&hevc_nal_header(19)); // IDR_W_RADL
idr.extend_from_slice(&[0x10]);
let f = parser.parse(&make_pes(idr, Some(0)));
assert_eq!(
nal_type_of(&nals_of(&f[0].data)[0]),
19,
"IDR at a marked boundary must stay IDR"
);
// Marker was consumed by the IDR: a following CRA is NOT rewritten.
let f2 = parser.parse(&make_pes(cra_au(&[0x20]), Some(90000)));
assert_eq!(
nal_type_of(&nals_of(&f2[0].data)[0]),
NAL_CRA_NUT,
"the IDR consumed the boundary marker; later CRA stays CRA"
);
// RASL leading pictures (types 8/9) preceding the splice CRA must not be
// touched and must not consume the marker — only the CRA itself does.
let mut parser = HevcParser::new();
parser.mark_clip_boundary();
let mut au = vec![0x00, 0x00, 0x01];
au.extend_from_slice(&hevc_nal_header(8)); // RASL_N
au.extend_from_slice(&[0xAA]);
au.extend_from_slice(&[0x00, 0x00, 0x01]);
au.extend_from_slice(&hevc_nal_header(9)); // RASL_R
au.extend_from_slice(&[0xBB]);
au.extend_from_slice(&cra_au(&[0xCC])); // CRA after the RASLs
let f = parser.parse(&make_pes(au, Some(0)));
let nals = nals_of(&f[0].data);
let types: Vec<u8> = nals.iter().map(|n| nal_type_of(n)).collect();
assert_eq!(
types,
vec![8, 9, NAL_BLA_W_LP],
"RASLs pass through untouched; the CRA (after them) becomes BLA"
);
}
/// Test 4: a frame stream with NO boundary marker is BYTE-IDENTICAL to a
/// parser that has no splice-rewrite field at all (the UHD-safety guarantee).
/// We assert byte-equality of every emitted frame across a multi-AU stream
/// containing CRAs, IDRs, RASLs, VPS/SPS/PPS, and trailing slices — none of
/// which is ever marked.
#[test]
fn no_boundary_marker_is_byte_identical() {
let build = || {
let mut d = Vec::new();
// AU0: VPS/SPS/PPS + CRA keyframe.
d.extend_from_slice(&[0x00, 0x00, 0x01]);
d.extend_from_slice(&hevc_nal_header(32));
d.extend_from_slice(&[0xAA]);
d.extend_from_slice(&[0x00, 0x00, 0x01]);
d.extend_from_slice(&hevc_nal_header(33));
d.extend_from_slice(&[0xBB, 0xCC, 0xDD]);
d.extend_from_slice(&[0x00, 0x00, 0x01]);
d.extend_from_slice(&hevc_nal_header(34));
d.extend_from_slice(&[0xEE]);
d.extend_from_slice(&cra_au(&[0x11, 0x22]));
d
};
// Reference parser: the rewrite field exists but is NEVER marked, so its
// output is exactly the pre-feature behaviour. We compare a never-marked
// run against a second never-marked run AND against the documented
// invariant that the CRA is emitted as-is (type 21, payload intact).
let mut a = HevcParser::new();
let mut b = HevcParser::new();
let fa = a.parse(&make_pes(build(), Some(0)));
let fb = b.parse(&make_pes(build(), Some(0)));
assert_eq!(fa.len(), 1);
assert_eq!(fa[0].data, fb[0].data, "never-marked output must be stable");
// And the CRA was NOT converted (type 21 still present, no BLA).
let types: Vec<u8> = nals_of(&fa[0].data)
.iter()
.map(|n| nal_type_of(n))
.collect();
assert!(
types.contains(&NAL_CRA_NUT) && !types.contains(&NAL_BLA_W_LP),
"unmarked stream must keep its CRA (no BLA), got {types:?}"
);
// Feed a second AU (a CRA) to the same unmarked parser: still a CRA.
// Param sets are re-asserted ahead of the keyframe, so locate the CRA
// among the emitted NALs rather than assuming it is first.
let f2 = a.parse(&make_pes(cra_au(&[0x33]), Some(90000)));
let t2: Vec<u8> = nals_of(&f2[0].data)
.iter()
.map(|n| nal_type_of(n))
.collect();
assert!(
t2.contains(&NAL_CRA_NUT) && !t2.contains(&NAL_BLA_W_LP),
"unmarked mid-stream CRA must never become BLA, got {t2:?}"
);
}
/// Test 5: a SEAMLESS boundary (connection_condition 0x05/0x06) is expressed
/// by NOT calling `mark_clip_boundary`, so a CRA across a seamless join is
/// left unchanged. This encodes the contract: only non-seamless joins call
/// `mark_clip_boundary`; seamless ones never do, so no rewrite occurs.
#[test]
fn seamless_boundary_no_rewrite() {
// Simulate two clips joined seamlessly: the caller does NOT mark, so the
// second clip's opening CRA stays a CRA.
let mut parser = HevcParser::new();
// Clip 1 ends with a CRA (no marker — mid-content).
let f1 = parser.parse(&make_pes(cra_au(&[0x01]), Some(0)));
assert_eq!(nal_type_of(&nals_of(&f1[0].data)[0]), NAL_CRA_NUT);
// Seamless join: caller deliberately does NOT call mark_clip_boundary().
// Clip 2 opens with a CRA → must remain a CRA.
let f2 = parser.parse(&make_pes(cra_au(&[0x02]), Some(90000)));
assert_eq!(
nal_type_of(&nals_of(&f2[0].data)[0]),
NAL_CRA_NUT,
"a seamless join (no marker) must never rewrite the CRA"
);
}
// --- non-IRAP (trailing) → not keyframe ---
#[test]
@@ -792,7 +1334,7 @@ mod tests {
// --- VPS/SPS/PPS stripped from frame data ---
#[test]
fn param_sets_stripped_from_frame() {
fn param_sets_seed_codecprivate_and_reassert_at_keyframe() {
let mut parser = HevcParser::new();
let mut data = Vec::new();
@@ -818,14 +1360,28 @@ mod tests {
let frames = parser.parse(&pes);
assert_eq!(frames.len(), 1);
// Frame data should only have the IDR NAL (length-prefixed)
// The param sets seed codecPrivate (hvcC).
assert!(
parser.codec_private().is_some(),
"VPS/SPS/PPS must seed codecPrivate"
);
// Because this is a keyframe, the active VPS/SPS/PPS are ALSO re-asserted
// in-band ahead of the IDR so the keyframe is self-contained. Frame data
// = VPS, SPS, PPS, IDR (4 length-prefixed NALs, in that order).
let fd = &frames[0].data;
let length = u32::from_be_bytes([fd[0], fd[1], fd[2], fd[3]]);
// IDR NAL = 2 bytes header + 2 bytes payload = 4 bytes
let mut types = Vec::new();
let mut o = 0;
while o + 4 <= fd.len() {
let len = u32::from_be_bytes([fd[o], fd[o + 1], fd[o + 2], fd[o + 3]]) as usize;
o += 4;
types.push((fd[o] >> 1) & 0x3F);
o += len;
}
assert_eq!(
length as usize + 4,
fd.len(),
"frame should contain exactly one length-prefixed NAL"
types,
vec![32, 33, 34, 19],
"keyframe must re-assert VPS/SPS/PPS in-band ahead of the IDR slice"
);
}
@@ -876,27 +1432,32 @@ mod tests {
let f = parser.parse(&make_pes(d, Some(1)));
assert_eq!(count_pps(&f[0].data), 1, "redefined PPS must be inline");
// PES3: PPS-B repeated — still differs from codecPrivate(A), so emitted
// AGAIN. Every keyframe of the redefined segment must carry it, because
// the player re-applies the hvcC (codecPrivate) copy at each keyframe;
// emitting once would be reverted at the next keyframe.
// PES3: PPS-B repeated on a NON-keyframe slice — B is already the active
// set, so this carries no change and is stripped. (Re-assertion for
// players that re-apply hvcC at keyframes is handled by
// `reassert_active` at KEYFRAMES, not on every trailing frame; these
// slices are TRAIL_R, not IRAP.)
let mut d = pps(0xBB);
d.extend(slice());
let f = parser.parse(&make_pes(d, Some(2)));
assert_eq!(
count_pps(&f[0].data),
1,
"redefined PPS re-emitted every occurrence"
0,
"PPS equal to the active set carries no change → stripped"
);
// PES4: back to PPS-A (== codecPrivate) → stripped (hvcC supplies it).
// PES4: back to PPS-A. Even though A == codecPrivate, the ACTIVE set is
// B, so switching to A is a real change and MUST be emitted in-band — a
// streaming decoder (hvcC at init, in-band updates only) is sitting on B
// and would otherwise never revert. (This is the Fight Club bug: the old
// `== codecPrivate → strip` rule dropped exactly this revert.)
let mut d = pps(0xAA);
d.extend(slice());
let f = parser.parse(&make_pes(d, Some(3)));
assert_eq!(
count_pps(&f[0].data),
0,
"occurrence equal to codecPrivate stripped"
1,
"switch back to the codecPrivate body is a change → emitted in-band"
);
}
@@ -1051,10 +1612,14 @@ mod tests {
"frame data must contain Dolby Vision RPU NAL (type 62), got: {:?}",
nal_types
);
// Self-contained keyframe: the active VPS/SPS/PPS are re-asserted in-band
// ahead of the IDR, so the frame is VPS, SPS, PPS, IDR, RPU — in that
// order. The RPU (type 62) is preserved (never stripped); only the
// duplicate-suppression of unchanged param sets was lifted at keyframes.
assert_eq!(
nal_types.len(),
2,
"frame data should have exactly 2 NALs (IDR + RPU), got: {:?}",
nal_types,
vec![32, 33, 34, 19, 62],
"keyframe carries re-asserted param sets + IDR + preserved RPU, got: {:?}",
nal_types
);
src/mux/codec/mpeg2.rs
+711 -439
View File
File diff suppressed because it is too large Load Diff
src/mux/codec/vc1.rs
+244 -14
View File
@@ -13,8 +13,22 @@ const SC_ENTRY_POINT: u8 = 0x0E;
const SC_FRAME: u8 = 0x0D;
pub struct Vc1Parser {
// First-seen seq_header + entry_point seed the MKV codecPrivate
// (BITMAPINFOHEADER extra data). These are the only out-of-band copies
// the player gets. A stream may redefine either header mid-title; any
// occurrence whose body DIFFERS from the active value must be emitted
// IN-BAND at each point it appears, and at every keyframe (RAP) if the
// active value differs from the codecPrivate copy, so seek points carry
// valid decoder state (SMPTE 421M requires seq+entry before every RAP).
seq_header: Option<Vec<u8>>,
entry_point: Option<Vec<u8>>,
// Currently-ACTIVE body of each type — the most recent the bitstream
// defined. Distinct from the fixed codecPrivate copies above. The
// strip/emit decision is made against `cur_*`, not the first-seen copy:
// a switch BACK to the first-seen body (== codecPrivate) is still a
// change a streaming decoder must be told about.
cur_seq_header: Option<Vec<u8>>,
cur_entry_point: Option<Vec<u8>>,
width: u32,
height: u32,
}
@@ -30,12 +44,70 @@ impl Vc1Parser {
Self {
seq_header: None,
entry_point: None,
cur_seq_header: None,
cur_entry_point: None,
width: 1920,
height: 1080,
}
}
}
/// Handle a seq_header or entry_point start-code unit (Annex B raw bytes).
///
/// Decision is against the currently-ACTIVE body `cur`, not the codecPrivate
/// copy `first`:
/// - First of its type → seeds codecPrivate; stripped (decoder gets it from
/// the BITMAPINFOHEADER extra data at init).
/// - Equal to the active set `cur` → redundant; stripped.
/// - Different from `cur` (a change in EITHER direction, including reverting
/// to the codecPrivate/first value) → prepended into `prefix` in Annex B
/// form and `cur` updated.
///
/// Returns `true` when the unit was emitted into `prefix`.
fn handle_header(
first: &mut Option<Vec<u8>>,
cur: &mut Option<Vec<u8>>,
unit: &[u8],
prefix: &mut Vec<u8>,
) -> bool {
let is_first = first.is_none();
if is_first {
first.replace(unit.to_vec()); // seeds codecPrivate; stripped here
}
let changed = cur.as_deref() != Some(unit);
if changed {
*cur = Some(unit.to_vec());
}
// Strip the seeding occurrence and any unit that doesn't change the
// active header. Emit only a genuine change.
if is_first || !changed {
return false;
}
prefix.extend_from_slice(unit);
true
}
/// Re-assert the active header `cur` into `prefix` (raw Annex B bytes) at every
/// keyframe (RAP) so the RAP is SELF-CONTAINED. Skipped only when this AU already
/// emitted the header in-band (`emitted`) or no active header exists yet.
///
/// Unconditional (not only when the active differs from codecPrivate): SMPTE 421M
/// requires seq_header + entry_point before every RAP. A decoder applies the
/// codecPrivate copy once at init, then relies on in-band repetition; if a source
/// stops repeating an (unchanged) header at later RAPs and the decoder drops it,
/// nothing re-sends it and seeks/segments land with wrong decoder state. Re-asserting
/// at every RAP — what compliant muxers do — makes decode self-healing. Re-sending
/// an identical header is benign. This strictly supersets the change-only re-assert.
fn reassert_active(prefix: &mut Vec<u8>, cur: &Option<Vec<u8>>, emitted: bool) {
if emitted {
return;
}
let Some(active) = cur.as_deref() else {
return;
};
prefix.extend_from_slice(active);
}
impl CodecParser for Vc1Parser {
fn parse(&mut self, pes: &PesPacket) -> Vec<Frame> {
if pes.data.is_empty() {
@@ -50,6 +122,13 @@ impl CodecParser for Vc1Parser {
let mut has_seq_header = false;
let mut has_entry_point = false;
let mut frame_start: Option<usize> = None;
// Track whether this AU already emitted each header in-band (a
// redefinition vs the active value).
let mut emitted_seq = false;
let mut emitted_ep = false;
// In-band prefix: changed/new seq_header and/or entry_point units that
// must appear before the SC_FRAME data in the MKV block.
let mut prefix: Vec<u8> = Vec::new();
// Scan for start codes (00 00 01 XX)
let data = &pes.data;
@@ -61,17 +140,29 @@ impl CodecParser for Vc1Parser {
SC_SEQUENCE_HEADER => {
let end = find_next_sc(data, i + 4).unwrap_or(data.len());
let sh = &data[i..end];
self.seq_header = Some(sh.to_vec());
// Try to parse resolution from advanced profile sequence header
if let Some((w, h)) = parse_vc1_resolution(sh) {
self.width = w;
self.height = h;
if self.seq_header.is_none() {
if let Some((w, h)) = parse_vc1_resolution(sh) {
self.width = w;
self.height = h;
}
}
emitted_seq |= handle_header(
&mut self.seq_header,
&mut self.cur_seq_header,
sh,
&mut prefix,
);
has_seq_header = true;
}
SC_ENTRY_POINT => {
let end = find_next_sc(data, i + 4).unwrap_or(data.len());
self.entry_point = Some(data[i..end].to_vec());
emitted_ep |= handle_header(
&mut self.entry_point,
&mut self.cur_entry_point,
&data[i..end],
&mut prefix,
);
has_entry_point = true;
}
SC_FRAME => {
@@ -91,11 +182,28 @@ impl CodecParser for Vc1Parser {
// Keyframe = this PES contains a sequence header (I-frame indicator in BD)
let keyframe = has_seq_header;
// Strip sequence header + entry point from frame data — those are in
// codecPrivate, not coded-picture data. Only include data from the
// frame start code onwards.
// At every keyframe (RAP), re-assert the active seq_header + entry_point
// in-band (even when unchanged vs codecPrivate) so the RAP is
// self-contained. SMPTE 421M requires seq+entry before every RAP; a
// decoder that dropped them recovers, and seeks land with correct state.
// Skipped per-header only when this AU already emitted it in-band.
if keyframe {
reassert_active(&mut prefix, &self.cur_seq_header, emitted_seq);
reassert_active(&mut prefix, &self.cur_entry_point, emitted_ep);
}
// Assemble frame data: any in-band header changes + picture data from
// the first SC_FRAME onwards.
let frame_data = match frame_start {
Some(start) => &data[start..],
Some(start) => {
if prefix.is_empty() {
data[start..].to_vec()
} else {
let mut out = prefix;
out.extend_from_slice(&data[start..]);
out
}
}
None => {
// No frame start code. If this PES carried only parameter sets
// (sequence header / entry point, captured above into
@@ -106,14 +214,14 @@ impl CodecParser for Vc1Parser {
if has_seq_header || has_entry_point {
return Vec::new();
}
data // genuine picture payload with no leading 0x0D — pass through
data.to_vec() // genuine picture payload with no leading 0x0D — pass through
}
};
vec![Frame {
pts_ns: ts_ns,
keyframe,
data: frame_data.to_vec(),
data: frame_data,
duration_ns: None,
}]
}
@@ -385,9 +493,20 @@ mod tests {
let frames = parser.parse(&pes);
assert_eq!(frames.len(), 1);
// Frame data should start with the frame start code (00 00 01 0D)
assert!(frames[0].data.len() >= 4);
assert_eq!(&frames[0].data[0..4], &[0x00, 0x00, 0x01, SC_FRAME]);
// Seq+entry seed codecPrivate on first occurrence, but because this is a
// keyframe (RAP) they are re-asserted in-band so the RAP is
// self-contained. Frame data therefore STARTS with the seq_header start
// code, and the SC_FRAME picture data follows.
let fd = &frames[0].data;
assert!(fd.len() >= 4);
assert_eq!(&fd[0..4], &[0x00, 0x00, 0x01, SC_SEQUENCE_HEADER]);
let frame_sc = fd
.windows(4)
.position(|w| w == [0x00, 0x00, 0x01, SC_FRAME]);
assert!(
frame_sc.is_some(),
"SC_FRAME picture data must follow the re-asserted headers"
);
}
// --- parameter-set-only PES (seq header + entry point, no frame SC) ---
@@ -749,4 +868,115 @@ mod tests {
// Extra data should start with the sequence header start code
assert_eq!(&extra[0..4], &[0x00, 0x00, 0x01, SC_SEQUENCE_HEADER]);
}
// --- regression: mid-stream entry_point A→B→A revert emitted in-band ---
/// Regression: entry_point is redefined from A (== codecPrivate) to B, then
/// switched BACK to A. A streaming decoder applied codecPrivate at init and
/// is now on B; the revert to A must be emitted IN-BAND even though A ==
/// codecPrivate, or the A-segment decodes against the wrong entry point.
#[test]
fn vc1_emits_entry_point_revert_to_first_value() {
let sh = vec![0x00, 0x00, 0x01, SC_SEQUENCE_HEADER, 0xAA, 0xBB];
let ep_a = vec![0x00, 0x00, 0x01, SC_ENTRY_POINT, 0x11, 0x22];
let ep_b = vec![0x00, 0x00, 0x01, SC_ENTRY_POINT, 0x33, 0x44, 0x55];
let frame = vec![0x00, 0x00, 0x01, SC_FRAME, 0x77];
let mut parser = Vc1Parser::new();
// AU1: seeds codecPrivate with sh + ep_a. Both are first → stripped from frame.
let au1: Vec<u8> = sh
.iter()
.chain(ep_a.iter())
.chain(frame.iter())
.cloned()
.collect();
let f1 = parser.parse(&make_pes(au1, Some(0)));
assert_eq!(f1.len(), 1, "AU1 emits a frame");
// seq+entry seed codecPrivate, but this is a keyframe (RAP) so the active
// headers are re-asserted in-band (self-contained RAP) — ep_a present.
assert!(
contains_sc(&f1[0].data, SC_ENTRY_POINT),
"AU1: keyframe re-asserts the active entry_point in-band"
);
assert!(
f1[0].data.windows(ep_a.len()).any(|w| w == ep_a),
"AU1 carries the active ep_a bytes in-band"
);
// AU2: entry_point redefined to B → must be emitted in-band.
let au2: Vec<u8> = ep_b.iter().chain(frame.iter()).cloned().collect();
let f2 = parser.parse(&make_pes(au2, Some(90000)));
assert_eq!(f2.len(), 1, "AU2 emits a frame");
assert!(
contains_sc(&f2[0].data, SC_ENTRY_POINT),
"AU2: redefined entry_point B must be in-band"
);
assert!(
f2[0].data.windows(ep_b.len()).any(|w| w == ep_b),
"AU2 must carry the ep_b bytes"
);
// AU3: entry_point reverts to A (== codecPrivate). Active was B; this is
// a real change and must still be emitted in-band.
let au3: Vec<u8> = ep_a.iter().chain(frame.iter()).cloned().collect();
let f3 = parser.parse(&make_pes(au3, Some(180000)));
assert_eq!(f3.len(), 1, "AU3 emits a frame");
assert!(
f3[0].data.windows(ep_a.len()).any(|w| w == ep_a),
"AU3: revert to A (== codecPrivate) must be emitted in-band"
);
}
/// Regression: a bare keyframe (no seq_header / entry_point in PES) after
/// a mid-title redefinition must re-assert the active headers in-band so
/// seek points carry valid decoder state (SMPTE 421M).
#[test]
fn vc1_reasserts_active_headers_at_bare_keyframe() {
let sh_a = vec![0x00, 0x00, 0x01, SC_SEQUENCE_HEADER, 0xAA, 0xBB];
let ep_a = vec![0x00, 0x00, 0x01, SC_ENTRY_POINT, 0x11, 0x22];
let ep_b = vec![0x00, 0x00, 0x01, SC_ENTRY_POINT, 0x33, 0x44, 0x55];
let frame = vec![0x00, 0x00, 0x01, SC_FRAME, 0x77];
let mut parser = Vc1Parser::new();
// AU1: seed codecPrivate.
let au1: Vec<u8> = sh_a
.iter()
.chain(ep_a.iter())
.chain(frame.iter())
.cloned()
.collect();
parser.parse(&make_pes(au1, Some(0)));
// AU2: redefine entry_point to B at a keyframe.
let au2: Vec<u8> = sh_a
.iter()
.chain(ep_b.iter())
.chain(frame.iter())
.cloned()
.collect();
parser.parse(&make_pes(au2, Some(90000)));
// AU3: bare keyframe — only SC_SEQUENCE_HEADER (keyframe signal) + SC_FRAME,
// no entry_point. Active entry_point is B (differs from codecPrivate A);
// must be re-asserted in-band so seeks into this frame don't revert to A.
let au3: Vec<u8> = sh_a.iter().chain(frame.iter()).cloned().collect();
let f3 = parser.parse(&make_pes(au3, Some(180000)));
assert_eq!(f3.len(), 1, "AU3 emits a frame");
assert!(
f3[0].data.windows(ep_b.len()).any(|w| w == ep_b),
"bare keyframe must re-assert active entry_point B in-band"
);
assert!(
!f3[0].data.windows(ep_a.len()).any(|w| w == ep_a),
"must not re-assert stale codecPrivate entry_point A"
);
}
/// Helper: does `data` contain a start-code unit with the given type byte?
fn contains_sc(data: &[u8], sc_type: u8) -> bool {
data.windows(4)
.any(|w| w[0] == 0x00 && w[1] == 0x00 && w[2] == 0x01 && w[3] == sc_type)
}
}