diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ad39b0d39..f74563bb0 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -377,6 +377,15 @@ jobs: # (`coreav ffmpeg`'s encode, `coreav transcode`), which # `cargo test --workspace` does not build. - run: cargo test -p coreav-cli --features ffmpeg-fallback --lib + - name: Compare complete MP3 files with the pinned oracle + env: + COREAV_REQUIRE_FFMPEG: '1' + COREAV_FFMPEG: ${{ runner.temp }}/coreav-encoders/ffmpeg + COREAV_FFPROBE: ${{ runner.temp }}/coreav-encoders/ffprobe + run: | + set -euo pipefail + cargo test --locked -p coreav-cli --features ffmpeg-fallback --test transcode ffmpeg_mp3_information_headers_match_complete_oracle_files -- --exact --nocapture --color never 2>&1 | tee "$RUNNER_TEMP/mp3-information.log" + grep -F 'test ffmpeg_mp3_information_headers_match_complete_oracle_files ... ok' "$RUNNER_TEMP/mp3-information.log" # The AAC LC pipeline and command, with the opt-in feature # (docs/design/audio-decode.md, "AAC-LC"). - run: | diff --git a/crates/coreav-cli/tests/transcode.rs b/crates/coreav-cli/tests/transcode.rs index 33d2b00d8..b1e545a96 100644 --- a/crates/coreav-cli/tests/transcode.rs +++ b/crates/coreav-cli/tests/transcode.rs @@ -3115,6 +3115,121 @@ fn audio_snr(reference: &[f32], decoded: &[f32]) -> f64 { 10.0 * (signal / error).log10() } +#[cfg(unix)] +#[test] +fn ffmpeg_mp3_information_headers_match_complete_oracle_files() { + let oracle = test_oracle::require(); + let dir = dir("mp3-information"); + let mut cases = Vec::new(); + for frames in [ + 2, 5, 85, 99, 100, 101, 399, 400, 401, 799, 800, 801, 1600, 1601, + ] { + cases.push((48000, 1, frames, false)); + } + for (rate, channels) in [(44100, 2), (22050, 1), (8000, 2)] { + for frames in [85, 100, 401] { + cases.push((rate, channels, frames, false)); + } + } + for (rate, channels) in [ + (44100, 1), + (32000, 1), + (32000, 2), + (24000, 2), + (22050, 2), + (16000, 1), + (16000, 2), + (12000, 1), + (11025, 2), + (8000, 1), + ] { + cases.push((rate, channels, 100, false)); + } + cases.extend([ + (48000, 1, 100, true), + (32000, 2, 100, true), + (8000, 1, 100, true), + ]); + for (rate, channels, frames, silent) in cases { + let samples = if rate >= 32000 { + (frames - 1) * 1152 + } else { + (frames - 2) * 576 + }; + let source = dir.join(format!("source-{rate}-{channels}-{frames}-{silent}.mp4")); + let frequency = if silent { 0 } else { 701 }; + let run = Command::new(oracle.ffmpeg()) + .args(["-nostdin", "-v", "error", "-f", "lavfi"]) + .args(include_str!("../../../scripts/oracle-audio-args.txt").split_whitespace()) + .args([ + "-i", + &format!( + "sine=frequency={frequency}:sample_rate={rate},atrim=end_sample={samples}" + ), + "-ac", + &channels.to_string(), + "-c:a", + "flac", + "-strict", + "-2", + ]) + .arg(&source) + .output() + .unwrap(); + assert!(run.status.success(), "{run:?}"); + for (mode, settings, tag) in [ + ("cbr", ["-b:a", "64k"], b"Info"), + ("vbr", ["-q:a", "2"], if silent { b"Info" } else { b"Xing" }), + ] { + let output = dir.join(format!("{rate}-{channels}-{frames}-{mode}-{silent}.mp3")); + let reference = output.with_extension("reference.mp3"); + let run = Command::new(bin()) + .args(["ffmpeg", "-i"]) + .arg(&source) + .args(["-c:a", "libmp3lame"]) + .args(settings) + .arg(&output) + .env("COREAV_FFMPEG", oracle.ffmpeg()) + .env("COREAV_FALLBACK", NO_FALLBACK) + .env_remove("COREAV_FALLBACK_ACTIVE") + .env_remove("COREAV_STRICT_SAFE") + .output() + .unwrap(); + assert!( + run.status.success(), + "{rate} {channels} {frames} {mode}: {run:?}" + ); + let run = Command::new(oracle.ffmpeg()) + .args(["-nostdin", "-v", "error"]) + .args(include_str!("../../../scripts/oracle-audio-args.txt").split_whitespace()) + .arg("-i") + .arg(&source) + .args(["-c:a", "libmp3lame"]) + .args(settings) + .arg(&reference) + .output() + .unwrap(); + assert!(run.status.success(), "{run:?}"); + let actual = std::fs::read(&output).unwrap(); + let expected = std::fs::read(&reference).unwrap(); + let at = expected.windows(4).position(|bytes| bytes == tag).unwrap(); + assert_eq!( + u32::from_be_bytes(expected[at + 8..at + 12].try_into().unwrap()), + frames, + "{rate} {channels} {mode}: fixture must hit the requested frame count" + ); + assert!( + actual == expected, + "{rate} {channels} {frames} {mode}: complete bytes differ at {:?}, lengths {} / {}", + actual.iter().zip(&expected).position(|(a, b)| a != b), + actual.len(), + expected.len() + ); + } + } + nothing_left(&dir); +} + #[cfg(unix)] #[test] fn ffmpeg_mp3_outputs_keep_the_source_samples_and_quality() { diff --git a/crates/coreav-transcode/src/mp3.rs b/crates/coreav-transcode/src/mp3.rs index 319c9b518..a5bce08aa 100644 --- a/crates/coreav-transcode/src/mp3.rs +++ b/crates/coreav-transcode/src/mp3.rs @@ -140,6 +140,7 @@ pub(crate) struct Info { software: String, delay: u32, padding: u32, + bit_rate: Option, variable: bool, music_crc: u16, } @@ -258,6 +259,7 @@ pub fn read_output( let mut offset = u64::from(size) + 10; let mut first = None; let mut first_rate = None; + let mut variable = false; let mut music_crc = 0; let mut bytes = Vec::new(); while offset < length { @@ -280,7 +282,8 @@ pub fn read_output( { return Err(refused("a frame does not match its size, rate or channels")); } - if !expected.variable && first_rate.is_some_and(|rate| rate != header.bit_rate) { + variable |= first_rate.is_some_and(|rate| rate != header.bit_rate); + if !expected.variable && variable { return Err(refused( "different frame bit rates in a constant-rate encode", )); @@ -331,7 +334,8 @@ pub fn read_output( software, delay: 576, padding: 576 + u32::from(expected.guard), - variable: expected.variable, + bit_rate: if expected.variable { None } else { first_rate }, + variable, music_crc, }, }) @@ -431,14 +435,15 @@ pub(crate) fn info_frame(info: &Info, sizes: &[u32]) -> Result, ReadErro (_, 1) => 9, _ => 17, }; - let needed = (4 + side + 120 + 36).max(190); - let base = 0xffe0_0000 | (info.header & 0x001e_0cc0) | (1 << 16); + let needed = 4 + side + 120 + 36; + let channel_mode = if original.channels() == 1 { 3 << 6 } else { 0 }; + let base = 0xffe0_0000 | (info.header & 0x001e_0c00) | (1 << 16) | channel_mode; let mut selected = None; for index in 1..15u32 { let word = base | (index << 12); let header = Header::parse(&word.to_be_bytes()).map_err(|e| refused(e.to_string()))?; if header.frame_bytes().is_some_and(|size| size >= needed) - && header.bit_rate >= original.bit_rate + && info.bit_rate.is_none_or(|rate| header.bit_rate >= rate) { selected = Some((word, header.frame_bytes().unwrap_or(0))); break; @@ -460,10 +465,16 @@ pub(crate) fn info_frame(info: &Info, sizes: &[u32]) -> Result, ReadErro out.extend_from_slice(&15u32.to_be_bytes()); out.extend_from_slice(&frame_count.to_be_bytes()); out.extend_from_slice(&total.to_be_bytes()); + let mut stride = 1usize; + while sizes.len() / stride >= 400 { + stride *= 2; + } + let seek_points = sizes.len() / stride; let mut offset = u64::try_from(size).unwrap_or(u64::MAX); let mut frame = 0usize; - for percent in 0..100usize { - let target = sizes.len().saturating_mul(percent).div_ceil(100); + out.push(0); + for percent in 1..100usize { + let target = (seek_points * percent / 100 + 1) * stride; while frame < target { offset += u64::from( *sizes @@ -472,11 +483,7 @@ pub(crate) fn info_frame(info: &Info, sizes: &[u32]) -> Result, ReadErro ); frame += 1; } - out.push(if percent == 0 { - 0 - } else { - u8::try_from((offset * 256 / u64::from(total)).min(255)).unwrap_or(255) - }); + out.push(u8::try_from((offset * 256 / u64::from(total)).min(255)).unwrap_or(255)); } out.extend_from_slice(&0u32.to_be_bytes()); let encoder = info.encoder.as_bytes(); @@ -493,7 +500,7 @@ pub(crate) fn info_frame(info: &Info, sizes: &[u32]) -> Result, ReadErro out.extend_from_slice(&info.music_crc.to_be_bytes()); let checksum_at = out.len(); out.extend_from_slice(&[0, 0]); - out.resize(size, 0); + out.resize(size.max(190), 0); let checksum = crc( 0, out.get(..190) @@ -502,6 +509,7 @@ pub(crate) fn info_frame(info: &Info, sizes: &[u32]) -> Result, ReadErro out.get_mut(checksum_at..checksum_at + 2) .ok_or_else(|| refused("information-frame CRC offset"))? .copy_from_slice(&checksum.to_be_bytes()); + out.truncate(size); Ok(out) } @@ -516,6 +524,7 @@ pub(crate) mod tests { software: "Lavf1.2.3".into(), delay: 576, padding: 576, + bit_rate: None, variable: false, music_crc: 0, }; diff --git a/docs/agents/ci.md b/docs/agents/ci.md index 5e695520c..c0bf1c0b7 100644 --- a/docs/agents/ci.md +++ b/docs/agents/ci.md @@ -39,6 +39,7 @@ List development caches with `docker volume ls --filter name=coreav-dev-`. After | Rule | Enforced by | |---|---| +| MP3 byte parity executes real generated media in required Linux CI rather than passing with an unbuilt or unselected transcode test | The explicit `check` step enables `ffmpeg-fallback`, selects the exact MP3 test after oracle qualification and requires its success witness with pipeline failure propagation. `test_required_linux_mp3_comparison_rejects_zero_tests_and_failed_commands` rejects missing, failed and unrelated tests, and a failed Cargo command that printed the witness. Cargo features and test selection are runtime CI facts, not properties of a Rust test body | | A development image verifies its Rust bootstrap before executing it | `scripts/dev/Dockerfile` selects versioned rustup-init binaries and committed architecture-specific SHA-256 values; `test_corrupt_bootstrap_is_not_executed` executes its shell step with a corrupt download for both architectures and requires checksum failure without execution. The compiler toolchain remains owned by `rust-toolchain.toml` | | Local Linux development commands mount only their linked worktree and named Cargo caches, without writable Git pointers, host credentials or default runtime networking | `scripts/dev-container.py` owns the Docker argument list and explicit build inputs; `test_dev_container.py` checks the read-only `.git` overlay, primary-checkout refusal, mounts, non-root identity, limits, network opt-in, argument forwarding, build context, and refusal outside the worktree. Keep secrets outside the mounted worktree; arbitrary file contents cannot be classified by a path check | | A credentialed manual workflow that builds a dispatched commit admits only commits on this repository's branches, so pull-request code from forks never runs beside corpus credentials | The HEVC reference workflow's admission step refuses a candidate no branch contains before the build and every credentialed step; `test_candidate_must_be_on_a_branch_before_it_builds_or_sees_credentials` pins that order. Writers already hold the repository's secrets, so this closes the only path that widens access. Workflow step order cannot be encoded in Rust types | diff --git a/docs/agents/transcode.md b/docs/agents/transcode.md index f6651931c..4d98d5872 100644 --- a/docs/agents/transcode.md +++ b/docs/agents/transcode.md @@ -5,6 +5,7 @@ Encode path, sandboxed workers, and audio-encode selection. | Rule | Enforced by | |---|---| | The ffmpeg adapter's AAC MP4 timing ends a partially presented final sample at priming plus the submitted sample count without changing native transcode bytes, edits or Matroska frames | `mp4_audio_samples` owns the terminal delta, selected by the adapter-only `aac_mp4_tail` policy for replacement tracks. `aac_terminal_timing_matches_the_complete_oracle_boxes` compares complete stts, mdhd and elst bytes and full decoded audio with the pinned oracle. Replacement regressions preserve the default complete-frame timing, exact boundaries, wholly padded packets and Opus durations; the unchanged legacy-encoder comparison retains byte-strict native transcode verification. Runtime oracle bytes cannot be established by codec frame length alone | +| MP3 Xing/Info seek positions retain the pinned oracle's integer-percentile and long-file rounding without changing command admission | `mp3::info_frame` owns the frame-size index and its seek resolution. `ffmpeg_mp3_information_headers_match_complete_oracle_files` checks complete CBR/VBR files from generated lossless sources, verifies the actual reference frame counts and covers both sides of the 400/800/1600-frame resolution changes. The header definition gives approximate positions but no normative encoder rounding; external byte identity needs a runtime comparison | | Legacy encoder comparisons admit only a source-declared SAR delta, including its exact forced output length | `sar_delta::check` compares every other summary byte, exit code, stderr, box field and complete `mdat` payload exactly; SPS changes use the audited owner's bit boundary and exact RBSP splice. The full legacy gate retains its reference and decodes both outputs; pure mutations and an actual-case `mdat` mutation reject non-SAR changes with named fields. Structural growth, not a file allowlist, owns `output.bytes` | | Unscaled H.264 encoding retains valid source sample-aspect declarations, including square pixels, without changing scale normalization | `sample_aspect` receives an optional scale result rather than inferring a scale request from dimensions. The declared/absent/invalid unit matrix and `unscaled_encoding_preserves_declared_sar_without_changing_scale` cover summary, `pasp`, encoder signalling and exact declared-source output; identity-scale controls retain normalization. The strict-safe controls query `coreav_worker::enforces_memory_limit` and assert the exact closed refusal on unsupported hosts, while retaining success and pixel comparisons on supported hosts. A ratio's numerical value cannot encode declaration presence, and a decoder feature cannot prove sandbox capability | | Unscaled AV1 input retains CPU or shared storage through the common encoder writer, including its direct-pipe capability | `Process::spawn` delegates to the same retaining launch path; `shared_av1_input_is_not_downloaded_without_scaling` checks the original shared owner and the scaling control, while `shared_frame_pipe` checks complete protocol bytes, direct writes without parent reads and owner release. The required AV1 fixture also transcodes a real AV1 source. Storage kinds are explicit in `Pixels`; pipe support remains an external runtime capability | diff --git a/docs/design/transcode.md b/docs/design/transcode.md index 36f97cd99..8c547b0c8 100644 --- a/docs/design/transcode.md +++ b/docs/design/transcode.md @@ -1057,6 +1057,36 @@ The fixed delay and flush contract is qualified against the pinned FFmpeg build, not independently signalled by raw MP3 frames. An operator's custom libmp3lame build with a changed encoder delay is outside this contract. +**Information-frame byte parity.** The TOC describes approximate seek +positions, not an ISO-mandated rounding algorithm. The +[Xing header description](https://teslabs.com/openplayer/docs/docs/specs/mp3_structure.pdf) +defines each entry as a position scaled by 256 over the MPEG audio byte +length; the Info Tag specification retains that layout for CBR. +Compatibility with the pinned FFmpeg requires an additional rounding +choice, established from generated files rather than implementation source. +For `N` audio frames, let `S` be the smallest power of two such that +`floor(N / S) < 400`, and let `K = floor(N / S)`. Entry zero is zero. +For percentiles `p = 1..99`, the chosen byte position is immediately after +audio frame `S * (floor(K * p / 100) + 1)`, counting frames from one. +The position includes the information frame but excludes ID3. Scale it by +256 over the total MPEG audio byte count, truncate, and clamp to 255. +Below 400 frames this differs from ceiling at exact integer percentiles. +At and above 400 frames it also retains the oracle's coarser seek positions. +The information frame uses mono or ordinary stereo, not the audio frame's +joint-stereo mode. Constant-rate output retains its encoded bitrate as a +minimum; quality-selected output uses the smallest frame that holds the +tag. The `Info` versus `Xing` identifier follows observed audio bitrate +variation, so constant-bitrate silence in quality mode still writes `Info`. +Short information frames retain the oracle's 190-byte checksum span with +zero extension, without publishing those extra bytes. +The regression compares complete output files from lossless inputs in CBR +and VBR modes. It checks the reference's actual audio-frame count before +comparing bytes, with counts around integer percentiles and seek-table +resolution changes at 400, 800 and 1,600 frames. The matrix includes mono +and stereo, MPEG-1, MPEG-2 and MPEG-2.5, tonal and silent input, with no change to encoder selection +or native command admission. Existing non-frame-aligned EOF differences +remain outside complete-file equality. + The compatibility surface is `-c:a` or `-acodec libmp3lame`, default MP3 encoding for `.mp3` or `-f mp3`, `-b:a` and `-q:a`/`-qscale:a`, with `-vn` or one selected audio stream. The source's supported MP3 sampling rate is diff --git a/scripts/tests/test_main_ci_plan.py b/scripts/tests/test_main_ci_plan.py index 46fd6a6e6..0e808e217 100644 --- a/scripts/tests/test_main_ci_plan.py +++ b/scripts/tests/test_main_ci_plan.py @@ -137,6 +137,49 @@ def test_aac_source_build_runs_the_whole_transcode_target(self): '--target-dir', 'target/fallback', ], 'Run the complete transcode target with AAC enabled; remove test-name filters') + def test_required_linux_mp3_comparison_rejects_zero_tests_and_failed_commands(self): + steps = self.workflows['ci']['jobs']['check']['steps'] + selected = [s for s in steps if s.get('name') == 'Compare complete MP3 files with the pinned oracle'] + self.assertEqual(len(selected), 1, + 'Run the MP3 byte comparison in required Linux check, not only the full tier') + step = selected[0] + self.assertNotIn('if', step) + self.assertEqual(step['env'], { + 'COREAV_REQUIRE_FFMPEG': '1', + 'COREAV_FFMPEG': '${{ runner.temp }}/coreav-encoders/ffmpeg', + 'COREAV_FFPROBE': '${{ runner.temp }}/coreav-encoders/ffprobe', + }) + self.assertEqual(step['run'].splitlines(), [ + 'set -euo pipefail', + 'cargo test --locked -p coreav-cli --features ffmpeg-fallback --test transcode ' + 'ffmpeg_mp3_information_headers_match_complete_oracle_files ' + '-- --exact --nocapture --color never 2>&1 | tee "$RUNNER_TEMP/mp3-information.log"', + "grep -F 'test ffmpeg_mp3_information_headers_match_complete_oracle_files ... ok' " + '"$RUNNER_TEMP/mp3-information.log"', + ], 'Enable transcode, select the exact MP3 test and require its success witness') + provision, = [s for s in steps if s.get('name') == 'Verify the pinned encoder oracle'] + self.assertLess(steps.index(provision), steps.index(step)) + with tempfile.TemporaryDirectory() as directory: + root = pathlib.Path(directory) + cargo = root / 'cargo' + cargo.write_text('#!/bin/sh\ncat "$TEST_OUTPUT"\nexit "$TEST_STATUS"\n') + cargo.chmod(0o700) + output = root / 'output' + witness = 'test ffmpeg_mp3_information_headers_match_complete_oracle_files ... ok\n' + for text, status, succeeds in [ + ('running 0 tests\ntest result: ok. 0 passed; 0 failed\n', 0, False), + ('test ffmpeg_mp3_information_headers_match_complete_oracle_files ... FAILED\n', 101, False), + ('test unrelated_test ... ok\n', 0, False), + (witness, 0, True), + (witness, 101, False), + ]: + output.write_text(text) + result = subprocess.run(['bash', '-c', step['run']], capture_output=True, text=True, + env={'RUNNER_TEMP': directory, 'PATH': f'{directory}:/usr/bin:/bin', + 'TEST_OUTPUT': str(output), 'TEST_STATUS': str(status)}) + self.assertEqual(result.returncode == 0, succeeds, + 'The Linux MP3 gate must reject absent tests and pipeline failures') + def test_macos_runs_the_declared_sar_media_case_with_qualified_tools(self): steps = self.workflows['ci']['jobs']['check-macos']['steps'] selected = [step for step in steps if step.get('name') == 'Declared sample aspect ratios on macOS'] diff --git a/test-support/oracle-dependent.json b/test-support/oracle-dependent.json index 48689dce7..87b2a8642 100644 --- a/test-support/oracle-dependent.json +++ b/test-support/oracle-dependent.json @@ -203,6 +203,7 @@ "ffmpeg_libx264_refuses_before_encoding", "ffmpeg_libx264_refuses_video_no_decoder_takes", "ffmpeg_mp3_eof_guard_preserves_exact_boundary_lengths", + "ffmpeg_mp3_information_headers_match_complete_oracle_files", "ffmpeg_mp3_outputs_keep_the_source_samples_and_quality", "ffmpeg_mp3_sources_and_refusals_are_build_aware", "ffmpeg_strict_safe_authorizes_resolved_audio_before_discovery",