Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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: |
Expand Down
115 changes: 115 additions & 0 deletions crates/coreav-cli/tests/transcode.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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() {
Expand Down
35 changes: 22 additions & 13 deletions crates/coreav-transcode/src/mp3.rs
Original file line number Diff line number Diff line change
Expand Up @@ -140,6 +140,7 @@ pub(crate) struct Info {
software: String,
delay: u32,
padding: u32,
bit_rate: Option<u32>,
variable: bool,
music_crc: u16,
}
Expand Down Expand Up @@ -258,6 +259,7 @@ pub fn read_output<S: Source>(
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 {
Expand All @@ -280,7 +282,8 @@ pub fn read_output<S: Source>(
{
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",
));
Expand Down Expand Up @@ -331,7 +334,8 @@ pub fn read_output<S: Source>(
software,
delay: 576,
padding: 576 + u32::from(expected.guard),
variable: expected.variable,
bit_rate: if expected.variable { None } else { first_rate },
variable,
music_crc,
},
})
Expand Down Expand Up @@ -431,14 +435,15 @@ pub(crate) fn info_frame(info: &Info, sizes: &[u32]) -> Result<Vec<u8>, 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;
Expand All @@ -460,10 +465,16 @@ pub(crate) fn info_frame(info: &Info, sizes: &[u32]) -> Result<Vec<u8>, 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
Expand All @@ -472,11 +483,7 @@ pub(crate) fn info_frame(info: &Info, sizes: &[u32]) -> Result<Vec<u8>, 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();
Expand All @@ -493,7 +500,7 @@ pub(crate) fn info_frame(info: &Info, sizes: &[u32]) -> Result<Vec<u8>, 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)
Expand All @@ -502,6 +509,7 @@ pub(crate) fn info_frame(info: &Info, sizes: &[u32]) -> Result<Vec<u8>, 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)
}

Expand All @@ -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,
};
Expand Down
1 change: 1 addition & 0 deletions docs/agents/ci.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
1 change: 1 addition & 0 deletions docs/agents/transcode.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
30 changes: 30 additions & 0 deletions docs/design/transcode.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading
Loading