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

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

18 changes: 15 additions & 3 deletions doc/bin/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ Docker; see [Install](/setup/install).
| `import` | `rtsp --connect <url>` | Pull an IP camera's stream. |
| `import` | `archive <url>` | Replay a recording from an object store. |
| `export` | `fmp4`, `mkv`, `ts`, `flv`, `h264`, `h265` | Write a container to stdout. |
| `export` | `mp4 --output <file>` | Record a regular MP4 that stays playable if the recording is cut short. |
| `export` | `hls --listen`, `hls --output <dir>` | Serve the broadcast as HLS over HTTP, record it to a directory, or both. |
| `export` | `rtmp`, `srt`, `rtc` | Serve plays (`--listen`) or push to a remote (`--connect`). |
| `export` | `archive <url>` | Record every broadcast under the prefix into an object store. |
Expand Down Expand Up @@ -170,7 +171,7 @@ moq --connect https://relay.example.com/anon --broadcast camera.hang \

## Export

The `fmp4`, `mkv`, `flv`, `h264`, and `h265` exports pick renditions with
The `fmp4`, `mp4`, `mkv`, `flv`, `h264`, and `h265` exports pick renditions with
`--video-name`, `--audio-name`, `--video-codec`, `--audio-codec`, `--video <on|off>`,
and `--audio <on|off>` (both default to `on`). `ts`, `archive`, and the gateways
export everything and refuse these flags.
Expand All @@ -196,6 +197,17 @@ the samples, so an encoder restarting with a new SPS does not end the export.
Each keyframe carries them, so a keyframe whose sets never appeared ends it.
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
kept, though only the finished file indexes it.

```bash
moq ... export mp4 --output recording.mp4
```

MPEG-TS export pads to the source's constant mux rate when the catalog
recorded one, or to `--mux-rate`, on a constant-rate schedule an IRD or groomer
can lock to. Each frame goes out as early as the receiver's buffers admit, up
Expand Down Expand Up @@ -458,8 +470,8 @@ See [Authentication](/bin/relay/auth).
## Retention and latency

`import --max-age` (default 30 s) tells relays how long to keep old groups
fetchable, which the [HLS gateway](/bin/hls) depends on. `export fmp4`, `export h264`,
and `export h265` take `--max-delay` (default 500 ms): how far a stalled group
fetchable, which the [HLS gateway](/bin/hls) depends on. `export fmp4`, `export mp4`,
`export h264`, and `export h265` take `--max-delay` (default 500 ms): how far a stalled group
may fall behind the live edge before *this* consumer skips it. Raising
`--max-age` never delays playback.
At stdin EOF, `import` keeps the finished broadcast announced for
Expand Down
1 change: 0 additions & 1 deletion quest/m2/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,7 +128,6 @@ lite-07; bitrate enforcement is not part of this release.
- [Watch decode gate](/quest/m2/watch-decode-gate.md) - video lookahead stays encoded until it is near presentation, like audio
- [One support probe for watch audio and video](/quest/m2/watch-support-probe.md) - one probe helper with video's cache, and audio reports unsupported renditions
- [moqsrc A/V sync](/quest/m2/moqsrc-av-sync.md) - a nightly test measures A/V skew from `moqsrc` through clock-synced sinks
- [MP4 export](/quest/m2/mp4-export.md) - `moq export mp4 --output` records crash-safe fragments, then finishes a regular MP4 with moov at the end
- [fMP4 ambisonic layout](/quest/m2/mux-vr-ambisonic-fmp4.md) - fMP4 Opus import fills `ambisonic` from the `dOps` mapping table
- [Linux decoded frames](/quest/m2/obs-decode-linux.md) - present supported native decoded surfaces with visible CPU fallback
- [Windows decoded frames](/quest/m2/obs-decode-windows.md) - present decoded D3D11 surfaces in OBS without CPU readback
Expand Down
41 changes: 0 additions & 41 deletions quest/m2/mp4-export.md

This file was deleted.

4 changes: 0 additions & 4 deletions quest/m2/mp4-repair.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,3 @@ Follow-up of [moq-dev/moq#7357](https://github.com/moq-dev/moq/pull/7357). Its f
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.

## Required

- [moq export mp4](/quest/m2/mp4-export.md) - its PR, #7357, adds the recorder and the moof indexer
4 changes: 0 additions & 4 deletions quest/m2/mp4-sigint-flush.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,3 @@ Follow-up of [moq-dev/moq#7357](https://github.com/moq-dev/moq/pull/7357), which
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.

## Required

- [moq export mp4](/quest/m2/mp4-export.md) - its PR, #7357, adds the recorder
2 changes: 2 additions & 0 deletions rs/moq-cli/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -136,6 +136,8 @@ serde = { workspace = true }
serde_json = { workspace = true }
terminal_size = "0.4.4"
tokio = { workspace = true, features = ["full"] }
# Tells a recording to finish its file on the first shutdown signal.
tokio-util = { workspace = true }
tower-http = { workspace = true }
tracing = { workspace = true }
url = { workspace = true }
Expand Down
78 changes: 56 additions & 22 deletions rs/moq-cli/src/args.rs
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@
//! the separator stays unconditional rather than context-sensitive.

use std::ffi::{OsStr, OsString};
use std::path::PathBuf;
use std::time::Duration;

use crate::publish::PublishFormat;
Expand Down Expand Up @@ -390,12 +391,10 @@ impl Invocation {
);
}
if export.echo.is_some() {
if export.sink.stdout().is_none()
if export.sink.container().is_none()
&& let Some(sink) = export.sink.ignores_selection()
{
anyhow::bail!(
"--echo reports what a stdout container export reads, and `export {sink}` is not one"
);
anyhow::bail!("--echo reports what a container export reads, and `export {sink}` is not one");
}
let msf = match export.catalog_format {
Some(format) => matches!(format, CatalogFormatArg::Msf),
Expand All @@ -409,7 +408,15 @@ impl Invocation {
"--echo follows the hang catalog's `echo` section, which the MSF catalog does not carry"
);
}
if let Some(stdout) = export.sink.stdout() {
if let Some(output) = export.sink.container().and_then(|container| container.output) {
// Refused before anything dials, rather than once the broadcast arrives.
anyhow::ensure!(
!output.exists(),
"--output {} already exists; pick a new file",
output.display()
);
}
if let Some(stdout) = export.sink.container() {
anyhow::ensure!(
stdout.follow.is_zero() || matches!(stdout.format, SubscribeFormat::Ts),
"--linger is gone, and following a broadcast's return needs an output that can mark the restart: only `export ts --follow` can"
Expand Down Expand Up @@ -1076,6 +1083,7 @@ impl Export {
}
match &self.sink {
ExportSink::Fmp4(args) => found.extend(args.container.deprecated()),
ExportSink::Mp4(args) => found.extend(args.fragmented.container.deprecated()),
ExportSink::Mkv(args) => found.extend(args.container.deprecated()),
ExportSink::Ts(args) => found.extend(args.deprecated()),
ExportSink::Flv(args) => found.extend(args.deprecated()),
Expand All @@ -1089,11 +1097,13 @@ impl Export {
}

/// The single sink draining the Origin on an export. The container formats write
/// to stdout; the gateways bridge another protocol.
/// to stdout, except `mp4`, which records to a file; the gateways bridge another protocol.
#[derive(usage_rs::Subcommands, Clone)]
pub enum ExportSink {
/// Fragmented MP4 / CMAF to stdout.
Fmp4(Fragmented),
/// Regular MP4 recorded to a file, which plays as fragmented MP4 if the recording is cut short.
Mp4(Recorded),
/// Matroska / WebM to stdout.
Mkv(BufferedFragmented),
/// MPEG-TS to stdout.
Expand Down Expand Up @@ -1124,7 +1134,7 @@ impl ExportSink {
/// The sink's name when it doesn't apply selection, so the selection flags would be ignored.
fn ignores_selection(&self) -> Option<&'static str> {
Some(match self {
Self::Fmp4(_) | Self::Mkv(_) | Self::Flv(_) | Self::H264(_) | Self::H265(_) => return None,
Self::Fmp4(_) | Self::Mp4(_) | Self::Mkv(_) | Self::Flv(_) | Self::H264(_) | Self::H265(_) => return None,
Self::Ts(_) => "ts",
Self::Hls(_) => "hls",
Self::Rtmp(_) => "rtmp",
Expand All @@ -1145,49 +1155,57 @@ impl ExportSink {
}
}

/// Whether this sink writes to stdout (the container formats and the report sinks).
/// Whether this sink writes to stdout (the container formats but `mp4`, and the report sinks).
pub fn is_stdout(&self) -> bool {
self.stdout().is_some() || self.report().is_some()
self.container().is_some_and(|container| container.output.is_none()) || self.report().is_some()
}

/// The stdout container format and its options, when this sink writes to
/// stdout. The fragment cap is fmp4/mkv-only and the mux rate is TS-only.
pub fn stdout(&self) -> Option<Stdout> {
let container = |format, container: &Container| Stdout {
/// The container format and its options, when this sink is one. The fragment cap is
/// fmp4/mp4/mkv-only and the mux rate is TS-only.
pub fn container(&self) -> Option<ContainerSink> {
let container = |format, container: &Container| ContainerSink {
format,
max_delay: container.max_delay.into(),
follow: container.linger.into(),
stitch: false,
fragment_duration: None,
mux_rate: None,
passthrough: false,
output: None,
};
let buffered = |format, args: &Buffered| Stdout {
let buffered = |format, args: &Buffered| ContainerSink {
format,
max_delay: args.delay.into(),
follow: args.linger.into(),
stitch: false,
fragment_duration: None,
mux_rate: None,
passthrough: false,
output: None,
};
Some(match self {
Self::Fmp4(args) => Stdout {
Self::Fmp4(args) => ContainerSink {
fragment_duration: args.fragment_duration.map(Into::into),
..container(SubscribeFormat::Fmp4, &args.container)
},
Self::Mkv(args) => Stdout {
Self::Mp4(args) => ContainerSink {
fragment_duration: args.fragmented.fragment_duration.map(Into::into),
output: Some(args.output.clone()),
..container(SubscribeFormat::Mp4, &args.fragmented.container)
},
Self::Mkv(args) => ContainerSink {
fragment_duration: args.fragment_duration.map(Into::into),
..buffered(SubscribeFormat::Mkv, &args.container)
},
Self::Ts(args) => Stdout {
Self::Ts(args) => ContainerSink {
format: SubscribeFormat::Ts,
max_delay: args.delay.into(),
follow: args.follow.into(),
stitch: args.stitch,
fragment_duration: None,
mux_rate: args.mux_rate,
passthrough: args.passthrough,
output: None,
},
Self::Flv(args) => buffered(SubscribeFormat::Flv, args),
Self::H264(args) => container(SubscribeFormat::H264, args),
Expand All @@ -1197,8 +1215,8 @@ impl ExportSink {
}
}

/// A stdout sink's format and the options that apply to it.
pub struct Stdout {
/// A container sink's format and the options that apply to it.
pub struct ContainerSink {
pub format: SubscribeFormat,
/// The staleness budget, also the FLV/MKV release delay and how far behind the source `ts`
/// runs (`--delay`).
Expand All @@ -1212,6 +1230,8 @@ pub struct Stdout {
pub mux_rate: Option<u64>,
/// Write the `m2ts` passthrough track back out (`ts` only).
pub passthrough: bool,
/// The file a recording writes (`mp4` only); the rest write to stdout.
pub output: Option<PathBuf>,
}

/// Staleness options for stdout sinks without a fixed release delay.
Expand Down Expand Up @@ -1361,6 +1381,20 @@ impl Transport {
}
}

/// A regular MP4 recording.
#[derive(usage_rs::Args, Clone)]
#[usage(unknown_flags = "error", args_override_self = false)]
pub struct Recorded {
#[usage(flatten)]
pub fragmented: Fragmented,

/// 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.
#[usage(long, value_name = "FILE", value_hint = usage_rs::ValueHint::FilePath)]
pub output: PathBuf,
}

/// The fMP4 stdout container with a fragment cap.
#[derive(usage_rs::Args, Clone)]
#[usage(unknown_flags = "error", args_override_self = false)]
Expand Down Expand Up @@ -1435,7 +1469,7 @@ mod tests {
let Command::Export(export) = &cli.stages[0] else {
panic!("not an export");
};
export.sink.stdout().unwrap().max_delay
export.sink.container().unwrap().max_delay
};
assert_eq!(stdout(&[]), Duration::from_secs(1));
assert_eq!(stdout(&["--delay", "2s"]), Duration::from_secs(2));
Expand Down Expand Up @@ -1618,7 +1652,7 @@ mod tests {
let Command::Export(export) = &cli.stages[0] else {
panic!("not an export");
};
let stdout = export.sink.stdout().unwrap();
let stdout = export.sink.container().unwrap();
assert!(stdout.passthrough);
assert_eq!(stdout.max_delay, Duration::from_secs(2));
for flags in [&["--stitch"][..], &["--follow", "10s"], &["--mux-rate", "20000000"]] {
Expand Down Expand Up @@ -2543,7 +2577,7 @@ mod tests {
let Command::Export(export) = &cli.stages[0] else {
panic!("expected export")
};
export.sink.stdout().unwrap().max_delay
export.sink.container().unwrap().max_delay
};

for format in ["fmp4", "h264", "h265"] {
Expand Down
Loading