Struct Consumer 

pub struct Consumer<F: Container> { /* private fields */ }

Decode a moq-lite track into a stream of media Frames in latency-bounded presentation order.

Consumer wraps a moq_net::track::Subscriber and a Container format implementation, typically catalog::hang::Container. Yields decoded frames via read.

Ordering & latency skipping

Groups can arrive on the wire out of order. The consumer always reads frames within a group in arrival order, but across groups it advances by sequence number, skipping stalled or missing groups when the difference between the oldest pending timestamp and the newest available timestamp exceeds the configured latency. With the default latency of zero, the consumer skips aggressively. Any group that has a newer alternative is dropped. With a non-zero latency, slow groups are tolerated up to that budget before being skipped.

A stalled group is also skipped early, regardless of the latency budget, once it has presented up to where the next group begins. CMAF frames carry a per-sample duration, so a group whose most recent frame ends (timestamp + duration) at or past the next group’s first timestamp has nothing left worth waiting for. Containers without a duration report zero, which disables this check and falls back to the latency budget.

Set the latency with with_latency (builder) or set_latency (mid-stream).

Timeline rewinds

If a newer group’s timestamps jump backwards past the live edge, the publisher is reneging the buffered tail (e.g. a voice agent interrupted mid-utterance). The consumer drops the reneged groups, resumes at the rewound timeline, and bumps discontinuity so downstream consumers can flush their own buffers. This is always on.

Implementations

impl<F: Container> Consumer<F>

pub fn new(track: Subscriber, format: F) -> Self

Create a Consumer wrapping the given moq-lite consumer, decoding format.

Skips aggressively by default; raise the tolerance with with_latency.

pub fn with_latency(self, latency: Duration) -> Self

Set the maximum latency tolerance.

Groups with timestamps older than the newest timestamp minus this value are skipped. Zero (the default) skips aggressively: any group with a newer alternative is dropped.

pub fn discontinuity(&self) -> u64

A counter that increments each time the consumer detects a timeline rewind and drops the reneged buffer.

When a newer group’s timestamps jump backwards past the live edge, the publisher is reneging everything buffered after that point (e.g. a voice agent interrupted mid-utterance). Downstream consumers should compare this across reads and, when it changes, flush any media still queued in their decoder or render buffers. The frame returned by the read that bumps it is the first of the new timeline.

pub async fn read(&mut self) -> Result<Option<Frame>, F::Error>

Read the next frame from the track.

This method handles timestamp decoding, group ordering, and latency management automatically. It will skip groups that are too far behind to maintain the configured latency target.

Returns None when the track has ended.

pub fn poll_read( &mut self, waiter: &Waiter, ) -> Poll<Result<Option<Frame>, F::Error>>

Poll-based implementation of the read loop.

Uses a single waiter that gets registered on all relevant kio channels, avoiding the need for tokio::select! or FuturesUnordered.

pub fn set_latency(&mut self, latency: Duration)

Set the maximum latency tolerance.