Skip to content
Closed
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
19 changes: 16 additions & 3 deletions doc/bin/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -452,8 +452,7 @@ continuity error, and the rest carry on. It takes neither `--linger`,
`export ts --sync` renders every packet from the broadcast alone, so two exports
of it, joined at different moments and fed with different skew, emit identical
TS for the content both receive, continuity counters included, as the legs of a
1+1 pair must; an SMPTE ST 2022-7 pair also needs identical RTP framing around
it, which this command does not write. Each PID gets a fixed lane of the constant rate, sized
1+1 pair must. Each PID gets a fixed lane of the constant rate, sized
for its codec's most, with video taking the rest; content one leg lacks leaves
its packets as stuffing there. The PCR rides a PID of its own, and each PID's
continuity counter restarts at every group with the break flagged. It needs a
Expand All @@ -465,7 +464,21 @@ narrow to absorb that one, is logged and counted in `overruns`: the legs can
differ there. So can reordered video whose SPS declares no reorder depth
(`max_num_reorder_frames`), which is logged, and SI while one leg holds an older
revision than the other or around an SI table the catalog adds or drops, which
each leg takes up when its catalog update arrives.
each leg takes up when its catalog update arrives. With `--rtp IP:PORT` (such
as `--rtp 239.1.1.1:5004`) it sends the multiplex as RTP (RFC 2250) over UDP
instead of to stdout, for an SMPTE ST 2022-7 pair: two legs send the same
datagram, headers included, wherever both hold its packets, and each withholds
one it is not sure of, so legs whose losses fall in different datagrams send
between them every datagram a clean leg sends; a datagram both lost part of
goes out from neither (the framing is
`Export::with_rtp`'s, in [`moq-mux`](https://docs.rs/moq-mux)). SI
one leg missed, and a unit of a sparse track (such as SCTE-35) lost with no
later jump in it, still go out as stuffing where the other leg has them. The
SSRC follows the publisher [epoch](/concept/moq-lite#publisher-epochs), so
every hop must carry it: moq-transport draft 17 or later, or the opt-in
moq-lite 07 (see [Publisher runs](#publisher-runs)). The datagrams go out at
the multiplex rate on the `--delay` clock, so `--rtp` refuses `--delay 0s`. A
multicast destination gets the system's default TTL.

A stdout export ends with the broadcast. `export ts --linger 10s` waits that
long for the same publisher instance to come back, and carries on with the same
Expand Down
1 change: 0 additions & 1 deletion quest/m1/ts-reliability/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,5 @@ remain with their current quests.

## Related

- [TS over RTP legs](/quest/m2/ts-rtp-egress.md) - TS identity alone is not ST 2022-7, which also needs matching RTP headers
- [MSFTS mapping](/quest/m3/msfts-convergence.md) - document the exact equivalence and differences between the carriage modes

1 change: 0 additions & 1 deletion quest/m2/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -133,7 +133,6 @@ ranked just below deterministic TS legs, which it requires.
- [Watch decode gate](/quest/m2/watch-decode-gate.md) - video lookahead stays encoded until it is near presentation, like audio
- [Drop announce="never"](/quest/m2/publish-announce-never.md) - `@moq/publish` offers only announce modes a watcher can reach
- [Deterministic H.265 TS legs](/quest/m2/ts-hitless-h265.md) - H.265's buffering period gets the same group anchor as H.264
- [TS over RTP legs](/quest/m2/ts-rtp-egress.md) - two legs send identical RTP packets, headers included, so an ST 2022-7 receiver can merge them
- [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 edit lists](/quest/m2/fmp4-edit-lists.md) - the fMP4 importer applies edit lists to frame timestamps
Expand Down
56 changes: 0 additions & 56 deletions quest/m2/ts-rtp-egress.md

This file was deleted.

66 changes: 64 additions & 2 deletions rs/moq-cli/src/args.rs
Original file line number Diff line number Diff line change
Expand Up @@ -366,6 +366,18 @@ impl Invocation {
stdout.linger.is_zero() || matches!(stdout.format, SubscribeFormat::Ts),
"--linger needs an output that can mark a restart, and only `export ts` can"
);
anyhow::ensure!(
stdout.rtp.is_none() || stdout.sync,
Comment thread
kixelated marked this conversation as resolved.
Resolved
"--rtp needs --sync: only a synced multiplex lays each packet where every leg does"
);
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
anyhow::ensure!(
stdout.rtp.is_none_or(|addr| addr.port() != 0),
"--rtp needs a destination port other than 0"
);
anyhow::ensure!(
stdout.rtp.is_none() || !stdout.max_delay.is_zero(),
"--rtp needs a --delay: without one no clock paces the datagrams"
);
if matches!(stdout.format, SubscribeFormat::H264 | SubscribeFormat::H265) {
anyhow::ensure!(
!export.select.no_video,
Expand Down Expand Up @@ -1052,9 +1064,10 @@ 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 `ts --rtp`, and the report
/// sinks).
pub fn is_stdout(&self) -> bool {
self.stdout().is_some() || self.report().is_some()
self.stdout().is_some_and(|stdout| stdout.rtp.is_none()) || self.report().is_some()
}

/// The stdout container format and its options, when this sink writes to
Expand All @@ -1069,6 +1082,7 @@ impl ExportSink {
mux_rate: None,
passthrough: false,
sync: false,
rtp: None,
};
let buffered = |format, args: &Buffered| Stdout {
format,
Expand All @@ -1079,6 +1093,7 @@ impl ExportSink {
mux_rate: None,
passthrough: false,
sync: false,
rtp: None,
};
Some(match self {
Self::Fmp4(args) => Stdout {
Expand All @@ -1098,6 +1113,7 @@ impl ExportSink {
mux_rate: args.mux_rate,
passthrough: args.passthrough,
sync: args.sync,
rtp: args.rtp,
},
Self::Flv(args) => buffered(SubscribeFormat::Flv, args),
Self::H264(args) => container(SubscribeFormat::H264, args),
Expand All @@ -1122,6 +1138,8 @@ pub struct Stdout {
pub passthrough: bool,
/// Render identical packets to every other `--sync` export of the broadcast (`ts` only).
pub sync: bool,
/// Send RTP to this address rather than write to stdout (`ts` only).
pub rtp: Option<std::net::SocketAddr>,
}

/// Staleness options for stdout sinks without a fixed release delay.
Expand Down Expand Up @@ -1251,6 +1269,15 @@ pub struct Transport {
#[usage(long, conflicts("--stitch", "--passthrough"))]
pub sync: bool,

/// Send the output as RTP (RFC 2250) over UDP to `ADDR` (`IP:PORT`) instead of stdout, seven
/// TS packets a datagram, with headers that follow from the packets' place on the multiplex
/// and from the broadcast, so the legs of a 1+1 pair send the same datagrams for an SMPTE
/// ST 2022-7 receiver to merge, paced at the multiplex rate on the `--delay` clock. Needs
/// `--sync`, a nonzero `--delay`, and a route carrying the publisher's epoch: moq-transport
/// draft 17 or later, or moq-lite 07, on every hop.
#[usage(long, value_name = "ADDR", conflicts("--stitch", "--passthrough"))]
pub rtp: Option<std::net::SocketAddr>,

/// The released spelling of [`Self::delay`].
#[usage(long = "max-age", hide = true)]
max_age: Option<crate::duration::Duration>,
Expand Down Expand Up @@ -1393,6 +1420,41 @@ mod tests {
}
}

/// `export ts --rtp` sends what `--sync` renders, so it needs it and refuses what it
/// refuses, takes a destination with a port and a delay to pace by, refused before anything
/// dials, and leaves stdout to another stage.
#[test]
fn export_ts_rtp_needs_sync_and_leaves_stdout() {
let parse = |rtp: &str, args: &[&str]| {
let mut argv = vec!["moq", "export", "--broadcast", "b", "ts", "--rtp", rtp];
argv.extend_from_slice(args);
Invocation::try_parse_from(argv)
};
let cli = parse("127.0.0.1:5004", &["--sync"]).unwrap();
cli.validate().unwrap();
let Command::Export(export) = &cli.stages[0] else {
panic!("not an export");
};
assert_eq!(export.sink.stdout().unwrap().rtp, Some(([127, 0, 0, 1], 5004).into()));
assert!(!export.sink.is_stdout());
let err = parse("127.0.0.1:5004", &[]).unwrap().validate().unwrap_err();
assert!(err.to_string().contains("--rtp needs --sync"), "{err}");
for flags in [&["--sync", "--stitch"][..], &["--passthrough"]] {
assert!(
parse("127.0.0.1:5004", flags).is_err(),
"{flags:?} must not start a run"
);
}
assert!(parse("127.0.0.1", &["--sync"]).is_err(), "a destination without a port");
let err = parse("[::1]:0", &["--sync"]).unwrap().validate().unwrap_err();
assert!(err.to_string().contains("port other than 0"), "{err}");
let err = parse("127.0.0.1:5004", &["--sync", "--delay", "0s"])
.unwrap()
.validate()
.unwrap_err();
assert!(err.to_string().contains("--rtp needs a --delay"), "{err}");
}

fn export(flags: &[&str]) -> Result<Invocation, ParseError> {
let argv = ["moq", "--connect", "http://relay", "--broadcast", "room", "export"];
Invocation::try_parse_from(argv.iter().chain(flags).copied())
Expand Down
1 change: 1 addition & 0 deletions rs/moq-cli/src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -832,6 +832,7 @@ fn spawn_export(
mux_rate: stdout.mux_rate,
passthrough: stdout.passthrough,
sync: stdout.sync,
rtp: stdout.rtp,
catalog: export.catalog_format,
select: export.select,
};
Expand Down
103 changes: 97 additions & 6 deletions rs/moq-cli/src/subscribe.rs
Original file line number Diff line number Diff line change
Expand Up @@ -200,6 +200,9 @@ pub struct SubscribeArgs {
/// Render identical packets to every other synced export of the broadcast (TS only).
pub sync: bool,

/// Send the synced multiplex as RTP to this UDP address instead of stdout (TS only).
pub rtp: Option<std::net::SocketAddr>,

/// Catalog format for track discovery (default: detect from the broadcast suffix).
pub catalog: Option<CatalogFormatArg>,

Expand Down Expand Up @@ -276,6 +279,52 @@ fn log_release(release: &moq_mux::container::ts::stats::Release, message: &'stat
);
}

/// The datagrams `--rtp` could not send since it last reported them, and why the last one could
/// not.
#[derive(Default)]
struct Unsent {
count: u64,
last: Option<std::io::Error>,
}

impl Unsent {
/// Send `datagram` now, or count it lost: a full send queue or a route briefly down loses
/// that datagram, as the network would, not the stream, and the export never waits on the
/// socket. A receiver not listening yet answers with ICMP, which a connected socket reports
/// on a later send, and is not counted.
fn send(&mut self, socket: &std::net::UdpSocket, datagram: &[u8]) {
match socket.send(datagram) {
Comment thread
kixelated marked this conversation as resolved.
Resolved
Err(err) if err.kind() != std::io::ErrorKind::ConnectionRefused => {
self.count += 1;
self.last = Some(err);
}
_ => {}
}
}

/// Log the datagrams lost since the last report, if any.
fn report(&mut self) {
if let Some(err) = self.last.take() {
let count = std::mem::take(&mut self.count);
tracing::warn!(count, %err, "--rtp dropped datagrams it could not send");
}
}
}

/// A UDP socket bound to an ephemeral port and connected to `addr`. It is nonblocking, and sent
/// on directly ([`Unsent::send`]): tokio's own readiness would refuse a send until its reactor
/// first saw the socket writable.
fn rtp_socket(addr: std::net::SocketAddr) -> std::io::Result<std::net::UdpSocket> {
let local: std::net::SocketAddr = match addr {
std::net::SocketAddr::V4(_) => (std::net::Ipv4Addr::UNSPECIFIED, 0).into(),
std::net::SocketAddr::V6(_) => (std::net::Ipv6Addr::UNSPECIFIED, 0).into(),
};
let socket = std::net::UdpSocket::bind(local)?;
socket.connect(addr)?;
socket.set_nonblocking(true)?;
Ok(socket)
}

impl Subscribe {
/// Resolve the broadcast at `path` on `origin` to export it with the resolved settings;
/// [`run`](Self::run) drives it.
Expand Down Expand Up @@ -422,6 +471,13 @@ impl Subscribe {
if self.args.sync {
ts = ts.with_sync();
}
let rtp = match self.args.rtp {
Some(addr) => {
ts = ts.with_rtp();
Some(rtp_socket(addr).with_context(|| format!("could not open a UDP socket to {addr}"))?)
}
None => None,
};

// A TS byte stream carries no per-frame timing, so delivery time is the only
// carrier of each frame's spacing (#2984). The export lays each slice of the PCR
Expand All @@ -435,6 +491,7 @@ impl Subscribe {
// the way `publish` reports one that stops arriving.
let mut log = moq_mux::container::ts::stats::Log::default();
let mut sampled = moq_clock::now();
let mut unsent = Unsent::default();
// The export's drop, gap, out-of-tolerance and `--sync` counts, as last logged.
let mut reported = (0, 0, 0, 0, 0, 0);
let sections = self.sections;
Expand All @@ -447,16 +504,31 @@ impl Subscribe {
}
};
let end = loop {
let frame = match ts.next().await {
Ok(Some(frame)) => frame,
Ok(None) => break Ok(()),
Err(err) => break Err(err),
// Sampled on the interval whether a frame comes or not: an RTP leg withholding every
// run hands out none for as long as it does.
let due = sampled + moq_mux::container::ts::stats::Log::INTERVAL;
let next = tokio::select! {
next = ts.next() => Some(next),
_ = moq_clock::sleep_until(due) => None,
};
stdout.write_all(&frame.payload).await?;
stdout.flush().await?;
if let Some(next) = next {
let frame = match next {
Ok(Some(frame)) => frame,
Ok(None) => break Ok(()),
Err(err) => break Err(err),
};
match &rtp {
Some(socket) => unsent.send(socket, &frame.payload),
None => {
stdout.write_all(&frame.payload).await?;
stdout.flush().await?;
}
}
}

if sampled.elapsed() >= moq_mux::container::ts::stats::Log::INTERVAL {
sampled = moq_clock::now();
unsent.report();
let stats = ts.export().stats();
report(&stats);
let release = &stats.release;
Expand All @@ -475,6 +547,7 @@ impl Subscribe {
log.sample(stats.into());
}
};
unsent.report();
let stats = ts.export().stats();
report(&stats);
log_release(&stats.release, "TS export release clock");
Expand Down Expand Up @@ -539,3 +612,21 @@ impl Subscribe {
Ok(())
}
}

#[cfg(test)]
mod tests {
use super::*;

/// A datagram the socket refuses is counted and dropped, and the export sends on.
#[test]
fn an_rtp_datagram_the_socket_refuses_is_counted_not_fatal() {
let socket = rtp_socket((std::net::Ipv4Addr::LOCALHOST, 9).into()).unwrap();
let mut unsent = Unsent::default();
// Longer than any UDP datagram over IPv4 can be.
unsent.send(&socket, &[0; 70_000]);
unsent.send(&socket, &[0; 1_328]);
assert_eq!(unsent.count, 1);
unsent.report();
assert_eq!((unsent.count, unsent.last.is_none()), (0, true));
}
}
Loading