diff --git a/doc/bin/cli.md b/doc/bin/cli.md index e98f611a13f..fab9bdecf50 100644 --- a/doc/bin/cli.md +++ b/doc/bin/cli.md @@ -36,6 +36,7 @@ Pi 4, CM4, or Zero 2 W on a 64-bit OS. On a CPU missing a feature rind needs, | `announced` | `[prefix]` | Follow the broadcasts announced on a relay. | | `fetch` | `` | Write one group of a track to stdout. | | `auth` | | Generate, sign, and verify relay JWTs. | +| `repair` | `mp4 ` | Finish an `export mp4` recording that was cut short. | | `devices` | | List capture sources and their ids. | ## Grammar @@ -207,11 +208,15 @@ fragmented MP4 while recording, so a crash leaves a playable file, and the broadcast's end or the first Ctrl-C (or SIGTERM) finishes it as a regular MP4 with its index at the end, without copying the media. Finishing writes everything received, the fragment still buffering included. A second signal exits at once -and leaves it fragmented, minus that fragment. Unlike `fmp4`, a rendition that joins mid-recording is -kept, though only the finished file indexes it. +and leaves it fragmented, minus that fragment. Unlike `fmp4`, a rendition that +joins mid-recording is kept, though only the finished file indexes it. +`moq repair mp4 ` finishes a recording that a crash or second signal left +fragmented, in place and the same way: it indexes every fragment written in full, +late renditions included, and cuts a partial one at the end. ```bash moq ... export mp4 --output recording.mp4 +moq repair mp4 recording.mp4 ``` MPEG-TS export pads to the source's constant mux rate when the catalog diff --git a/quest/m2/README.md b/quest/m2/README.md index f95c170a423..fd1acc4fc4b 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -234,8 +234,7 @@ lite-07; bitrate enforcement is not part of this release. - [We own our WebRTC stack](/quest/m2/webrtc/README.md) - moq-rtc becomes moq-webrtc with moq-ice, the data-channel transport, and a vendored, trimmed str0m/dimpl/is/sctp-proto - [Certificate reload and qmux's tasks are supervised](/quest/m2/tls-reload-supervision.md) - a panic in either fails loudly instead of silently stopping - [PUBLISH_DONE says why](/quest/m2/publish-done-codes.md) - GOING_AWAY, TOO_FAR_BEHIND, and EXPIRED round-trip as stream codes -- [Repair a crashed mp4 recording](/quest/m2/mp4-repair.md) - a crashed recording's fragmented file becomes a regular MP4 -- [moq repair refuses a live recording](/quest/m2/mp4-repair-lock.md) - the recorder's advisory lock keeps `moq repair` off a file still being written +- [moq repair refuses a live recording](/quest/m2/mp4-repair-lock.md) - the recorder's advisory lock keeps `moq repair mp4` off a file still being written - [Windows receives notice truncated control data](/quest/m2/cmsg-windows-truncation.md) - Windows handles `MSG_CTRUNC` like the Unix paths - [The error-queue reader decodes truncated control data](/quest/m2/errqueue-truncation.md) - `MSG_ERRQUEUE` keeps what fit on `MSG_CTRUNC`, like the receive paths - [moq-quic's internal dev-dependencies are path-only](/quest/m2/quic-dev-dep-path.md) - moq-congestion is a path dev-dependency diff --git a/quest/m2/mp4-repair-lock.md b/quest/m2/mp4-repair-lock.md index a0acb9fcde5..ad067eb8862 100644 --- a/quest/m2/mp4-repair-lock.md +++ b/quest/m2/mp4-repair-lock.md @@ -2,18 +2,18 @@ ## Goal -`moq export mp4 --output ` holds an advisory lock on its output while it records, and `moq repair ` refuses, with a message saying a recorder still has it open, when it can't take that lock. Neither side runs unlocked: where the filesystem can't lock, both refuse. Repairing a file mid-recording no longer corrupts it. +`moq export mp4 --output ` holds an advisory lock on its output while it records, and `moq repair mp4 ` refuses, with a message saying a recorder still has it open, when it can't take that lock. Neither side runs unlocked: where the filesystem can't lock, both refuse. Repairing a file mid-recording no longer corrupts it. ## Plan -Found by [moq-dev/moq#7560](https://github.com/moq-dev/moq/pull/7560), which adds `moq repair`: it can't tell a running `export mp4` still writes the file, and repairing one corrupts it. #7560 is still a draft, so this waits on it landing; `moq repair` and `moq_mux::container::mp4::repair` don't exist on `main` until then. +Found by [moq-dev/moq#7560](https://github.com/moq-dev/moq/pull/7560), which adds `moq repair mp4`: it can't tell a running `export mp4` still writes the file, and repairing one corrupts it. This waits on #7560 landing; `moq repair mp4` and `moq_mux::container::mp4::repair` don't exist on `main` until then. Decided 2026-11-01 (maintainer, follow-up planning after the 2026-11-01 /quest-afk run): m2. An advisory lock taken by the recorder and checked by repair, as #7560 suggested. - The CLI owns the lock, not moq-mux: `repair` in moq-mux takes `impl Read + Seek` and stays file-agnostic. Use an exclusive `flock`-style lock on the open file (`std::fs::File::try_lock` is stable in Rust 1.89), held for the recording's life and released by the OS if the recorder dies, so a crashed recording stays repairable. - Supported or refused (`AGENTS.md`), on both sides. The recorder fails at startup if it can't take the lock, a filesystem without lock support included, since its recording could never be repaired safely. `repair` takes the same lock non-blocking before scanning and refuses if it can't: held means a recorder still has the file open, and any other lock error (no lock support) refuses with that error rather than repairing unlocked. -- Test: a held lock makes `moq repair` refuse and leave the file untouched; #7560's nightly `export::a_killed_mp4_recording_is_repaired` still repairs after SIGKILL, since the lock dies with the process. -- Update `doc/bin/cli.md`'s `repair` entry. +- Test: a held lock makes `moq repair mp4` refuse and leave the file untouched; #7560's nightly `export::a_killed_mp4_recording_is_repaired` still repairs after SIGKILL, since the lock dies with the process. +- Update `doc/bin/cli.md`'s `repair mp4` entry. Public API: none (CLI behavior only). Wire: none. diff --git a/quest/m2/mp4-repair.md b/quest/m2/mp4-repair.md deleted file mode 100644 index ce5ff24bf2f..00000000000 --- a/quest/m2/mp4-repair.md +++ /dev/null @@ -1,13 +0,0 @@ -# [M] Repair a crashed mp4 recording - -## Goal - -`moq` can turn the fragmented file a crashed or twice-interrupted `moq export mp4` left behind into a regular MP4, with the same layout a clean finish produces, including renditions that joined mid-recording. - -## Plan - -Follow-up of [moq-dev/moq#7357](https://github.com/moq-dev/moq/pull/7357). Its finish step already rebuilds the sample tables by parsing the written moofs back; reuse that indexer rather than writing a second one. - -Decided 2026-10-30 (maintainer, follow-up planning after the /quest-afk run). Late renditions are written inside `free` boxes that only the final `moov` indexes, so they're unrecoverable today: the recorder must also write each late rendition's track description into the file at the time it joins. Test a file cut at several points (mid-fragment, after a late rendition joins) and check the repaired file decodes like a clean finish of the same data. - -Public API: a CLI subcommand or flag (pick the shape in the PR and list it). Wire: none. diff --git a/rs/moq-cli/src/args.rs b/rs/moq-cli/src/args.rs index 9f45c72542a..539143e1c68 100644 --- a/rs/moq-cli/src/args.rs +++ b/rs/moq-cli/src/args.rs @@ -445,7 +445,7 @@ impl Invocation { // Only `import` and `export` share an Origin. The rest own the process: `play` // drives a window on the main thread, `transcode` builds its own Origin, `fetch` - // and `announced` open their own session, and `auth` / `devices` never touch the network at all. + // and `announced` open their own session, and `auth` / `repair` / `devices` never touch the network at all. if let Some(command) = self.stages.iter().find(|command| !command.is_stageable()) { anyhow::bail!( "`{}` must be the only verb; it can't share a process with another `--` stage", @@ -685,6 +685,8 @@ pub enum Command { Announced(crate::announced::Args), /// Write one group of a track to stdout. Fetch(crate::fetch::Args), + /// Finish a recording that a crash or second signal left unfinished. + Repair(crate::repair::Args), /// Play a broadcast in a native window and speaker. #[cfg(feature = "play")] Play(crate::play::Args), @@ -744,6 +746,7 @@ impl Command { Self::Export(_) | Self::Subscribe(_) => "export", Self::Announced(_) => "announced", Self::Fetch(_) => "fetch", + Self::Repair(_) => "repair", #[cfg(feature = "play")] Self::Play(_) => "play", #[cfg(feature = "transcode")] @@ -1390,7 +1393,7 @@ pub struct Recorded { /// The file to record to, which must not exist yet. It plays as fragmented MP4 while /// recording; the broadcast's end or the first SIGINT/SIGTERM finishes it as a regular - /// MP4, and a second signal exits at once, leaving it fragmented. + /// MP4, and a second signal exits at once, leaving it fragmented for `moq repair mp4`. #[usage(long, value_name = "FILE", value_hint = usage_rs::ValueHint::FilePath)] pub output: PathBuf, } @@ -2775,7 +2778,11 @@ mod tests { Invocation::try_parse_from(argv).unwrap_or_else(|err| panic!("{flag:?}: {err}")) }; - for verb in [&["auth", "generate"][..], &["completion", "bash"]] { + for verb in [ + &["auth", "generate"][..], + &["completion", "bash"], + &["repair", "mp4", "recording.mp4"], + ] { for flag in accept.iter().chain(dial) { let err = parse(flag, verb).reject(verb[0]).unwrap_err().to_string(); assert!(err.contains(flag[0]), "{verb:?} {flag:?}: {err}"); diff --git a/rs/moq-cli/src/main.rs b/rs/moq-cli/src/main.rs index 4ec8fcf129f..89dadceef91 100644 --- a/rs/moq-cli/src/main.rs +++ b/rs/moq-cli/src/main.rs @@ -16,6 +16,7 @@ mod hls; mod moq; mod play; mod publish; +mod repair; mod report; mod rtc; mod rtmp; @@ -365,6 +366,10 @@ async fn run() -> anyhow::Result<()> { cli.reject("completion")?; return completion.run(); } + Command::Repair(repair) => { + cli.reject("repair")?; + return repair.run().await; + } #[cfg(feature = "capture")] Command::Devices => { cli.reject("devices")?; diff --git a/rs/moq-cli/src/repair.rs b/rs/moq-cli/src/repair.rs new file mode 100644 index 00000000000..8f2499ce2c7 --- /dev/null +++ b/rs/moq-cli/src/repair.rs @@ -0,0 +1,66 @@ +//! `moq repair `: finish a recording that its recorder left unfinished. + +use std::path::PathBuf; + +use anyhow::Context; + +/// Finish a recording that a crash or second signal left unfinished. +#[derive(usage_rs::Args, Clone)] +#[usage(unknown_flags = "error", args_override_self = false)] +pub struct Args { + #[usage(subcommand)] + format: Format, +} + +impl Args { + /// Repair the recording in the named format. + pub async fn run(self) -> anyhow::Result<()> { + match self.format { + Format::Mp4(mp4) => mp4.run().await, + } + } +} + +/// The recorder that left the file, one per format that can be cut short. +#[derive(usage_rs::Subcommands, Clone)] +enum Format { + /// Finish an `export mp4` recording that a crash or second signal left fragmented. + Mp4(Mp4), +} + +/// `moq repair mp4 `. +#[derive(usage_rs::Args, Clone)] +#[usage(unknown_flags = "error", args_override_self = false)] +struct Mp4 { + /// The recording, finished in place as a regular MP4 that indexes every complete fragment. + #[usage(arg, value_name = "FILE", value_hint = usage_rs::ValueHint::FilePath)] + file: PathBuf, +} + +impl Mp4 { + /// Index the recording and write its `moov`, or report that it is already finished. + async fn run(self) -> anyhow::Result<()> { + let path = self.file; + let file = std::fs::OpenOptions::new() + .read(true) + .write(true) + .open(&path) + .with_context(|| format!("failed to open {}", path.display()))?; + let (file, finish) = tokio::task::spawn_blocking(move || { + let mut file = file; + let finish = moq_mux::container::mp4::repair(&mut file); + (file, finish) + }) + .await?; + let finish = finish.with_context(|| format!("failed to repair {}", path.display()))?; + + match finish { + Some(finish) => { + crate::subscribe::write_finish(&mut tokio::fs::File::from_std(file), &finish).await?; + tracing::info!(path = %path.display(), "recording repaired"); + } + None => tracing::info!(path = %path.display(), "recording already finished"), + } + Ok(()) + } +} diff --git a/rs/moq-cli/src/subscribe.rs b/rs/moq-cli/src/subscribe.rs index c55e5484e29..e58c102ad74 100644 --- a/rs/moq-cli/src/subscribe.rs +++ b/rs/moq-cli/src/subscribe.rs @@ -410,12 +410,7 @@ impl Subscribe { match mp4.finish()? { Some(trailer) => { - file.write_all(&trailer.moov).await?; - // The header points readers past the media at the moov, so the moov must be on disk first. - file.sync_data().await?; - file.seek(std::io::SeekFrom::Start(trailer.mdat_offset)).await?; - file.write_all(&trailer.mdat).await?; - file.sync_all().await?; + write_finish(&mut file, &trailer).await?; tracing::info!(path = %path.display(), "recording finished"); } // Nothing reached the file, so there is no recording to keep. @@ -604,3 +599,16 @@ impl Subscribe { Ok(()) } } + +/// Make the writes that turn a recording into a regular MP4: the moov where the media ends, +/// then the mdat header over the reserved box. +pub async fn write_finish(file: &mut tokio::fs::File, finish: &moq_mux::container::mp4::Finish) -> std::io::Result<()> { + file.set_len(finish.moov_offset).await?; + file.seek(std::io::SeekFrom::Start(finish.moov_offset)).await?; + file.write_all(&finish.moov).await?; + // The header points readers past the media at the moov, so the moov must be on disk first. + file.sync_data().await?; + file.seek(std::io::SeekFrom::Start(finish.mdat_offset)).await?; + file.write_all(&finish.mdat).await?; + file.sync_all().await +} diff --git a/rs/moq-cli/tests/integration/export.rs b/rs/moq-cli/tests/integration/export.rs index 30d2301b920..763e782f922 100644 --- a/rs/moq-cli/tests/integration/export.rs +++ b/rs/moq-cli/tests/integration/export.rs @@ -1111,6 +1111,70 @@ async fn a_passthrough_export_ends_with_its_redundant_importer() { feeding.abort(); } +/// `repair mp4` finishes a recording whose `export mp4` was killed as a regular MP4, and leaves +/// it alone once finished. +#[tokio::test] +#[ignore = "real-time process test: just rs cli-export"] +async fn a_killed_mp4_recording_is_repaired() { + let relay = relay().await; + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("recording.mp4"); + let mut recording = moq(&relay, &[]) + .args(["export", "mp4", "--output"]) + .arg(&path) + .spawn() + .expect("spawn export"); + let (mut publisher, feeding) = import(&relay); + + kio::clock::timeout(TIMEOUT, async { + while std::fs::metadata(&path).map_or(0, |file| file.len()) < 10_000 { + kio::clock::sleep(Duration::from_millis(50)).await; + } + }) + .await + .expect("the recording never grew"); + recording.kill().await.unwrap(); + let killed = std::fs::read(&path).unwrap(); + assert_eq!( + boxes(&killed)[1].kind().to_string(), + "free", + "the killed recording is unfinished" + ); + + let repair = || async { + let output = tokio::process::Command::new(env!("CARGO_BIN_EXE_moq")) + .args(["repair", "mp4"]) + .arg(&path) + .output(); + let output = kio::clock::timeout(TIMEOUT, output) + .await + .expect("repair never exited") + .unwrap(); + assert!(output.status.success(), "{}", String::from_utf8_lossy(&output.stderr)); + std::fs::read(&path).unwrap() + }; + let repaired = repair().await; + let boxes = boxes(&repaired); + let kinds: Vec = boxes.iter().map(|atom| atom.kind().to_string()).collect(); + assert_eq!(kinds, ["ftyp", "mdat", "moov"]); + let Some(mp4_atom::Any::Moov(moov)) = boxes.last() else { + unreachable!(); + }; + assert_eq!(moov.trak.len(), 2, "video and audio"); + // Only the reserved box changed before the moov, which replaces any partial fragment. + let reserved = u32::from_be_bytes(killed[..4].try_into().unwrap()) as usize; + let media = reserved + u64::from_be_bytes(repaired[reserved + 8..reserved + 16].try_into().unwrap()) as usize; + assert!(media <= killed.len()); + assert_eq!(repaired[..reserved], killed[..reserved]); + assert_eq!(repaired[reserved + 16..media], killed[reserved + 16..media]); + + assert_eq!(repair().await, repaired, "a finished recording is left alone"); + + let stdin = feeding.await.unwrap(); + drop(stdin); + assert!(wait(&mut publisher).await.success()); +} + /// The top-level boxes of an MP4 file, by kind. fn boxes(file: &[u8]) -> Vec { use mp4_atom::DecodeMaybe; diff --git a/rs/moq-mux/src/container/fmp4/mod.rs b/rs/moq-mux/src/container/fmp4/mod.rs index b14ff7d172f..da472731c0b 100644 --- a/rs/moq-mux/src/container/fmp4/mod.rs +++ b/rs/moq-mux/src/container/fmp4/mod.rs @@ -370,6 +370,10 @@ pub enum Error { /// What the sample tables can't express. reason: &'static str, }, + + /// A file to repair is not a recording that an MP4 export left unfinished. + #[error("not an unfinished mp4 recording: {0}")] + Unrepairable(&'static str), } impl From for Error { diff --git a/rs/moq-mux/src/container/mp4.rs b/rs/moq-mux/src/container/mp4.rs index 9d526e34fce..0d86c8de171 100644 --- a/rs/moq-mux/src/container/mp4.rs +++ b/rs/moq-mux/src/container/mp4.rs @@ -2,7 +2,8 @@ //! //! [`Export`] writes a file that is a valid fragmented MP4 while it grows, so a crash still //! leaves a playable file, and [`Export::finish`] turns it into a regular MP4 with its `moov` -//! at the end without moving any media, the way OBS's hybrid MP4 does. +//! at the end without moving any media, the way OBS's hybrid MP4 does. [`repair`] finishes a +//! file the same way after a crash. //! //! The file starts with `ftyp`, a reserved 16-byte `free` box and the fragmented `moov`, then //! the moof+mdat fragments. Finishing appends a `moov` that indexes every sample where it @@ -11,9 +12,12 @@ //! header there would swallow the fragmented `moov` and leave a crashed file unreadable. //! //! A rendition that joins after the fragmented `moov` is written into `free` boxes, which a -//! reader of the unfinished file skips, and only the final `moov` indexes it. +//! reader of the unfinished file skips. Before a track's first fragment, and again whenever +//! its description changes, a `free` box holds a `moov` declaring it, so the final `moov` +//! can be rebuilt from the file alone. use std::collections::{BTreeMap, HashMap, HashSet}; +use std::io::{Read, Seek, SeekFrom}; use std::task::Poll; use std::time::Duration; @@ -33,10 +37,10 @@ const NON_SYNC: u32 = 0x0001_0000; /// Subscribe to a moq broadcast and record it as a crash-safe regular MP4. /// /// [`next`](Self::next) returns the bytes to append to the file, the same fMP4 an -/// [`fmp4::Export`] writes plus the reserved box, so the file plays if the recording never -/// finishes. [`finish`](Self::finish) then returns the trailing `moov` and the `mdat` header -/// that make it a regular MP4. Writing those needs a file that can be overwritten in place, -/// not a stream. +/// [`fmp4::Export`] writes plus the reserved box and track descriptions, so the file plays if +/// the recording never finishes. [`finish`](Self::finish) then returns the trailing `moov` and +/// the `mdat` header that make it a regular MP4. Writing those needs a file that can be +/// overwritten in place, not a stream. /// /// Unlike [`fmp4::Export`], a rendition that joins after the fragmented `moov` is recorded. pub struct Export { @@ -45,51 +49,22 @@ pub struct Export { /// Bytes returned so far, which is where the next chunk starts in the file. written: u64, - /// The fragmented `moov`, once written. - header: Option
, + /// What the file holds, once the fragmented `moov` is written. + index: Option, - /// What each track wrote, by track id. - tracks: BTreeMap, -} - -/// What the fragmented `moov` fixed. -struct Header { - /// Where the reserved box starts. - reserved: u64, - /// The movie timescale. - timescale: u32, - /// The tracks it declares. Any other track joined later. - declared: HashSet, -} - -/// What one track wrote, in decode order. -#[derive(Default)] -struct Track { - /// One chunk per `trun`, its samples contiguous in the file. - chunks: Vec, - samples: Vec, -} - -struct Run { - /// Where the first sample starts in the file. - offset: u64, - /// The first sample's decode time, in media ticks. - decode_time: u64, - /// How many samples the run holds. - count: u32, -} - -struct Sample { - size: u32, - duration: u32, - cts: i64, - sync: bool, + /// The declaration the file last described each track with, by track id. + described: HashMap, } /// The writes that finish a recording, in order. #[derive(Clone, Debug)] pub struct Finish { - /// The regular `moov`, appended after everything [`Export::next`] returned. + /// Where [`moov`](Self::moov) is written, from the start of the file, which is cut there + /// first: the end of everything [`Export::next`] returned, or of a repaired file's last + /// complete fragment. + pub moov_offset: u64, + + /// The regular `moov`, written first. pub moov: Bytes, /// Where [`mdat`](Self::mdat) overwrites the reserved box, from the start of the file. @@ -105,8 +80,8 @@ impl Export { Self { fmp4: fmp4::Export::new(source, catalog).with_late_tracks(), written: 0, - header: None, - tracks: BTreeMap::new(), + index: None, + described: HashMap::new(), } } @@ -154,72 +129,7 @@ impl Export { /// Media still buffered for a fragment that has not closed is left out, unless /// [`stop`](Self::stop) wrote it first. pub fn finish(self) -> Result> { - let Some(header) = &self.header else { - return Ok(None); - }; - - let declarations: HashMap = - self.fmp4.declarations().map(|(id, trak, _)| (id, trak)).collect(); - let mut timelines = Vec::new(); - for (&id, track) in self.tracks.iter().filter(|(_, track)| !track.samples.is_empty()) { - let Some(&trak) = declarations.get(&id) else { - return Err(unindexable(id, "the track has no declaration").into()); - }; - timelines.push((trak, track, Timeline::new(id, trak, track)?)); - } - - let movie = u128::from(header.timescale); - let to_movie = |ticks: u64, timescale: u32| { - u64::try_from(u128::from(ticks) * movie / u128::from(timescale)).map_err(|_| Error::PtsOverflow) - }; - // The earliest track starts the movie; the rest start that much later. - let mut origin = u64::MAX; - for (trak, _, timeline) in &timelines { - origin = origin.min(to_movie(timeline.start, trak.mdia.mdhd.timescale)?); - } - - let mut traks = Vec::new(); - for (trak, track, timeline) in timelines { - let timescale = trak.mdia.mdhd.timescale; - let delay = to_movie(timeline.start, timescale)? - origin; - let presented = to_movie(timeline.duration, timescale)?; - let mut trak = trak.clone(); - trak.mdia.mdhd.duration = timeline.deltas.iter().map(|&delta| u64::from(delta)).sum(); - trak.tkhd.duration = delay + presented; - trak.edts = edits(delay, timeline.media_time, presented); - trak.mdia.minf.stbl = sample_table(&trak.mdia.minf.stbl.stsd, track, &timeline); - traks.push(trak); - } - traks.sort_by_key(|trak| (trak.mdia.hdlr.handler != b"vide".into(), trak.tkhd.track_id)); - - let moov = mp4_atom::Moov { - mvhd: mp4_atom::Mvhd { - timescale: header.timescale, - duration: traks.iter().map(|trak| trak.tkhd.duration).max().unwrap_or(0), - // Normal playback rate and full volume; both default to 0. - rate: mp4_atom::FixedPoint::from(1), - volume: mp4_atom::FixedPoint::from(1), - next_track_id: traks.iter().map(|trak| trak.tkhd.track_id).max().unwrap_or(0) + 1, - ..Default::default() - }, - trak: traks, - ..Default::default() - }; - let mut buf = Vec::new(); - moov.encode(&mut buf)?; - - // Everything from the reserved box to the moov, the fragmented moov and every moof - // included, becomes one mdat that a reader skips through to the moov. - let mut mdat = BytesMut::with_capacity(RESERVED as usize); - mdat.put_u32(1); - mdat.put_slice(b"mdat"); - mdat.put_u64(self.written - header.reserved); - - Ok(Some(Finish { - moov: Bytes::from(buf), - mdat_offset: header.reserved, - mdat: mdat.freeze(), - })) + self.index.map(|index| index.finish(self.written)).transpose() } /// The file header: the init segment's `ftyp`, the reserved box, then its `moov`. @@ -236,24 +146,42 @@ impl Export { data.put_u64(0); data.put_slice(&init[split..]); - self.header = Some(Header { - reserved: self.written + split as u64, - timescale: moov.mvhd.timescale, - declared: moov.trak.iter().map(|trak| trak.tkhd.track_id).collect(), - }); + self.index = Some(Index::new(self.written + split as u64, &moov)?); + self.described = self + .fmp4 + .declarations() + .map(|(id, trak, trex)| (id, Description::new(trak, trex))) + .collect(); Ok(data.freeze()) } - /// Index a moof+mdat fragment where it will land, wrapping a late track's in a `free` box. + /// Index a moof+mdat fragment where it will land, after a description of each track the + /// file has yet to describe as it is now, and wrapping a late track's in a `free` box. fn fragment(&mut self, fragment: Bytes) -> Result { - let header = self.header.as_ref().expect("the init segment comes first"); + let index = self.index.as_mut().expect("the init segment comes first"); let moof = mp4_atom::Moof::decode(&mut std::io::Cursor::new(fragment.as_ref()))?; let mut data = BytesMut::new(); + for traf in &moof.traf { + let id = traf.tfhd.track_id; + let Some((trak, trex)) = self.fmp4.declaration(id) else { + return Err(unindexable(id, "the track has no declaration").into()); + }; + if self + .described + .get(&id) + .is_none_or(|known| known.trak != *trak || known.trex != *trex) + { + let description = Description::new(trak, trex); + // Indexed as a repair reads it back, which keeps the two finishes identical. + index.describe(&description.encode(index.timescale, &mut data)?)?; + self.described.insert(id, description); + } + } if moof .traf .iter() - .any(|traf| !header.declared.contains(&traf.tfhd.track_id)) + .any(|traf| !index.declared.contains(&traf.tfhd.track_id)) { mp4_atom::Header { kind: b"free".into(), @@ -261,18 +189,264 @@ impl Export { } .encode(&mut data)?; } - let start = self.written + data.len() as u64; - for traf in &moof.traf { - self.index(start, traf)?; - } + index.fragment(self.written + data.len() as u64, &moof)?; data.put_slice(&fragment); Ok(data.freeze()) } +} + +/// Rebuild the writes that finish a recording [`Export`] left unfinished, such as after a +/// crash or a cut-short finish, or `None` when the file is already a regular MP4. +/// +/// The final `moov` indexes every complete fragment, the same as finishing the recording +/// right after writing the last one. Whatever follows it, such as a partial fragment or +/// `moov`, is cut, so a repair cut short can itself be repaired. +pub fn repair(file: &mut F) -> Result> { + let eof = file.seek(SeekFrom::End(0))?; + let Some(ftyp) = Atom::read(file, 0, eof)?.filter(|atom| atom.kind == *b"ftyp") else { + return Err(Error::Unrepairable("it does not start with an ftyp box").into()); + }; + let Some(reserved) = Atom::read(file, ftyp.end, eof)? else { + return Err(Error::Unrepairable("it ends before its header").into()); + }; + if reserved.kind == *b"mdat" { + return Ok(None); + } + if reserved.kind != *b"free" || reserved.end - reserved.start != RESERVED { + return Err(Error::Unrepairable("it has no reserved box").into()); + } + let Some(header) = Atom::read(file, reserved.end, eof)?.filter(|atom| atom.kind == *b"moov") else { + return Err(Error::Unrepairable("it has no complete moov after its reserved box").into()); + }; + let moov: mp4_atom::Moov = header.decode(file)?; + if moov.mvex.is_none() { + return Err(Error::Unrepairable("its moov is not fragmented").into()); + } + let mut index = Index::new(reserved.start, &moov)?; + + // Where the last complete fragment ends, and the descriptions written since, which only + // count once the fragment written with them is complete. + let mut end = header.end; + let mut described = Vec::new(); + let mut position = header.end; + while let Some(atom) = Atom::read(file, position, eof)? { + let moof = match &atom.kind { + b"moof" => { + let Some(mdat) = Atom::read(file, atom.end, eof)? else { + break; + }; + if mdat.kind != *b"mdat" { + return Err(Error::Unrepairable("a moof is not followed by its mdat").into()); + } + position = mdat.end; + atom + } + b"free" => { + position = atom.end; + match Atom::read(file, atom.body, atom.end)? { + Some(inner) if inner.kind == *b"moof" => { + let mdat = Atom::read(file, inner.end, atom.end)?; + if mdat.is_none_or(|mdat| mdat.kind != *b"mdat" || mdat.end != atom.end) { + return Err(Error::Unrepairable("a free box holds a moof without its mdat").into()); + } + inner + } + Some(inner) if inner.kind == *b"moov" => { + described.push(inner.decode::<_, mp4_atom::Moov>(file)?); + continue; + } + _ => return Err(Error::Unrepairable("a free box holds neither a fragment nor a moov").into()), + } + } + // A finish cut short appended part or all of a moov, which ends the recording. + b"moov" => break, + _ => return Err(Error::Unrepairable("it holds a box a recording never writes").into()), + }; + for moov in described.drain(..) { + index.describe(&moov)?; + } + index.fragment(moof.start, &moof.decode(file)?)?; + end = position; + } + if end < eof { + tracing::warn!( + offset = end, + bytes = eof - end, + "cutting what follows the last complete fragment" + ); + } + Ok(Some(index.finish(end)?)) +} + +/// One box in a file. +struct Atom { + kind: [u8; 4], + /// Where the box starts. + start: u64, + /// Where its body starts, past the header. + body: u64, + /// Where the box ends. + end: u64, +} + +impl Atom { + /// The box at `start`, or `None` when it does not end by `limit`: cut short, or not a box. + fn read(file: &mut F, start: u64, limit: u64) -> Result> { + let mut header = [0u8; 16]; + let available = limit.saturating_sub(start).min(16) as usize; + if available < 8 { + return Ok(None); + } + file.seek(SeekFrom::Start(start))?; + file.read_exact(&mut header[..available])?; + let kind = header[4..8].try_into().unwrap(); + let (length, size) = match u32::from_be_bytes(header[..4].try_into().unwrap()) { + 1 if available == 16 => (16, u64::from_be_bytes(header[8..].try_into().unwrap())), + // A crash can leave zeroes, and a recording never writes a box that runs to the end. + 0 | 1 => return Ok(None), + size => (8, u64::from(size)), + }; + let end = start.checked_add(size).filter(|&end| size >= length && end <= limit); + Ok(end.map(|end| Self { + kind, + start, + body: start + length, + end, + })) + } + + /// Read and decode the whole box. + fn decode(&self, file: &mut F) -> Result { + let mut data = vec![0u8; (self.end - self.start) as usize]; + file.seek(SeekFrom::Start(self.start))?; + file.read_exact(&mut data)?; + Ok(T::decode(&mut std::io::Cursor::new(data.as_slice()))?) + } +} + +/// What a recording's file holds: its header, each track's latest description, and the +/// samples of every fragment. +#[derive(Clone)] +struct Index { + /// Where the reserved box starts. + reserved: u64, + /// The movie timescale. + timescale: u32, + /// The tracks the fragmented `moov` declares. Any other track joined later. + declared: HashSet, + /// The latest description of each track, by track id. + descriptions: HashMap, + /// What each track wrote, by track id. + tracks: BTreeMap, +} + +/// How a track is declared. +#[derive(Clone)] +struct Description { + trak: mp4_atom::Trak, + trex: mp4_atom::Trex, +} + +impl Description { + fn new(trak: &mp4_atom::Trak, trex: &mp4_atom::Trex) -> Self { + Self { + trak: trak.clone(), + trex: trex.clone(), + } + } + + /// Write a `free` box holding a `moov` that declares the track, returning that `moov` as + /// read back from the file. + fn encode(&self, timescale: u32, data: &mut BytesMut) -> Result { + let moov = mp4_atom::Moov { + mvhd: mp4_atom::Mvhd { + timescale, + ..Default::default() + }, + trak: vec![self.trak.clone()], + mvex: Some(mp4_atom::Mvex { + trex: vec![self.trex.clone()], + ..Default::default() + }), + ..Default::default() + }; + let mut buf = Vec::new(); + moov.encode(&mut buf)?; + mp4_atom::Header { + kind: b"free".into(), + size: Some(buf.len()), + } + .encode(data)?; + data.put_slice(&buf); + Ok(mp4_atom::Moov::decode(&mut std::io::Cursor::new(buf.as_slice()))?) + } +} + +/// What one track wrote, in decode order. +#[derive(Clone, Default)] +struct Track { + /// One chunk per `trun`, its samples contiguous in the file. + chunks: Vec, + samples: Vec, +} + +#[derive(Clone)] +struct Run { + /// Where the first sample starts in the file. + offset: u64, + /// The first sample's decode time, in media ticks. + decode_time: u64, + /// How many samples the run holds. + count: u32, +} + +#[derive(Clone)] +struct Sample { + size: u32, + duration: u32, + cts: i64, + sync: bool, +} + +impl Index { + /// Index a file whose reserved box starts at `reserved`, followed by the fragmented `moov`. + fn new(reserved: u64, moov: &mp4_atom::Moov) -> Result { + let mut index = Self { + reserved, + timescale: moov.mvhd.timescale, + declared: moov.trak.iter().map(|trak| trak.tkhd.track_id).collect(), + descriptions: HashMap::new(), + tracks: BTreeMap::new(), + }; + index.describe(moov)?; + Ok(index) + } + + /// Take each track `moov` declares as its description from here on. + fn describe(&mut self, moov: &mp4_atom::Moov) -> Result<()> { + let trexs = moov.mvex.as_ref().map_or(&[][..], |mvex| mvex.trex.as_slice()); + for trak in &moov.trak { + let id = trak.tkhd.track_id; + let Some(trex) = trexs.iter().find(|trex| trex.track_id == id) else { + return Err(unindexable(id, "the track has no trex").into()); + }; + self.descriptions.insert(id, Description::new(trak, trex)); + } + Ok(()) + } + + /// Record the samples of `moof`, which starts at `offset` in the file. + fn fragment(&mut self, offset: u64, moof: &mp4_atom::Moof) -> Result<()> { + for traf in &moof.traf { + self.traf(offset, traf)?; + } + Ok(()) + } /// Record the samples of `traf`, whose moof starts at `moof` in the file. - fn index(&mut self, moof: u64, traf: &mp4_atom::Traf) -> Result<()> { + fn traf(&mut self, moof: u64, traf: &mp4_atom::Traf) -> Result<()> { let id = traf.tfhd.track_id; - let Some((_, trex)) = self.fmp4.declaration(id) else { + let Some(Description { trex, .. }) = self.descriptions.get(&id) else { return Err(unindexable(id, "the track has no declaration").into()); }; let Some(tfdt) = &traf.tfdt else { @@ -315,6 +489,71 @@ impl Export { } Ok(()) } + + /// The writes that make the file a regular MP4 with its `moov` at `end`. + fn finish(&self, end: u64) -> Result { + let mut timelines = Vec::new(); + for (&id, track) in self.tracks.iter().filter(|(_, track)| !track.samples.is_empty()) { + let Some(Description { trak, .. }) = self.descriptions.get(&id) else { + return Err(unindexable(id, "the track has no declaration").into()); + }; + timelines.push((trak, track, Timeline::new(id, trak, track)?)); + } + + let movie = u128::from(self.timescale); + let to_movie = |ticks: u64, timescale: u32| { + u64::try_from(u128::from(ticks) * movie / u128::from(timescale)).map_err(|_| Error::PtsOverflow) + }; + // The earliest track starts the movie; the rest start that much later. + let mut origin = u64::MAX; + for (trak, _, timeline) in &timelines { + origin = origin.min(to_movie(timeline.start, trak.mdia.mdhd.timescale)?); + } + + let mut traks = Vec::new(); + for (trak, track, timeline) in timelines { + let timescale = trak.mdia.mdhd.timescale; + let delay = to_movie(timeline.start, timescale)? - origin; + let presented = to_movie(timeline.duration, timescale)?; + let mut trak = trak.clone(); + trak.mdia.mdhd.duration = timeline.deltas.iter().map(|&delta| u64::from(delta)).sum(); + trak.tkhd.duration = delay + presented; + trak.edts = edits(delay, timeline.media_time, presented); + trak.mdia.minf.stbl = sample_table(&trak.mdia.minf.stbl.stsd, track, &timeline); + traks.push(trak); + } + traks.sort_by_key(|trak| (trak.mdia.hdlr.handler != b"vide".into(), trak.tkhd.track_id)); + + let moov = mp4_atom::Moov { + mvhd: mp4_atom::Mvhd { + timescale: self.timescale, + duration: traks.iter().map(|trak| trak.tkhd.duration).max().unwrap_or(0), + // Normal playback rate and full volume; both default to 0. + rate: mp4_atom::FixedPoint::from(1), + volume: mp4_atom::FixedPoint::from(1), + next_track_id: traks.iter().map(|trak| trak.tkhd.track_id).max().unwrap_or(0) + 1, + ..Default::default() + }, + trak: traks, + ..Default::default() + }; + let mut buf = Vec::new(); + moov.encode(&mut buf)?; + + // Everything from the reserved box to the moov, the fragmented moov and every moof + // included, becomes one mdat that a reader skips through to the moov. + let mut mdat = BytesMut::with_capacity(RESERVED as usize); + mdat.put_u32(1); + mdat.put_slice(b"mdat"); + mdat.put_u64(end - self.reserved); + + Ok(Finish { + moov_offset: end, + moov: Bytes::from(buf), + mdat_offset: self.reserved, + mdat: mdat.freeze(), + }) + } } fn unindexable(track: u32, reason: &'static str) -> Error { @@ -547,14 +786,46 @@ mod tests { } } + /// Append everything the export writes like [`record`], keeping the file's length and what + /// the export indexed after each write. + async fn record_indexed( + export: &mut super::Export, + file: &mut Vec, + indexes: &mut Vec<(usize, super::Index)>, + ) { + while let Ok(next) = kio::clock::timeout(Duration::from_millis(1), export.next()).await { + match next.expect("export failed") { + Some(data) => file.extend_from_slice(&data), + None => break, + } + indexes.push((file.len(), export.index.clone().expect("the header comes first"))); + } + } + /// Finish the recording in `file` the way a writer does. fn finish(export: super::Export, file: &mut Vec) { - let finish = export.finish().expect("finish").expect("something was written"); + apply(export.finish().expect("finish").expect("something was written"), file); + } + + /// Make the writes of `finish` to `file`. + fn apply(finish: super::Finish, file: &mut Vec) { + file.truncate(finish.moov_offset as usize); file.extend_from_slice(&finish.moov); let offset = finish.mdat_offset as usize; file[offset..offset + finish.mdat.len()].copy_from_slice(&finish.mdat); } + fn repair(file: &[u8]) -> crate::Result> { + super::repair(&mut std::io::Cursor::new(file)) + } + + fn assert_same(finish: &super::Finish, expected: &super::Finish, cut: usize) { + assert_eq!(finish.moov_offset, expected.moov_offset, "cut at {cut}"); + assert_eq!(finish.moov, expected.moov, "cut at {cut}"); + assert_eq!(finish.mdat_offset, expected.mdat_offset, "cut at {cut}"); + assert_eq!(finish.mdat, expected.mdat, "cut at {cut}"); + } + fn atoms(file: &[u8]) -> Vec { let mut cursor = std::io::Cursor::new(file); let mut atoms = Vec::new(); @@ -635,7 +906,7 @@ mod tests { #[tokio::test(start_paused = true)] async fn a_finished_recording_is_a_regular_mp4() { let mut live = Live::avc3(); - let mut audio = add_opus(&mut live, 0); + let mut audio = add_opus(&mut live, 312); let video: Vec<_> = (0..9u64).map(|i| video_frame(i * 33_000, i % 3 == 0)).collect(); for frame in &video { live.track.write(frame.clone()).unwrap(); @@ -650,13 +921,15 @@ mod tests { let mut file = Vec::new(); record(&mut export, &mut file).await; - // Unfinished, it is the fMP4 a crash would leave. + // Unfinished, it is the fMP4 a crash would leave. The fragmented moov already describes + // every track as written, Opus pre-skip edit included. let unfinished = atoms(&file); assert_eq!(kinds(&unfinished[..3]), ["ftyp", "free", "moov"]); assert!( kinds(&unfinished[3..]) .iter() - .all(|kind| kind == "moof" || kind == "mdat") + .all(|kind| kind == "moof" || kind == "mdat"), + "no description beyond the fragmented moov" ); assert!(moov(unfinished).mvex.is_some()); @@ -715,7 +988,10 @@ mod tests { .iter() .filter(|atom| matches!(atom, mp4_atom::Any::Free(_))) .count(); - assert_eq!(frees, 3, "the reserved box and both audio fragments"); + assert_eq!( + frees, 4, + "the reserved box, the audio description and both audio fragments" + ); finish(export, &mut file); let moov = moov(atoms(&file)); @@ -874,8 +1150,16 @@ mod tests { let mut export = export(&live).await; let mut file = Vec::new(); record(&mut export, &mut file).await; - let written = - |export: &super::Export<_>| export.tracks.values().map(|track| track.samples.len()).sum::(); + let written = |export: &super::Export<_>| { + export + .index + .as_ref() + .unwrap() + .tracks + .values() + .map(|track| track.samples.len()) + .sum::() + }; assert_eq!(written(&export), 3 + 5, "only the closed groups"); export.stop(); @@ -950,4 +1234,89 @@ mod tests { let export = export(&live).await; assert!(export.finish().unwrap().is_none()); } + + /// A recording cut anywhere, mid-fragment or right after a late rendition joins, repairs + /// to exactly what finishing it after its last complete write would have produced. + #[tokio::test(start_paused = true)] + async fn a_cut_recording_repairs_like_a_finish_there() { + let mut live = Live::avc3(); + for i in 0..4u64 { + live.track.write(video_frame(i * 33_000, i % 3 == 0)).unwrap(); + } + let mut export = export(&live).await; + let mut file = Vec::new(); + let mut indexes = Vec::new(); + record_indexed(&mut export, &mut file, &mut indexes).await; + + let mut audio = add_opus(&mut live, 312); + for i in 0..10u64 { + audio.write(raw_frame(100_000 + i * 20_000, OPUS, i % 5 == 0)).unwrap(); + } + audio.finish().unwrap(); + for i in 4..9u64 { + live.track.write(video_frame(i * 33_000, i % 3 == 0)).unwrap(); + } + live.track.finish().unwrap(); + record_indexed(&mut export, &mut file, &mut indexes).await; + assert!(indexes.len() > 4, "several writes to cut between"); + + for cut in 0..=file.len() { + let repaired = repair(&file[..cut]); + let Some((end, index)) = indexes.iter().rev().find(|(end, _)| *end <= cut) else { + assert!(repaired.is_err(), "a header cut at {cut} is no recording"); + continue; + }; + let repaired = repaired.unwrap().expect("unfinished"); + assert_same(&repaired, &index.finish(*end as u64).unwrap(), cut); + + // A repair cut short after its moov leaves a file that repairs the same. + let mut half = file[..cut].to_vec(); + half.truncate(repaired.moov_offset as usize); + half.extend_from_slice(&repaired.moov); + assert_same(&repair(&half).unwrap().expect("unfinished"), &repaired, cut); + } + + // Uncut, the repair is the finish byte for byte, and indexes the late rendition. + let mut repaired = file.clone(); + apply(repair(&file).unwrap().expect("unfinished"), &mut repaired); + finish(export, &mut file); + assert_eq!(repaired, file); + let moov = moov(atoms(&file)); + assert_eq!(samples(&file, trak(&moov, b"soun")), vec![OPUS; 10]); + assert_eq!(samples(&file, trak(&moov, b"vide")).len(), 9); + } + + /// A finish cut short before its mdat header leaves part or all of the moov at the end, + /// which the repair cuts and writes again. + #[tokio::test(start_paused = true)] + async fn an_interrupted_finish_repairs() { + let mut live = Live::avc3(); + let mut audio = add_opus(&mut live, 0); + for i in 0..6u64 { + live.track.write(video_frame(i * 33_000, i % 3 == 0)).unwrap(); + audio.write(raw_frame(i * 20_000, OPUS, i == 0)).unwrap(); + } + live.track.finish().unwrap(); + audio.finish().unwrap(); + let mut export = export(&live).await; + let mut file = Vec::new(); + record(&mut export, &mut file).await; + let finished = export.finish().unwrap().expect("something was written"); + + for appended in [1, 8, finished.moov.len() / 2, finished.moov.len()] { + let mut cut = file.clone(); + cut.extend_from_slice(&finished.moov[..appended]); + assert_same(&repair(&cut).unwrap().expect("unfinished"), &finished, appended); + } + + let mut done = file.clone(); + apply(finished, &mut done); + assert_eq!(kinds(&atoms(&done)), ["ftyp", "mdat", "moov"]); + assert!(repair(&done).unwrap().is_none(), "already a regular MP4"); + + // A plain fMP4 has no reserved box for the mdat header. + let ftyp = u32::from_be_bytes(file[..4].try_into().unwrap()) as usize; + let fmp4 = [&file[..ftyp], &file[ftyp + 16..]].concat(); + assert!(repair(&fmp4).is_err()); + } }