diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1f32d7262..5254da1d2 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1264,6 +1264,14 @@ jobs: --test legacy_encoders --target-dir target/fallback cargo test --locked --release -p coreav-cli --features ffmpeg-fallback,dav1d,libvpx,libopus,aac --test transcode \ --target-dir target/fallback + - name: Check the MP3 worker encoder-only protocol + env: + COREAV_FFMPEG: ${{ runner.temp }}/coreav-oracle-bin/ffmpeg + run: | + cargo test --locked --release -p coreav-cli --features ffmpeg-fallback,dav1d,libvpx,libopus --test mp3_worker \ + --target-dir target/fallback + cargo test --locked --release -p coreav-cli --features ffmpeg-fallback,dav1d,libvpx,libopus,aac --test mp3_worker \ + --target-dir target/fallback - name: Copied video with AAC encoding preserves exact fallback env: COREAV_REQUIRE_FFMPEG: '1' diff --git a/crates/coreav-cli/tests/mp3_worker.rs b/crates/coreav-cli/tests/mp3_worker.rs new file mode 100644 index 000000000..1970f7ed6 --- /dev/null +++ b/crates/coreav-cli/tests/mp3_worker.rs @@ -0,0 +1,32 @@ +//! Actual MP3 worker starts and output checked by the frozen compatibility tools. +#![cfg(all(unix, feature = "transcode"))] +#![allow(clippy::unwrap_used, clippy::panic)] + +#[path = "../../../test-support/oracle.rs"] +mod test_oracle; + +#[test] +fn mp3_worker_starts_and_output_pass_the_frozen_checks() { + let oracle = test_oracle::require(); + let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../.."); + let work = std::path::Path::new(env!("CARGO_TARGET_TMPDIR")).join("mp3-worker-protocol"); + if work.exists() { + std::fs::remove_dir_all(&work).unwrap(); + } + let result = std::process::Command::new("python3") + .arg(root.join("scripts/mp3_worker_check.py")) + .args(["--coreav", env!("CARGO_BIN_EXE_coreav"), "--work"]) + .arg(&work) + .env("COREAV_FFMPEG", oracle.ffmpeg()) + .env("COREAV_FFPROBE", oracle.ffprobe()) + .output() + .unwrap(); + assert!( + result.status.success(), + "{}{}", + String::from_utf8_lossy(&result.stdout), + String::from_utf8_lossy(&result.stderr) + ); + print!("{}", String::from_utf8_lossy(&result.stdout)); + std::fs::remove_dir_all(work).unwrap(); +} diff --git a/crates/coreav-transcode/src/audio.rs b/crates/coreav-transcode/src/audio.rs index 98a7c7ace..87a1d1e75 100644 --- a/crates/coreav-transcode/src/audio.rs +++ b/crates/coreav-transcode/src/audio.rs @@ -5,7 +5,7 @@ //! (`coreav_worker::opus`, through the sandbox launcher), on samples //! resampled to 48 kHz; the AAC encoder is the operator's `ffmpeg` program //! (`crate::aac`), on samples at the stream's own rate. MP3 uses the -//! operator's `ffmpeg -c:a libmp3lame`, with checked Matroska readback and +//! operator's `ffmpeg -c:a libmp3lame`, with checked MP3 readback and //! an explicit EOF zero guard removed by the MP3 writer's gapless tag. //! //! The audio is encoded before the video, so that a stream CoreAV does not @@ -503,10 +503,10 @@ fn encode_with( Encode::Mp3(..) => "mp3", }, )?; - // The AAC encoder's Matroska, read back once it has ended. let raw = match encode { Encode::Opus(_) => None, - Encode::Aac(..) | Encode::Mp3(..) => Some(Spool::create(output, "mkv")?), + Encode::Aac(..) => Some(Spool::create(output, "mkv")?), + Encode::Mp3(..) => Some(Spool::create(output, "mp3-raw")?), }; let mut feed = Feed { encode, @@ -563,7 +563,13 @@ fn encode_with( } else { 0 }; - let (sizes, pre_skip, description, duration) = match process.finish().map_err(Error::Encode)? { + let (output, stderr) = if matches!(encode, Encode::Mp3(..)) { + process.finish_with_stderr() + } else { + process.finish().map(|sink| (sink, String::new())) + } + .map_err(Error::Encode)?; + let (sizes, pre_skip, description, duration) = match output { Output::Opus(Packets { reader, mut file, @@ -641,10 +647,12 @@ fn encode_with( ) ), }; - let read = checked_readback( + let mut read = checked_readback( mp3::read_output(&mut written, &expected, &limits.matroska), deadline, )?; + read.info.encoder = + mp3::encoder_identity(&stderr).map_err(|e| encoder_error(e.to_string()))?; ( read.frames .iter() @@ -750,31 +758,43 @@ fn probe_encoder( deadline: Instant, codec: &str, ) -> Result<(), Error> { - struct Answer(Vec); + struct Answer(Vec, bool); impl Sink for Answer { fn write(&mut self, bytes: &[u8]) -> Result<(), coreav_decode::Error> { let room = PROBE_ANSWER.saturating_sub(self.0.len()); + if self.1 && bytes.len() > room { + return Err(coreav_decode::Error::new( + ErrorKind::Limit, + "the MP3 encoder probe exceeded its output limit", + )); + } self.0 .extend_from_slice(bytes.get(..room.min(bytes.len())).unwrap_or_default()); Ok(()) } } - let command = command( - program, - &[ + let args = if codec == "libmp3lame" { + mp3::encode_args(48000, 1, mp3::Mode::Constant(None)) + } else { + [ "-hide_banner", "-loglevel", "error", "-h", &format!("encoder={codec}"), ] - .map(std::ffi::OsString::from), + .map(std::ffi::OsString::from) + .to_vec() + }; + let command = command( + program, + &args, HugePages::Kept, launcher, &EncoderLimits::new(AAC_ENCODER_MEMORY), deadline, ); - let Answer(answer) = Process::spawn( + let Answer(answer, _) = Process::spawn( if codec == "aac" { "the AAC encoder" } else { @@ -784,10 +804,28 @@ fn probe_encoder( command, program, deadline, - Answer(Vec::new()), + Answer(Vec::new(), codec == "libmp3lame"), ) .and_then(Process::finish) - .map_err(Error::Encode)?; + .map_err(|error| { + if codec == "libmp3lame" + && error.kind == ErrorKind::Backend + && error + .message + .starts_with("the MP3 encoder failed (exit status: ") + && error.message.contains("Unknown encoder 'libmp3lame'") + { + Error::Unsupported("the ffmpeg program has no libmp3lame encoder".into()) + } else { + Error::Encode(error) + } + })?; + if codec == "libmp3lame" && !answer.is_empty() { + if !answer.starts_with(b"ID3\x04\0\0") { + return Err(encoder_error("invalid MP3 encoder probe output".into())); + } + return Ok(()); + } if !answer.starts_with(format!("Encoder {codec} [").as_bytes()) { return Err(Error::Unsupported(format!( "the ffmpeg program {} has no {codec} encoder; install FFmpeg with that encoder", @@ -1353,12 +1391,7 @@ mod tests { } let mut frame = vec![0xff, 0xfb, 0x54, 0xc4]; frame.resize(192, 0); - let bytes = crate::mp3::tests::fixture( - "A_MPEG/L3", - 23_020_833, - &[frame.clone(), frame], - &[None, Some(979_167)], - ); + let bytes = crate::mp3::tests::fixture(&[frame.clone(), frame]); let reads = Cell::new(0); let deadline = Instant::now() + std::time::Duration::from_millis(20); let source = TimedSource { @@ -1584,6 +1617,52 @@ mod tests { } } + #[cfg(unix)] + #[test] + fn mp3_availability_errors_keep_their_classification_and_output_bound() { + for (name, body, unsupported) in [ + ("mp3-silent", "true", true), + ( + "mp3-unavailable", + "printf \"Unknown encoder 'libmp3lame'\\n\" >&2; exit 1", + true, + ), + ( + "mp3-unavailable-status-eight", + "printf \"Unknown encoder 'libmp3lame'\\n\" >&2; exit 8", + true, + ), + ( + "mp3-unknown-before-flood", + "printf \"Unknown encoder 'libmp3lame'\\n\" >&2; exec yes", + false, + ), + ( + "mp3-unknown-before-signal", + "printf \"Unknown encoder 'libmp3lame'\\n\" >&2; kill -TERM $$", + false, + ), + ("mp3-invalid", "printf bad", false), + ("mp3-flood", "exec yes", false), + ("mp3-failure", "echo 'other failure' >&2; exit 1", false), + ] { + let (dir, script) = ffmpeg_stand_in(name, body); + let result = probe_encoder( + &script, + None, + Instant::now() + Duration::from_secs(5), + "libmp3lame", + ); + assert!(result.is_err(), "{name}"); + assert_eq!( + matches!(result, Err(Error::Unsupported(_))), + unsupported, + "{name}" + ); + std::fs::remove_dir_all(dir).unwrap(); + } + } + #[cfg(unix)] #[test] fn an_aac_encoder_that_floods_its_output_is_stopped_at_once() { diff --git a/crates/coreav-transcode/src/encoder.rs b/crates/coreav-transcode/src/encoder.rs index a728d9242..53f87d5f1 100644 --- a/crates/coreav-transcode/src/encoder.rs +++ b/crates/coreav-transcode/src/encoder.rs @@ -1412,7 +1412,15 @@ impl Process { /// deadline. Returns the sink; a process that exited with an error, was /// killed or did not read every chunk is an error carrying the end of /// its standard error. - pub(crate) fn finish(mut self) -> Result { + pub(crate) fn finish(self) -> Result { + self.finish_inner(false).map(|(sink, _)| sink) + } + + pub(crate) fn finish_with_stderr(self) -> Result<(S, String), Error> { + self.finish_inner(true) + } + + fn finish_inner(mut self, diagnostics: bool) -> Result<(S, String), Error> { if let Some(e) = self.error.take() { return Err(e); } @@ -1478,7 +1486,14 @@ impl Process { ), ))); } - Ok(sink) + Ok(( + sink, + if diagnostics { + self.shared.stderr_text() + } else { + String::new() + }, + )) } /// Ends the encode with `error`: stops the writer, kills the encoder, diff --git a/crates/coreav-transcode/src/mp3.rs b/crates/coreav-transcode/src/mp3.rs index cc1052e44..319c9b518 100644 --- a/crates/coreav-transcode/src/mp3.rs +++ b/crates/coreav-transcode/src/mp3.rs @@ -1,5 +1,5 @@ //! External libmp3lame encoding and checked Layer III output. The process -//! writes Matroska (RFC 9559); file metadata follows ID3v2.4 and the MP3 +//! writes MP3; file metadata follows ID3v2.4 and the MP3 //! Info Tag specification linked from `docs/design/transcode.md`. use std::ffi::OsString; @@ -8,7 +8,6 @@ use std::ops::Range; use coreav_audio::mp3::{Header, Version}; use coreav_isobmff::Source; -use coreav_mkv::{Allowlist, Codec, Encoding, TrackKind}; /// The decoder's filterbank delay plus its one-sample alignment. pub const DECODER_DELAY: u32 = 529; @@ -43,13 +42,14 @@ pub fn takes_rate(rate: u32) -> bool { ) } -/// Raw float input and one MP3 track on Matroska standard output. +/// Raw float input and Layer III frames on MP3 standard output. pub fn encode_args(rate: u32, channels: u8, mode: Mode) -> Vec { let mut args: Vec = [ "-nostdin", "-hide_banner", + "-nostats", "-loglevel", - "error", + "info", "-f", "f32le", "-ar", @@ -71,11 +71,11 @@ pub fn encode_args(rate: u32, channels: u8, mode: Mode) -> Vec { Mode::Quality(quality) => args.extend(["-q:a".into(), quality.to_string().into()]), Mode::Constant(None) => {} } - args.extend(["-f", "matroska", "pipe:1"].map(OsString::from)); + args.extend(["-f", "mp3", "pipe:1"].map(OsString::from)); args } -/// A conservative bound for frames, Matroska headers and block overhead. +/// A conservative bound for frames and the encoder's ID3 header. pub fn most_bytes(samples: u64) -> u64 { samples .saturating_add(u64::from(DECODER_DELAY + 2 * MAX_TRIM)) @@ -136,7 +136,7 @@ pub struct Output { #[derive(Debug)] pub(crate) struct Info { header: u32, - encoder: String, + pub(crate) encoder: String, software: String, delay: u32, padding: u32, @@ -168,152 +168,117 @@ fn version(text: &str, prefix: &str) -> bool { }) } -/// Reads only one uncompressed MP3 track, validating each frame and the -/// exact sample total after CodecDelay and final DiscardPadding. +pub(crate) fn encoder_identity(stderr: &str) -> Result { + let mut identities = stderr.lines().filter_map(|line| { + let (key, value) = line.trim().split_once(':')?; + if key.trim() != "encoder" { + return None; + } + value.trim().strip_suffix(" libmp3lame") + }); + let identity = identities + .next() + .filter(|text| version(text, "Lavc")) + .ok_or_else(|| refused("no bounded libmp3lame encoder identity"))?; + if identities.next().is_some() { + return Err(refused("multiple encoder identities")); + } + Ok(identity.to_owned()) +} + +/// Reads the encoder-only MP3 pipe, checking its complete framing and +/// libmp3lame's frame-aligned sample accounting before publishing metadata. pub fn read_output( mut source: S, expected: &Expected, limits: &coreav_mkv::Limits, ) -> Result { + let frame_samples = if expected.sample_rate >= 32_000 { + 1152 + } else { + 576 + }; if !takes_rate(expected.sample_rate) || !matches!(expected.channels, 1 | 2) || expected.samples <= u64::from(expected.guard) + || u32::from(expected.guard) >= frame_samples + || expected.samples % u64::from(frame_samples) != 0 { return Err(refused("invalid submitted PCM settings")); } - let mkv = |error: coreav_mkv::Error| refused(format!("its Matroska: {error}")); - let segment = - coreav_mkv::probe_with_metadata(&mut source, limits, &Allowlist::all()).map_err(mkv)?; - let [track] = segment.tracks.as_slice() else { - return Err(refused("not one track")); - }; - if segment.timestamp_scale == 0 || segment.timestamp_scale > 1_000_000 { - return Err(refused( - "encoder timestamps are coarser than one millisecond", - )); + let length = source.len().map_err(|e| refused(e.to_string()))?; + if length > most_bytes(expected.samples) { + return Err(refused("output exceeds its submitted PCM bound")); } - if !segment.dropped.is_empty() - || !segment.warnings.is_empty() - || track.kind != TrackKind::Audio - || track.codec != Codec::Mp3 - || track.encoding != Encoding::None - || track.codec_private.as_ref().is_some_and(|v| !v.is_empty()) - { - return Err(refused("not one uncompressed MP3 track")); + let mut header = [0u8; 10]; + source + .read_exact_at(0, &mut header) + .map_err(|e| refused(e.to_string()))?; + if header.get(..6) != Some(b"ID3\x04\0\0") { + return Err(refused("not an unflagged ID3v2.4 header")); } - let audio = track - .audio - .as_ref() - .ok_or_else(|| refused("no audio settings"))?; - if audio.sampling_frequency.to_bits() != f64::from(expected.sample_rate).to_bits() - || audio.channels != u64::from(expected.channels) - { - return Err(refused("its rate or channels are not those submitted")); + let size = read_syncsafe(header.get(6..10).unwrap_or_default())?; + if !(10..=256).contains(&size) || u64::from(size) + 10 > length { + return Err(refused("invalid encoder metadata size")); } - let to_samples = |ns: u64| { - u32::try_from( - (u128::from(ns) * u128::from(expected.sample_rate) + 500_000_000) / 1_000_000_000, - ) - .map_err(|_| refused("sample trim overflow")) - }; - let priming = to_samples(track.codec_delay)?; - let delay = priming - .checked_sub(DECODER_DELAY) - .filter(|&n| n <= MAX_TRIM) - .ok_or_else(|| refused("an unrepresentable encoder delay"))?; - let software = segment - .muxing_app - .as_deref() - .filter(|s| version(s, "Lavf")) + let mut metadata = vec![0; usize::try_from(size).map_err(|_| refused("ID3 size overflow"))?]; + source + .read_exact_at(10, &mut metadata) + .map_err(|e| refused(e.to_string()))?; + if metadata.get(..4) != Some(b"TSSE") || metadata.get(8..11) != Some(&[0, 0, 3]) { + return Err(refused("not the encoder software text frame")); + } + let text_size = usize::try_from(read_syncsafe(metadata.get(4..8).unwrap_or_default())?) + .map_err(|_| refused("text size overflow"))?; + let end = 10usize + .checked_add(text_size) + .ok_or_else(|| refused("text size overflow"))?; + let software = metadata + .get(11..end) + .and_then(|bytes| bytes.strip_suffix(&[0])) + .and_then(|bytes| std::str::from_utf8(bytes).ok()) + .filter(|text| version(text, "Lavf")) .ok_or_else(|| refused("no bounded encoder software identity"))? .to_owned(); - let encoder = segment - .tags - .iter() - .filter(|tag| track.uid.is_some_and(|uid| tag.track_uids.contains(&uid))) - .flat_map(|tag| &tag.simple_tags) - .filter(|tag| tag.name == "ENCODER") - .filter_map(|tag| tag.string.as_deref()) - .find_map(|s| s.strip_suffix(" libmp3lame").filter(|s| version(s, "Lavc"))) - .ok_or_else(|| refused("no libmp3lame encoder identity"))? - .to_owned(); - let most = expected + if !metadata + .get(end..) + .is_some_and(|bytes| bytes.iter().all(|&b| b == 0)) + { + return Err(refused("unexpected encoder metadata")); + } + let count = expected .samples - .saturating_add(u64::from(DECODER_DELAY + 2 * MAX_TRIM)) - .div_ceil(576); + .checked_add(1152) + .map(|n| n / u64::from(frame_samples)) + .ok_or_else(|| refused("sample count overflow"))?; + if count > limits.max_index_bytes / std::mem::size_of::() as u64 { + return Err(refused("frame index exceeds its limit")); + } let mut frames = Vec::new(); - let mut total = 0u64; - let mut padding = None; + let mut offset = u64::from(size) + 10; let mut first = None; let mut first_rate = None; - let mut frame_samples = 0; let mut music_crc = 0; let mut bytes = Vec::new(); - let mut packets = segment.packets(&mut source, limits).with_audit(); - while let Some(packet) = packets.next() { - let packet = packet.map_err(mkv)?; - if packet.track != 0 - || packet.block_additions.is_some() - || packet.codec_state - || padding.is_some() - || u64::try_from(frames.len()).unwrap_or(u64::MAX) >= most - { - return Err(refused("frames after the final padding or too many frames")); + while offset < length { + if frames.len() as u64 >= count { + return Err(refused("frames after the submitted PCM")); } - let size = u32::try_from(packet.stored_size) - .ok() - .filter(|n| packet.stripped == 0 && (4..=MAX_FRAME_BYTES).contains(n)) - .ok_or_else(|| refused("invalid frame size"))?; - bytes.resize( - usize::try_from(size).map_err(|_| refused("frame size overflow"))?, - 0, - ); - packets - .source_mut() - .read_exact_at(packet.offset, &mut bytes) + let mut word = [0u8; 4]; + source + .read_exact_at(offset, &mut word) .map_err(|e| refused(e.to_string()))?; - let header = Header::parse(&bytes).map_err(|e| refused(e.to_string()))?; - let expected_ns = i128::from(total) * 1_000_000_000 / i128::from(expected.sample_rate) - - i128::from(track.codec_delay); - let delta = packet - .pts_ns(&segment) - .and_then(|pts| pts.checked_sub(expected_ns)) - .ok_or_else(|| refused("an unknown or overflowing frame timestamp"))?; - if delta.unsigned_abs() > u128::from(segment.timestamp_scale) { - return Err(refused( - "a frame timestamp does not match the sample sequence", - )); - } - let frame_ns = u128::try_from(header.samples()) - .map_err(|_| refused("frame duration overflow"))? - * 1_000_000_000 - / u128::from(expected.sample_rate); - let trim_ns = u128::try_from(packet.discard_padding.unwrap_or(0)) - .map_err(|_| refused("negative discard padding"))?; - if trim_ns > frame_ns + 1 { - return Err(refused("discard padding exceeds its frame")); - } - let presented_ns = frame_ns.saturating_sub(trim_ns); - if packet.block_duration.is_some_and(|n| { - (u128::from(n) * u128::from(segment.timestamp_scale)).abs_diff(presented_ns) - > u128::from(segment.timestamp_scale) - }) || track - .default_duration - .is_some_and(|n| u128::from(n).abs_diff(frame_ns) > 1) - { - return Err(refused(format!( - "a frame duration does not match its header: block {:?} ticks, default {:?} ns, frame {frame_ns} ns", - packet.block_duration, track.default_duration - ))); - } - music_crc = crc(music_crc, &bytes); + let header = Header::parse(&word).map_err(|e| refused(e.to_string()))?; + let size = header + .frame_bytes() + .filter(|&n| (4..=MAX_FRAME_BYTES as usize).contains(&n)) + .ok_or_else(|| refused("invalid frame size"))?; if header.sample_rate != expected.sample_rate || header.channels() != usize::from(expected.channels) - || header.frame_bytes() != Some(bytes.len()) + || header.samples() as u32 != frame_samples + || size as u64 > length - offset { - return Err(refused( - "a frame header does not match its size, rate or channels", - )); + 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) { return Err(refused( @@ -321,53 +286,63 @@ pub fn read_output( )); } first_rate.get_or_insert(header.bit_rate); - let word = <[u8; 4]>::try_from(bytes.get(..4).unwrap_or_default()) - .map_err(|_| refused("no frame header"))?; first.get_or_insert(u32::from_be_bytes(word)); - frame_samples = - u32::try_from(header.samples()).map_err(|_| refused("frame sample overflow"))?; - total = total - .checked_add(u64::from(frame_samples)) - .ok_or_else(|| refused("sample count overflow"))?; - if let Some(ns) = packet.discard_padding.filter(|&n| n != 0) { - let ns = u64::try_from(ns).map_err(|_| refused("negative discard padding"))?; - padding = Some(to_samples(ns)?); + bytes.resize(size, 0); + source + .read_exact_at(offset, &mut bytes) + .map_err(|e| refused(e.to_string()))?; + let side = match (header.version, header.channels()) { + (Version::Mpeg1, 1) => 17, + (Version::Mpeg1, _) => 32, + (_, 1) => 9, + _ => 17, + }; + if frames.is_empty() + && bytes + .get(4 + side..8 + side) + .is_some_and(|tag| matches!(tag, b"Xing" | b"Info")) + { + return Err(refused( + "an unexpected information frame in the encoder pipe", + )); } + music_crc = crc(music_crc, &bytes); + frames + .try_reserve(1) + .map_err(|_| refused("frame index allocation failed"))?; frames.push(Frame { - offset: packet.offset, - size, + offset, + size: size as u32, }); + offset += size as u64; } - if !packets.warnings().is_empty() { - return Err(refused("invalid packet listing")); - } - let discarded = padding.unwrap_or(0); - if total.checked_sub(u64::from(priming) + u64::from(discarded)) != Some(expected.samples) { + if frames.len() as u64 != count { return Err(refused( "the decoded sample total does not match the submitted PCM", )); } - let padding = discarded - .checked_add(DECODER_DELAY) - .and_then(|n| n.checked_add(u32::from(expected.guard))) - .filter(|&n| n <= MAX_TRIM) - .ok_or_else(|| refused("unrepresentable final padding"))?; Ok(Output { frames, frame_samples, - priming, + priming: 576 + DECODER_DELAY, info: Info { header: first.ok_or_else(|| refused("no frames"))?, - encoder, + encoder: software.clone(), software, - delay, - padding, + delay: 576, + padding: 576 + u32::from(expected.guard), variable: expected.variable, music_crc, }, }) } +fn read_syncsafe(bytes: &[u8]) -> Result { + if bytes.len() != 4 || bytes.iter().any(|&b| b & 128 != 0) { + return Err(refused("invalid ID3 syncsafe size")); + } + Ok(bytes.iter().fold(0, |n, &b| (n << 7) | u32::from(b))) +} fn syncsafe(n: usize) -> Result<[u8; 4], ReadError> { let n = u32::try_from(n) .ok() @@ -534,99 +509,21 @@ pub(crate) fn info_frame(info: &Info, sizes: &[u32]) -> Result, ReadErro pub(crate) mod tests { use super::*; - fn element(id: &[u8], bytes: &[u8]) -> Vec { - let mut out = id.to_vec(); - out.push(1); - out.extend_from_slice(&u64::try_from(bytes.len()).unwrap().to_be_bytes()[1..]); - out.extend_from_slice(bytes); - out - } - - fn uint(id: &[u8], n: u64) -> Vec { - element(id, &n.to_be_bytes()) - } - - pub(crate) fn fixture( - codec: &str, - delay: u64, - frames: &[Vec], - padding: &[Option], - ) -> Vec { - fixture_extra(codec, delay, frames, padding, &[]) - } - - fn fixture_extra( - codec: &str, - delay: u64, - frames: &[Vec], - padding: &[Option], - extra: &[u8], - ) -> Vec { - let header = [ - uint(&[0x42, 0x86], 1), - uint(&[0x42, 0xf7], 1), - uint(&[0x42, 0xf2], 4), - uint(&[0x42, 0xf3], 8), - element(&[0x42, 0x82], b"matroska"), - uint(&[0x42, 0x87], 4), - uint(&[0x42, 0x85], 2), - ] - .concat(); - let audio = [element(&[0xb5], &48000f64.to_be_bytes()), uint(&[0x9f], 1)].concat(); - let track = [ - uint(&[0xd7], 1), - uint(&[0x73, 0xc5], 1), - uint(&[0x83], 2), - element(&[0x86], codec.as_bytes()), - uint(&[0x56, 0xaa], delay), - element(&[0xe1], &audio), - ] - .concat(); - let info = [ - uint(&[0x2a, 0xd7, 0xb1], 1_000_000), - element(&[0x4d, 0x80], b"Lavf1.2.3"), - element(&[0x57, 0x41], b"Lavf1.2.3"), - ] - .concat(); - let tag = [ - element(&[0x63, 0xc0], &uint(&[0x63, 0xc5], 1)), - element( - &[0x67, 0xc8], - &[ - element(&[0x45, 0xa3], b"ENCODER"), - element(&[0x44, 0x87], b"Lavc1.2.3 libmp3lame"), - ] - .concat(), - ), - ] - .concat(); - let mut cluster = uint(&[0xe7], 0); - for (index, frame) in frames.iter().enumerate() { - let mut block = vec![0x81]; - block.extend_from_slice(&i16::try_from(index * 24).unwrap().to_be_bytes()); - block.push(0); - block.extend_from_slice(frame); - let mut group = element(&[0xa1], &block); - if index == 0 { - group.extend_from_slice(extra); - } - if let Some(padding) = padding.get(index).copied().flatten() { - group.extend(element(&[0x75, 0xa2], &padding.to_be_bytes())); - } - cluster.extend(element(&[0xa0], &group)); + pub(crate) fn fixture(frames: &[Vec]) -> Vec { + let info = Info { + header: 0, + encoder: "Lavc1.2.3".into(), + software: "Lavf1.2.3".into(), + delay: 576, + padding: 576, + variable: false, + music_crc: 0, + }; + let mut out = metadata(&info, &[]).unwrap(); + for frame in frames { + out.extend_from_slice(frame); } - let segment = [ - element(&[0x15, 0x49, 0xa9, 0x66], &info), - element(&[0x16, 0x54, 0xae, 0x6b], &element(&[0xae], &track)), - element(&[0x12, 0x54, 0xc3, 0x67], &element(&[0x73, 0x73], &tag)), - element(&[0x1f, 0x43, 0xb6, 0x75], &cluster), - ] - .concat(); - [ - element(&[0x1a, 0x45, 0xdf, 0xa3], &header), - element(&[0x18, 0x53, 0x80, 0x67], &segment), - ] - .concat() + out } fn frame() -> Vec { @@ -653,10 +550,25 @@ pub(crate) mod tests { ) } + #[test] + fn encoder_identity_requires_one_declared_libmp3lame_version() { + let line = " encoder : Lavc63.1.102 libmp3lame\n"; + assert_eq!(encoder_identity(line).unwrap(), "Lavc63.1.102"); + for text in [ + String::new(), + line.repeat(2), + line.replace("Lavc", "Lavf"), + line.replace("libmp3lame", "aac"), + line.replace("63.1.102", "invalid"), + line.replace("63.1.102", &"1".repeat(65)), + ] { + assert!(encoder_identity(&text).is_err()); + } + } + #[test] fn complete_frames_and_exact_sample_accounting_are_required() { - let frames = [frame(), frame()]; - let file = fixture("A_MPEG/L3", 23_020_833, &frames, &[None, Some(979_167)]); + let file = fixture(&[frame(), frame()]); let output = read(&file, expected()).unwrap(); assert_eq!(output.frames.len(), 2); assert_eq!(output.priming, 1105); @@ -672,22 +584,10 @@ pub(crate) mod tests { .unwrap(); assert_eq!(guarded.info.padding, 1727); for bytes in [ - fixture("A_AAC", 23_020_833, &frames, &[None, Some(979_167)]), - fixture("A_MPEG/L3", 0, &frames, &[None, Some(979_167)]), - fixture("A_MPEG/L3", 23_020_833, &frames, &[Some(979_167), None]), - fixture("A_MPEG/L3", 23_020_833, &frames, &[None, Some(-1)]), - fixture( - "A_MPEG/L3", - 23_020_833, - &[vec![0; 192], frame()], - &[None, Some(979_167)], - ), - fixture( - "A_MPEG/L3", - 23_020_833, - &[vec![0xff, 0xfb, 0x54, 0xc4], frame()], - &[None, Some(979_167)], - ), + fixture(&[frame()]), + fixture(&[frame(), frame(), frame()]), + fixture(&[vec![0; 192], frame()]), + fixture(&[vec![0xff, 0xfb, 0x54, 0xc4], frame()]), ] { assert!(read(&bytes, expected()).is_err()); } @@ -708,6 +608,10 @@ pub(crate) mod tests { guard: 1152, ..expected() }, + Expected { + samples: u64::MAX, + ..expected() + }, ] { assert!(read(&file, changed).is_err()); } @@ -718,44 +622,58 @@ pub(crate) mod tests { #[test] fn full_output_structure_auxiliary_data_and_timestamps_are_checked() { - let frames = [frame(), frame()]; - let padding = [None, Some(979_167)]; - let file = fixture("A_MPEG/L3", 23_020_833, &frames, &padding); - for tail in [vec![0xff; 10], file.clone()] { + let file = fixture(&[frame(), frame()]); + for tail in [vec![0xff; 10], file.clone(), vec![0; 128]] { let mut appended = file.clone(); appended.extend(tail); assert!(read(&appended, expected()).is_err()); } - for extra in [ - element(&[0xa4], b"state"), - element( - &[0x75, 0xa1], - &element(&[0xa6], &element(&[0xa5], b"addition")), - ), - uint(&[0x9b], 1000), + for (at, value) in [ + (3, 3), + (5, 0x10), + (6, 128), + (9, 255), + (10, b'X'), + (11, b'I'), + (18, 1), + (20, 1), + (21, b'X'), ] { - let bytes = fixture_extra("A_MPEG/L3", 23_020_833, &frames, &padding, &extra); - assert!(read(&bytes, expected()).is_err()); + let mut changed = file.clone(); + changed[at] = value; + assert!(read(&changed, expected()).is_err(), "{at}"); } - let mut moved = file; - let frame_offsets: Vec<_> = moved - .windows(4) - .enumerate() - .filter_map(|(i, bytes)| (bytes == [0xff, 0xfb, 0x54, 0xc4]).then_some(i)) - .collect(); - let second = frame_offsets[1]; - moved[second - 3..second - 1].copy_from_slice(&(-30000i16).to_be_bytes()); - assert!(read(&moved, expected()).is_err()); + let mut info_frame = frame(); + info_frame[21..25].copy_from_slice(b"Info"); + assert!(read(&fixture(&[info_frame, frame()]), expected()).is_err()); + let mut changed = frame(); + changed[3] = 0; + assert!(read(&fixture(&[frame(), changed]), expected()).is_err()); + let mut changed = frame(); + changed[2] = 0x64; + changed.resize(240, 0); + let bytes = fixture(&[frame(), changed]); + assert!(read(&bytes, expected()).is_err()); + assert!( + read( + &bytes, + Expected { + variable: true, + ..expected() + } + ) + .is_ok() + ); + let limits = coreav_mkv::Limits { + max_index_bytes: 0, + ..Default::default() + }; + assert!(read_output(coreav_mkv::SliceSource::new(&file), &expected(), &limits).is_err()); } #[test] fn the_writer_describes_audio_frames_without_counting_its_information_frame() { - let file = fixture( - "A_MPEG/L3", - 23_020_833, - &[frame(), frame()], - &[None, Some(979_167)], - ); + let file = fixture(&[frame(), frame()]); let output = read(&file, expected()).unwrap(); let info = info_frame(&output.info, &[192, 192]).unwrap(); assert_eq!(&info[21..25], b"Info"); diff --git a/docs/agents/transcode.md b/docs/agents/transcode.md index 67ec3ebb8..452c5d3ac 100644 --- a/docs/agents/transcode.md +++ b/docs/agents/transcode.md @@ -13,8 +13,10 @@ Encode path, sandboxed workers, and audio-encode selection. | Strict-safe diagnostic tests prove the diagnostic refusal rather than accepting CLI usage or earlier platform errors | `in_process_diagnostics_refuse_strict_safe` checks the boundary directly on every platform; `diagnostic_errors_precede_media_probing` passes the root option before the subcommand, requires structured error JSON and checks the exact diagnostic on Linux, or the earlier OS-limit refusal elsewhere. A generic stderr substring cannot establish which boundary ran | | Once native FFV1 encoding starts, changed frames and decoder capability failures are terminal and never enter compatibility fallback | `Run::refused` and `Run::decode_error` classify errors from the existing encoder state; `InvalidFrame` maps to invalid data, not an unsupported-input refusal. The shape snapshot stores raw frame colour before container inheritance, so disappearing declarations cannot be masked. `late_frame_changes_are_terminal_without_publishing_another_packet` covers geometry, pixel format, colour changes and disappearing colour. `ffv1_check.py` changes geometry and colour mid-stream and requires specific diagnostics, exit 1, an unchanged destination and no fallback log entry in required CI, with colour checked in both strict modes. Negative tests reject unrelated exit-1 causes. Runtime decoder output and external diagnostics cannot be fixed by a static source format type | | AVI MP3 uses the shared PCM feeder and audited reader without changing its complete frames or packet clock | `audio::encode_with` owns process settings, sample feeding and readback for both callers; `EncodedAudio::mp3_packets` only retains checked frames. `ffmpeg_avi_mp3_keeps_the_previous_complete_file_bytes` compares entire AVI files with the former raw-pipe encoder invocation and unchanged AVI writer, including mono/stereo, MPEG rate families, default/explicit bitrates and EOF boundaries (`ci.yml`). An external encoder's byte identity needs a runtime comparison | -| MP3 encoding validates the full PCM count including its EOF zero guard, then removes that explicit guard in the gapless tag | The shared audio feeder counts original and fed samples separately; `mp3::read_output` requires exact CodecDelay/DiscardPadding accounting. `ffmpeg_mp3_eof_guard_preserves_exact_boundary_lengths` checks seekable oracle decoding and ffprobe at residues 1, 46 and 47 in all three MPEG rate families; malformed, truncated and out-of-bound output is covered by `mp3` unit tests and the `mp3_output` fuzz target | -| MP3 encoder readback audits the entire spool, rejects auxiliary/state changes and verifies frame timing within Matroska quantization, under the encode deadline | `Packets::with_audit` owns the full-file walk; packet fields retain `CodecState` and block additions for the MP3 boundary to reject. `full_output_structure_auxiliary_data_and_timestamps_are_checked` covers appended bytes/segments, additions, codec state, duration and reordered timestamps. `TimedSource` checks cached parser reads too; `readback_checks_the_deadline_inside_parser_reads` requires timeout classification and at most one underlying read after a controlled deadline crossing | +| MP3 encoding validates the full PCM count including its EOF zero guard, then removes that explicit guard in the gapless tag | The shared audio feeder counts original and fed samples separately; `mp3::read_output` requires the frame-aligned libmp3lame flush count and documented default encoder delay. `ffmpeg_mp3_eof_guard_preserves_exact_boundary_lengths` checks seekable oracle decoding and ffprobe at residues 1, 46 and 47 in all three MPEG rate families; malformed, truncated and out-of-bound output is covered by `mp3` unit tests and the `mp3_output` fuzz target | +| MP3 encoder readback audits the entire spool and rejects extra metadata, information frames and changed framing under the encode deadline | `mp3::read_output` owns the strict ID3 and complete-frame walk without resynchronization. `full_output_structure_auxiliary_data_and_timestamps_are_checked` covers appended bytes, metadata mutations, information frames, changed channels and bit rates. `TimedSource` checks cached parser reads too; `readback_checks_the_deadline_inside_parser_reads` requires timeout classification and at most one underlying read after a controlled deadline crossing | +| An external MP3 encode starts only encoder-only MP3 commands, with no help probe or external container adaptation | The availability probe and MP3 feeder share the argument owner; `mp3_worker_starts_and_output_pass_the_frozen_checks` observes every sandboxed start with the existing FIFO logger, applies the unchanged frozen classifier and compares complete decoded output and timing with the pinned oracle in both source builds (`ci.yml`). Static argument types cannot prove actual external process starts | +| A missing external MP3 encoder refuses on its diagnostic after a normal nonzero exit, without assuming exit status 1 or converting resource and signal failures into refusals | `probe_encoder` owns the classification; `mp3_availability_errors_keep_their_classification_and_output_bound` checks statuses 1 and 8 and preserves terminal flood and signal failures even when their stderr contains the missing-encoder diagnostic. The external program's exit convention and diagnostic require runtime checks rather than a static type | | A failed B9 baseline preserves explicit `-an` and otherwise retains the remux audio expectation; it supplies no quality evidence | `check_compat` derives explicit audio absence from its command tokens. The baseline-failure regressions in `scripts/transcode_check_selftest.py` check both expectations, rejection of unexpected audio and failed Q1/Q2 judgments. External command outcomes need runtime checks | | Audio encodes take the first source stream the build decodes, or the explicitly selected stream, applying source trimming once before output encoder delay | `coreav_audio::decode` owns stream selection and presentation trimming; `Codec::from_name` supplies the CLI's build-aware capability check. The AAC-only, Opus-only, Opus-before-FLAC and timing cases in `coreav-cli/tests/transcode.rs` run with and without `aac` (`ci.yml`) | | A stopped encoder returns its queued decoder slots without destroying queued caller-provided frames on the caller's thread | The encoder keeper owns queued-frame disposal after process teardown; the frame-pool, early-exit and closed-input cases in `coreav-transcode/tests/sandboxed.rs` check nonblocking caller cleanup and prompt slot return | diff --git a/docs/design/transcode.md b/docs/design/transcode.md index dcfb5874d..d3000df89 100644 --- a/docs/design/transcode.md +++ b/docs/design/transcode.md @@ -992,24 +992,36 @@ transcode fixture target with and without `aac`. MP3 encoding uses the operator's `ffmpeg -c:a libmp3lame` as a separate resource-limited process under policy record 0042. CoreAV supplies decoded -float PCM, never the input file. The process writes Matroska to a bounded -spool: RFC 9559's `CodecDelay` and final `DiscardPadding` retain the -presentation boundaries that a raw MP3 pipe does not. At EOF, CoreAV adds +float PCM, never the input file. The process writes MP3 on standard output +to a bounded spool, using only raw-input and encoder options. CoreAV owns +the ID3 and Xing/Info adaptation and every destination container. The +encoder keeps its existing pipe transport, process limits and sandbox; +allowing it to write a seekable file would weaken the no-file-writes rule. +MP3 checks availability with an empty raw-PCM encode, not an encoder-help +command. Both starts are encoder-only MP3 invocations; an unavailable +encoder is refused before source decoding or output publication. +At EOF, CoreAV adds an explicit zero guard to finish a complete codec frame: for N presented samples and a frame size F, G = (F - N mod F) mod F. F is 1,152 at 32, 44.1 and 48 kHz, and 576 at the lower supported rates. The reader validates all N + G fed samples, and the writer adds G to its final padding field so that the published file presents only N. CoreAV's reader -checks one uncompressed `A_MPEG/L3` track, rate, channels, every complete -Layer III frame and the exact decoded sample total before writing output. -The existing Matroska structure audit covers the entire spool, including -anything after the first segment. Block additions and codec-state changes -are refused, and frame timestamps and durations must match the sample -sequence within the container's timestamp quantum. Readback checks the +checks the bounded ID3v2.4 software identity and every complete Layer III +frame through the exact end of the spool, with no resynchronization or +trailing metadata. Headers must retain the submitted rate and channels, +and constant-rate mode must retain its bit rate. The raw pipe has no +gapless tag: the adapter uses libmp3lame's documented default 576-sample +encoder delay, plus the 529-sample decoder delay. With frame-aligned fed +PCM, the encoder must produce exactly 1,152 additional decoded samples; +CoreAV rejects a different total instead of deriving arbitrary padding +from it. The stored delay is 576 and the stored final padding is 576 + G. +This contract is specific to the external libmp3lame encoder, not a general +MP3 parser or a claim that raw frames describe their presentation. +Readback checks the encode deadline before and after source reads, including buffered reads; a single synchronous source operation cannot be interrupted. -These checks add a bounded structural walk and a clock check at each +These checks add a bounded frame walk and a clock check at each readback source call. Packet listing retains one codec-state flag; no throughput or instruction-count improvement is claimed. @@ -1023,6 +1035,14 @@ documented by the [LAME technical FAQ](https://lame.sourceforge.io/tech-FAQ.txt) it is not counted twice in the stored encoder-delay field. ID3 text uses the [ID3v2.4 structure](https://id3.org/id3v2.4.0-structure) and [frame specification](https://id3.org/id3v2.4.0-frames). +The raw output's `Lavf` software identity is retained in ID3. The real +encoding command's bounded standard-error tail supplies its declared +`Lavc` encoder identity for the information tag. Progress statistics are +disabled, and missing or ambiguous identities fail closed. No version is +inferred from a different library's version. +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. 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` @@ -1078,6 +1098,15 @@ Committed before the MP3 correctness matrix runs: output. Every command in the requested MP3 command set is reported as passed or blocked, with a reason; unsupported containers stay blocked. +The worker-protocol regression uses generated lossless sources at all nine +rates, mono and stereo, with default rate control, an explicit constant +rate and variable-rate quality. It records every actual encoder start +through the existing sandbox-safe FIFO logger and passes them to the +unchanged compatibility classifier. The frozen output comparator checks +complete decoded samples and exact frame timing against FFmpeg 9.0.2. +This is development evidence, not a new command-set measurement or a claim +that AAC source decoding is byte-identical to the oracle. + ## Through `coreav ffmpeg` `coreav ffmpeg` ([`compat-cli.md`](compat-cli.md)) runs the common diff --git a/scripts/mp3_worker_check.py b/scripts/mp3_worker_check.py new file mode 100644 index 000000000..5eee0f5ca --- /dev/null +++ b/scripts/mp3_worker_check.py @@ -0,0 +1,70 @@ +"""Check actual MP3 worker starts with the unchanged compatibility classifier.""" +import argparse +import os +from pathlib import Path +import subprocess +import sys + +ROOT = Path(__file__).resolve().parents[1] +sys.path[:0] = [str(ROOT / 'tools/compat-corpus'), str(ROOT / 'scripts')] +import decoded_output +import encode_breadth +import test_oracle + + +def run(args, env=None): + result = subprocess.run(list(map(str, args)), env=env, capture_output=True, timeout=60) + if result.returncode: + raise AssertionError(f'command exited {result.returncode}: {result.stderr.decode(errors="replace")}') + return result + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('--coreav', type=Path, required=True) + parser.add_argument('--work', type=Path, required=True) + args = parser.parse_args() + oracle = test_oracle.require() + args.work.mkdir(parents=True, exist_ok=True) + log = encode_breadth.ProgramLog(args.work / 'programs', oracle.ffmpeg, oracle.ffmpeg) + env = {**os.environ, 'COREAV_FFMPEG': str(log.wrappers['ffmpeg']), + 'COREAV_FALLBACK': '/nonexistent/coreav-mp3-worker-fallback'} + checked = 0 + try: + for samples in (4608, 4992): + for rate in (48000, 44100, 32000, 24000, 22050, 16000, 12000, 11025, 8000): + for channels in (1, 2): + source = args.work / f'source-{samples}-{rate}-{channels}.mp4' + run([oracle.ffmpeg, '-nostdin', '-v', 'error', '-f', 'lavfi', '-i', + f'sine=frequency=440:sample_rate={rate}', '-af', f'atrim=end_sample={samples}', + '-ac', channels, '-c:a', 'flac', source]) + for mode, options in (('default', []), ('constant', ['-b:a', '128k']), + ('quality', ['-q:a', '2.5'])): + name = f'{samples}-{rate}-{channels}-{mode}' + candidate, reference = [args.work / f'{name}-{side}.mp3' + for side in ('candidate', 'reference')] + run([args.coreav, 'ffmpeg', '-i', source, *options, candidate], env) + starts = log.drain() + assert len(starts) == 2, (name, starts) + assert all(start['program'] == 'ffmpeg' and + encode_breadth.mp3_encoder_start(start['args']) and + encode_breadth.encoder_start(start['program'], start['args']) + for start in starts), (name, starts) + rejected = [*starts[0]['args']] + rejected[rejected.index('mp3')] = 'matroska' + assert not encode_breadth.mp3_encoder_start(rejected) + run([oracle.ffmpeg, '-nostdin', '-v', 'error', '-i', source, *options, reference]) + scratch = args.work / f'{name}-comparison' + scratch.mkdir() + verdict = decoded_output.compare(candidate, reference, oracle.ffmpeg, + oracle.ffprobe, os.environ, scratch, + exact_frame_timeline=True) + assert verdict == ('verified', 'exact decoded output'), (name, verdict) + checked += 1 + finally: + log.close() + print(f'{checked} MP3 commands: both encoder starts accepted; exact decoded output and timing') + + +if __name__ == '__main__': + main() diff --git a/scripts/tests/test_mp3_worker.py b/scripts/tests/test_mp3_worker.py new file mode 100644 index 000000000..d56ccbd9b --- /dev/null +++ b/scripts/tests/test_mp3_worker.py @@ -0,0 +1,27 @@ +"""Keep the MP3 protocol regression in both oracle-enabled source builds.""" +from pathlib import Path +import shlex +import unittest + + +class WorkerWorkflow(unittest.TestCase): + def test_both_transcode_fixture_builds_run_the_protocol_target(self): + root = Path(__file__).resolve().parents[2] + workflow = (root / '.github/workflows/ci.yml').read_text().replace('\\\n', ' ') + commands = [shlex.split(line.strip()) for line in workflow.splitlines() + if line.strip().startswith('cargo test ')] + for features in ('ffmpeg-fallback,dav1d,libvpx,libopus', + 'ffmpeg-fallback,dav1d,libvpx,libopus,aac'): + selected = [args for args in commands if '--no-run' not in args and '--features' in args and + args[args.index('--features') + 1] == features and + '--test' in args and 'transcode' in args] + self.assertEqual(len(selected), 1, features) + protocol = [args for args in commands if '--no-run' not in args and '--features' in args and + args[args.index('--features') + 1] == features and '--test' in args and + args[args.index('--test') + 1] == 'mp3_worker'] + self.assertEqual(len(protocol), 1, + 'Run --test mp3_worker beside each complete transcode fixture target') + + +if __name__ == '__main__': + unittest.main()