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
5 changes: 3 additions & 2 deletions doc/bin/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -557,8 +557,9 @@ of `--follow`.

`import --report` names a track in the catalog's `stats` section and reports
what each rendition has written, about once a second while someone subscribes,
with the connection's RTT, estimated send rate, and loss. It covers the stdin imports;
capture, the gateways, `archive`, and `ts --program all` refuse it.
with the connection's RTT, estimated send rate, and loss. It covers the stdin imports
and `capture`, whose renditions also report the encoder's target bitrate and the
video frames it fell behind on; the gateways, `archive`, and `ts --program all` refuse it.

`import --echo-path <path>` solicits feedback from the same imports: it sets
the catalog's `echo` path, resolved against the broadcast like a relative URL,
Expand Down
5 changes: 3 additions & 2 deletions doc/concept/stats.md
Original file line number Diff line number Diff line change
Expand Up @@ -146,8 +146,9 @@ A viewer's loss counters describe its own uplink, so they are reported but not
graded. Loss and headroom divide the connection's transport counters by the
report's own media, so they hold when the broadcast is the only one its
connection publishes. The transport limits were measured on one paced TS feed
through a shaped link over five-second intervals; no CLI reporter emits
`skipped`, `late`, `errors`, or `stalled`, so their limits are not measured.
through a shaped link over five-second intervals. Only `import capture`
emits `skipped`, and no CLI reporter emits `late`, `errors`, or `stalled`, so
those limits are not measured.

A publisher whose link falls below its media rate sends no report at all,
since its report track sits below every media track. Its health goes stale
Expand Down
4 changes: 2 additions & 2 deletions quest/m2/stats/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -111,8 +111,8 @@ connection view and the dashboard flow.

## Required

- [Rust reporters](/quest/m2/stats/rust.md) - the player, encoders, and
gateways publish stats and feedback, as the CLI remuxes do
- [Rust reporters](/quest/m2/stats/rust.md) - the player and gateways
publish stats and feedback, as the CLI remuxes and capture do
- [Browser reporters](/quest/m2/stats/js.md) - `<moq-publish>` publishes
stats and `<moq-watch>` publishes feedback
- [Preflight](/quest/m2/stats/preflight.md) - a bounded test run over a
Expand Down
57 changes: 34 additions & 23 deletions quest/m2/stats/rust.md
Original file line number Diff line number Diff line change
@@ -1,49 +1,60 @@
# [M] The Rust player, encoders, and gateways report stats and feedback
# [M] The Rust player and gateways report stats and feedback

## Goal

- `moq import capture --report` announces a stats track in the catalog and
fills it with what its encoders send, `skipped` and `bitrate` included.
- `moq play`, given `--echo <name>`, publishes an `.echo` broadcast under each
watched catalog's echo path and fills its feedback track with what it
received, decoded, and played.
- The gateway imports (`hls`, `rtmp`, `srt`, `rtsp`, `rtc`) and `archive` take
`--report`.
- Capture, the gateways, and `archive` take `--echo-path`, which sets the
catalog's `echo` section as it does for the stdin imports.
`--report` and `--echo-path`, which set the catalog's `stats` and `echo`
sections as they do for the stdin imports and capture.
- `import capture --report` counts the audio frames a microphone capture
dropped in `skipped`, as it already does for video.

## Plan

- `moq import --report` for the stdin imports, `moq export --echo`, and the
`export report` and `export echo` sinks already report what the `moq-mux`
importers write and exporters read (`rs/moq-mux/src/stats.rs`,
`rs/moq-cli/src/report.rs`), and `import --echo-path` solicits feedback for
the stdin imports. This quest adds the counters they lack and reuses the
rest; `import --report` and `--echo-path` refuse capture and the gateways
until it lands.
- `import --report` and `--echo-path` already cover the stdin imports and
capture, and `export --echo` and the `export report` and `export echo` sinks
already read and print the reports (`rs/moq-mux/src/stats.rs`,
`rs/moq-cli/src/report.rs`). The catalog's `Sent` registry counts what every
track minted under it writes, and an encoder reports its skips and target
through `container::Producer::report_skipped` and `report_bitrate`. This quest
adds the counters still missing and reuses the rest; `--report` and
`--echo-path` refuse the gateways until it lands.
- Counters come from the source, per track, as cumulative `stats()`
snapshots: no callback, no per-frame lock.
- Publisher: the `moq-video` and `moq-audio` encode producers create their
tracks directly on the broadcast, so they count frames, bytes, keyframes,
and drops themselves, and expose the target bitrate.
- Viewer: the decode and render paths count received, decoded, late,
stalled, underruns, and errors. `underruns` in
`rs/moq-audio/src/playback` is already counted privately.
- The gateways build their catalogs in their own crates, so each needs a way
to name the stats track and the echo path before its first catalog.
Capture publishes its catalog as its encoders start, so both sections reach
it before they do.
`rs/moq-audio/src/playback` is already counted privately. The player reads
video through `moq_mux::container::Consumer` directly, so it bypasses the
`Source`'s `Received` registry today.
- Audio capture: `capture::Samples::gap` only flags that buffers were
dropped. Counting `skipped` needs the drop size, converted to codec frames.
- The gateways build their catalogs in their own crates (`moq-rtmp`,
`moq-srt`, `moq-rtc`, `moq-archive`; `hls` and `rtsp` build theirs in
`rs/moq-cli`), so each needs a way to name the stats track and the echo path
before its first catalog, and a reporter to run beside each session's
catalog. The report writer lives in `rs/moq-cli/src/report.rs` and reads the
transport from a `moq_tokio` connection monitor, which the gateway crates do
not see.
- Decided 2026-10-31 (maintainer): move the report writer into `moq-mux`, with
the transport passed in as data rather than read from a `moq_tokio` monitor,
and give each gateway builder `with_report` and `with_echo`. A library user
embedding a gateway gets reports too; the cost, accepted, is that `Stats`
becomes a library API. Rejected: handing each session's catalog back to the
CLI through a returned handle, which keeps the writer in `moq-cli` but leaves
library users without reports.
- `moq play --echo` reconciles each watched catalog's `echo` section as
`export --echo` does, and refuses `--catalog-format msf` the same way: the
MSF catalog does not carry an `echo` solicitation.
MSF catalog does not carry an `echo` solicitation. `play` attaches only the
consume direction today, so it also needs the publish direction.
- The media test captures with `--report` and plays with `--echo` against a
publisher that solicits feedback. It asserts the encoder's frame count and
that the player's newest arrival advances.
- Decided 2026-10-08: no E2EE refusal here. The CLI has no encrypted
broadcast yet, so [Encrypted native CLI](/quest/m2/e2ee/cli.md) refuses `--report` and
`--echo` when it adds one: they would publish rendition IDs and per-track
counters in plaintext beside it.

- Decided 2026-10-22 (maintainer): the publisher's solicit option moved here
from [encoder feedback](/quest/m3/stats-encoder-feedback.md), which keeps
only the adaptation loop and reuses `--echo-path`.
Expand Down
26 changes: 25 additions & 1 deletion rs/moq-audio/src/encode/producer.rs
Original file line number Diff line number Diff line change
Expand Up @@ -194,6 +194,8 @@ impl Reserved {
/// Spend the reservation on a registered encoder, publishing through the track.
pub(crate) fn encode(self, registered: Registered) -> Producer {
let retention = self.track.track().info().max_age.unwrap_or(hang::container::MAX_AGE);
let bitrate = registered.encoder.bitrate();
self.track.report_bitrate(bitrate);

Producer {
backlog: Backlog::new(
Expand All @@ -203,7 +205,7 @@ impl Reserved {
),
active: true,
reset_pending: false,
bitrate: registered.encoder.bitrate(),
bitrate,
encoder: Some(registered.encoder),
input: registered.input,
remix: registered.remix,
Expand Down Expand Up @@ -319,6 +321,7 @@ impl Producer {
return Err(err.into());
}
self.bitrate = encoder.bitrate();
self.track.report_bitrate(self.bitrate);
Ok(())
}

Expand Down Expand Up @@ -680,6 +683,27 @@ mod tests {
}
}

/// The catalog's stats follow the encoder's target from the first rendition on.
#[tokio::test]
async fn stats_follow_the_target_bitrate() {
let mut broadcast = moq_net::broadcast::Info::new().produce();
let catalog = moq_mux::catalog::Producer::new(&mut broadcast, moq_mux::catalog::Config::default()).unwrap();
let options = Options {
track: Some("audio".into()),
..Options::default()
};
let mut producer = Producer::new(&mut broadcast, catalog.clone(), Input::default(), &options).unwrap();
let reported = || catalog.stats().remove("audio").and_then(|stats| stats.bitrate);
assert_eq!(reported(), Some(producer.bitrate().as_bps()));

let initial = producer.bitrate();
producer
.set_bitrate(moq_net::bandwidth::Rate::from_bps(initial.as_bps() / 2))
.unwrap();
assert_ne!(producer.bitrate(), initial);
assert_eq!(reported(), Some(producer.bitrate().as_bps()));
}

#[tokio::test]
#[ignore = "measures real codec CPU; run with just rs bench-playback"]
async fn benchmark_raw_audio() {
Expand Down
24 changes: 9 additions & 15 deletions rs/moq-cli/src/args.rs
Original file line number Diff line number Diff line change
Expand Up @@ -333,7 +333,7 @@ impl Invocation {
}
if let Command::Import(import) = command
&& import.report
&& let Some(reason) = import.source.report_refusal()
&& let Some(reason) = import.source.catalog_refusal()
{
anyhow::bail!("--report names a track in the catalog the import builds, but {reason}");
}
Expand Down Expand Up @@ -826,13 +826,14 @@ pub struct Import {
latency_max: Option<moq_tokio::cli::Duration>,

/// Name a media report track in the catalog's `stats` section and fill it with what each
/// track has written, about once a second while subscribed. The stdin imports only.
/// track has written, about once a second while subscribed. The stdin imports and capture
/// only.
#[usage(long)]
pub report: bool,

/// Solicit viewer feedback in the catalog: `export --echo <NAME>` publishes `<NAME>.echo`
/// under this prefix, resolved against the broadcast like a relative URL (`viewers` from
/// `room/event` is `room/viewers`). The stdin imports only.
/// `room/event` is `room/viewers`). The stdin imports and capture only.
#[usage(long, value_name = "PATH")]
pub echo_path: Option<String>,

Expand Down Expand Up @@ -908,7 +909,8 @@ impl ImportSource {
}

/// Why the CLI can't add a section to this source's first catalog, or `None` when it can:
/// a stdin import's one catalog waits for its importer's tracks.
/// a stdin import's one catalog waits for its importer's tracks, and a capture's for its
/// encoders.
fn catalog_refusal(&self) -> Option<&'static str> {
match self {
Self::Ts(args) if args.program == Some(TsProgram::All) => {
Expand All @@ -918,21 +920,11 @@ impl ImportSource {
Some("the gateway and archive imports build their own catalogs")
}
#[cfg(feature = "capture")]
Self::Capture(_) => Some("`import capture` publishes its catalog as its encoders start"),
Self::Capture(_) => None,
Self::Avc3 | Self::Fmp4(_) | Self::Ts(_) | Self::Flv => None,
}
}

/// Why `--report` can't report this source, or `None` when it can: the CLI builds the one
/// catalog of a stdin import, whose tracks `moq-mux` counts.
fn report_refusal(&self) -> Option<&'static str> {
#[cfg(feature = "capture")]
if matches!(self, Self::Capture(_)) {
return Some("`import capture` encodes, and its encoders do not count yet");
}
self.catalog_refusal()
}

/// 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> {
Expand Down Expand Up @@ -1846,6 +1838,8 @@ mod tests {
] {
import(flags, source).validate().unwrap();
}
#[cfg(feature = "capture")]
import(flags, &["capture"]).validate().unwrap();
for source in [
["ts", "--program", "all"].as_slice(),
&["hls", "http://origin/master.m3u8"],
Expand Down
45 changes: 36 additions & 9 deletions rs/moq-cli/src/publish.rs
Original file line number Diff line number Diff line change
Expand Up @@ -332,6 +332,9 @@ enum Source {
catalog: moq_mux::catalog::Producer,
video: Option<moq_video::encode::Capture>,
audio: Option<moq_audio::encode::Capture>,
/// Withholds the catalog until [`Publish::run`] starts the encoders, so the `stats` and
/// `echo` sections set before then ride the first catalog rather than an empty one.
gate: moq_mux::catalog::Reserved,
},
}

Expand Down Expand Up @@ -554,6 +557,7 @@ impl Publish {
Ok(Self {
source: Source::Capture {
broadcast: broadcast.clone(),
gate: catalog.reserve(),
catalog,
video,
audio,
Expand All @@ -573,16 +577,20 @@ impl Publish {
///
/// Call it before the importer declares its tracks, so the section rides the first catalog.
pub fn with_report(mut self, connection: Option<moq_tokio::connection::Monitor>) -> anyhow::Result<Self> {
let (Some(broadcast), Source::Stream { catalog, .. }) = (self.broadcast.as_mut(), &self.source) else {
anyhow::bail!("--report reports a stdin import's one catalog");
let Some(broadcast) = self.broadcast.as_mut() else {
anyhow::bail!("`import ts --program all` builds a catalog per program");
};
if let Some(republish) = &mut self.republish {
republish.report = Some(connection.clone());
}
let report = match catalog {
PublishCatalog::Media(catalog) => crate::report::Stats::new(broadcast, catalog, connection)?,
PublishCatalog::Ts(catalog) => crate::report::Stats::new(broadcast, catalog, connection)?,
PublishCatalog::TsPrograms => anyhow::bail!("`import ts --program all` builds a catalog per program"),
let report = match &self.source {
Source::Stream { catalog, .. } => match catalog {
PublishCatalog::Media(catalog) => crate::report::Stats::new(broadcast, catalog, connection)?,
PublishCatalog::Ts(catalog) => crate::report::Stats::new(broadcast, catalog, connection)?,
PublishCatalog::TsPrograms => anyhow::bail!("`import ts --program all` builds a catalog per program"),
},
#[cfg(feature = "capture")]
Source::Capture { catalog, .. } => crate::report::Stats::new(broadcast, catalog, connection)?,
};
self.report = Some(report);
Ok(self)
Expand All @@ -595,7 +603,10 @@ impl Publish {
let catalog = match &mut self.source {
Source::Stream { catalog, .. } => catalog,
#[cfg(feature = "capture")]
Source::Capture { .. } => anyhow::bail!("--echo-path solicits feedback in a stdin import's one catalog"),
Source::Capture { catalog, .. } => {
catalog.mutate(|catalog| catalog.echo = Some(echo))?;
return Ok(self);
}
};
if let Some(republish) = &mut self.republish {
republish.echo = Some(echo.clone());
Expand Down Expand Up @@ -654,7 +665,10 @@ impl Publish {
catalog,
video,
audio,
gate,
} => {
drop(gate);
let mut report = self.report;
// Each enabled medium publishes its own track onto the shared
// broadcast + catalog. Both stamp frames on the catalog's
// advertised clock, so HLS/DASH wall times match the mapping on
Expand Down Expand Up @@ -683,8 +697,21 @@ impl Publish {
}
};

tokio::try_join!(video_fut, audio_fut)?;
Ok(())
let capture = async { tokio::try_join!(video_fut, audio_fut).map(|_| ()) };
// Written beside the encoders, so a capture waiting on its first viewer still reports.
let result = match report.as_mut() {
Some(report) => tokio::select! {
result = capture => result,
never = report.run() => match never {},
},
None => capture.await,
};
match (&result, report) {
(Ok(()), Some(mut report)) => report.finish(),
(Err(err), Some(report)) => report.abort(moq_net::Error::Transport(err.to_string())),
(_, None) => {}
}
result
}
}
}
Expand Down
12 changes: 12 additions & 0 deletions rs/moq-mux/src/codec/h264/import.rs
Original file line number Diff line number Diff line change
Expand Up @@ -173,6 +173,18 @@ impl Import {
Ok(())
}

/// Report frames the encoder feeding this track skipped. See
/// [`Producer::report_skipped`](crate::container::Producer::report_skipped).
pub fn report_skipped(&self, frames: u64) {
self.track.report_skipped(frames);
}

/// Report the target bitrate of the encoder feeding this track. See
/// [`Producer::report_bitrate`](crate::container::Producer::report_bitrate).
pub fn report_bitrate(&self, bitrate: moq_net::bandwidth::Rate) {
self.track.report_bitrate(bitrate);
}

/// Close the current group and open the next one at `sequence`.
pub fn seek(&mut self, sequence: u64) -> Result<()> {
self.track.seek(sequence)?;
Expand Down
12 changes: 12 additions & 0 deletions rs/moq-mux/src/codec/h265/import.rs
Original file line number Diff line number Diff line change
Expand Up @@ -176,6 +176,18 @@ impl Import {
Ok(())
}

/// Report frames the encoder feeding this track skipped. See
/// [`Producer::report_skipped`](crate::container::Producer::report_skipped).
pub fn report_skipped(&self, frames: u64) {
self.track.report_skipped(frames);
}

/// Report the target bitrate of the encoder feeding this track. See
/// [`Producer::report_bitrate`](crate::container::Producer::report_bitrate).
pub fn report_bitrate(&self, bitrate: moq_net::bandwidth::Rate) {
self.track.report_bitrate(bitrate);
}

/// Close the current group and open the next one at `sequence`.
pub fn seek(&mut self, sequence: u64) -> Result<()> {
self.track.seek(sequence)?;
Expand Down
16 changes: 16 additions & 0 deletions rs/moq-mux/src/container/producer.rs
Original file line number Diff line number Diff line change
Expand Up @@ -545,6 +545,22 @@ where
self
}

/// Report `frames` frames the source produced but never handed to this track, such as ones an
/// encoder fell behind on, in its catalog's [`stats`](crate::catalog::Producer::stats).
pub fn report_skipped(&self, frames: u64) {
if let Some(sent) = &self.sent {
sent.skip(frames);
}
}

/// Report the encoder's latest target bitrate in its catalog's
/// [`stats`](crate::catalog::Producer::stats). The catalog's `bitrate` stays the maximum.
pub fn report_bitrate(&self, bitrate: moq_net::bandwidth::Rate) {
if let Some(sent) = &self.sent {
sent.target(bitrate);
}
}

/// Count a written frame. Only video keyframes count as keyframes: elsewhere the bit only
/// marks where a group starts.
fn count(&self, bytes: usize, keyframe: bool) {
Expand Down
Loading
Loading