Skip to content
Merged
10 changes: 8 additions & 2 deletions doc/bin/webrtc.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,9 @@ receives the largest enabled video rendition (then highest bitrate) in its negot
the highest-bitrate enabled Opus rendition (then sample rate, then channels). It
follows the catalog: a peer whose rendition is disabled moves to the next best at
that rendition's first keyframe, a better one that re-enables wins the peer back,
and with none enabled the peer receives nothing until one is. `--cors-origin`
and with none enabled the peer receives nothing until one is. A WHEP offer gets one
audio and one video line at most: the answer rejects the rest, which would only repeat
the same media. `--cors-origin`
opens the endpoint to browsers on other origins. Every session shares one UDP
media port, `--udp-bind` (OS-picked by default), bound at startup so a taken port
fails before the listener reports ready. Behind NAT, `--public-addr` advertises
Expand All @@ -43,7 +45,11 @@ reconnects while its stale session lingers replaces it at once.
An export stays on the publisher it started with. A replacement publisher never
reaches its session, so timestamps and codec state never reset mid-session.
Once the original publisher leaves, the session ends with an error, and the
player or `export webrtc --connect` must reconnect to reach the replacement.
player or `export webrtc --connect` must reconnect to reach the replacement. A
publisher that ends cleanly, such as an RTMP `deleteStream`, ends the session
cleanly once its last frames are sent: the peer connection closes with an RTCP BYE
and a DTLS close\_notify, which a browser reports as its `RTCDtlsTransport` state
turning `closed`.
`--connect` runs until its session ends.

Built on [str0m](https://github.com/algesten/str0m), with DTLS and SRTP on [rind](https://github.com/kixel-ai/rind); the library is
Expand Down
30 changes: 30 additions & 0 deletions quest/m1/export-evicts-every-group.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# [M] A live export reads each group to its end instead of evicting it

## Goal

A container export following a steady live broadcast reads every group to its
clean end: it logs no `current group evicted` and counts no loss while nothing
is lost. Each group's tail frames reach the export.

## Plan

Seen 2026-11-17 while validating
[moq-dev/moq#9049](https://github.com/moq-dev/moq/pull/9049) on `main`: a
local `moq-relay`, ffmpeg pushing 30 fps H.264 with a 1 s GOP over RTMP into
`moq import rtmp`, and `moq export webrtc --listen` from the relay (both on
moq-lite-06, WebTransport). The export logged `current group evicted; skipping
to next buffered group ... error=Moq(Stream(Old))` from
`rs/moq-mux/src/container/consumer.rs` once per group (33 in 33 s), while
Chrome still decoded about 30 fps. Every evicted group calls `lose()`, so the
export's loss accounting reports a loss per group.

Reproduce first, then find which side ends a finished group as `Old`: the
relay hop, `moq-rtmp`'s group writes, or the consumer reading a group whose
successor started. Recent candidates touching this path:
[#8910](https://github.com/moq-dev/moq/pull/8910) (an ordered track reports
the groups it gives up on) and
[#8961](https://github.com/moq-dev/moq/pull/8961) (a group's end in one word).

## Related

- [Export order](/quest/m3/export-order.md) - the same warning after an outage, where the eviction is real
37 changes: 0 additions & 37 deletions quest/m1/precut-fixes/whep-egress-end.md

This file was deleted.

39 changes: 39 additions & 0 deletions quest/m3/webrtc-clean-end.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# [S] A clean end crosses the WebRTC gateway as a clean end

## Goal

A broadcast that ends cleanly on one side of a WebRTC session ends cleanly
on the other. moq-webrtc's WHIP client (`moq export webrtc --connect`) ends
its resource with a `DELETE`, so the WHIP server finishes the ingested
broadcast and serves it for its linger. Its WHEP client
(`moq import webrtc --connect`) finishes its output when the server closes
cleanly, keeping the frames it already received, instead of aborting it.

## Plan

Since [moq-dev/moq#9049](https://github.com/moq-dev/moq/pull/9049), an egress
whose broadcast ends cleanly closes its peer connection (RTCP BYE and DTLS
close_notify) once its last frames are sent; before it, the session never
ended. An ingest reads that close like a vanished peer: `Session::run` aborts
the sink with `session closed`. So a WHIP server aborts a broadcast whose
publisher ended cleanly, and moq's WHEP client aborts its output, which
fails any read of a frame it received but its readers had not reached yet
(seen while writing #9049's tests).

- WHIP client: `client::whip::dial` keeps the answer's `Location` (resolved
against the dialed URL, keeping its query token), and after `Session::run`
returns `Ok` sends the `DELETE` (RFC 9725) before returning.
- WHIP server: a publisher's close_notify (str0m's `Event::Closed`) is a
clean end, like a `DELETE`: the server finishes the broadcast and lingers
it. A browser's `pc.close()` sends close_notify without a `DELETE`. Only a
peer that vanishes (ICE consent failure, establishment timeout) aborts.
Decided on #9049: ✅ both close_notify and `DELETE` end cleanly (rejected:
`DELETE` only, which RFC 9725 names but which aborts the broadcast of every
publisher that skips it).
- WHEP client: a WHEP server has no request to end a session with, so the
server's close_notify is its only clean end. An ingest session that sees
`Event::Closed` returns as the peer's clean end, and `Client::pull`
finishes the sink as `AcceptedSession` does after a `DELETE`. The WHIP
server's ingest takes the same path.

Public API: none. Wire: the WHIP client sends a `DELETE`.
4 changes: 3 additions & 1 deletion rs/moq-webrtc/src/client/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,9 @@ impl Client {
/// `client publish`: push the broadcast `source` resolved to a remote WHIP endpoint,
/// until the session ends.
///
/// It stays on that publisher instance, and fails once the instance's route dies.
/// It stays on that publisher instance, and fails once the instance's route dies. A
/// broadcast that ends cleanly closes the peer connection once its last frames are sent,
/// and ends `Ok`.
/// The source's origin resolves a rendition whose catalog `broadcast` field references
/// a sibling broadcast.
pub async fn publish(&self, url: Url, source: moq_mux::Source) -> crate::Result<()> {
Expand Down
23 changes: 18 additions & 5 deletions rs/moq-webrtc/src/egress.rs
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,9 @@ pub struct EgressSource {
catalog: watch::Receiver<Catalog>,
/// Why the catalog stopped, until the session takes it.
catalog_end: Option<tokio::task::JoinHandle<Result<()>>>,
writes_tx: mpsc::Sender<WriteRequest>,
/// Cloned into each pump until [`Self::end`], so the writes channel closes once the
/// catalog ended and every pump has written what it holds.
writes_tx: Option<mpsc::Sender<WriteRequest>>,
writes_rx: Option<mpsc::Receiver<WriteRequest>>,
}

Expand All @@ -122,7 +124,7 @@ impl EgressSource {
source,
catalog,
catalog_end: Some(catalog_end),
writes_tx: tx,
writes_tx: Some(tx),
writes_rx: Some(rx),
})
}
Expand All @@ -139,12 +141,23 @@ impl EgressSource {
self.catalog_end.take().expect("EgressSource catalog_end already taken")
}

/// Open no more lines, as the catalog ended cleanly: the writes channel closes once every
/// pump has served its rendition to the end.
pub(crate) fn end(&mut self) {
self.writes_tx = None;
}

/// Spawn a pump task for a newly added (sendonly) media line.
///
/// `mid` and `formats` come from str0m's negotiated state, `formats` in the peer's order.
/// The pump serves the best enabled catalog rendition in any of them and forwards every
/// frame as a [`WriteRequest`] in that rendition's format.
/// frame as a [`WriteRequest`] in that rendition's format. A line added after
/// [`Self::end`] serves nothing.
pub fn on_track(&mut self, mid: Mid, formats: Vec<Format>) -> Result<()> {
let Some(tx) = &self.writes_tx else {
tracing::debug!(?mid, "egress track added after the catalog ended; ignored");
return Ok(());
};
if !formats
.iter()
.any(|format| format.codec == Codec::Opus || video_kind(format.codec).is_some())
Expand All @@ -157,7 +170,7 @@ impl EgressSource {
formats,
source: self.source.clone(),
catalog: self.catalog.clone(),
tx: self.writes_tx.clone(),
tx: tx.clone(),
playhead: None,
};
// Subscribing blocks on SUBSCRIBE_OK, so keep it inside the pump task to keep this
Expand Down Expand Up @@ -663,7 +676,7 @@ mod tests {
source,
catalog: watch::channel(catalog).1,
catalog_end: None,
writes_tx,
writes_tx: Some(writes_tx),
writes_rx: Some(writes_rx),
};

Expand Down
Loading