diff --git a/doc/bin/cli.md b/doc/bin/cli.md index f6be125bb8b..e98f611a13f 100644 --- a/doc/bin/cli.md +++ b/doc/bin/cli.md @@ -205,8 +205,9 @@ Other video waits for its first keyframe. `mp4 --output ` records to a new file the way OBS's hybrid MP4 does: it is 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. A second signal exits at once -and leaves it fragmented. Unlike `fmp4`, a rendition that joins mid-recording is +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. ```bash diff --git a/quest/m2/README.md b/quest/m2/README.md index a5077df3886..4f47325f46b 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -241,7 +241,6 @@ 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 -- [An interrupted mp4 recording keeps its last fragment](/quest/m2/mp4-sigint-flush.md) - SIGINT flushes the buffering fragment before finishing - [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 - [Windows receives notice truncated control data](/quest/m2/cmsg-windows-truncation.md) - Windows handles `MSG_CTRUNC` like the Unix paths diff --git a/quest/m2/mp4-repair-lock.md b/quest/m2/mp4-repair-lock.md index 97736e180e9..a0acb9fcde5 100644 --- a/quest/m2/mp4-repair-lock.md +++ b/quest/m2/mp4-repair-lock.md @@ -19,4 +19,4 @@ Public API: none (CLI behavior only). Wire: none. ## Related -- [An interrupted mp4 recording keeps its last fragment](/quest/m2/mp4-sigint-flush.md) - the other half of recording durability +- [An interrupted mp4 recording keeps its last fragment](/doc/bin/cli.md#export) - the other half of recording durability diff --git a/quest/m2/mp4-sigint-flush.md b/quest/m2/mp4-sigint-flush.md deleted file mode 100644 index e1a0167c63c..00000000000 --- a/quest/m2/mp4-sigint-flush.md +++ /dev/null @@ -1,13 +0,0 @@ -# [S] An interrupted mp4 recording keeps its last fragment - -## Goal - -On the first SIGINT or SIGTERM, `moq export mp4 --output` writes the fragment it is still buffering before finishing the file, so an interrupted recording loses nothing it had received. - -## Plan - -Follow-up of [moq-dev/moq#7357](https://github.com/moq-dev/moq/pull/7357), which drops up to one buffering fragment on SIGINT. - -Decided 2026-10-30 (maintainer, follow-up planning after the /quest-afk run). Flush through the fMP4 exporter's normal fragment path so the flushed fragment is indexed by the final `moov` like any other; extend #7357's nightly SIGINT test to check the last frames received before the signal are in the file. - -Public API: none. Wire: none. diff --git a/rs/moq-cli/src/subscribe.rs b/rs/moq-cli/src/subscribe.rs index cefbecb1c65..c55e5484e29 100644 --- a/rs/moq-cli/src/subscribe.rs +++ b/rs/moq-cli/src/subscribe.rs @@ -373,7 +373,8 @@ impl Subscribe { Ok(()) } - /// Record a regular MP4 until the broadcast ends or `finish` is cancelled, then finish it. + /// Record a regular MP4 until the broadcast ends or `finish` is cancelled, then finish it with + /// everything it received. async fn run_mp4(self) -> anyhow::Result<()> { let path = self.args.output.clone().context("an mp4 export records to --output")?; let finish = self.finish.clone(); @@ -389,10 +390,16 @@ impl Subscribe { .with_context(|| format!("failed to create {}", path.display()))?; // A failed export still finishes what it recorded; a failed write leaves the file as is. + let mut stopped = false; let ended = loop { let next = tokio::select! { next = mp4.next() => next, - () = finish.cancelled() => break Ok(()), + // Write out what was received before finishing. + () = finish.cancelled(), if !stopped => { + mp4.stop(); + stopped = true; + continue; + } }; match next { Ok(Some(data)) => file.write_all(&data).await?, diff --git a/rs/moq-cli/tests/integration/export.rs b/rs/moq-cli/tests/integration/export.rs index 9e7db241973..30d2301b920 100644 --- a/rs/moq-cli/tests/integration/export.rs +++ b/rs/moq-cli/tests/integration/export.rs @@ -10,6 +10,7 @@ use std::io::Cursor; use std::os::fd::AsRawFd; use std::process::Stdio; +use std::sync::atomic::{AtomicUsize, Ordering}; use std::sync::{Arc, Mutex}; use std::time::Duration; @@ -1121,28 +1122,83 @@ fn boxes(file: &[u8]) -> Vec { boxes } -/// SIGINT during `export mp4` finishes the recording as a regular MP4 with its moov at the end. +/// Count the frames the relay delivers on `demo`'s video track as they arrive. A GOP lasts two +/// seconds, so subscribing during the first one counts them all. +fn delivered(relay: &Relay) -> Arc { + let count = Arc::::default(); + let counting = count.clone(); + let origin = relay.origin.clone(); + tokio::spawn(async move { + let broadcast = origin.follow("demo", None).unwrap().available().await.unwrap(); + let mut catalogs = hang::catalog::Catalog::<()>::subscribe(&broadcast).await.unwrap(); + let name = loop { + let catalog = catalogs.next().await.unwrap().expect("the catalog ended"); + if let Some(name) = catalog.video.renditions.keys().next() { + break name.clone(); + } + }; + let mut track = broadcast.track(&name).unwrap().subscribe(None).await.unwrap(); + while let Some(mut group) = track.recv_group().await.unwrap() { + while group.read_frame().await.unwrap().is_some() { + counting.fetch_add(1, Ordering::SeqCst); + } + } + }); + count +} + +/// How many samples the regular MP4 `moov` indexes for `handler`'s track. +fn indexed(moov: &mp4_atom::Moov, handler: &[u8; 4]) -> usize { + let trak = moov + .trak + .iter() + .find(|trak| trak.mdia.hdlr.handler == handler.into()) + .expect("a trak"); + match &trak.mdia.minf.stbl.stsz.samples { + mp4_atom::StszSamples::Identical { count, .. } => *count as usize, + mp4_atom::StszSamples::Different { sizes } => sizes.len(), + } +} + +/// SIGINT during `export mp4` finishes the recording as a regular MP4 with its moov at the end, +/// keeping every frame received, the GOP it was still buffering included. #[tokio::test] #[ignore = "real-time process test: just rs cli-export"] async fn an_interrupted_mp4_recording_is_finished() { let relay = relay().await; let dir = tempfile::tempdir().unwrap(); let path = dir.path().join("recording.mp4"); + let video = delivered(&relay); let mut recording = moq(&relay, &[]) .args(["export", "mp4", "--output"]) .arg(&path) .stderr(Stdio::piped()) .spawn() .expect("spawn export"); - let (mut publisher, feeding) = import(&relay); + // Stop feeding partway into the second GOP, which then stays open. + let format = Format { + clip: &CLIP[..120_320], + ..TS + }; + let (mut publisher, feeding) = import_as(&relay, &[], format); + let stdin = feeding.await.unwrap(); + // The relay delivers the export the same frames as the counter, so once it stops growing + // the export has received what it will before the signal. + let delivered = || video.load(Ordering::SeqCst); 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; + let mut last = delivered(); + loop { + kio::clock::sleep(Duration::from_secs(1)).await; + let now = delivered(); + if now == last && now > 0 { + break; + } + last = now; } }) .await - .expect("the recording never grew"); + .expect("the relay kept delivering"); let pid = recording.id().expect("running").to_string(); let status = std::process::Command::new("kill") .args(["-INT", &pid]) @@ -1169,8 +1225,12 @@ async fn an_interrupted_mp4_recording_is_finished() { }; assert!(moov.mvex.is_none()); assert_eq!(moov.trak.len(), 2, "video and audio"); + assert_eq!( + indexed(moov, b"vide"), + delivered(), + "every video frame delivered before the signal" + ); - let stdin = feeding.await.unwrap(); drop(stdin); assert!(wait(&mut publisher).await.success()); } diff --git a/rs/moq-mux/CHANGELOG.md b/rs/moq-mux/CHANGELOG.md index b2e93a15cb5..7238150996d 100644 --- a/rs/moq-mux/CHANGELOG.md +++ b/rs/moq-mux/CHANGELOG.md @@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - MP4 and Matroska import fill a video rendition's `projection` and `stereo` from Spherical Video V2's `sv3d`/`st3d` boxes and Matroska's `Projection`/`StereoMode`, and Opus channel mapping family 2 (raw Opus, Matroska, and other OpusHead sources) imports with `layout: "ambisonic"`. What the catalog cannot describe is refused with `fmp4::Error::UnsupportedSpatial`, `mkv::Error::UnsupportedSpatial`, or `opus::Error::UnsupportedChannelCount`: a cubemap or mesh projection, a nonzero pose, uncentred or vertically cropped equirectangular bounds, a stereo packing other than mono, left-right, or top-bottom with the left eye first, and family 2 at zeroth order or with RFC 8486's non-diegetic stereo pair. - fMP4 carries surround Opus: a `dOps` channel mapping table (family 1, 2, or 255) imports into the OpusHead description, and an exported `dOps` writes the description's table back instead of refusing it with `opus::Error::UnsupportedMappingFamily`. Family 3, whose OpusHead carries a demixing matrix rather than a table, is still refused both ways. +- `container::mp4::Export::stop` ends a recording before the broadcast does: `next` still returns the fragment each track was buffering, then `None`, so `finish` indexes it. ### Changed diff --git a/rs/moq-mux/src/container/fmp4/export.rs b/rs/moq-mux/src/container/fmp4/export.rs index c1ec519686f..ed9cdad1f93 100644 --- a/rs/moq-mux/src/container/fmp4/export.rs +++ b/rs/moq-mux/src/container/fmp4/export.rs @@ -90,6 +90,9 @@ pub struct Export { /// that declares it elsewhere. Its fragments carry a track id the init never declared. late: bool, + /// Set by [`stop`](Self::stop), after which nothing more is read. + stopped: bool, + /// The `tkhd.track_id` the next new rendition gets. next_track_id: u32, @@ -498,6 +501,7 @@ impl Export { queued: VecDeque::new(), init_emitted: false, late: false, + stopped: false, next_track_id: 1, sequence_number: 1, } @@ -538,6 +542,19 @@ impl Export { self } + /// Stop reading the broadcast. The export still writes out the media it read, the + /// fragment each track was buffering included, then ends. + /// + /// Stopping before the init segment could be written ends the export without writing. + pub(crate) fn stop(&mut self) { + self.catalog = None; + for track in self.tracks.values_mut() { + track.source = None; + track.finished = true; + } + self.stopped = true; + } + /// The `trak` and `trex` declaring `track_id`, once the track could be described. pub(crate) fn declaration(&self, track_id: u32) -> Option<(&mp4_atom::Trak, &mp4_atom::Trex)> { self.declarations() @@ -668,7 +685,7 @@ impl Export { } if self.catalog.is_none() && self.tracks.values().all(|t| t.finished) { // Media was read but can't be written without every track's description. - if !self.queued.is_empty() { + if !self.queued.is_empty() && !self.stopped { return Poll::Ready(Err(Error::TrackUndescribed(self.undescribed()).into())); } return Poll::Ready(Ok(None)); @@ -823,7 +840,8 @@ impl Export { .iter() .filter(|(_, track)| { !track.buffer.is_empty() - && (track.finished + // A stopped track's pending frame joins its buffer first. + && ((track.finished && track.pending.is_none()) || track.group_finished || (self.fragment_duration == Some(Duration::ZERO) && track.buffer.last().is_some_and(|frame| frame.duration.is_some()))) diff --git a/rs/moq-mux/src/container/mp4.rs b/rs/moq-mux/src/container/mp4.rs index aa955fc8744..9d526e34fce 100644 --- a/rs/moq-mux/src/container/mp4.rs +++ b/rs/moq-mux/src/container/mp4.rs @@ -124,7 +124,8 @@ impl Export { self } - /// The next bytes to append to the file, or `None` once the broadcast ends. + /// The next bytes to append to the file, or `None` once the broadcast ends or the export + /// [stops](Self::stop). pub async fn next(&mut self) -> Result> { kio::wait(|waiter| self.poll_next(waiter)).await } @@ -142,9 +143,16 @@ impl Export { Poll::Ready(Ok(Some(data))) } + /// Stop recording before the broadcast ends. [`next`](Self::next) still returns the media + /// already read, the fragment each track was buffering included, then `None`. + pub fn stop(&mut self) { + self.fmp4.stop(); + } + /// The writes that turn the file into a regular MP4, or `None` when nothing was written. /// - /// Media still buffered for a fragment that has not closed is left out. + /// 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); @@ -849,6 +857,92 @@ mod tests { assert_eq!(presented, expected); } + /// Stopping writes out the fragment each track was still buffering, so the finished file + /// holds every frame read, and ends the export without waiting for more. + #[tokio::test(start_paused = true)] + async fn stopping_writes_the_buffered_fragments() { + let mut live = Live::avc3(); + let mut audio = add_opus(&mut live, 0); + let video: Vec<_> = (0..5u64).map(|i| video_frame(i * 33_000, i % 3 == 0)).collect(); + for frame in &video { + live.track.write(frame.clone()).unwrap(); + } + for i in 0..8u64 { + audio.write(raw_frame(i * 20_000, OPUS, i % 5 == 0)).unwrap(); + } + + 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::(); + assert_eq!(written(&export), 3 + 5, "only the closed groups"); + + export.stop(); + while let Some(data) = export.next().await.expect("export failed") { + file.extend_from_slice(&data); + } + assert_eq!(written(&export), 5 + 8); + + finish(export, &mut file); + let moov = moov(atoms(&file)); + let expected: Vec> = video.iter().map(length_prefixed).collect(); + assert_eq!(samples(&file, trak(&moov, b"vide")), expected); + assert_eq!(samples(&file, trak(&moov, b"soun")), vec![OPUS; 8]); + } + + /// A frame read but not yet placed in a fragment, as each track's first is when the header + /// goes out, is written too. + #[tokio::test(start_paused = true)] + async fn stopping_writes_the_frames_read() { + let mut live = Live::avc3(); + let mut audio = add_opus(&mut live, 0); + let frame = video_frame(0, true); + live.track.write(frame.clone()).unwrap(); + audio.write(raw_frame(0, OPUS, true)).unwrap(); + + let mut export = export(&live).await; + let mut file = export.next().await.unwrap().expect("the header").to_vec(); + export.stop(); + while let Some(data) = export.next().await.expect("export failed") { + file.extend_from_slice(&data); + } + + finish(export, &mut file); + let moov = moov(atoms(&file)); + assert_eq!(samples(&file, trak(&moov, b"vide")), [length_prefixed(&frame)]); + assert_eq!(samples(&file, trak(&moov, b"soun")), [OPUS]); + } + + /// Stopping before every track can be described ends the export without a header, rather + /// than failing on the media it could not write. + #[tokio::test(start_paused = true)] + async fn stopping_before_the_header_writes_nothing() { + /// An IDR without the SPS a High profile track waits for. + const IDR_ONLY: &[u8] = &[0, 0, 0, 1, 0x65, 0x88, 0x84, 0x21]; + + let mut live = Live::avc3(); + let mut audio = add_opus(&mut live, 0); + if let Some(config) = live.catalog.modify().unwrap().video.renditions.values_mut().next() + && let hang::catalog::VideoCodec::H264(h264) = &mut config.codec + { + h264.profile = 110; + } + live.track.write(raw_frame(0, IDR_ONLY, true)).unwrap(); + for i in 0..10u64 { + audio.write(raw_frame(i * 20_000, OPUS, i % 5 == 0)).unwrap(); + } + + let mut export = export(&live).await; + let mut file = Vec::new(); + record(&mut export, &mut file).await; + assert!(file.is_empty(), "the video holds the header back"); + + export.stop(); + assert!(export.next().await.expect("stopping is not a failure").is_none()); + assert!(export.finish().unwrap().is_none()); + } + /// Nothing to finish before the header is written. #[tokio::test(start_paused = true)] async fn nothing_written_needs_no_finish() { diff --git a/rs/moq-relay/src/listener.rs b/rs/moq-relay/src/listener.rs index 09d5a12fc2b..f88bfff2862 100644 --- a/rs/moq-relay/src/listener.rs +++ b/rs/moq-relay/src/listener.rs @@ -17,7 +17,9 @@ mod demux; mod idle; pub(crate) use demux::{Classified, Stream, Tls, classify}; -pub(crate) use idle::{Admission, Io}; +pub(crate) use idle::Admission; +#[cfg(feature = "websocket")] +pub(crate) use idle::Io; use std::{ io,