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
13 changes: 9 additions & 4 deletions doc/bin/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -415,13 +415,18 @@ fetchable, which the [HLS gateway](/bin/hls) depends on. `export fmp4`, `export
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 up for its max-age, so a
subscriber still catching up can drain it; Ctrl-C ends that early. A gateway
At stdin EOF, `import` keeps the finished broadcast announced for
`--linger` (default 30 s) from the end, so a subscriber that arrives late, such
as a player that read the final catalog after the end, still gets the tail;
`--linger 0s` closes it at once, and Ctrl-C ends the wait early. A gateway
import does the same at a clean end: an RTMP unpublish (`deleteStream`) or
completed play, the end of an SRT stream, a WHIP `DELETE`, or an HLS playlist
ending with `EXT-X-ENDLIST`. A dropped connection or an error closes the
broadcast at once, and a reconnect, which publishes a newer
[epoch](/concept/moq-lite#publisher-epochs) at the same path, ends the wait.
broadcast at once. A reconnect publishes a newer
[epoch](/concept/moq-lite#publisher-epochs) at the same path, which takes over
the path while the old broadcast finishes its linger. `import rtsp` redials
after every session, so it closes each run at once and refuses `--linger`, as
do `import archive`, `import capture`, and a WHEP pull (`import rtc --connect`).

`export ts`, `export flv`, `export rtmp`, and `export mkv` take `--delay` instead, like an SRT
receiver's latency, all tracks in decode order, so two exporters of one broadcast
Expand Down
7 changes: 5 additions & 2 deletions doc/bin/gstreamer.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ Each `sink_%u` request pad is one track. Pad properties: `track` names it
(default: after the codec), `container=loc` publishes it as
[LOC](/concept/standard#loc) instead of the legacy hang container, and
`track-status`/`track-error` report its lifecycle. Element properties:
`url`, `broadcast`, `connect-version`, `tls-disable-verify`, `quic-idle-timeout`, `quic-keylog`,
`url`, `broadcast`, `linger`, `connect-version`, `tls-disable-verify`, `quic-idle-timeout`, `quic-keylog`,
`quic-keep-alive`, and read-only `status`, `connected`, `moq-version`, and
`estimated-send-rate`, `estimated-recv-rate`, `connection-stats`, and
`sessions`. The sink reconnects for as long as the pipeline runs and only
Expand All @@ -84,7 +84,10 @@ it is released, reaches EOS, or fails; a flush or new stream after that EOS
holds it back again. Opaque data pads are not listed. Later
catalog updates do not wait for newly requested pads.

Once every pad reaches EOS, the sink closes the broadcast and posts EOS.
Once every pad reaches EOS, the sink keeps the finished broadcast announced
for `linger` milliseconds (default 30000), so a subscriber that arrives late
still gets the tail, then closes it and posts EOS. `linger=0` closes it at once,
and stopping the pipeline (`READY` or `NULL`) during the wait closes it early.

All pads share one media timeline on one wall clock. The first timed buffer places
it using UNIX or NTP reference timestamp metadata; other clock domains use the
Expand Down
2 changes: 1 addition & 1 deletion doc/bin/hls.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ The CLI serves the one `--broadcast` it was given, at

Import follows a live playlist, joining a few segments behind its live edge,
until every rendition's playlist ends with `EXT-X-ENDLIST`. It then keeps the
finished broadcast up until its media is stale
finished broadcast up for `--linger`
(see [retention](/bin/cli#retention-and-latency)). A playlist that has already
ended, such as a VOD recording, is refused with an error rather than imported.
An `EXT-X-DISCONTINUITY` keeps the source's timestamps. Timestamp resets are not
Expand Down
1 change: 0 additions & 1 deletion quest/m1/broadcast-lifecycle/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,6 @@ timer on main at 1582fdc07d:

## Required

- [Publisher retention in moq-mux](/quest/m1/broadcast-lifecycle/retention.md) - moq-cli, the gateways, and moqsink keep a finished broadcast up for a fixed `--linger` (default 30s) through a moq-mux helper instead of moq-net's `Finish`
- [Stateless broadcasts](/quest/m1/broadcast-lifecycle/stateless.md) - `Finish`, its linger, and finished-only supersession are gone from moq-net, `@moq/net`, moq-ffi, moq-c, and every binding
- [TS export follows by cause](/quest/m1/broadcast-lifecycle/ts-follow.md) - `export ts|srt --linger` becomes `--follow <duration>`, a replacement's catalog has no separate deadline, and a track failure is classified by its cause instead of a 1s grace
- [SRT tells a clean end from a failure](/quest/m1/broadcast-lifecycle/srt-end.md) - an SRT ingest whose peer goes silent aborts instead of finishing as if it had shut down
Expand Down
42 changes: 0 additions & 42 deletions quest/m1/broadcast-lifecycle/retention.md

This file was deleted.

4 changes: 0 additions & 4 deletions quest/m1/broadcast-lifecycle/stateless.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,3 @@ Decided with the maintainer on 2026-10-23; see the epic for why.

Public API: breaking in moq-net, `@moq/net`, moq-ffi, moq-c, and every
binding. Wire: none.

## Required

- [Publisher retention in moq-mux](/quest/m1/broadcast-lifecycle/retention.md) - Rust publishers stop using `Finish` first, so none loses its tail in between
6 changes: 3 additions & 3 deletions quest/m1/broadcast-lifecycle/ts-follow.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@
`moq export ts --linger` and `moq export srt --linger` become `--follow
<duration>`: how long to wait for the publisher, or with `--stitch` a
replacement, to come back. The default 0 means don't follow. The Rust
`container::ts::Follower::with_linger` and moq-srt's `Subscribe::with_linger`
and `Client::with_linger` become `with_follow`. A replacement's first catalog
`container::ts::Follower::with_linger` becomes `with_follow`, matching
moq-srt's `Subscribe::with_follow` and `Client::with_follow`. A replacement's first catalog
is awaited until it arrives or the replacement withdraws, with no deadline of
its own. A track failure is classified by its cause, not by waiting
`CLOSE_GRACE` (1s) to see whether the announcement also goes.
Expand Down Expand Up @@ -36,5 +36,5 @@ Decided with the maintainer on 2026-10-23:
- Docs: `doc/bin/cli.md`, plus a migration note for moq-cli, moq-mux, and
moq-srt in the Impact bullet.

Public API: moq-mux and moq-srt renames (breaking); moq-cli flag rename.
Public API: moq-mux rename (breaking); moq-cli flag rename.
Wire: none unless the failure cause needs a new code.
6 changes: 6 additions & 0 deletions rs/moq-cli/MIGRATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,12 @@ How to update your invocation and config for each breaking change, newest first.

## Unreleased

### `import --linger` sets how long a finished broadcast stays up

A cleanly ended import used to stay up for its `--max-age`; it now stays up for `--linger` (default 30 s), counted from the end, and `--max-age` only sets retention.
Replace `import --max-age 5s` used to shorten that wait with `import --linger 5s`, or `--linger 0s` to close at once.
A reconnect at the same path no longer ends the wait. `import rtsp`, `import archive`, `import capture`, and `import rtc --connect` refuse `--linger`.

### The `nvenc` and `nvdec` Cargo features are removed ([#6483](https://github.com/moq-dev/moq/pull/6483))

Enable `nvidia` instead; the old names were aliases for it.
Expand Down
41 changes: 39 additions & 2 deletions rs/moq-cli/src/args.rs
Original file line number Diff line number Diff line change
Expand Up @@ -318,6 +318,12 @@ impl Invocation {
{
anyhow::bail!("--report names a track in the catalog the import builds, but {reason}");
}
if let Command::Import(import) = command
&& import.linger.is_some()
&& let Some(reason) = import.source.linger_refusal()
{
anyhow::bail!("--linger keeps a cleanly ended broadcast up, but {reason}");
}
let Command::Export(export) = command else {
continue;
};
Expand Down Expand Up @@ -745,11 +751,20 @@ pub struct Import {
/// wait for a late group). The default suits a segmented egress (HLS/DASH), which may only
/// advertise segments that are still fetchable; lower it when nothing reads history and the
/// memory matters. Media tracks only -- the catalog and timeline are read at the live edge,
/// which is retained unconditionally. A stdin import also stays up this long after EOF, so
/// a subscriber still catching up can drain the finished broadcast.
/// which is retained unconditionally.
#[usage(long)]
pub max_age: Option<moq_tokio::cli::Duration>,

/// How long a cleanly ended broadcast stays up, counted from its end, e.g. "30s"; "0s"
/// closes it at once. Defaults to 30s.
///
/// Subscribers already reading get the tail either way; this serves one that arrives after
/// the end, such as a player that read the final catalog late. A clean end is stdin EOF, an
/// RTMP unpublish or completed play, the end of an SRT stream, a WHIP `DELETE`, or an HLS
/// playlist's `EXT-X-ENDLIST`. A failure, and Ctrl-C, close the broadcast at once.
#[usage(long)]
pub linger: Option<moq_tokio::cli::Duration>,

/// The released spelling of [`Self::max_age`].
#[usage(long = "latency-max", hide = true)]
latency_max: Option<moq_tokio::cli::Duration>,
Expand Down Expand Up @@ -841,6 +856,28 @@ impl ImportSource {
Self::Avc3 | Self::Fmp4(_) | Self::Ts(_) | Self::Flv => None,
}
}

/// Why `--linger` can't apply to this source, or `None` when it can: only a source with a
/// clean end has a finished broadcast to keep up.
fn linger_refusal(&self) -> Option<&'static str> {
match self {
// Every run is followed by a redial publishing the next one, so a run's end is not
// the end of the content, and its finished catalog would tell readers to stop.
Self::Rtsp(_) => Some("`import rtsp` redials after every session, so a run's end is not the content's"),
Self::Rtc(rtc) if rtc.connect.is_some() => Some("a WHEP pull has no clean end"),
Self::Archive(_) => Some("`import archive` serves its recording until stopped"),
#[cfg(feature = "capture")]
Self::Capture(_) => Some("`import capture` has no clean end"),
Self::Avc3
| Self::Fmp4(_)
| Self::Ts(_)
| Self::Flv
| Self::Hls(_)
| Self::Rtmp(_)
| Self::Srt(_)
| Self::Rtc(_) => None,
}
}
}

/// The fMP4 stdin container: whether to unwrap its fragments.
Expand Down
15 changes: 8 additions & 7 deletions rs/moq-cli/src/hls.rs
Original file line number Diff line number Diff line change
Expand Up @@ -150,13 +150,13 @@ impl Tls {
}

/// Pull a remote HLS/LL-HLS playlist (URL or file path) into the Origin under `target.name`,
/// announced under `epoch`. Once the playlist ends, serve the finished broadcast until its
/// media is stale.
/// announced under `epoch`. Once the playlist ends, serve the finished broadcast for the linger.
pub async fn import(target: ImportTarget, args: ImportArgs, epoch: moq_net::Epoch) -> anyhow::Result<()> {
let ImportTarget {
origin,
name,
max_age,
linger,
bandwidth,
} = target;
let mut producer = origin.create_broadcast(&name).context("failed to create broadcast")?;
Expand Down Expand Up @@ -189,11 +189,11 @@ pub async fn import(target: ImportTarget, args: ImportArgs, epoch: moq_net::Epoc
return Err(err);
}

// The playlist ended: serve the finished broadcast until its media is stale, so
// subscribers still catching up drain the tail. An interrupt drops it at once.
let finish = importer.finish()?;
tracing::info!(linger = ?finish.linger(), "playlist ended; serving the finished broadcast until its media is stale");
finish.wait().await;
// The playlist ended: serve the finished broadcast for the linger, so a subscriber that
// arrives after the end still gets the tail. An interrupt drops it at once.
importer.finish()?;
tracing::info!(?linger, "playlist ended; serving the finished broadcast");
moq_mux::Linger::new([producer], importer, linger).wait().await;
Ok(())
}

Expand Down Expand Up @@ -424,6 +424,7 @@ mod test {
origin,
name: "hls".to_string(),
max_age: None,
linger: moq_mux::Linger::DEFAULT,
bandwidth: Default::default(),
};
let args = ImportArgs {
Expand Down
5 changes: 4 additions & 1 deletion rs/moq-cli/src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -707,12 +707,14 @@ fn spawn_import(
}

let max_age = import.max_age.map(Into::into);
let linger = import.linger.map_or(moq_mux::Linger::DEFAULT, Into::into);
// The MoQ side every gateway publishes into, minted per source since each takes it
// by value onto its own task.
let target = |name: String| crate::moq::ImportTarget {
origin: origin.clone(),
name,
max_age,
linger,
bandwidth: bandwidth.clone(),
};

Expand All @@ -733,7 +735,8 @@ fn spawn_import(
} else {
let broadcast = origin.create_broadcast(&name).context("failed to create broadcast")?;
Publish::new(broadcast, &format, config)?
};
}
.with_linger(linger);
publish.announce(epoch)?;
local = Some(publish);
} else {
Expand Down
10 changes: 6 additions & 4 deletions rs/moq-cli/src/moq.rs
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,10 @@
use hang::moq_net;

/// The MoQ side of an import: where a gateway publishes, under what name, the
/// retention it declares on the media tracks it mints, and the connection
/// allocator those tracks claim on.
/// retention it declares on the media tracks it mints, how long a clean end stays
/// up, and the connection allocator those tracks claim on.
///
/// Every gateway needs all four regardless of protocol, so they travel together
/// rather than as loose arguments per entry point.
/// They travel together rather than as loose arguments per entry point.
#[derive(Clone)]
pub struct ImportTarget {
/// The Origin the gateway publishes into.
Expand All @@ -24,6 +23,9 @@ pub struct ImportTarget {
/// (`--max-age`), or `None` for the publisher's own default.
pub max_age: Option<std::time::Duration>,

/// How long a cleanly ended broadcast stays up (`--linger`).
pub linger: std::time::Duration,

/// Connection allocator each passthrough track claims its peak-hold bitrate on,
/// so a co-resident encoder targets what is left. Unlimited when there is no
/// uplink estimate.
Expand Down
Loading
Loading