From 055fb3bf0ec334df27f6f633df5ac6eac94fb187 Mon Sep 17 00:00:00 2001 From: Gunwoo Kim Date: Mon, 9 Nov 2026 01:52:49 +0900 Subject: [PATCH 1/3] docs(transcode): plan native Matroska cadence Signed-off-by: Gunwoo Kim --- docs/design/cli-native-h264-matroska.md | 38 +++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 docs/design/cli-native-h264-matroska.md diff --git a/docs/design/cli-native-h264-matroska.md b/docs/design/cli-native-h264-matroska.md new file mode 100644 index 00000000..4a770320 --- /dev/null +++ b/docs/design/cli-native-h264-matroska.md @@ -0,0 +1,38 @@ +# Native H.264 Matroska cadence + +## Scope + +Extend the opt-in CLI selector to Matroska, without changing native MP4 admission, encoder algorithms, default or release features, or commands that do not select the native encoder. WebM remains excluded. Every command admitted natively before this change must remain native with identical complete output bytes. + +## Clock representation + +Matroska DefaultDuration is a positive integer number of nanoseconds, independent of TimestampScale (RFC 9559 Section 5.1.4.1.13). Block timestamps use TimestampScale. The current writer rounds each absolute presentation timestamp to the nearest millisecond and uses TimestampScale 1,000,000. A constant 30 fps source consequently has alternating 33 and 34 ms packet intervals. Inferring cadence from identical rounded intervals loses its nominal frame duration. + +For native H.264 Matroska replacements only, derive DefaultDuration from the encoder's admitted exact rational frame rate: round half up `1,000,000,000 * fps_den / fps_num` with checked integer arithmetic. Keep the current millisecond packet timestamps and TimestampScale. Do not infer nominal cadence from their rounded differences. Do not write a per-packet BlockDuration that supersedes the nominal default. + +The exact rational remains in the H.264 VUI. DefaultDuration differs from its exact period by at most half a nanosecond, and each absolute block PTS retains the existing millisecond quantization rather than accumulating rounding drift. Common rates must read back exactly through the pinned oracle; unusual rates are checked against the independently parsed integer duration and timestamp quantization, not an assumed ffprobe fraction. + +New native Matroska admission requires a nominal period of at least one millisecond and strictly increasing output PTS after rounding. Higher rates or collisions retain their previous external path. No native Matroska command exists before this change, so these boundaries do not move an existing native command. Keep the merged native timing predicate, including its legacy single-picture and terminal-zero defaults, unchanged for MP4. + +## Boundary + +Add a checked video-cadence value and an explicit writer entrypoint for one H.264 video replacement. Existing writer calls retain their current behavior. The new entrypoint validates that the named stream is the actual video replacement, supplies its nominal default duration, and rejects rounded timestamp collisions before publication. Audio packets, source offsets, stream selection, display dimensions, codec private data, cluster policy and all other writer paths remain unchanged. + +The transcode pipeline uses that entrypoint only for a completed native H.264 Matroska encode, with the admitted encoder frame rate. MP4 never constructs the cadence override. Unsupported native cadence retries the unchanged external command under the original deadline; I/O, malformed-input and timeout errors remain terminal. + +## Verification + +- Build and retain a separate native binary from the actual pre-change main revision. Compare complete MP4 bytes for the existing metadata, quality, thread, GOP, legacy duration, input, audio-copy and selector axes, with external programs unavailable. Record named cases and counts, not just candidate self-comparisons. +- Preserve complete default, feature-enabled unselected and external Matroska output bytes against that revision. Retain unsupported-option, WebM, VFR, high-rate and timestamp-collision fallback controls and transactional deadline tests. +- Check new Matroska output with an independent EBML parser: DefaultDuration, TimestampScale, block PTS, absence of conflicting BlockDuration, display ratio, codec private data and keyframe flags. Independently parse VUI timing and aspect. +- Cover integer, NTSC and unusual rational rates, absent and explicit aspects, single pictures, legacy zero durations, source origins, the 250-picture GOP boundary, thread counts and copied audio. +- Compare complete encoded access units and pinned-oracle reconstruction between same-head MP4 and Matroska. Verify frame counts and timestamp error against the declared quantization. +- Run affected Rust and Python tests in Linux CI by name, unchanged feature-graph checks, public-text checks and exact-head similarity before readiness. + +## References + +- https://www.rfc-editor.org/rfc/rfc9559.html#section-5.1.4.1.13 +- https://www.matroska.org/technical/notes.html +- https://www.matroska.org/technical/elements.html + +Refs coreav-dev/coreav#25. From f448d0a96db51f6aaa65dc06fba05e195f41272e Mon Sep 17 00:00:00 2001 From: Gunwoo Kim Date: Mon, 9 Nov 2026 03:18:37 +0900 Subject: [PATCH 2/3] feat(cli): support native H.264 Matroska Signed-off-by: Gunwoo Kim --- .github/workflows/h264-encoder.yml | 10 + crates/coreav-cli/src/ffmpeg/native_h264.rs | 20 +- crates/coreav-isobmff-write/src/mkv_output.rs | 101 +++- .../src/mkv_output/source.rs | 13 +- .../src/mkv_output/tests.rs | 533 +++++++++++++++++ crates/coreav-transcode/src/pipeline.rs | 76 ++- docs/design/cli-native-h264-matroska.md | 7 +- docs/design/cli-native-h264-metadata.md | 2 +- docs/design/cli-native-h264.md | 8 +- scripts/native_h264_cli.py | 376 ++++++++++-- scripts/native_h264_matroska.py | 324 ++++++++++ scripts/tests/test_native_h264_cli.py | 561 +++++++++++++++++- 12 files changed, 1974 insertions(+), 57 deletions(-) create mode 100644 crates/coreav-isobmff-write/src/mkv_output/tests.rs create mode 100644 scripts/native_h264_matroska.py diff --git a/.github/workflows/h264-encoder.yml b/.github/workflows/h264-encoder.yml index c0183838..e4d103db 100644 --- a/.github/workflows/h264-encoder.yml +++ b/.github/workflows/h264-encoder.yml @@ -9,8 +9,11 @@ on: - crates/coreav-h264-encoder/** - crates/coreav-cli/** - crates/coreav-transcode/** + - crates/coreav-isobmff-write/** - crates/coreav-frame/** - scripts/native_h264_cli.py + - scripts/native_h264_matroska.py + - scripts/tests/test_native_h264_cli.py - scripts/track_boxes.py - crates/coreav-kernels-h264/** - crates/coreav-h264/** @@ -42,8 +45,11 @@ on: - crates/coreav-h264-encoder/** - crates/coreav-cli/** - crates/coreav-transcode/** + - crates/coreav-isobmff-write/** - crates/coreav-frame/** - scripts/native_h264_cli.py + - scripts/native_h264_matroska.py + - scripts/tests/test_native_h264_cli.py - scripts/track_boxes.py - crates/coreav-kernels-h264/** - crates/coreav-h264/** @@ -110,6 +116,8 @@ jobs: - name: Preserve base-build byte references run: | cd ../baseline + git rev-parse HEAD + test "$(git rev-parse HEAD)" = '${{ github.event.pull_request.base.sha || github.sha }}' cargo build --locked --release -p coreav-cli cp target/release/coreav "$RUNNER_TEMP/default-base" cargo build --locked --release -p coreav-cli --features native-h264 @@ -134,6 +142,7 @@ jobs: cargo test --locked --release -p coreav-cli --features native-h264-encoder,native-h264 --lib ffmpeg -- --nocapture cargo test --locked --release -p coreav-cli --features native-h264-encoder,native-h264 --test docs_site --test strict_safe_limit --test ffprobe_limits --test native_h264_cli cargo test --locked --release -p coreav-transcode --features h264-native --lib + cargo test --locked --release -p coreav-isobmff-write --lib mkv_output cargo clippy --locked -p coreav-cli --features native-h264-encoder,native-h264 --all-targets -- -D warnings cargo build --locked --release -p coreav-cli --features native-h264-encoder,native-h264 cargo build --locked --release -p coreav-h264-encoder --features full --example p @@ -157,6 +166,7 @@ jobs: --baseline-default "$RUNNER_TEMP/default-base" \ --baseline-external "$RUNNER_TEMP/external-base" \ --baseline-native "$RUNNER_TEMP/native-base" \ + --baseline-revision "$(git -C ../baseline rev-parse HEAD)" \ --driver target/release/examples/p \ --ffmpeg "$RUNNER_TEMP/cli-oracles/ffmpeg" \ --output "$RUNNER_TEMP/native-cli" diff --git a/crates/coreav-cli/src/ffmpeg/native_h264.rs b/crates/coreav-cli/src/ffmpeg/native_h264.rs index c9af6fa3..fe94f000 100644 --- a/crates/coreav-cli/src/ffmpeg/native_h264.rs +++ b/crates/coreav-cli/src/ffmpeg/native_h264.rs @@ -21,7 +21,7 @@ fn candidate(args: &[String]) -> Option<(Command, NativeH264)> { let (command, qp) = super::args::native_h264(args).ok()?; let encoding = &command.encoding; if !command.more_inputs.is_empty() - || command.muxer != Muxer::Mp4 + || !matches!(command.muxer, Muxer::Mp4 | Muxer::Matroska) || !command.codecs.iter().any(|(spec, codec)| { *codec == Codec::Libx264 && matches!(spec, Spec::Kind(Kind2::Video, None | Some(0))) }) @@ -208,6 +208,24 @@ mod tests { ); } + #[test] + fn matroska_selection_keeps_arguments_and_excludes_webm() { + for suffix in ["out.mp4", "out.mkv", "-f matroska out.bin"] { + let args: Vec = format!("-i in.mp4 -an -c:v libx264 -crf 23 {suffix}") + .split_whitespace() + .map(str::to_owned) + .collect(); + let before = args.clone(); + assert!(candidate(&args).is_some(), "{suffix}"); + assert_eq!(args, before); + } + let webm: Vec = "-i in.mp4 -an -c:v libx264 out.webm" + .split_whitespace() + .map(str::to_owned) + .collect(); + assert!(candidate(&webm).is_none()); + } + #[test] fn unsupported_controls_keep_the_existing_command() { for option in [ diff --git a/crates/coreav-isobmff-write/src/mkv_output.rs b/crates/coreav-isobmff-write/src/mkv_output.rs index a6028ef8..123d2b78 100644 --- a/crates/coreav-isobmff-write/src/mkv_output.rs +++ b/crates/coreav-isobmff-write/src/mkv_output.rs @@ -2,6 +2,8 @@ mod config; mod source; +#[cfg(test)] +mod tests; use crate::{Replacements, replace}; use coreav_isobmff::{Limits, Rational, Source}; @@ -21,6 +23,36 @@ pub struct OutputOptions { pub streams: Option>, } +/// Explicit constant cadence for one replaced AVC video stream. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct VideoCadence { + stream_index: usize, + default_duration_ns: u64, +} + +impl VideoCadence { + /// Round a positive rate of at most 1,000 frames per second to nanoseconds. + pub fn new(stream_index: usize, fps_num: u32, fps_den: u32) -> Result { + if fps_num == 0 || fps_den == 0 || u128::from(fps_num) > 1_000 * u128::from(fps_den) { + return Err(unsupported( + "video cadence needs a positive rate at most 1000 fps", + )); + } + let numerator = u128::from(fps_den) + .checked_mul(1_000_000_000) + .and_then(|n| n.checked_add(u128::from(fps_num) / 2)) + .ok_or_else(|| unsupported("video cadence exceeds nanosecond limits"))?; + let default_duration_ns = u64::try_from(numerator / u128::from(fps_num)) + .ok() + .filter(|n| *n > 0) + .ok_or_else(|| unsupported("video cadence exceeds nanosecond limits"))?; + Ok(Self { + stream_index, + default_duration_ns, + }) + } +} + /// One written track. #[derive(Clone, Debug)] pub struct OutputTrack { @@ -111,11 +143,45 @@ pub fn copied_audio(source: &mut S, streams: &[usize]) -> Result<(), /// Plans selected tracks and replacements, then streams their payloads to /// the output. Media stays in its original source or encoder spool. pub fn write_output( + source: S, + options: &OutputOptions, + limits: &Limits, + mkv_limits: &coreav_mkv::Limits, + replacements: Replacements<'_, R>, + out: W, +) -> Result { + write_output_inner(source, options, limits, mkv_limits, replacements, None, out) +} + +/// Writes one replaced AVC stream with caller-established constant cadence. +/// Copied ISO Opus follows its source edit rather than its informative pre-skip. +pub fn write_output_with_video_cadence( + source: S, + options: &OutputOptions, + limits: &Limits, + mkv_limits: &coreav_mkv::Limits, + replacements: Replacements<'_, R>, + cadence: VideoCadence, + out: W, +) -> Result { + write_output_inner( + source, + options, + limits, + mkv_limits, + replacements, + Some(cadence), + out, + ) +} + +fn write_output_inner( mut source: S, options: &OutputOptions, limits: &Limits, mkv_limits: &coreav_mkv::Limits, mut replacements: Replacements<'_, R>, + video_cadence: Option, out: W, ) -> Result { if options @@ -130,7 +196,18 @@ pub fn write_output( limit: mkv_limits.max_retained_bytes, }; if let Some(v) = &mut replacements.video { - replace::validate(v, limits).map_err(iso)?; + let codec = replace::validate(v, limits).map_err(iso)?; + if let Some(cadence) = video_cadence + && (cadence.stream_index != v.stream_index + || codec != replace::EntryCodec::H264 + || options.doc_type != DocType::Matroska) + { + return Err(unsupported( + "video cadence needs its selected AVC replacement in Matroska", + )); + } + } else if video_cadence.is_some() { + return Err(unsupported("video cadence needs an AVC replacement")); } if let Some(a) = &mut replacements.audio { replace::validate_audio(a, limits).map_err(iso)?; @@ -163,7 +240,10 @@ pub fn write_output( } else { source::isobmff( &mut source, - options, + source::IsoOptions { + output: options, + preserve_opus_edit: video_cadence.is_some(), + }, limits, mkv_limits, &replacement_headers, @@ -205,7 +285,22 @@ pub fn write_output( .checked_add(u64::from(sample.size)) .ok_or_else(overflow)?; } - cadence(t); + if let Some(cadence) = video_cadence { + if t.packets.windows(2).any(|w| match w { + [a, b] => a.packet.pts_ns >= b.packet.pts_ns, + _ => true, + }) { + return Err(unsupported( + "video cadence needs increasing millisecond timestamps", + )); + } + t.header.default_duration_ns = Some(cadence.default_duration_ns); + for packet in &mut t.packets { + packet.packet.duration_ns = None; + } + } else { + cadence(t); + } t.prefix.clear(); t.replaced = true; } diff --git a/crates/coreav-isobmff-write/src/mkv_output/source.rs b/crates/coreav-isobmff-write/src/mkv_output/source.rs index 3bfdfc6f..d13a05cb 100644 --- a/crates/coreav-isobmff-write/src/mkv_output/source.rs +++ b/crates/coreav-isobmff-write/src/mkv_output/source.rs @@ -4,15 +4,24 @@ use super::{ }; use coreav_isobmff::{Allowlist, EditList, Limits, TrackKind}; +pub(super) struct IsoOptions<'a> { + pub output: &'a OutputOptions, + pub preserve_opus_edit: bool, +} + pub(super) fn isobmff( source: &mut S, - options: &OutputOptions, + options: IsoOptions<'_>, limits: &Limits, mkv_limits: &coreav_mkv::Limits, replacements: &[(usize, Track)], total: &mut usize, metadata: &mut MetadataBudget, ) -> Result, Error> { + let IsoOptions { + output: options, + preserve_opus_edit, + } = options; let probe_limits = Limits { max_retained_bytes: limits .max_retained_bytes @@ -121,7 +130,7 @@ pub(super) fn isobmff( }; let mut trim = u64::try_from(media).map_err(|_| unsupported("a negative media edit time"))?; - if replacement.is_none() && d.codec == coreav_isobmff::Codec::Opus { + if replacement.is_none() && d.codec == coreav_isobmff::Codec::Opus && !preserve_opus_edit { let skip = header .private .get(10..12) diff --git a/crates/coreav-isobmff-write/src/mkv_output/tests.rs b/crates/coreav-isobmff-write/src/mkv_output/tests.rs new file mode 100644 index 00000000..05f5ce6c --- /dev/null +++ b/crates/coreav-isobmff-write/src/mkv_output/tests.rs @@ -0,0 +1,533 @@ +#![allow(clippy::unwrap_used, clippy::indexing_slicing)] + +use super::*; +use crate::{Replacement, ReplacementSample}; +use coreav_isobmff::SliceSource; +use coreav_mkv::write::{CodecId, plan}; + +const AVC: [u8; 7] = [1, 100, 0, 30, 255, 224, 0]; + +struct Fixture { + input: Vec, + entry: Vec, + samples: Vec, + data: Vec, + last_duration: u32, +} + +impl Fixture { + fn new(times: &[i64], last_duration: u32) -> Self { + let header = + config::description(CodecId::H264, Some((16, 16)), None, None, None, None, &AVC) + .unwrap(); + let packets = [Packet { + track: 0, + pts_ns: 0, + duration_ns: Some(1_000_000_000), + size: 1, + keyframe: true, + invisible: false, + discard_padding_ns: None, + }]; + let mut input = Vec::new(); + plan( + &[header], + &packets, + Options { + timestamp_scale_ns: 1, + ..Options::default() + }, + &coreav_mkv::Limits::default(), + ) + .unwrap() + .write(&mut input, |_, out| { + out.write_all(&[7]).map_err(|e| Error::Io(e.kind())) + }) + .unwrap(); + Self { + input, + entry: crate::mux::avc1_sample_entry(16, 16, &AVC, None, None).unwrap(), + samples: times + .iter() + .enumerate() + .map(|(index, &time)| ReplacementSample { + size: 1, + sync: index == 0, + decode_time: time, + presentation_time: time, + }) + .collect(), + data: vec![7; times.len()], + last_duration, + } + } + + fn write( + &self, + cadence: Option, + stream: usize, + options: &OutputOptions, + out: &mut Vec, + ) -> Result { + let replacements = Replacements { + video: Some(Replacement { + stream_index: stream, + sample_entry: &self.entry, + width: 16 << 16, + height: 16 << 16, + samples: &self.samples, + last_duration: self.last_duration, + data: SliceSource::new(&self.data), + }), + audio: None, + }; + match cadence { + Some(cadence) => write_output_with_video_cadence( + SliceSource::new(&self.input), + options, + &Limits::default(), + &coreav_mkv::Limits::default(), + replacements, + cadence, + out, + ), + None => write_output( + SliceSource::new(&self.input), + options, + &Limits::default(), + &coreav_mkv::Limits::default(), + replacements, + out, + ), + } + } +} + +fn options() -> OutputOptions { + OutputOptions { + matroska_source: true, + doc_type: DocType::Matroska, + streams: None, + } +} + +fn probe(bytes: &[u8]) -> coreav_mkv::Segment { + coreav_mkv::probe( + SliceSource::new(bytes), + &coreav_mkv::Limits::default(), + &coreav_mkv::Allowlist::any(), + ) + .unwrap() +} + +#[test] +fn video_cadence_checks_rate_bounds_and_rounds_nanoseconds() { + for (num, den, expected) in [ + (25, 1, 40_000_000), + (30, 1, 33_333_333), + (24000, 1001, 41_708_333), + (30000, 1001, 33_366_667), + (1000, 33, 33_000_000), + (1000, 1, 1_000_000), + (u32::MAX, u32::MAX, 1_000_000_000), + (1, u32::MAX, 4_294_967_295_000_000_000), + ] { + assert_eq!( + VideoCadence::new(7, num, den).unwrap(), + VideoCadence { + stream_index: 7, + default_duration_ns: expected, + } + ); + } + for (num, den) in [(0, 1), (1, 0), (0, 0), (1001, 1), (u32::MAX, 1)] { + assert!(matches!( + VideoCadence::new(0, num, den), + Err(Error::Unsupported { .. }) + )); + } +} + +#[test] +fn explicit_video_cadence_serializes_default_duration_without_block_overrides() { + for (num, den, times, last, expected, pts) in [ + ( + 30, + 1, + vec![0, 33_333_333, 66_666_667], + 33_333_333, + 33_333_333, + vec![0, 33, 67], + ), + ( + 30000, + 1001, + vec![0, 33_366_667, 66_733_333], + 33_366_667, + 33_366_667, + vec![0, 33, 67], + ), + ( + 24000, + 1001, + vec![0, 41_708_333, 83_416_667], + 41_708_333, + 41_708_333, + vec![0, 42, 83], + ), + (25, 1, vec![70_000_000], 40_000_000, 40_000_000, vec![70]), + ] { + let fixture = Fixture::new(×, last); + let mut bytes = Vec::new(); + fixture + .write( + Some(VideoCadence::new(0, num, den).unwrap()), + 0, + &options(), + &mut bytes, + ) + .unwrap(); + let segment = probe(&bytes); + assert_eq!(segment.timestamp_scale, 1_000_000); + assert_eq!(segment.tracks[0].default_duration, Some(expected)); + let packets = segment + .packets(SliceSource::new(&bytes), &coreav_mkv::Limits::default()) + .collect::, _>>() + .unwrap(); + assert_eq!( + packets.iter().map(|p| p.pts.unwrap()).collect::>(), + pts + ); + assert!(packets.iter().all(|p| p.block_duration.is_none())); + assert!(packets[0].keyframe); + assert!(packets.iter().skip(1).all(|p| !p.keyframe)); + assert!(packets.iter().all(|p| bytes[p.offset as usize] == 7)); + } +} + +#[test] +fn ordinary_output_keeps_its_serialized_packet_duration_policy() { + let fixture = Fixture::new(&[0, 33_333_333, 66_666_667], 33_333_333); + let mut actual = Vec::new(); + fixture.write(None, 0, &options(), &mut actual).unwrap(); + let header = config::entry(&fixture.entry, false).unwrap(); + let packets: Vec<_> = [0, 33_000_000, 67_000_000] + .into_iter() + .enumerate() + .map(|(index, pts_ns)| Packet { + track: 0, + pts_ns, + duration_ns: Some(if index == 1 { 33_333_334 } else { 33_333_333 }), + size: 1, + keyframe: index == 0, + invisible: false, + discard_padding_ns: None, + }) + .collect(); + let mut expected = Vec::new(); + plan( + &[header], + &packets, + Options::default(), + &coreav_mkv::Limits::default(), + ) + .unwrap() + .write(&mut expected, |_, out| { + out.write_all(&[7]).map_err(|e| Error::Io(e.kind())) + }) + .unwrap(); + assert_eq!(actual, expected); + let segment = probe(&actual); + assert_eq!(segment.tracks[0].default_duration, None); + assert!( + segment + .packets(SliceSource::new(&actual), &coreav_mkv::Limits::default()) + .all(|p| p.unwrap().block_duration == Some(33)) + ); +} + +#[test] +fn video_cadence_refuses_millisecond_collisions_and_reversed_presentation_before_writing() { + for (decode, present) in [ + (vec![0, 400_000], vec![0, 400_000]), + (vec![0, 1_000_000], vec![1_000_000, 1_000_000]), + (vec![0, 1_000_000], vec![2_000_000, 1_000_000]), + ] { + let mut fixture = Fixture::new(&decode, 1_000_000); + for (sample, pts) in fixture.samples.iter_mut().zip(present) { + sample.presentation_time = pts; + } + let mut bytes = Vec::new(); + assert!(matches!( + fixture.write( + Some(VideoCadence::new(0, 1000, 1).unwrap()), + 0, + &options(), + &mut bytes + ), + Err(Error::Unsupported { .. }) + )); + assert!(bytes.is_empty()); + } +} + +#[test] +fn video_cadence_requires_its_selected_avc_replacement() { + let fixture = Fixture::new(&[0], 33_333_333); + for (cadence_stream, replacement_stream, selected, doc_type) in [ + (1, 0, None, DocType::Matroska), + (1, 1, None, DocType::Matroska), + (0, 0, Some(Vec::new()), DocType::Matroska), + (0, 0, None, DocType::Webm), + ] { + let mut bytes = Vec::new(); + let options = OutputOptions { + streams: selected, + doc_type, + ..options() + }; + assert!(matches!( + fixture.write( + Some(VideoCadence::new(cadence_stream, 30, 1).unwrap()), + replacement_stream, + &options, + &mut bytes + ), + Err(Error::Unsupported { .. }) + )); + assert!(bytes.is_empty()); + } + let mut bytes = Vec::new(); + assert!(matches!( + write_output_with_video_cadence( + SliceSource::new(&fixture.input), + &options(), + &Limits::default(), + &coreav_mkv::Limits::default(), + Replacements::> { + video: None, + audio: None + }, + VideoCadence::new(0, 30, 1).unwrap(), + &mut bytes, + ), + Err(Error::Unsupported { .. }) + )); + assert!(bytes.is_empty()); + let mut fixture = fixture; + fixture.entry[4..8].copy_from_slice(b"hvc1"); + assert!(matches!( + fixture.write( + Some(VideoCadence::new(0, 30, 1).unwrap()), + 0, + &options(), + &mut bytes + ), + Err(Error::Unsupported { .. }) + )); + assert!(bytes.is_empty()); +} + +fn opus_edit_fixture(media_time: u32) -> Fixture { + use crate::mux::{ + Edit, FileType, MovieHeader, Muxer, RawBox, Sample, TrackHeader, TrackMedia, + audio_sample_entry, + }; + use coreav_isobmff::FourCc; + + let mut fixture = Fixture::new(&[0, 1, 2, 3, 4], 1); + let mut dops = vec![0, 2]; + dops.extend(312u16.to_be_bytes()); + dops.extend(48_000u32.to_be_bytes()); + dops.extend([0, 0, 0]); + let audio_entry = audio_sample_entry( + FourCc(*b"Opus"), + 2, + 16, + 48_000, + &[RawBox { + kind: FourCc(*b"dOps"), + payload: dops, + }], + ) + .unwrap(); + let mut muxer = Muxer::new( + FileType { + major: FourCc(*b"isom"), + minor: 0, + compatible: vec![FourCc(*b"isom")], + }, + MovieHeader { + timescale: 48_000, + creation_time: 0, + boxes: Vec::new(), + }, + &Limits::default(), + ) + .unwrap(); + for (media, timescale, entry, edits, count, duration) in [ + ( + TrackMedia::Video { + matrix: coreav_isobmff::IDENTITY_MATRIX, + width: 16 << 16, + height: 16 << 16, + }, + 25, + fixture.entry.clone(), + Vec::new(), + 5, + 1, + ), + ( + TrackMedia::Audio { volume: 0x100 }, + 48_000, + audio_entry, + vec![Edit { + duration: 7992, + media_time: i64::from(media_time), + rate: Edit::UNIT_RATE, + }], + 10, + 960, + ), + ] { + let track = muxer + .add_track(TrackHeader { + media, + timescale, + language: *b"und", + creation_time: 0, + media_creation_time: 0, + flags: 3, + layer: 0, + alternate_group: 0, + edits, + duration: None, + media_duration: None, + sample_entry: entry, + sample_table_boxes: Vec::new(), + boxes: Vec::new(), + }) + .unwrap(); + for _ in 0..count { + muxer + .push_sample( + track, + Sample { + size: 1, + duration, + sync: true, + composition_offset: 0, + }, + ) + .unwrap(); + } + } + let mut bytes = Vec::new(); + muxer.write_head(&mut bytes).unwrap(); + muxer + .for_each_chunk::(|track, count| { + bytes.extend(std::iter::repeat_n( + if track == 0 { 7 } else { 31 << 3 }, + count as usize, + )); + Ok(()) + }) + .unwrap(); + fixture.input = bytes; + fixture +} + +#[test] +fn native_video_cadence_preserves_iso_opus_edit_presentation_without_changing_ordinary_trim() { + for media_time in [0, 960] { + let fixture = opus_edit_fixture(media_time); + let options = OutputOptions { + matroska_source: false, + ..options() + }; + let source = coreav_isobmff::probe( + SliceSource::new(&fixture.input), + &Limits::default(), + &coreav_isobmff::Allowlist::listing(), + ) + .unwrap(); + let audio = &source.tracks[1]; + assert!(matches!( + audio.edit_list, + coreav_isobmff::EditList::Simple { media_time: time, .. } + if time == i64::from(media_time) + )); + assert_eq!( + audio.presentation(source.timescale).unwrap(), + ( + coreav_isobmff::Rational::from_int(0), + coreav_isobmff::Rational::new(7992, 48_000).unwrap() + ) + ); + let mut ordinary = Vec::new(); + fixture.write(None, 0, &options, &mut ordinary).unwrap(); + let mut native = Vec::new(); + fixture + .write( + Some(VideoCadence::new(0, 25, 1).unwrap()), + 0, + &options, + &mut native, + ) + .unwrap(); + if media_time >= 312 { + assert_eq!(ordinary, native); + } else { + assert_ne!(ordinary, native); + } + for (bytes, trim, presented_samples) in [ + ( + &ordinary, + media_time.max(312), + if media_time == 0 { 7680 } else { 7992 }, + ), + (&native, media_time, 7992), + ] { + let segment = probe(bytes); + let header = &segment.tracks[1]; + let delay = u64::from(trim) * 1_000_000_000 / 48_000; + assert_eq!(header.codec_delay, delay); + let opus_head = header.codec_private.as_ref().unwrap(); + assert_eq!(&opus_head[..8], b"OpusHead"); + assert_eq!( + u16::from_le_bytes(opus_head[10..12].try_into().unwrap()), + trim as u16 + ); + let packets: Vec<_> = segment + .packets(SliceSource::new(bytes), &coreav_mkv::Limits::default()) + .collect::, _>>() + .unwrap() + .into_iter() + .filter(|p| p.track == 1) + .collect(); + assert_eq!(packets.len(), if media_time == 0 { 9 } else { 10 }); + assert_eq!(packets[0].block_timestamp, 0); + assert_eq!(packets[0].pts_ns(&segment), Some(-i128::from(delay))); + assert_eq!(packets.last().unwrap().discard_padding, Some(13_500_000)); + assert!( + packets + .iter() + .take(packets.len() - 1) + .all(|p| p.discard_padding.is_none()) + ); + for (index, packet) in packets.iter().enumerate() { + let ideal = index as i128 * 20_000_000 - i128::from(delay); + let stored = packet.pts_ns(&segment).unwrap(); + assert!(stored.abs_diff(ideal) <= 1_000_000); + assert_eq!(bytes[packet.offset as usize], 31 << 3); + } + let padding_samples = + packets.last().unwrap().discard_padding.unwrap() as u64 * 48_000 / 1_000_000_000; + assert_eq!( + packets.len() as u64 * 960 - u64::from(trim) - padding_samples, + presented_samples + ); + } + } +} diff --git a/crates/coreav-transcode/src/pipeline.rs b/crates/coreav-transcode/src/pipeline.rs index f872d727..16ebe6ee 100644 --- a/crates/coreav-transcode/src/pipeline.rs +++ b/crates/coreav-transcode/src/pipeline.rs @@ -332,6 +332,15 @@ impl fmt::Display for Error { impl std::error::Error for Error {} +fn native_matroska_error(error: coreav_mkv::Error) -> Error { + match error { + coreav_mkv::Error::Unsupported { .. } => { + Error::NativeIneligible("the native Matroska cadence or track cannot be represented") + } + error => Error::Matroska(error), + } +} + impl From for Error { fn from(e: coreav_thumbnail::Error) -> Self { use coreav_thumbnail::Error as T; @@ -552,8 +561,8 @@ fn execute( #[cfg(feature = "h264-native")] let (program, frame_rate) = match options.native_h264 { Some(native) => { - if options.matroska_output.is_some() { - return Err(Error::NativeIneligible("native H.264 requires MP4 output")); + if options.matroska_output == Some(coreav_mkv::DocType::Webm) { + return Err(Error::NativeIneligible("native H.264 cannot write WebM")); } let source_rate = options .frame_rates @@ -791,21 +800,47 @@ fn execute( ), }; let remux = if let Some(doc_type) = options.matroska_output { - Remuxed::OutputMatroska( - coreav_isobmff_write::mkv_output::write_output( + let output_options = coreav_isobmff_write::mkv_output::OutputOptions { + matroska_source: kind == SourceKind::Matroska, + doc_type, + streams, + }; + #[cfg(feature = "h264-native")] + let cadence = match (&completed.encoding, options.native_h264) { + (Encoding::H264 { frame_rate, .. }, Some(_)) => Some( + coreav_isobmff_write::mkv_output::VideoCadence::new( + video.stream_index, + frame_rate.num, + frame_rate.den, + ) + .map_err(native_matroska_error)?, + ), + _ => None, + }; + #[cfg(not(feature = "h264-native"))] + let cadence = None; + let summary = match cadence { + Some(cadence) => coreav_isobmff_write::mkv_output::write_output_with_video_cadence( &mut source, - &coreav_isobmff_write::mkv_output::OutputOptions { - matroska_source: kind == SourceKind::Matroska, - doc_type, - streams, - }, + &output_options, + &options.isobmff_limits, + &options.matroska_limits, + replacements, + cadence, + out, + ) + .map_err(native_matroska_error)?, + None => coreav_isobmff_write::mkv_output::write_output( + &mut source, + &output_options, &options.isobmff_limits, &options.matroska_limits, replacements, out, ) .map_err(Error::Matroska)?, - ) + }; + Remuxed::OutputMatroska(summary) } else { match kind { SourceKind::Mp4 => Remuxed::Mp4( @@ -2197,6 +2232,27 @@ mod tests { } use super::*; + #[test] + fn native_matroska_retry_keeps_io_and_malformed_errors_terminal() { + assert!(matches!( + native_matroska_error(coreav_mkv::Error::Unsupported { + reason: "rounded presentation times collide", + }), + Error::NativeIneligible(_) + )); + for error in [ + coreav_mkv::Error::Io(std::io::ErrorKind::UnexpectedEof), + coreav_mkv::Error::InvalidElement { + offset: 0, + id: 0, + reason: "invalid block", + }, + coreav_mkv::Error::Overflow { offset: 0 }, + ] { + assert!(matches!(native_matroska_error(error), Error::Matroska(_))); + } + } + #[cfg(feature = "h264-native")] #[test] fn native_clock_uses_exact_positive_rationals_and_last_duration() { diff --git a/docs/design/cli-native-h264-matroska.md b/docs/design/cli-native-h264-matroska.md index 4a770320..cc8ab3ac 100644 --- a/docs/design/cli-native-h264-matroska.md +++ b/docs/design/cli-native-h264-matroska.md @@ -12,11 +12,15 @@ For native H.264 Matroska replacements only, derive DefaultDuration from the enc The exact rational remains in the H.264 VUI. DefaultDuration differs from its exact period by at most half a nanosecond, and each absolute block PTS retains the existing millisecond quantization rather than accumulating rounding drift. Common rates must read back exactly through the pinned oracle; unusual rates are checked against the independently parsed integer duration and timestamp quantization, not an assumed ffprobe fraction. +For nominal 29/7 fps, the pinned oracle reports `r_frame_rate=58/7` and `avg_frame_rate=29/7`. This one field-clock readback is recorded explicitly; the independent SPS check still requires `time_scale / (2 * num_units_in_tick) = 29/7` (AVC E.2.1), and DefaultDuration still requires the rounded nominal frame period (RFC 9559 Section 5.1.4.1.13). No other guessed rate is accepted by this generated comparison. + New native Matroska admission requires a nominal period of at least one millisecond and strictly increasing output PTS after rounding. Higher rates or collisions retain their previous external path. No native Matroska command exists before this change, so these boundaries do not move an existing native command. Keep the merged native timing predicate, including its legacy single-picture and terminal-zero defaults, unchanged for MP4. ## Boundary -Add a checked video-cadence value and an explicit writer entrypoint for one H.264 video replacement. Existing writer calls retain their current behavior. The new entrypoint validates that the named stream is the actual video replacement, supplies its nominal default duration, and rejects rounded timestamp collisions before publication. Audio packets, source offsets, stream selection, display dimensions, codec private data, cluster policy and all other writer paths remain unchanged. +Add a checked video-cadence value and an explicit writer entrypoint for one H.264 video replacement. Existing writer calls retain their current behavior. The new entrypoint validates that the named stream is the actual video replacement, supplies its nominal default duration, and rejects rounded timestamp collisions before publication. Audio payloads, stream selection, display dimensions and cluster policy remain unchanged. + +For copied Opus from ISO base media, this new entrypoint follows the original source edit list, not the informative dOps PreSkip field (Opus ISO mapping Sections 4.3.2 and 4.4). It carries that edit's trim into CodecDelay and OpusHead and retains its declared terminal presentation. The ordinary writer still takes the greater of the edit trim and PreSkip; correcting that existing path is separate work. In particular, media time zero with PreSkip of 312 and a declared 7,992-sample presentation retains all 7,992 samples in native Matroska, instead of the ordinary writer's 7,680 samples. Native MP4 remains byte-identical to its actual base. The transcode pipeline uses that entrypoint only for a completed native H.264 Matroska encode, with the admitted encoder frame rate. MP4 never constructs the cadence override. Unsupported native cadence retries the unchanged external command under the original deadline; I/O, malformed-input and timeout errors remain terminal. @@ -34,5 +38,6 @@ The transcode pipeline uses that entrypoint only for a completed native H.264 Ma - https://www.rfc-editor.org/rfc/rfc9559.html#section-5.1.4.1.13 - https://www.matroska.org/technical/notes.html - https://www.matroska.org/technical/elements.html +- https://www.opus-codec.org/docs/opus_in_isobmff.html Refs coreav-dev/coreav#25. diff --git a/docs/design/cli-native-h264-metadata.md b/docs/design/cli-native-h264-metadata.md index f83a1d20..56902e58 100644 --- a/docs/design/cli-native-h264-metadata.md +++ b/docs/design/cli-native-h264-metadata.md @@ -2,7 +2,7 @@ ## Scope -Extend the explicit MP4 encoder preference from coreav-dev/coreav#509 using the checked timing and sample-aspect types from coreav-dev/coreav#511. Admit supported positive constant rational frame rates and declared non-square sample aspects. Keep the default build, release feature sets, unflagged commands, original fallback arguments, command deadline, geometry, pixel-format and color exclusions unchanged. Matroska output remains separate work. +Extend the explicit MP4 encoder preference from coreav-dev/coreav#509 using the checked timing and sample-aspect types from coreav-dev/coreav#511. Admit supported positive constant rational frame rates and declared non-square sample aspects. Keep the default build, release feature sets, unflagged commands, original fallback arguments, command deadline, geometry, pixel-format and color exclusions unchanged. Matroska output is covered by the separate [cadence design](cli-native-h264-matroska.md). ## Exact presentation clock diff --git a/docs/design/cli-native-h264.md b/docs/design/cli-native-h264.md index 5e9685c1..b79e34e2 100644 --- a/docs/design/cli-native-h264.md +++ b/docs/design/cli-native-h264.md @@ -8,9 +8,9 @@ The selector belongs to CoreAV, before the subcommand. A new codec name would re ## Admission and fallback -The existing argument parser and transcode planner remain authoritative. Native selection requires explicit effective `-c:v libx264`, a file output in MP4, and no unsupported encoder options. Integer `-crf` values from 10 through 51 map to `RateMode::Crf`; integer `-qp` values in the same range map to `RateMode::FixedQp`. Neither option means CRF 23. Both together, fractional values, bitrate, VBV, profiles, B-frame controls, presets, filters, and other unmodeled controls keep the existing path. The original FFmpeg arguments are never rewritten for fallback. +The existing argument parser and transcode planner remain authoritative. Native selection requires explicit effective `-c:v libx264`, a file output in MP4 or Matroska, and no unsupported encoder options. Integer `-crf` values from 10 through 51 map to `RateMode::Crf`; integer `-qp` values in the same range map to `RateMode::FixedQp`. Neither option means CRF 23. Both together, fractional values, bitrate, VBV, profiles, B-frame controls, presets, filters, and other unmodeled controls keep the existing path. The original FFmpeg arguments are never rewritten for fallback. -Verification narrowed the initial MP4 and Matroska design to MP4. The existing Matroska cadence calculation omits `DefaultDuration` when rounded nanosecond intervals differ. Pinned ffprobe then reports 60 fps for the native stream instead of 30. Matroska therefore keeps the existing external path; correcting its shared cadence calculation is separate work. +The [Matroska cadence design](cli-native-h264-matroska.md) supplies `DefaultDuration` from the exact native frame rate rather than inferring it from rounded packet intervals. Matroska retains its existing millisecond timestamps. Rates above 1000 fps and presentation times that collide after rounding keep the existing external path. WebM remains excluded. The default writer, external encoders and native MP4 retain their existing behavior. Decoded pictures must be progressive planar 8-bit 4:2:0, with even dimensions from 16 through 1920 horizontally and 16 through 1080 vertically. The source must also fit those dimensions. The [metadata design](cli-native-h264-metadata.md) admits supported positive constant rational frame rates from the exact presentation clock and retains declared non-square sample aspects in both VUI and MP4. Variable or rounded alternating clocks and unrepresentable ratios keep the external path. Absent, unspecified and square aspects preserve the former native signalling. Unsupported color descriptions also keep the external path. The adapter maps absent color code points to unspecified, without converting samples. @@ -25,7 +25,7 @@ The native path checks its deadline before and after each bounded picture. It do - Compare default-build command output with the pre-change binary, and compare feature-enabled commands without the flag with today's external path. - Exercise every excluded option and input category, requiring unchanged fallback arguments and byte-identical output with and without the flag. - Encode CRF and fixed-QP boundary values through the CLI, check emitted syntax and clocks, and decode the stored output with pinned FFmpeg 9.0.2 and CoreAV. -- Compare complete native MP4 bytes across thread counts, retain exact external Matroska output, and run the existing CLI limit and timeout tests. +- Compare complete existing native MP4 bytes with the actual base across metadata, quality, threads, GOP, input, audio and selector cases. Check native Matroska cadence, complete access units and reconstruction, retain exact unselected and external output, and run the existing CLI limit and timeout tests. - Check default and release feature graphs, generated command documentation, public text, DCO, CI, and exact-head similarity. -Speed and quality comparisons are outside this change. Matroska output admission remains separate work. +Speed and quality comparisons are outside this change. diff --git a/scripts/native_h264_cli.py b/scripts/native_h264_cli.py index 1b4df53a..d75fe409 100644 --- a/scripts/native_h264_cli.py +++ b/scripts/native_h264_cli.py @@ -2,6 +2,7 @@ """Generated CLI encoding, unchanged defaults, and exact external fallback.""" import argparse from fractions import Fraction +import hashlib import json import os from pathlib import Path @@ -13,6 +14,7 @@ sys.path.insert(0, str(Path(__file__).resolve().parent)) import h264_crf_conformance as crf import h264_p_conformance as syntax +import native_h264_matroska as matroska import test_oracle import track_boxes @@ -29,6 +31,126 @@ def same(actual, expected, label): raise ValueError(f'{label} differs') +def native_pair(candidate, baseline, command, *, env, group, label, groups): + output = Path(command[-1]) + previous = output.with_name(output.stem + '.baseline' + output.suffix) + for executable, destination in ((candidate, output), (baseline, previous)): + try: + run([executable, '--native-h264-encoder', 'ffmpeg', *command[:-1], destination], env=env) + except ValueError as error: + raise ValueError(f'actual-base/{group}/{label}: {error}') from error + same(output.read_bytes(), previous.read_bytes(), f'actual-base/{group}/{label}/whole MP4 bytes') + groups.setdefault(group, []).append(label) + + +def byte_groups(groups): + return {name: dict(count=len(labels), cases=labels) for name, labels in groups.items()} + + +def deterministic_fallback(ffmpeg, directory): + directory.mkdir(parents=True, exist_ok=True) + path = directory / 'ffmpeg' + path.write_text(f'#!{sys.executable}\nimport os, sys\n' + f'os.execv({str(ffmpeg)!r}, [{str(ffmpeg)!r}, *sys.argv[1:-1], ' + '"-fflags", "+bitexact", sys.argv[-1]])\n') + path.chmod(0o755) + return path + + +def require_fallback_success(status, contents, label): + if status != 0 or contents == b'preserved destination': + raise ValueError(f'fallback/{label}/expected successful oracle output replacing destination') + + +def oracle_rates(stream, rate, common): + reported = {field: Fraction(stream[field]) for field in ('r_frame_rate', 'avg_frame_rate')} + interpretation = 'nominal-frame-rate' + for field, value in reported.items(): + if common: + same(value, rate, f'oracle common-rate {field}') + if (not common and field == 'r_frame_rate' and rate == Fraction(29, 7) + and value == Fraction(58, 7) and reported['avg_frame_rate'] == rate): + interpretation = 'known-29/7-sps-field-clock' + continue + if value <= 0 or abs(1 / value - 1 / rate) > Fraction(1, 1_000_000_000): + raise ValueError(f'oracle {field} nominal period exceeds one-nanosecond bound') + return dict(oracle_r_frame_rate=stream['r_frame_rate'], + oracle_avg_frame_rate=stream['avg_frame_rate'], oracle_rate_interpretation=interpretation) + + +def unchanged_outputs(args, root, source_path, environment, fallback_environment, *, commands=None): + if commands is None: + commands = [('default-copy', ['-c', 'copy']), + ('external', ['-an', '-c:v', 'libx264', '-crf', '23'])] + groups = {} + for container in ('mp4', 'mkv'): + for label, command in commands: + for mode, candidate, baseline in ( + ('unselected', args.candidate, args.baseline_external), + ('default', args.default_candidate, args.baseline_default), + ): + previous = root / f'{label}-{mode}-base.{container}' + current = root / f'{label}-{mode}.{container}' + selected_environment = fallback_environment if container == 'mkv' else environment + for binary, output in ((baseline, previous), (candidate, current)): + run([binary, 'ffmpeg', '-i', source_path, *command, output], env=selected_environment) + same(current.read_bytes(), previous.read_bytes(), + f'actual-base/{container}/{label}/{mode}/whole bytes') + groups.setdefault(f'{container}-{mode}', []).append(label) + return groups + + +def copied_audio_sources(root, ffmpeg, video30, video25): + sources = [] + for label, container, encoder, rate, offset in [ + ('audio-copy', 'mp4', 'aac', 30, '0'), + ('audio-mp4-mp3', 'mp4', 'libmp3lame', 30, '0'), + ('audio-mp4-opus', 'mp4', 'libopus', 30, '0'), + ('audio-mkv-aac', 'mkv', 'aac', 25, '0'), + ('audio-mkv-opus', 'mkv', 'libopus', 25, '0'), + ('audio-offset', 'mp4', 'aac', 30, '0.04'), + ('video-offset', 'mp4', 'aac', 30, '-0.04'), + ]: + path = root / f'{label}-source.{container}' + run([ffmpeg, '-v', 'error', '-i', video25 if rate == 25 else video30, '-itsoffset', offset, + '-f', 'lavfi', '-i', 'sine=frequency=997:sample_rate=48000:duration=0.16', + '-map', '0:v:0', '-map', '1:a:0', '-c:v', 'copy', '-c:a', encoder, + '-avoid_negative_ts', 'make_non_negative', path]) + sources.append((label, path, Fraction(rate))) + return sources + + +def opus_source_pcm(source, prefix, ffmpeg, ffprobe): + original = source.read_bytes() + if source.suffix == '.mp4': + facts = matroska.opus_mp4_source(source) + decoder_input = prefix.with_suffix('.oracle-only.mp4') + decoder_input.write_bytes(facts.pop('clone')) + input_options = ['-ignore_editlist', '1'] + method = 'original-mp4-edit-over-zero-preskip-unedited-decode' + else: + facts = matroska.opus_matroska_source(original) + decoder_input, input_options = source, [] + method = 'original-matroska-declared-presentation' + readback = json.loads(run([ffprobe, '-v', 'error', '-select_streams', 'a:0', + '-show_streams', '-show_packets', '-of', 'json', source]).stdout) + stream, = readback['streams'] + same(len(readback['packets']), len(facts['packet_sha256']), 'source Opus: complete oracle packet readback') + facts['reported_pts'] = [str(Fraction(packet['pts']) * Fraction(stream['time_base'])) + for packet in readback['packets']] + decoded = prefix.with_suffix('.source.f32le') + run([ffmpeg, '-v', 'error', '-xerror', *input_options, '-i', decoder_input, + '-map', '0:a:0', '-vn', '-c:a', 'pcm_f32le', '-f', 'f32le', decoded]) + pcm = decoded.read_bytes() + facts['oracle_decoded_samples'] = len(pcm) // (facts['channels'] * 4) + expected = matroska.opus_presentation_slice(pcm, facts) if source.suffix == '.mp4' else pcm + matroska.compare_opus_pcm(expected, expected, facts) + same(source.read_bytes(), original, 'source Opus: original input bytes remain unchanged') + facts['reference_method'] = method + facts['expected_pcm_sha256'] = hashlib.sha256(expected).hexdigest() + return expected, facts + + def annexb_units(data): parts = re.split(rb'\x00\x00\x00?\x01', data) if parts.pop(0) or not parts or any(not part for part in parts): @@ -120,6 +242,142 @@ def sps_metadata(nal): return Fraction(scale, 2 * tick), aspect +def matroska_matrix(args, tools, root, source, native, native_only, source_path, + legacy_sources, gop_source): + cases = [] + for index, (rate, sar) in enumerate([ + ('25', None), ('30', '1/1'), ('24000/1001', '12/11'), ('30000/1001', '16/15'), + ('25/2', '4/3'), ('1000/33', '40/33'), ('60000/1001', '17/13'), + ('29/7', '65535/65534'), ('1000', None), + ]): + extra = ('-vf', f'setsar={sar}:max=65535') if sar else () + path = source(f'mkv-rate-{index}', rate=rate, extra=extra) + for mode, quality in (('crf', 23), ('qp', 28)): + cases.append((f'rate-{index}-{mode}', path, Fraction(rate), Fraction(sar or 1), + 18, 34, 4, ['-an', f'-{mode}', quality], index < 4)) + for mode, quality in [('crf', 10), ('crf', 23), ('crf', 51), ('qp', 10), ('qp', 28), ('qp', 51)]: + cases.append((f'quality-{mode}-{quality}', source_path, Fraction(30), Fraction(1), + 18, 34, 4, ['-an', f'-{mode}', quality], True)) + for label, path in legacy_sources: + cases.append((f'legacy-{label}', path, Fraction(30), Fraction(1), 18, 34, + 1 if label == 'one-zero-duration' else 4, ['-an'], True)) + for rate, sar in [('30000/1001', '16/15'), ('25', '17/13')]: + path = source(f'mkv-single-{len(cases)}', rate=rate, frames=1, + extra=('-vf', f'setsar={sar}:max=65535')) + cases.append((f'single-{len(cases)}', path, Fraction(rate), Fraction(sar), + 18, 34, 1, ['-an'], True)) + cases.append(('gop-251', gop_source, Fraction(30), Fraction(1), 16, 16, 251, ['-an'], True)) + + mkv_source = root / 'admitted-input.mkv' + video25 = source('admitted-input-25', rate='25') + run([tools.ffmpeg, '-v', 'error', '-i', video25, '-c', 'copy', '-fflags', '+bitexact', mkv_source]) + origin = source('source-origin', extra=('-output_ts_offset', '2')) + audio_sources = copied_audio_sources(root, tools.ffmpeg, source_path, video25) + opus_sources = {path: opus_source_pcm(path, root / f'original-{label}', tools.ffmpeg, tools.ffprobe) + for label, path, _ in audio_sources if label.endswith('-opus')} + axes = [ + ('matroska-input', mkv_source, Fraction(25), ['-an']), + ('source-origin', origin, Fraction(30), ['-an', '-fps_mode', 'passthrough']), + ('mapped-video', source_path, Fraction(30), ['-map', '0:v:0', '-an']), + ('remove-readd-map', source_path, Fraction(30), ['-map', '0', '-map', '-0:v', '-map', '0:v:0', '-an']), + ('explicit-pixel-format', source_path, Fraction(30), ['-an', '-pix_fmt', 'yuv420p']), + ] + for label, path, rate in audio_sources: + axes.append((label, path, rate, ['-c:a', 'copy', '-fps_mode', 'passthrough'])) + axes.append(('mapped-audio-copy', audio_sources[0][1], Fraction(30), + ['-map', '0:v:0', '-map', '0:a:0', '-c:a', 'copy', '-fps_mode', 'passthrough'])) + for label, path, rate, extra in axes: + native(['-i', path, '-c:v:0', 'libx264', *extra, root / f'axis-{label}.mp4'], 'source-audio-selection', label) + cases.append((f'axis-{label}', path, rate, Fraction(1), 18, 34, 4, extra, True)) + + def probe(path, selection='v:0', hashes=False): + return json.loads(run([tools.ffprobe, '-v', 'error', '-select_streams', selection, + '-show_streams', '-show_packets', + *(['-show_data_hash', 'sha256'] if hashes else []), + '-of', 'json', path]).stdout) + + rows = [] + for label, path, rate, sar, width, height, frames, extra, common in cases: + identity = None + opus_reference = opus_sources.get(path) + for threads in ('1', '2', '8', '0', 'auto'): + case = f'matroska/{label}/threads-{threads}' + peer = root / f'mkv-{label}-{threads}.mp4' + command = ['-i', path, '-c:v', 'libx264', *extra, '-threads', threads] + native([*command, peer], 'matroska-peer', f'{label}-threads-{threads}') + output = peer.with_suffix('.mkv') + try: + run([args.candidate, '--native-h264-encoder', 'ffmpeg', *command, output], env=native_only) + contents = output.read_bytes() + if identity is not None: + same(contents, identity, 'complete thread-independent Matroska bytes') + identity = contents + info = probe(peer) + stream, = info['streams'] + times = [Fraction(p['pts']) * Fraction(stream['time_base']) for p in info['packets']] + same(len(times), frames, 'same-head MP4 frame count') + same([time - times[0] for time in times], [Fraction(i) / rate for i in range(frames)], + 'same-head MP4 exact cadence') + independent = matroska.validate(contents, rate=rate, sar=sar, width=width, height=height, + times=times, sps_reader=sps_metadata, mp4=matroska.mp4_video(peer)) + same([i for i, p in enumerate(independent['packets']) if p['key']], + list(range(0, frames, 250)), '250-picture keyframe interval') + stored = probe(output) + stored_stream, = stored['streams'] + same(len(stored['packets']), frames, 'oracle Matroska frame count') + same(Fraction(stored_stream['sample_aspect_ratio'].replace(':', '/')), sar, + 'oracle Matroska sample aspect') + same(Fraction(stored_stream['display_aspect_ratio'].replace(':', '/')), + Fraction(width, height) * sar, 'oracle Matroska display aspect') + same([Fraction(p['pts']) * Fraction(stored_stream['time_base']) for p in stored['packets']], + [Fraction(p['pts'], 1000) for p in independent['packets']], 'oracle and EBML presentation clock') + readback = oracle_rates(stored_stream, rate, common) + if threads == '1': + decoded = [] + for container in (peer, output): + destination = container.with_suffix(container.suffix + '.decoded.yuv') + run([tools.ffmpeg, '-v', 'error', '-xerror', '-i', container, '-an', + '-pix_fmt', 'yuv420p', '-fps_mode', 'passthrough', '-f', 'rawvideo', destination]) + decoded.append(destination.read_bytes()) + same(*decoded, 'same-head full pinned-decoder reconstruction') + same(len(decoded[0]), frames * width * height * 3 // 2, 'complete decoded picture bytes') + own = output.with_suffix('.own.yuv') + run([args.candidate, 'ffmpeg', '-i', output, '-an', '-c:v', 'rawvideo', + '-pix_fmt', 'yuv420p', '-f', 'rawvideo', own], env=native_only) + same(own.read_bytes(), decoded[0], 'complete native Matroska decoder reconstruction') + audio = [probe(container, 'a:0', True) for container in (peer, output)] + same([p['data_hash'] for p in audio[0]['packets']], + [p['data_hash'] for p in audio[1]['packets']], 'copied audio complete packet bytes') + if audio[0]['packets']: + clocks = [[Fraction(p['pts']) * Fraction(info['streams'][0]['time_base']) + for p in info['packets']] for info in audio] + if opus_reference and path.suffix == '.mkv': + matroska.compare_opus_matroska_timeline(matroska.opus_matroska_source(contents), + clocks[1], opus_reference[1]) + else: + expected_clocks = opus_reference[1]['clocks'] if opus_reference else clocks[0] + same(clocks[1], [Fraction(matroska.round_timestamp(t * 1000), 1000) for t in expected_clocks], + 'copied audio original-source rounded PTS' if opus_reference else 'copied audio absolute rounded PTS') + if opus_reference: + expected_pcm, facts = opus_reference + same([p['data_hash'].split(':', 1)[1] for p in audio[1]['packets']], + facts['packet_sha256'], 'copied Opus complete original-source packet bytes') + actual_pcm = output.with_suffix('.opus.f32le') + run([tools.ffmpeg, '-v', 'error', '-xerror', '-i', output, '-map', '0:a:0', + '-vn', '-c:a', 'pcm_f32le', '-f', 'f32le', actual_pcm]) + matroska.compare_opus_pcm(actual_pcm.read_bytes(), expected_pcm, facts) + opus_proof = {} + if opus_reference: + facts = opus_reference[1] + opus_proof['source_opus_pcm'] = {key: value for key, value in facts.items() if key != 'clocks'} + opus_proof['source_opus_pcm']['verification'] = 'direct-decode' if threads == '1' else 'complete-thread-byte-identity' + rows.append(dict(case=label, threads=threads, frames=frames, rate=str(rate), sar=str(sar), + default_duration_ns=independent['duration'], common_rate=common, **readback, **opus_proof)) + except (ValueError, KeyError, StopIteration) as error: + raise ValueError(f'{case}: {error}') from error + return rows + + def verify(args): tools = test_oracle.require(args.ffmpeg, args.ffmpeg.with_name('ffprobe')) root = args.output.resolve() @@ -128,7 +386,13 @@ def verify(args): 'COREAV_FFMPEG': str(tools.ffmpeg), 'COREAV_FALLBACK': str(tools.ffmpeg), 'COREAV_STRICT_SAFE': '0'} native_only = {**environment, 'COREAV_FFMPEG': '/nonexistent/native-cli-ffmpeg', - 'COREAV_FALLBACK': '/nonexistent/native-cli-fallback'} + 'COREAV_FALLBACK': '/nonexistent/native-cli-fallback', + 'PATH': '/nonexistent/native-cli-path'} + baseline_groups = {} + + def native(command, group, label): + native_pair(args.candidate, args.baseline_native, command, env=native_only, + group=group, label=label, groups=baseline_groups) def source(name, width=18, height=34, rate='30', extra=(), frames=4, raw=None): path = root / f'{name}.mp4' @@ -147,6 +411,9 @@ def source(name, width=18, height=34, rate='30', extra=(), frames=4, raw=None): source_info = json.loads(run([tools.ffprobe, '-v', 'error', '-show_streams', '-of', 'json', source_path]).stdout)['streams'][0] same([source_info.get(key) for key in ('color_space', 'color_transfer', 'color_primaries')], ['bt709'] * 3, 'generated BT.709 source metadata') + fallback_environment = {**environment, 'COREAV_FALLBACK': str(deterministic_fallback( + tools.ffmpeg, root / 'deterministic-fallback'))} + unchanged_groups = unchanged_outputs(args, root, source_path, environment, fallback_environment) raw = root / 'decoded-source.yuv' run([tools.ffmpeg, '-v', 'error', '-i', source_path, '-an', '-pix_fmt', 'yuv420p', '-f', 'rawvideo', raw]) rows = [] @@ -162,7 +429,7 @@ def source(name, width=18, height=34, rate='30', extra=(), frames=4, raw=None): output = root / f'native-{mode}-{quality}-{threads}.{container}' command = ['-i', source_path, '-an', '-c:v', 'libx264', f'-{mode}', quality, '-threads', threads, output] - run([args.candidate, '--native-h264-encoder', 'ffmpeg', *command], env=native_only) + native(command, 'quality-and-threads', f'{mode}-{quality}-threads-{threads}') if identity is None: identity = output.read_bytes() else: @@ -220,8 +487,8 @@ def source(name, width=18, height=34, rate='30', extra=(), frames=4, raw=None): identity = None for threads in ('1', '2', '8', '0', 'auto'): output = root / f'metadata-{index}-{mode}-{threads}.mp4' - run([args.candidate, '--native-h264-encoder', 'ffmpeg', '-i', path, '-an', - '-c:v', 'libx264', f'-{mode}', quality, '-threads', threads, output], env=native_only) + native(['-i', path, '-an', '-c:v', 'libx264', f'-{mode}', quality, + '-threads', threads, output], 'metadata-and-threads', f'{index}-{mode}-threads-{threads}') if identity is not None: same(output.read_bytes(), identity, 'metadata thread-independent complete output') continue @@ -276,20 +543,13 @@ def source(name, width=18, height=34, rate='30', extra=(), frames=4, raw=None): final_zero.write_bytes(terminal_duration(source_path.read_bytes(), 0)) legacy_sources.extend([('one-zero-duration', one_zero), ('final-zero-duration', final_zero)]) for label, path in legacy_sources: - previous = [] - for index, executable in enumerate((args.baseline_native, args.candidate)): - output = root / f'legacy-{label}-{index}.mp4' - run([executable, '--native-h264-encoder', 'ffmpeg', '-i', path, '-an', '-c:v', 'libx264', output], env=native_only) - previous.append(output.read_bytes()) - same(*previous, f'unchanged previously eligible {label} bytes') - print('native base comparisons: ' + ', '.join(label for label, _ in legacy_sources)) + native(['-i', path, '-an', '-c:v', 'libx264', root / f'legacy-{label}.mp4'], 'legacy', label) flat = root / 'gop.yuv' flat.write_bytes(bytes([128]) * (384 * 251)) gop_source = source('gop', width=16, height=16, frames=251, raw=flat) gop_output = root / 'gop-native.mp4' - run([args.candidate, '--native-h264-encoder', 'ffmpeg', '-i', gop_source, - '-an', '-c:v', 'libx264', gop_output], env=native_only) + native(['-i', gop_source, '-an', '-c:v', 'libx264', gop_output], 'gop', '251-pictures') gop_packets = json.loads(run([tools.ffprobe, '-v', 'error', '-show_packets', '-of', 'json', gop_output]).stdout)['packets'] same(len(gop_packets), 251, 'default-quality GOP picture count') same([i for i,p in enumerate(gop_packets) if 'K' in p['flags']], [0, 250], 'native IDR interval') @@ -298,8 +558,20 @@ def source(name, width=18, height=34, rate='30', extra=(), frames=4, raw=None): same(gop_decoded.stat().st_size, 251 * 384, 'complete GOP decode') fallback_cases = [] + fallback_results = [] def compare(source_path, extra, label, container='mp4'): + comparison_environment = fallback_environment if container in ('mkv', 'webm') else environment + if container in ('mkv', 'webm'): + destination = root / f'excluded-{label}.{container}' + destination.write_bytes(b'preserved destination') + before = {path.name for path in root.iterdir()} + result = run([args.candidate, '--native-h264-encoder', 'ffmpeg', '-y', '-i', source_path, + '-an', '-c:v', 'libx264', *extra, destination], env=native_only, success=False) + if result.returncode == 0: + raise ValueError(f'excluded/{label}/native-only unexpectedly succeeded') + same(destination.read_bytes(), b'preserved destination', f'excluded/{label}/destination preservation') + same({path.name for path in root.iterdir()}, before, f'excluded/{label}/staging cleanup') outputs = [] statuses = [] for selected in (False, True): @@ -307,12 +579,31 @@ def compare(source_path, extra, label, container='mp4'): output.write_bytes(b'preserved destination') command = [args.candidate, *(['--native-h264-encoder'] if selected else []), 'ffmpeg', '-y', '-i', source_path, '-an', '-c:v', 'libx264', *extra, output] - result = run(command, env=environment, success=False) + result = run(command, env=comparison_environment, success=False) statuses.append(result.returncode) outputs.append(output.read_bytes()) - same(statuses[1], statuses[0], 'fallback exit status') + same(statuses[1], statuses[0], f'fallback/{label}/exit status') same(outputs[1], outputs[0], f'complete fallback bytes ({label})') + required_success = label in ('unsupported-matroska-option', 'matroska-high-rate', 'matroska-rounded-collision') + if required_success: + for mode, status, contents in zip(('unselected', 'selected'), statuses, outputs): + require_fallback_success(status, contents, f'{label}/{mode}') + receipt = dict(case=label, container=container, candidate_unselected=statuses[0], + candidate_selected=statuses[1], output_replaced=outputs[0] != b'preserved destination') + for name, binary, selected in [('external-base', args.baseline_external, False), + ('native-base', args.baseline_native, True)]: + output = root / f'fallback-{label}-{name}.{container}' + output.write_bytes(b'preserved destination') + result = run([binary, *(['--native-h264-encoder'] if selected else []), 'ffmpeg', + '-y', '-i', source_path, '-an', '-c:v', 'libx264', *extra, output], + env=comparison_environment, success=False) + same(result.returncode, statuses[0], f'actual-base/fallback/{label}/{name}/status') + same(output.read_bytes(), outputs[0], f'actual-base/fallback/{label}/{name}/whole bytes') + if required_success: + require_fallback_success(result.returncode, output.read_bytes(), f'{label}/{name}') + receipt[name] = result.returncode fallback_cases.append(label) + fallback_results.append(receipt) options = [('-profile:v', 'high'), ('-profile:v', 'baseline'), ('-bf', '2'), ('-b:v', '100k'), ('-maxrate', '100k', '-bufsize', '200k'), @@ -322,7 +613,13 @@ def compare(source_path, extra, label, container='mp4'): ('-x264-params', 'cabac=1'), ('-vf', 'scale=32:32'), ('-s', '32x32')] for index, extra in enumerate(options): compare(source_path, extra, f'option-{index}') - compare(source_path, (), 'matroska', 'mkv') + compare(source_path, ('-map', '0:v:0?'), 'optional-map') + compare(source_path, ('-bf', '2'), 'unsupported-matroska-option', 'mkv') + compare(source_path, (), 'webm', 'webm') + high_rate = source('high-rate', rate='1001') + compare(high_rate, (), 'matroska-high-rate', 'mkv') + collision = source('rounded-collision', rate='2000', frames=4) + compare(collision, (), 'matroska-rounded-collision', 'mkv') for name, parameters in [('small', dict(width=14, height=16)), ('wide', dict(width=1922, height=16, frames=1)), ('tall', dict(width=16, height=1082, frames=1)), @@ -337,6 +634,7 @@ def compare(source_path, extra, label, container='mp4'): '-fps_mode', 'passthrough')) compare(variable, ('-fps_mode', 'passthrough'), 'variable-rate') compare(variable, (), 'variable-native-clock') + compare(variable, (), 'matroska-variable-clock', 'mkv') rounded = source('rounded-clock', rate='30000/1001', extra=('-video_track_timescale', '1000')) compare(rounded, (), 'rounded-clock') for label, parameters in [ @@ -395,31 +693,41 @@ def compare(source_path, extra, label, container='mp4'): same({path.name for path in root.iterdir()}, before, 'late-refusal staging cleanup') compare(late, ('-qp', '10'), 'late-coding-limit') - for label, binary, command in [ - ('default-copy', args.baseline_default, ['-c', 'copy']), - ('external', args.baseline_external, ['-an', '-c:v', 'libx264', '-crf', '23']), - ]: - outputs = [] - for index, executable in enumerate((binary, args.candidate)): - output = root / f'{label}-{index}.mp4' - run([executable, 'ffmpeg', '-i', source_path, *command, output], env=environment) - outputs.append(output.read_bytes()) - same(*outputs, f'unchanged {label} bytes') - if label == 'default-copy': - output = root / 'default-current.mp4' - run([args.default_candidate, 'ffmpeg', '-i', source_path, *command, output], env=environment) - same(output.read_bytes(), outputs[0], 'default-build bytes against base') - - (root / 'summary.json').write_text(json.dumps(dict(native=rows, metadata=metadata_rows, legacy_native_cases=len(legacy_sources), legacy_native_shapes=[label for label, _ in legacy_sources], gop_frames=251, fallback_cases=fallback_cases, - default_bytes_unchanged=True), indent=2) + '\n') - print(f'native CLI: {len(rows)} conformance cases, {len(metadata_rows)} exact rate/SAR cases, thread identity, fallback and default byte checks passed') + matroska_rows = matroska_matrix(args, tools, root, source, native, native_only, + source_path, legacy_sources, gop_source) + for group, labels in unchanged_outputs( + args, root, root / 'audio-mp4-opus-source.mp4', environment, fallback_environment, + commands=[('opus-source-edit', ['-c:v', 'libx264', '-c:a', 'copy', '-fps_mode', 'passthrough'])], + ).items(): + unchanged_groups[group].extend(labels) + summary = dict(native=rows, metadata=metadata_rows, legacy_native_cases=len(legacy_sources), + legacy_native_shapes=[label for label, _ in legacy_sources], gop_frames=251, + fallback_cases=fallback_cases, default_bytes_unchanged=True, + fallback_results=fallback_results, + baseline_revision=args.baseline_revision, + actual_base_mp4_whole_bytes=byte_groups(baseline_groups), + actual_base_default_unselected_external_whole_bytes=byte_groups(unchanged_groups), + actual_base_fallback_whole_bytes=dict(count=len(fallback_cases) * 2, cases=fallback_cases), + matroska_fallback_oracle_output_flags=['-fflags', '+bitexact'], + matroska_fallback_oracle_contexts=['excluded-controls', 'default-unselected-external-byte-comparisons'], + source_opus_pcm=dict(cases=sum('source_opus_pcm' in row for row in matroska_rows), + direct_decodes=sum(row.get('source_opus_pcm', {}).get('verification') == 'direct-decode' + for row in matroska_rows)), + native_matroska=matroska_rows) + (root / 'summary.json').write_text(json.dumps(summary, indent=2) + '\n') + print(f'native CLI: {sum(map(len, baseline_groups.values()))} actual-base MP4 byte cases, ' + f'{sum(map(len, unchanged_groups.values()))} default/unselected/external byte cases, ' + f'{len(matroska_rows)} native Matroska cases; named groups in summary.json') def main(): parser = argparse.ArgumentParser(description=__doc__) for name in ('candidate', 'default-candidate', 'baseline-default', 'baseline-external', 'baseline-native', 'driver', 'ffmpeg', 'output'): parser.add_argument('--' + name, type=Path, required=True) + parser.add_argument('--baseline-revision', required=True) args = parser.parse_args() + if not re.fullmatch('[0-9a-f]{40}', args.baseline_revision): + parser.error('--baseline-revision must be the full SHA of the checkout used to build the baseline binaries') for name in ('candidate', 'default_candidate', 'baseline_default', 'baseline_external', 'baseline_native', 'driver', 'ffmpeg'): setattr(args, name, getattr(args, name).resolve()) verify(args) diff --git a/scripts/native_h264_matroska.py b/scripts/native_h264_matroska.py new file mode 100644 index 00000000..19bfa41f --- /dev/null +++ b/scripts/native_h264_matroska.py @@ -0,0 +1,324 @@ +"""Independent generated-output checks from RFC 9559 and ISO/IEC 14496-15.""" +from fractions import Fraction +import hashlib + +import track_boxes + + +def require(condition, label): + if not condition: + raise ValueError(label) + + +def round_half_up(value): + value = Fraction(value) + return (2 * value.numerator + value.denominator) // (2 * value.denominator) + + +def round_timestamp(value): + return -round_half_up(-value) if value < 0 else round_half_up(value) + + +def vint(data, at, *, identifier=False): + require(at < len(data) and data[at] != 0, 'EBML invalid variable integer') + width = 9 - data[at].bit_length() + require(width <= (4 if identifier else 8) and at + width <= len(data), + 'EBML truncated variable integer') + value = int.from_bytes(data[at:at + width], 'big') + if not identifier: + value &= (1 << (7 * width)) - 1 + require(value != (1 << (7 * width)) - 1, 'EBML unknown element size') + return value, at + width + + +def elements(data): + at = 0 + while at < len(data): + kind, at = vint(data, at, identifier=True) + size, at = vint(data, at) + require(at + size <= len(data), 'EBML element exceeds parent') + yield kind, data[at:at + size] + at += size + + +def one(children, kind, label, default=None): + found = [body for key, body in children if key == kind] + require(len(found) <= 1, f'{label}: duplicate element') + require(found or default is not None, f'{label}: missing element') + return found[0] if found else default + + +def uint(data): + require(0 < len(data) <= 8, 'EBML invalid unsigned integer') + return int.from_bytes(data, 'big') + + +def avcc(data): + require(len(data) >= 7 and data[0] == 1 and data[4] & 0xfc == 0xfc + and data[5] & 0xe0 == 0xe0, 'CodecPrivate: invalid AVC configuration') + length_size = (data[4] & 3) + 1 + require(length_size in (1, 2, 4), 'CodecPrivate: invalid NAL length size') + at, parameters = 6, [] + for kind, count in ((7, data[5] & 31), (8, None)): + if count is None: + require(at < len(data), 'CodecPrivate: missing PPS count') + count, at = data[at], at + 1 + require(count > 0, 'CodecPrivate: missing parameter sets') + for _ in range(count): + require(at + 2 <= len(data), 'CodecPrivate: truncated parameter length') + size = int.from_bytes(data[at:at + 2], 'big') + at += 2 + require(size > 0 and at + size <= len(data), 'CodecPrivate: truncated parameter set') + nal, at = data[at:at + size], at + size + require(nal[0] & 31 == kind, 'CodecPrivate: incorrect parameter type') + parameters.append(nal) + require(at == len(data), 'CodecPrivate: trailing bytes') + return length_size, parameters + + +def access_unit(data, length_size): + at, nals = 0, [] + while at < len(data): + require(at + length_size <= len(data), 'access unit: truncated NAL length') + size = int.from_bytes(data[at:at + length_size], 'big') + at += length_size + require(size > 0 and at + size <= len(data), 'access unit: truncated NAL') + nals.append(data[at:at + size]) + at += size + require(nals, 'access unit: empty packet') + return nals + + +def read(data): + top = list(elements(data)) + one(top, 0x1a45dfa3, 'EBML header') + segment = list(elements(one(top, 0x18538067, 'Segment'))) + info = list(elements(one(segment, 0x1549a966, 'Info'))) + scale = uint(one(info, 0x2ad7b1, 'TimestampScale')) + tracks = [list(elements(body)) for kind, body in elements(one(segment, 0x1654ae6b, 'Tracks')) + if kind == 0xae] + video = [track for track in tracks if uint(one(track, 0x83, 'TrackType')) == 1] + require(len(video) == 1, 'video: expected one track') + track, = video + number = uint(one(track, 0xd7, 'TrackNumber')) + require(number > 0, 'video: zero track number') + require(one(track, 0x86, 'CodecID') == b'V_MPEG4/ISO/AVC', 'video: incorrect CodecID') + private = one(track, 0x63a2, 'CodecPrivate') + length_size, parameters = avcc(private) + duration = uint(one(track, 0x23e383, 'DefaultDuration')) + dimensions = list(elements(one(track, 0xe0, 'Video'))) + width = uint(one(dimensions, 0xb0, 'PixelWidth')) + height = uint(one(dimensions, 0xba, 'PixelHeight')) + require(width > 0 and height > 0, 'video: zero geometry') + display_unit = uint(one(dimensions, 0x54b2, 'DisplayUnit', b'\0')) + require(display_unit in (0, 3), 'video: unsupported display unit') + dw = uint(one(dimensions, 0x54b0, 'DisplayWidth', width.to_bytes(8, 'big'))) + dh = uint(one(dimensions, 0x54ba, 'DisplayHeight', height.to_bytes(8, 'big'))) + require(dw > 0 and dh > 0, 'video: zero display geometry') + packets = [] + for kind, body in segment: + if kind != 0x1f43b675: + continue + cluster = list(elements(body)) + timestamp = uint(one(cluster, 0xe7, 'Cluster Timestamp')) + for kind, payload in cluster: + if kind not in (0xa3, 0xa0): + continue + group = list(elements(payload)) if kind == 0xa0 else [] + block = one(group, 0xa1, 'Block') if group else payload + track_number, at = vint(block, 0) + require(at + 3 <= len(block), 'Block: truncated header') + if track_number != number: + continue + require(not any(key == 0x9b for key, _ in group), 'video: conflicting BlockDuration') + flags = block[at + 2] + require(flags & 6 == 0, 'video: unexpected lacing') + pts = timestamp + int.from_bytes(block[at:at + 2], 'big', signed=True) + key = not any(key == 0xfb for key, _ in group) if group else bool(flags & 0x80) + payload = block[at + 3:] + nals = access_unit(payload, length_size) + require(key == any(nal[0] & 31 == 5 for nal in nals), 'video: keyframe flag disagrees with IDR') + packets.append(dict(pts=pts, key=key, data=payload, nals=nals)) + require(packets, 'video: missing packets') + return dict(scale=scale, duration=duration, width=width, height=height, + dar=Fraction(dw, dh), private=private, parameters=parameters, packets=packets) + + +def mp4_video(path): + movie = track_boxes.read_movie(path) + video = [track for track in movie['tracks'] if track['handler'] == 'vide'] + require(len(video) == 1, 'MP4: expected one video track') + track, = video + entry = track['entry'] + require(entry['type'] == 'avc1', 'MP4: expected AVC sample entry') + private_box = track_boxes.child(entry['payload'], (78, len(entry['payload'])), b'avcC') + require(private_box is not None, 'MP4: missing avcC') + private = entry['payload'][private_box[0]:private_box[1]] + samples = track['samples'] + packets = list(track_boxes.iter_sample_bytes(path, samples['offsets'], samples['sizes'], 0, + len(samples['sizes']))) + return private, packets, list(samples['sync']) + + +def opus_mp4_source(path): + original = path.read_bytes() + movie = track_boxes.read_movie(path) + tracks = [track for track in movie['tracks'] if track['handler'] == 'soun' + and track['entry']['type'] == 'Opus'] + require(len(tracks) == 1, 'source Opus: expected one MP4 audio track') + track, = tracks + require(track['timescale'] == 48_000, 'source Opus: expected 48 kHz media clock') + require(track['edits'] is not None and len(track['edits']) == 1, + 'source Opus: expected one original presentation edit') + duration, start, speed = track['edits'][0] + require(start >= 0 and duration > 0 and speed == 1, 'source Opus: invalid original presentation edit') + samples = Fraction(duration * 48_000, movie['movie_timescale']) + require(samples.denominator == 1, 'source Opus: fractional presentation sample') + channels = track['entry']['channels'] + moov = track_boxes.child(original, (0, len(original)), b'moov') + offsets = [] + for trak in track_boxes.children(original, moov, b'trak'): + mdia = track_boxes.child(original, trak, b'mdia') + hdlr = track_boxes.child(original, mdia, b'hdlr') + if hdlr is None or original[hdlr[0] + 8:hdlr[0] + 12] != b'soun': + continue + parent = track_boxes.child(original, mdia, b'minf') + parent = track_boxes.child(original, parent, b'stbl') + parent = track_boxes.child(original, parent, b'stsd') + require(parent is not None, 'source Opus: missing original sample entry') + entry = track_boxes.child(original, (parent[0] + 8, parent[1]), b'Opus') + if entry is None: + continue + dops = track_boxes.child(original, (entry[0] + 28, entry[1]), b'dOps') + require(dops is not None and dops[1] - dops[0] >= 11, 'source Opus: missing original dOps') + require(original[dops[0]] == 0 and original[dops[0] + 1] == channels, + 'source Opus: invalid original dOps') + offsets.append(dops[0] + 2) + require(len(offsets) == 1, 'source Opus: expected one original dOps pre-skip') + offset, = offsets + pre_skip = int.from_bytes(original[offset:offset + 2], 'big') + clone = bytearray(original) + clone[offset:offset + 2] = b'\0\0' + table = track['samples'] + packets = list(track_boxes.iter_sample_bytes(path, table['offsets'], table['sizes'], 0, len(table['sizes']))) + clocks, dts = [], table['base_dts'] + for duration, cto in zip(table['durations'], table['cto']): + clocks.append(Fraction(dts + cto - start, 48_000)) + dts += duration + return dict(clone=bytes(clone), channels=channels, start_samples=start, declared_samples=int(samples), + pre_skip=pre_skip, source_sha256=hashlib.sha256(original).hexdigest(), + packet_sha256=[hashlib.sha256(packet).hexdigest() for packet in packets], + clocks=clocks, original_edit=list(track['edits'][0])) + + +def opus_packet_samples(packet): + require(packet, 'source Opus: empty packet') + configuration = packet[0] >> 3 + if configuration < 12: + per_frame = (480, 960, 1920, 2880)[configuration & 3] + elif configuration < 16: + per_frame = (480, 960)[configuration & 1] + else: + per_frame = (120, 240, 480, 960)[configuration & 3] + code = packet[0] & 3 + require(code != 3 or len(packet) >= 2, 'source Opus: missing frame count') + frames = (1, 2, 2, packet[1] & 63 if len(packet) >= 2 else 0)[code] + require(0 < frames * per_frame <= 5760, 'source Opus: invalid packet duration') + return frames * per_frame + + +def opus_matroska_source(data): + segment = list(elements(one(list(elements(data)), 0x18538067, 'source Segment'))) + info = list(elements(one(segment, 0x1549a966, 'source Info'))) + scale = uint(one(info, 0x2ad7b1, 'source TimestampScale', b'\x0f\x42\x40')) + tracks = [list(elements(body)) for kind, body in elements(one(segment, 0x1654ae6b, 'source Tracks')) + if kind == 0xae] + tracks = [track for track in tracks if uint(one(track, 0x83, 'source TrackType')) == 2 + and one(track, 0x86, 'source CodecID') == b'A_OPUS'] + require(len(tracks) == 1, 'source Opus: expected one Matroska audio track') + track, = tracks + number = uint(one(track, 0xd7, 'source TrackNumber')) + private = one(track, 0x63a2, 'source CodecPrivate') + require(len(private) >= 19 and private[:8] == b'OpusHead', 'source Opus: invalid original OpusHead') + channels = private[9] + require(channels > 0, 'source Opus: zero channels') + delay = uint(one(track, 0x56aa, 'source CodecDelay', b'\0')) + delay_samples = Fraction(delay * 48_000, 1_000_000_000) + require(delay_samples.denominator == 1, 'source Opus: fractional codec delay sample') + packets, clocks, padding_samples = [], [], 0 + for kind, body in segment: + if kind != 0x1f43b675: + continue + cluster = list(elements(body)) + timestamp = uint(one(cluster, 0xe7, 'source Cluster Timestamp')) + for kind, payload in cluster: + if kind not in (0xa3, 0xa0): + continue + group = list(elements(payload)) if kind == 0xa0 else [] + block = one(group, 0xa1, 'source Block') if group else payload + track_number, at = vint(block, 0) + require(at + 3 <= len(block), 'source Block: truncated header') + if track_number != number: + continue + require(block[at + 2] & 6 == 0, 'source Opus: unexpected lacing') + relative = int.from_bytes(block[at:at + 2], 'big', signed=True) + packets.append(block[at + 3:]) + clocks.append(Fraction((timestamp + relative) * scale - delay, 1_000_000_000)) + padding = one(group, 0x75a2, 'source DiscardPadding', b'\0') + padding = Fraction(int.from_bytes(padding, 'big', signed=True) * 48_000, 1_000_000_000) + require(padding.denominator == 1 and padding >= 0, 'source Opus: invalid discard padding samples') + padding_samples += int(padding) + samples = sum(opus_packet_samples(packet) for packet in packets) - int(delay_samples) - padding_samples + require(samples > 0, 'source Opus: empty declared presentation') + return dict(channels=channels, declared_samples=samples, pre_skip=int.from_bytes(private[10:12], 'little'), + codec_delay_samples=int(delay_samples), discard_padding_samples=padding_samples, + source_sha256=hashlib.sha256(data).hexdigest(), + packet_sha256=[hashlib.sha256(packet).hexdigest() for packet in packets], clocks=clocks) + + +def opus_presentation_slice(decoded, source): + stride = source['channels'] * 4 + require(stride > 0 and len(decoded) % stride == 0, 'source Opus: incomplete decoded sample') + start = source['start_samples'] * stride + end = start + source['declared_samples'] * stride + require(0 <= start < end <= len(decoded), 'source Opus: original edit exceeds decoded samples') + return decoded[start:end] + + +def compare_opus_pcm(actual, expected, source): + size = source['declared_samples'] * source['channels'] * 4 + require(len(expected) == size, 'source Opus: reference does not match original declared presentation') + require(len(actual) == size, 'copied Opus: original declared sample count differs') + require(actual == expected, 'copied Opus: complete original-source PCM differs') + + +def compare_opus_matroska_timeline(output, reported_pts, source): + for field in ('clocks', 'codec_delay_samples', 'discard_padding_samples', 'declared_samples', 'pre_skip'): + require(output[field] == source[field], f'copied Opus: original Matroska {field} differs') + require(reported_pts == [Fraction(value) for value in source['reported_pts']], + 'copied Opus: original Matroska oracle PTS readback differs') + + +def validate(data, *, rate, sar, width, height, times, sps_reader, mp4): + result = read(data) + require(result['scale'] == 1_000_000, 'TimestampScale: expected one millisecond') + require(result['duration'] == round_half_up(Fraction(1_000_000_000, 1) / rate), + 'DefaultDuration: exact nominal period rounded half up') + require((result['width'], result['height']) == (width, height), 'video: pixel geometry differs') + require(result['dar'] == Fraction(width, height) * sar, 'video: display DAR differs') + packets = result['packets'] + expected_pts = [round_timestamp(time * 1000) for time in times] + require(len(packets) == len(times), 'video: picture count differs') + require([p['pts'] for p in packets] == expected_pts, 'video: absolute rounded PTS differs') + require(all(a < b for a, b in zip(expected_pts, expected_pts[1:])), 'video: rounded PTS collision') + for packet, time in zip(packets, times): + require(abs(Fraction(packet['pts'], 1000) - time) <= Fraction(1, 2000), + 'video: PTS quantization exceeds half a millisecond') + for nal in result['parameters'] + [n for p in packets for n in p['nals'] if n[0] & 31 == 7]: + if nal[0] & 31 == 7: + require(sps_reader(nal) == (rate, None if sar == 1 else sar), 'SPS: exact timing or SAR differs') + private, expected_packets, keys = mp4 + require(result['private'] == private, 'CodecPrivate: same-head MP4 differs') + require([p['data'] for p in packets] == expected_packets, 'access units: same-head MP4 differs') + require([int(p['key']) for p in packets] == keys, 'video: same-head MP4 key flags differ') + return result diff --git a/scripts/tests/test_native_h264_cli.py b/scripts/tests/test_native_h264_cli.py index a72d18a7..ebc6e34f 100644 --- a/scripts/tests/test_native_h264_cli.py +++ b/scripts/tests/test_native_h264_cli.py @@ -1,15 +1,573 @@ import pathlib +import ast +import contextlib from fractions import Fraction +import io import struct import sys +import tempfile +from types import SimpleNamespace import unittest +from unittest import mock ROOT = pathlib.Path(__file__).resolve().parents[2] sys.path.insert(0, str(ROOT / 'scripts')) import native_h264_cli as cli +import native_h264_matroska as mkv + + +def element(kind, body): + identifier = kind.to_bytes((kind.bit_length() + 7) // 8, 'big') + width = next(width for width in range(1, 9) if len(body) < (1 << (7 * width)) - 1) + return identifier + ((1 << (7 * width)) | len(body)).to_bytes(width, 'big') + body + + +def integer(kind, value): + return element(kind, value.to_bytes(max(1, (value.bit_length() + 7) // 8), 'big')) + + +def generated_sps(rate=Fraction(30), sar=Fraction(1)): + aspect = '0' if sar == 1 else '1' + f'{255:08b}{sar.numerator:016b}{sar.denominator:016b}' + bits = (f'{0x42c033:024b}' + '11011010' + '0' + '11' + '1101' + aspect + + '0110101' + f'{0x010101:024b}' + '1111' + + f'{rate.denominator:032b}{2 * rate.numerator:032b}' + '100001') + bits += '0' * (-len(bits) % 8) + escaped = bytearray() + for value in int(bits, 2).to_bytes(len(bits) // 8, 'big'): + if escaped[-2:] == b'\0\0' and value <= 3: + escaped.append(3) + escaped.append(value) + return b'\x67' + escaped + + +def generated_matroska(*, rate=Fraction(30), sar=Fraction(1), scale=1_000_000, + duration=None, pts=None, block_duration=False, wrong_key=False, + private_suffix=b'', changed_picture=False, display=None, duplicate_duration=False, + sps_rate=None, sps_sar=None, lacing=False, group=False): + sps = generated_sps(sps_rate or rate, sps_sar or sar) + pps = b'\x68\x80' + private = b'\x01\x42\xc0\x33\xff\xe1' + struct.pack('>H', len(sps)) + sps + b'\x01\x00\x02' + pps + pictures = [b'\x65\x80', b'\x41\x80', b'\x41\x80', b'\x41\x80'] + packets = [struct.pack('>I', len(picture)) + picture for picture in pictures] + period = duration if duration is not None else mkv.round_half_up(Fraction(1_000_000_000) / rate) + dimensions = integer(0xb0, 18) + integer(0xba, 34) + dw, dh = display or ((Fraction(18, 34) * sar).numerator, (Fraction(18, 34) * sar).denominator) + dimensions += integer(0x54b2, 3) + integer(0x54b0, dw) + integer(0x54ba, dh) + track = (integer(0xd7, 2) + integer(0x83, 1) + element(0x86, b'V_MPEG4/ISO/AVC') + + element(0x63a2, private + private_suffix) + integer(0x23e383, period) + element(0xe0, dimensions)) + if duplicate_duration: + track += integer(0x23e383, period) + tracks = element(0xae, integer(0xd7, 1) + integer(0x83, 2)) + element(0xae, track) + blocks = integer(0xe7, 0) + pts = pts if pts is not None else [mkv.round_half_up(Fraction(i, 1) / rate * 1000) for i in range(4)] + for index, timestamp in enumerate(pts): + key = index == 0 + flags = (0x80 if key != (wrong_key and index == 0) else 0) | (2 if lacing else 0) + payload = packets[index] + (b'\0' if changed_picture and index == 1 else b'') + block = b'\x82' + struct.pack('>hB', timestamp, flags) + payload + if group or block_duration: + contents = element(0xa1, block) + if not key: + contents += element(0xfb, b'\xff') + if block_duration: + contents += integer(0x9b, 33) + blocks += element(0xa0, contents) + else: + blocks += element(0xa3, block) + body = (element(0x1549a966, integer(0x2ad7b1, scale)) + element(0x1654ae6b, tracks) + + element(0x1f43b675, blocks)) + data = element(0x1a45dfa3, b'') + element(0x18538067, body) + return data, (private, packets, [1, 0, 0, 0]) + + +def generated_opus_mp4(*, media_start=0, edit_duration=63936, pre_skip=312): + def box(kind, body): + return struct.pack('>I4s', len(body) + 8, kind) + body + + entry = bytearray(28) + struct.pack_into('>H', entry, 16, 1) + struct.pack_into('>I', entry, 24, 48_000 << 16) + entry += box(b'dOps', struct.pack('>BBHIhB', 0, 1, pre_skip, 48_000, 0, 0)) + table = box(b'stsd', struct.pack('>II', 0, 1) + box(b'Opus', entry)) + table += box(b'stts', struct.pack('>IIII', 0, 1, 9, 960)) + table += box(b'stsz', struct.pack('>III', 0, 2, 9)) + table += box(b'stsc', struct.pack('>IIIII', 0, 1, 1, 9, 1)) + table += box(b'stco', struct.pack('>III', 0, 1, 8)) + media = box(b'mdhd', struct.pack('>IIIIIHH', 0, 0, 0, 48_000, 8640, 0, 0)) + media += box(b'hdlr', bytes(8) + b'soun') + box(b'minf', box(b'stbl', table)) + edit = box(b'elst', struct.pack('>IIIihh', 0, 1, edit_duration, media_start, 1, 0)) + track = box(b'tkhd', struct.pack('>IIIIII', 0, 0, 0, 1, 0, edit_duration)) + track += box(b'edts', edit) + box(b'mdia', media) + movie = box(b'mvhd', struct.pack('>IIIII', 0, 0, 0, 384_000, edit_duration)) + box(b'trak', track) + return box(b'mdat', b'\xf8\0' * 9) + box(b'moov', movie) + + +def generated_opus_matroska(*, delay=6_500_000, padding=13_500_000): + private = struct.pack('<8sBBHIhB', b'OpusHead', 1, 1, 312, 48_000, 0, 0) + track = (integer(0xd7, 1) + integer(0x83, 2) + element(0x86, b'A_OPUS') + + element(0x63a2, private) + integer(0x56aa, delay)) + blocks = integer(0xe7, 0) + for index in range(9): + block = element(0xa1, b'\x81' + struct.pack('>hB', index * 20 + int(index > 0), 0) + b'\xf8\0') + if index == 8: + block += element(0x75a2, padding.to_bytes(8, 'big', signed=True)) + blocks += element(0xa0, block) + segment = (element(0x1549a966, integer(0x2ad7b1, 1_000_000)) + + element(0x1654ae6b, element(0xae, track)) + element(0x1f43b675, blocks)) + return element(0x1a45dfa3, b'') + element(0x18538067, segment) class NativeCli(unittest.TestCase): + def test_edited_opus_preservation_command_copies_audio_and_matches_all_build_modes(self): + with tempfile.TemporaryDirectory() as directory: + root = pathlib.Path(directory) + + def executable(name, mode): + path = root / name + path.write_text(f'#!{sys.executable}\nimport json, pathlib, sys\n' + f'pathlib.Path(sys.argv[-1]).write_text(json.dumps([{mode!r}, sys.argv[1:-1]]))\n') + path.chmod(0o755) + return path + + args = SimpleNamespace(candidate=executable('candidate', 'native-decoder'), + baseline_external=executable('baseline-external', 'native-decoder'), + default_candidate=executable('default-candidate', 'default-decoder'), + baseline_default=executable('baseline-default', 'default-decoder')) + command = ['-c:v', 'libx264', '-c:a', 'copy', '-fps_mode', 'passthrough'] + source = root / 'audio-mp4-opus-source.mp4' + groups = cli.unchanged_outputs(args, root, source, None, None, + commands=[('opus-source-edit', command)]) + self.assertEqual(cli.byte_groups(groups), { + f'{container}-{mode}': {'count': 1, 'cases': ['opus-source-edit']} + for container in ('mp4', 'mkv') for mode in ('unselected', 'default')}) + for container in ('mp4', 'mkv'): + for mode, marker in (('unselected', 'native-decoder'), ('default', 'default-decoder')): + for suffix in ('', '-base'): + output = root / f'opus-source-edit-{mode}{suffix}.{container}' + self.assertEqual(cli.json.loads(output.read_text()), + [marker, ['ffmpeg', '-i', str(source), *command]]) + args.baseline_external = args.baseline_default + with self.assertRaisesRegex(ValueError, 'actual-base/mp4/opus-source-edit/unselected/whole bytes differs'): + cli.unchanged_outputs(args, root, source, None, None, + commands=[('opus-source-edit', command)]) + + def test_opus_source_oracle_uses_original_edit_and_only_zeroes_clone_informative_preskip(self): + with tempfile.TemporaryDirectory() as directory: + root = pathlib.Path(directory) + source = root / 'original.mp4' + original = generated_opus_mp4() + source.write_bytes(original) + raw = b''.join(struct.pack('BBHIhB', 0, 1, 312, 48_000, 0, 0), + struct.pack('>BBHIhB', 0, 1, 0, 48_000, 0, 0), 1) + self.assertEqual(clone.read_bytes(), expected_clone) + pathlib.Path(command[-1]).write_bytes(raw) + + with mock.patch.object(cli, 'run', side_effect=decode): + expected, facts = cli.opus_source_pcm(source, root / 'reference', 'pinned-ffmpeg', 'pinned-ffprobe') + self.assertEqual(len(commands), 1) + self.assertEqual(source.read_bytes(), original) + self.assertEqual(facts['original_edit'], [63936, 0, 1]) + self.assertEqual((facts['declared_samples'], facts['pre_skip']), (7992, 312)) + self.assertEqual(facts['oracle_decoded_samples'], 8640) + self.assertEqual(expected, raw[:7992 * 4]) + self.assertEqual(len(facts['packet_sha256']), 9) + + def test_opus_source_pcm_rejects_double_preskip_shortfall_wrong_edit_and_changed_samples(self): + with tempfile.TemporaryDirectory() as directory: + source = pathlib.Path(directory) / 'original.mp4' + source.write_bytes(generated_opus_mp4()) + facts = mkv.opus_mp4_source(source) + raw = b''.join(struct.pack(' 2 and isinstance(node.args[2], ast.Constant) + and node.args[2].value == 'optional-map'] + self.assertEqual(ast.literal_eval(fallback.args[1]), ('-map', '0:v:0?')) + + def test_matroska_fallback_adapter_preserves_arguments_and_only_pins_oracle_output(self): + with tempfile.TemporaryDirectory() as directory: + root = pathlib.Path(directory) + executable = root / 'oracle.py' + receipt = root / 'arguments.json' + executable.write_text(f'#!{sys.executable}\nimport json, pathlib, sys\n' + 'pathlib.Path(sys.argv[-1]).write_text(json.dumps(sys.argv[1:]))\n') + executable.chmod(0o755) + adapter = cli.deterministic_fallback(executable, root / 'fallback-bin') + cli.run([adapter, '-hide_banner', '-i', 'source with spaces.mp4', '-an', receipt]) + self.assertEqual(cli.json.loads(receipt.read_text()), + ['-hide_banner', '-i', 'source with spaces.mp4', '-an', '-fflags', '+bitexact', str(receipt)]) + + def test_fallback_adapter_structurally_uses_the_recognized_ffmpeg_program_name(self): + with tempfile.TemporaryDirectory() as directory: + directory = pathlib.Path(directory) / 'arbitrary-directory-name.py' + adapter = cli.deterministic_fallback(pathlib.Path('/qualified/ffmpeg'), directory) + self.assertTrue(directory.is_dir()) + self.assertEqual(adapter, directory / 'ffmpeg') + self.assertTrue(adapter.is_file()) + self.assertTrue(cli.os.access(adapter, cli.os.X_OK)) + + def test_supported_fallback_requires_success_and_replaced_destination(self): + cli.require_fallback_success(0, b'complete Matroska', 'matroska-high-rate') + for status, contents in ((4, b'preserved destination'), (0, b'preserved destination'), (1, b'partial output')): + with self.subTest(status=status, contents=contents): + with self.assertRaisesRegex(ValueError, 'fallback/matroska-high-rate/expected successful oracle output'): + cli.require_fallback_success(status, contents, 'matroska-high-rate') + + def test_actual_base_comparison_executes_both_binaries_without_external_encoders(self): + with tempfile.TemporaryDirectory() as directory: + output = pathlib.Path(directory) / 'out.mp4' + calls = [] + + def execute(argv, *, env): + calls.append((argv, env)) + pathlib.Path(argv[-1]).write_bytes(b'complete MP4') + + groups = {} + environment = {'PATH': '/nonexistent', 'COREAV_X264': '/nonexistent', + 'COREAV_FFMPEG': '/nonexistent', 'COREAV_FALLBACK': '/nonexistent'} + with mock.patch.object(cli, 'run', side_effect=execute): + cli.native_pair('candidate', 'actual-base', ['-i', 'source', '-an', '-c:v', 'libx264', output], + env=environment, group='quality', label='crf23-t2', groups=groups) + self.assertEqual([call[0][0] for call in calls], ['candidate', 'actual-base']) + self.assertEqual(calls[0][0][1:-1], calls[1][0][1:-1]) + self.assertEqual(calls[0][0][1:3], ['--native-h264-encoder', 'ffmpeg']) + self.assertEqual([call[1] for call in calls], [environment] * 2) + self.assertEqual(cli.byte_groups(groups), {'quality': {'count': 1, 'cases': ['crf23-t2']}}) + + def test_actual_base_comparison_rejects_changed_bytes_and_does_not_count_a_pass(self): + with tempfile.TemporaryDirectory() as directory: + output = pathlib.Path(directory) / 'out.mp4' + groups = {} + + def execute(argv, *, env): + pathlib.Path(argv[-1]).write_bytes(str(argv[0]).encode()) + + with mock.patch.object(cli, 'run', side_effect=execute): + with self.assertRaisesRegex(ValueError, 'actual-base/metadata/rate25/whole MP4 bytes differs'): + cli.native_pair('candidate', 'base', [output], env={}, group='metadata', label='rate25', groups=groups) + self.assertEqual(groups, {}) + + def test_actual_base_comparison_reports_the_case_when_a_binary_fails(self): + with mock.patch.object(cli, 'run', side_effect=ValueError('no encoder program')): + with self.assertRaisesRegex(ValueError, 'actual-base/gop/251: no encoder program'): + cli.native_pair('candidate', 'base', [pathlib.Path('out.mp4')], env={}, group='gop', label='251', groups={}) + + def test_matroska_reader_checks_common_and_unusual_exact_clocks_and_aspects(self): + for rate in map(Fraction, ('25', '30', '24000/1001', '30000/1001', '25/2', '1000/33', '29/7', '1000')): + for sar in map(Fraction, ('1', '12/11', '17/13', '65535/65534')): + with self.subTest(rate=rate, sar=sar): + for group in (False, True): + data, mp4 = generated_matroska(rate=rate, sar=sar, group=group) + result = mkv.validate(data, rate=rate, sar=sar, width=18, height=34, + times=[Fraction(i) / rate for i in range(4)], + sps_reader=cli.sps_metadata, mp4=mp4) + self.assertEqual(result['duration'], mkv.round_half_up(Fraction(1_000_000_000) / rate)) + + def test_matroska_mutations_reject_wrong_clocks_aspect_private_payload_and_key_flags(self): + for change, reason in [ + ({'scale': 1}, 'TimestampScale'), ({'duration': 33_000_000}, 'DefaultDuration'), + ({'pts': [0, 33, 66, 100]}, 'rounded PTS'), + ({'block_duration': True}, 'conflicting BlockDuration'), + ({'wrong_key': True}, 'keyframe flag'), ({'display': (1, 1)}, 'display DAR'), + ({'private_suffix': b'\0'}, 'CodecPrivate: trailing'), + ({'changed_picture': True}, 'access unit: truncated'), + ({'duplicate_duration': True}, 'DefaultDuration: duplicate'), + ({'sps_rate': Fraction(25)}, 'SPS: exact timing'), + ({'sps_sar': Fraction(17, 13)}, 'SPS: exact timing'), + ({'lacing': True}, 'unexpected lacing'), + ]: + with self.subTest(change=change): + data, mp4 = generated_matroska(**change) + with self.assertRaisesRegex(ValueError, reason): + mkv.validate(data, rate=Fraction(30), sar=Fraction(1), width=18, height=34, + times=[Fraction(i, 30) for i in range(4)], sps_reader=cli.sps_metadata, mp4=mp4) + + def test_matroska_comparison_consumes_complete_access_units_not_only_coded_pictures(self): + data, (private, packets, keys) = generated_matroska() + for mp4, reason in [((private + b'\0', packets, keys), 'CodecPrivate: same-head MP4'), + ((private, [packets[0], *packets[1:-1]], keys), 'access units: same-head MP4'), + ((private, [packets[0] + b'\0', *packets[1:]], keys), 'access units: same-head MP4'), + ((private, packets, [1, 1, 0, 0]), 'MP4 key flags')]: + with self.subTest(reason=reason): + with self.assertRaisesRegex(ValueError, reason): + mkv.validate(data, rate=Fraction(30), sar=Fraction(1), width=18, height=34, + times=[Fraction(i, 30) for i in range(4)], sps_reader=cli.sps_metadata, mp4=mp4) + + def test_matroska_reader_rejects_rounded_timestamp_collisions(self): + rate = Fraction(2000) + data, mp4 = generated_matroska(rate=rate) + with self.assertRaisesRegex(ValueError, 'rounded PTS collision'): + mkv.validate(data, rate=rate, sar=Fraction(1), width=18, height=34, + times=[Fraction(i) / rate for i in range(4)], sps_reader=cli.sps_metadata, mp4=mp4) + + def test_ebml_reader_rejects_truncated_and_unknown_size_elements(self): + for data in (b'\0', b'\x81', b'\x81\xff', b'\x81\x82\0', b'\x01'): + with self.subTest(data=data), self.assertRaisesRegex(ValueError, 'EBML'): + list(mkv.elements(data)) + + def test_nominal_duration_rounds_half_up_without_floating_point(self): + self.assertEqual(mkv.round_half_up(Fraction(5, 2)), 3) + self.assertEqual(mkv.round_half_up(Fraction(4_000_000_001, 2)), 2_000_000_001) + self.assertEqual(mkv.round_half_up(Fraction(1_001_000_000_000, 30000)), 33_366_667) + + def test_timestamp_rounding_handles_negative_and_positive_half_millisecond_ties(self): + for timestamp, expected in [(Fraction(-3, 2), -2), (Fraction(-1, 2), -1), + (Fraction(-499, 1000), 0), (Fraction(499, 1000), 0), + (Fraction(1, 2), 1), (Fraction(3, 2), 2)]: + with self.subTest(timestamp=timestamp): + self.assertEqual(mkv.round_timestamp(timestamp), expected) + def test_terminal_duration_changes_only_the_last_generated_sample(self): def box(kind, body): return struct.pack('>I4s', len(body) + 8, kind) + body @@ -88,10 +646,11 @@ def test_workflow_builds_actual_base_and_candidate_modes(self): self.assertIn('cargo build --locked --release -p coreav-cli --features native-h264-encoder,native-h264\n' ' cp target/release/coreav "$RUNNER_TEMP/native-base"', base_step) self.assertIn('--baseline-native "$RUNNER_TEMP/native-base"', job) + self.assertIn('--baseline-revision "$(git -C ../baseline rev-parse HEAD)"', job) for event in ('push:', 'pull_request:'): selected = workflow.split(' ' + event, 1)[1].split(' workflow_dispatch:', 1)[0] for path in ('crates/coreav-cli/**', 'crates/coreav-transcode/**', 'scripts/native_h264_cli.py', - 'scripts/track_boxes.py'): + 'scripts/native_h264_matroska.py', 'scripts/track_boxes.py'): self.assertIn(path, selected) def test_cli_oracles_install_nasm_before_x264(self): From d8a7180257eedbfabbc0725967483c73c9bed1a9 Mon Sep 17 00:00:00 2001 From: Gunwoo Kim Date: Mon, 9 Nov 2026 03:36:33 +0900 Subject: [PATCH 3/3] test(cli): use canonical audio oracle inputs Signed-off-by: Gunwoo Kim --- .github/workflows/h264-encoder.yml | 4 ++++ scripts/native_h264_cli.py | 15 +++++++++------ scripts/tests/test_native_h264_cli.py | 5 +++++ 3 files changed, 18 insertions(+), 6 deletions(-) diff --git a/.github/workflows/h264-encoder.yml b/.github/workflows/h264-encoder.yml index e4d103db..5b7c03ec 100644 --- a/.github/workflows/h264-encoder.yml +++ b/.github/workflows/h264-encoder.yml @@ -13,6 +13,8 @@ on: - crates/coreav-frame/** - scripts/native_h264_cli.py - scripts/native_h264_matroska.py + - scripts/oracle_audio.py + - scripts/oracle-audio-args.txt - scripts/tests/test_native_h264_cli.py - scripts/track_boxes.py - crates/coreav-kernels-h264/** @@ -49,6 +51,8 @@ on: - crates/coreav-frame/** - scripts/native_h264_cli.py - scripts/native_h264_matroska.py + - scripts/oracle_audio.py + - scripts/oracle-audio-args.txt - scripts/tests/test_native_h264_cli.py - scripts/track_boxes.py - crates/coreav-kernels-h264/** diff --git a/scripts/native_h264_cli.py b/scripts/native_h264_cli.py index d75fe409..10e6bda9 100644 --- a/scripts/native_h264_cli.py +++ b/scripts/native_h264_cli.py @@ -15,6 +15,7 @@ import h264_crf_conformance as crf import h264_p_conformance as syntax import native_h264_matroska as matroska +from oracle_audio import INPUT_ARGS as AUDIO_DECODE_INPUT import test_oracle import track_boxes @@ -120,6 +121,12 @@ def copied_audio_sources(root, ffmpeg, video30, video25): return sources +def oracle_audio_pcm(ffmpeg, source, output, *, input_options=()): + run([ffmpeg, '-v', 'error', '-xerror', *input_options, *AUDIO_DECODE_INPUT, '-i', source, + '-map', '0:a:0', '-vn', '-c:a', 'pcm_f32le', '-f', 'f32le', output]) + return output.read_bytes() + + def opus_source_pcm(source, prefix, ffmpeg, ffprobe): original = source.read_bytes() if source.suffix == '.mp4': @@ -139,9 +146,7 @@ def opus_source_pcm(source, prefix, ffmpeg, ffprobe): facts['reported_pts'] = [str(Fraction(packet['pts']) * Fraction(stream['time_base'])) for packet in readback['packets']] decoded = prefix.with_suffix('.source.f32le') - run([ffmpeg, '-v', 'error', '-xerror', *input_options, '-i', decoder_input, - '-map', '0:a:0', '-vn', '-c:a', 'pcm_f32le', '-f', 'f32le', decoded]) - pcm = decoded.read_bytes() + pcm = oracle_audio_pcm(ffmpeg, decoder_input, decoded, input_options=input_options) facts['oracle_decoded_samples'] = len(pcm) // (facts['channels'] * 4) expected = matroska.opus_presentation_slice(pcm, facts) if source.suffix == '.mp4' else pcm matroska.compare_opus_pcm(expected, expected, facts) @@ -363,9 +368,7 @@ def probe(path, selection='v:0', hashes=False): same([p['data_hash'].split(':', 1)[1] for p in audio[1]['packets']], facts['packet_sha256'], 'copied Opus complete original-source packet bytes') actual_pcm = output.with_suffix('.opus.f32le') - run([tools.ffmpeg, '-v', 'error', '-xerror', '-i', output, '-map', '0:a:0', - '-vn', '-c:a', 'pcm_f32le', '-f', 'f32le', actual_pcm]) - matroska.compare_opus_pcm(actual_pcm.read_bytes(), expected_pcm, facts) + matroska.compare_opus_pcm(oracle_audio_pcm(tools.ffmpeg, output, actual_pcm), expected_pcm, facts) opus_proof = {} if opus_reference: facts = opus_reference[1] diff --git a/scripts/tests/test_native_h264_cli.py b/scripts/tests/test_native_h264_cli.py index ebc6e34f..4a96a3dc 100644 --- a/scripts/tests/test_native_h264_cli.py +++ b/scripts/tests/test_native_h264_cli.py @@ -14,6 +14,7 @@ sys.path.insert(0, str(ROOT / 'scripts')) import native_h264_cli as cli import native_h264_matroska as mkv +import oracle_audio def element(kind, body): @@ -118,6 +119,10 @@ def generated_opus_matroska(*, delay=6_500_000, padding=13_500_000): class NativeCli(unittest.TestCase): + def test_actual_driver_audio_commands_follow_the_shared_oracle_input_policy(self): + driver = ROOT / 'scripts/native_h264_cli.py' + self.assertEqual(list(oracle_audio.python_problems(driver.read_text(), 'scripts/native_h264_cli.py')), []) + def test_edited_opus_preservation_command_copies_audio_and_matches_all_build_modes(self): with tempfile.TemporaryDirectory() as directory: root = pathlib.Path(directory)