Skip to content
5 changes: 3 additions & 2 deletions doc/bin/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -205,8 +205,9 @@ Other video waits for its first keyframe.
`mp4 --output <file>` 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
Expand Down
1 change: 0 additions & 1 deletion quest/m2/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion quest/m2/mp4-repair-lock.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
13 changes: 0 additions & 13 deletions quest/m2/mp4-sigint-flush.md

This file was deleted.

11 changes: 9 additions & 2 deletions rs/moq-cli/src/subscribe.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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();
Expand All @@ -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?,
Expand Down
72 changes: 66 additions & 6 deletions rs/moq-cli/tests/integration/export.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down Expand Up @@ -1121,28 +1122,83 @@ fn boxes(file: &[u8]) -> Vec<mp4_atom::Any> {
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<AtomicUsize> {
let count = Arc::<AtomicUsize>::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])
Expand All @@ -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());
}
1 change: 1 addition & 0 deletions rs/moq-mux/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
22 changes: 20 additions & 2 deletions rs/moq-mux/src/container/fmp4/export.rs
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,9 @@ pub struct Export<S: Stream> {
/// 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,

Expand Down Expand Up @@ -498,6 +501,7 @@ impl<S: Stream> Export<S> {
queued: VecDeque::new(),
init_emitted: false,
late: false,
stopped: false,
next_track_id: 1,
sequence_number: 1,
}
Expand Down Expand Up @@ -538,6 +542,19 @@ impl<S: Stream> Export<S> {
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()
Expand Down Expand Up @@ -668,7 +685,7 @@ impl<S: Stream> Export<S> {
}
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));
Expand Down Expand Up @@ -823,7 +840,8 @@ impl<S: Stream> Export<S> {
.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())))
Expand Down
98 changes: 96 additions & 2 deletions rs/moq-mux/src/container/mp4.rs
Original file line number Diff line number Diff line change
Expand Up @@ -124,7 +124,8 @@ impl<S: Stream> Export<S> {
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<Option<Bytes>> {
kio::wait(|waiter| self.poll_next(waiter)).await
}
Expand All @@ -142,9 +143,16 @@ impl<S: Stream> Export<S> {
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<Option<Finish>> {
let Some(header) = &self.header else {
return Ok(None);
Expand Down Expand Up @@ -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::<usize>();
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<Vec<u8>> = 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() {
Expand Down
4 changes: 3 additions & 1 deletion rs/moq-relay/src/listener.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down