diff --git a/doc/lib/rs/hang.md b/doc/lib/rs/hang.md index d56435f89b7..1350f66a161 100644 --- a/doc/lib/rs/hang.md +++ b/doc/lib/rs/hang.md @@ -27,7 +27,9 @@ the live edge to play: it skips groups that fall past `max`, and starts at the group covering the live edge less `min` (your playout delay), plus a rendition's catalog `warmup` passed to `with_warmup`, waiting up to that long for it when the newest group arrives first. Both default to zero, which starts at the newest -group at once; `max` never moves the start. +group at once. A backlog that landed before the first read starts within `max` +of the newest content, keeping the group covering the live edge less `min` and +the warmup. [`moq-video`](/lib/rs/moq-video) and [`moq-audio`](/lib/rs/moq-audio) publish from a device. Examples: [`video.rs`](https://github.com/moq-dev/moq/blob/main/rs/hang/examples/video.rs) diff --git a/js/hang/MIGRATE.md b/js/hang/MIGRATE.md index ba441db6466..c54c268de42 100644 --- a/js/hang/MIGRATE.md +++ b/js/hang/MIGRATE.md @@ -8,7 +8,7 @@ How to update your code for each breaking change, newest first. `ConsumerProps.maxDelay` is `delay: GetterInit`, where `Delay` is `{ min?: Milli; max?: Milli | null }` and an omitted field is zero. Replace `maxDelay: d` with `delay: { max: d }`, or derive it from a signal. `max: null` is no limit. -`min` is the playout delay: the consumer starts at the group covering the live edge less `min` plus any `warmup`, waiting for it when the newest group arrives first. `max` never moves the start. +`min` is the playout delay: the consumer starts at the group covering the live edge less `min` plus any `warmup`, waiting for it when the newest group arrives first. Before the first read, a backlog that already landed starts at the first group whose first frame is within `max`, plus the warmup, of the newest content, keeping the group covering the live edge less `min` and the warmup. ### The catalog rendition cap is removed diff --git a/js/hang/src/container/consumer.skips.test.ts b/js/hang/src/container/consumer.skips.test.ts index 33a29afae63..a7316087d1b 100644 --- a/js/hang/src/container/consumer.skips.test.ts +++ b/js/hang/src/container/consumer.skips.test.ts @@ -50,3 +50,92 @@ for (const count of [1, 16, 256]) { } }); } + +// Pairs `rs/moq-mux`'s `a_buffered_backlog_starts_within_the_budget`: a backlog that lands whole before +// the first read starts at the first group whose first frame is within the budget of the newest one. +// Five one-second groups of ten frames and a one-frame sixth at 5 s, with a 1.5 s budget, start at the +// 4 s group, whether the sixth is open or finished. +for (const open of [true, false]) { + test(`a buffered backlog starts within the budget (sixth group ${open ? "open" : "finished"})`, async () => { + const warn = spyOn(console, "warn").mockImplementation(() => {}); + const track = new Track.Producer("backlog"); + const consumer = new Consumer(track.subscribe({ maxDelay: Milli(30_000) }), { + format: new Format("data"), + delay: { max: Milli(1500) }, + }); + const frame = (micros: number) => ({ payload: Varint.encode(micros), timestamp: Time.Timestamp.now() }); + try { + for (let g = 0; g < 5; g++) { + const group = track.createGroup(g); + for (let f = 0; f < 10; f++) group.writeFrame(frame(g * 1_000_000 + f * 100_000)); + group.finish(); + } + const last = track.createGroup(5); + last.writeFrame(frame(5_000_000)); + if (!open) last.finish(); + while (consumer.buffered.peek().at(-1)?.end !== 5000) await consumer.buffered.changed(); + + const read: number[] = []; + for (let i = 0; i < 11; i++) { + const next = await consumer.next(); + if (next?.kind !== "frame") throw new Error(`unexpected read: ${JSON.stringify(next)}`); + read.push(next.frame.timestamp); + } + const expected = [...Array.from({ length: 10 }, (_, f) => 4_000_000 + f * 100_000), 5_000_000]; + expect(read).toEqual(expected); + } finally { + consumer.close(); + track.finish(); + track.close(); + warn.mockRestore(); + } + }); +} + +// The start waits on the next group's first frame, which may land within the budget, rather than +// dropping that group. Here the fifth group (4 s) arrived with its frames still in flight, so the start +// keeps the fourth and plays on into the fifth. Rust's +// `a_backlog_start_waits_on_a_successor_without_frames` pairs this case. +test("a backlog start waits on a successor without frames", async () => { + const warn = spyOn(console, "warn").mockImplementation(() => {}); + const track = new Track.Producer("backlog"); + const consumer = new Consumer(track.subscribe({ maxDelay: Milli(30_000) }), { + format: new Format("data"), + delay: { max: Milli(1500) }, + }); + const frame = (micros: number) => ({ payload: Varint.encode(micros), timestamp: Time.Timestamp.now() }); + const frames = (g: number) => Array.from({ length: 10 }, (_, f) => g * 1_000_000 + f * 100_000); + const read: number[] = []; + const readN = async (n: number) => { + for (let i = 0; i < n; i++) { + const next = await consumer.next(); + if (next?.kind !== "frame") throw new Error(`unexpected read: ${JSON.stringify(next)}`); + read.push(next.frame.timestamp); + } + }; + try { + for (let g = 0; g < 4; g++) { + const group = track.createGroup(g); + for (const micros of frames(g)) group.writeFrame(frame(micros)); + group.finish(); + } + const fifth = track.createGroup(4); + // The fifth group's frames left before the sixth's, though they land after it. + const sent = Time.Timestamp.now(); + const last = track.createGroup(5); + last.writeFrame(frame(5_000_000)); + last.finish(); + while (consumer.buffered.peek().at(-1)?.end !== 5000) await consumer.buffered.changed(); + + await readN(10); + for (const micros of frames(4)) fifth.writeFrame({ payload: Varint.encode(micros), timestamp: sent }); + fifth.finish(); + await readN(11); + expect(read).toEqual([...frames(3), ...frames(4), 5_000_000]); + } finally { + consumer.close(); + track.finish(); + track.close(); + warn.mockRestore(); + } +}); diff --git a/js/hang/src/container/consumer.ts b/js/hang/src/container/consumer.ts index d89bfae392d..2836e9c254a 100644 --- a/js/hang/src/container/consumer.ts +++ b/js/hang/src/container/consumer.ts @@ -23,7 +23,9 @@ export interface Delay { * late group is waited for. A missing sequence also expires this much monotonic time after * the first group past it arrived, even when the next group is a marker on a paused track. * The local half of the subscription's `maxDelay`; both measure the same budget, one on the wire - * and one as frames are read. It bounds lateness only: it never moves the start. + * and one as frames are read. It bounds a join's lateness too: a backlog that landed before the + * first read starts at the first group whose first frame is within it, plus any warmup, of the + * newest content, though the start keeps the group covering the live edge less `min` and the warmup. */ max?: Milli | null; } @@ -511,11 +513,21 @@ export class Consumer { const age = max - min; if (age <= threshold) break; - // Until the reader warms, a group may cover the start's reach though it began before it: it is - // stale only once its successor starts a whole budget behind the newest content. + // Until the reader warms, a group may cover the start's reach though it began before it. if (this.#warming()) { const nextStart = this.#groups[1].start; - if (nextStart === undefined || max - nextStart < threshold) break; + if (nextStart === undefined) break; + if (this.#edge === undefined) { + // Before the first item, a backlog that landed whole starts within the budget, so only + // the group covering the live edge less the reach is kept: one whose successor starts + // past that point. Rust's start skip, in `Consumer::poll_event_once`, measures the same. + const target = this.#startTarget(this.#reach(this.#delay.peek())); + if (target !== undefined && nextStart > target) break; + } else if (max - nextStart < threshold) { + // Once reading began, it is stale only once its successor starts a whole budget behind + // the newest content. + break; + } } this.#groups.shift(); diff --git a/quest/m1/cut-audit/README.md b/quest/m1/cut-audit/README.md index 7b71567913c..c944b27ed38 100644 --- a/quest/m1/cut-audit/README.md +++ b/quest/m1/cut-audit/README.md @@ -54,7 +54,6 @@ leaving JS-only redesigns of `js/net` to [rs2ts](/quest/m2/rs2ts-js.md). ## Required -- [Rust and JS skip a backlog by the same measure](/quest/m1/cut-audit/catalog-parity.md) - a backlog join starts at the same group in every player - [Text and data sections keep a prototype-named ID](/quest/m1/cut-audit/catalog-proto-ids.md) - text and data entries keep the ID JS's `z.record` drops ## Related diff --git a/quest/m1/cut-audit/catalog-parity.md b/quest/m1/cut-audit/catalog-parity.md deleted file mode 100644 index d78e3a4ea54..00000000000 --- a/quest/m1/cut-audit/catalog-parity.md +++ /dev/null @@ -1,34 +0,0 @@ -# [S] Rust and JS skip a backlog by the same measure - -## Goal - -A player joining a backlog starts at the same group in moq-cli, moqsrc, and -the browser. If they start at different groups, align the two container -consumers' skip measurements, with a test in each. - -## Plan - -Found by the 2026-10-24 pre-cut audit at 151a529670. The catalog half of -this quest (Rust and JS accept the same catalogs) landed separately in -[moq-dev/moq#7035](https://github.com/moq-dev/moq/pull/7035): any malformed -rendition refuses the whole catalog in both languages (maintainer, -2026-10-30). - -Rust measures newest content minus the next group's start -(`rs/moq-mux/src/container/consumer.rs`, the `should_skip` check in the -blocking-group path). JS measures from the oldest unread frame -(`js/hang/src/container/consumer.ts`, `#checkMaxDelay`). The Rust comment -argues for its measure: a group's own first frame is no bound, since a group -longer than the budget would be cut short whenever it blocks behind a newer -one, as a join's backlog does. - -They diverge, reproduced by a throwaway probe in each consumer: five -finished one-second groups of ten frames plus a one-frame sixth group, all -landing before the first read, with a 1500 ms budget. JS starts at the 4.0 s -group, while Rust starts at 0 and plays the whole backlog, whether the sixth -group is open or finished. Rust's skip only runs while the current group -blocks, so a fully buffered backlog never triggers it. - -Decide which start is right (likely JS's, which keeps the join within the -budget), align the other consumer, and keep the scenario as a paired test in -both. diff --git a/rs/moq-mux/CHANGELOG.md b/rs/moq-mux/CHANGELOG.md index a850cefe1a5..b2e93a15cb5 100644 --- a/rs/moq-mux/CHANGELOG.md +++ b/rs/moq-mux/CHANGELOG.md @@ -19,6 +19,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed +- `container::Consumer` no longer plays a backlog that landed before its first read from the oldest group: until the first item, the start moves past each group whose first frame trails the newest content by more than the max delay plus the warmup, as `@moq/hang`'s consumer does, keeping the group covering the live edge less `Delay::min` and the warmup. A join starts at the same group in Rust and the browser. Once reading begins, only a blocking group is skipped, as before. - fMP4 import applies each track's edit list to its frame timestamps and drops the samples before the edit, such as AAC priming, along with the video samples decoding from a dropped sync sample, and a passthrough init no longer carries the `edts`. A consumer that offsets AAC priming itself must stop, or it shifts the track twice. An edit list it can't reduce to one shift (several media edits, or a rate other than 1) is refused with `Error::UnsupportedEditList`. ## [0.10.11](https://github.com/moq-dev/moq/compare/moq-mux-v0.10.10...moq-mux-v0.10.11) - 2026-10-05 diff --git a/rs/moq-mux/MIGRATE.md b/rs/moq-mux/MIGRATE.md index 9abb9fd4679..92d25498a72 100644 --- a/rs/moq-mux/MIGRATE.md +++ b/rs/moq-mux/MIGRATE.md @@ -8,7 +8,7 @@ How to update your code for each breaking change, newest first. `container::Consumer::set_max_delay(Duration)` is `set_delay(Delay)`, and `with_delay(Delay)` is its builder. `container::Delay { min, max }` defaults to zero for both: `max` (`None` for no limit) is the max delay that `set_max_delay` took, and the subscription still carries it. -`min` is the playout delay. An unfloored consumer starts at the group covering the live edge less `min` plus any `with_warmup`, waiting for it when the newest group arrives first; the max delay never moves the start. +`min` is the playout delay. An unfloored consumer starts at the group covering the live edge less `min` plus any `with_warmup`, waiting for it when the newest group arrives first. Before the first read, a backlog that already landed starts at the first group whose first frame is within the max delay, plus the warmup, of the newest content, keeping the group covering the live edge less `min` and the warmup. Replace `consumer.set_max_delay(d)` with `consumer.set_delay(Delay { max: Some(d), ..Delay::default() })`, and set `min` to your playout delay. Call `with_warmup` before `with_delay`. ### Compression moves to the track diff --git a/rs/moq-mux/src/container/consumer.rs b/rs/moq-mux/src/container/consumer.rs index 2481abd1063..13a04065fa5 100644 --- a/rs/moq-mux/src/container/consumer.rs +++ b/rs/moq-mux/src/container/consumer.rs @@ -75,7 +75,11 @@ pub(crate) enum Item { /// [`Subscription::ranges`](moq_net::track::Subscription::ranges) when every range names one, waiting for that group under the budget; without one it /// starts at the lowest group that arrived, waiting for one covering the live edge less /// [`Delay::min`] plus any [`with_warmup`](Self::with_warmup). Both default to zero, so it waits -/// for nothing. The max delay never moves the start. From there +/// for nothing. Until the first item, the start also moves past each group whose first frame +/// trails the newest content by more than the max delay plus the warmup, as `@moq/hang`'s +/// consumer measures, unless that group covers the live edge less the min delay and the warmup: +/// a backlog that landed whole would otherwise play from its oldest group, since nothing +/// blocks, and stay that far behind. From there /// the same budget is the one rule that catches the consumer up to the live edge, and /// history the publisher no longer serves expires like any other gap, since its reach /// sits a full budget behind the newest content. @@ -220,8 +224,10 @@ pub struct Delay { pub min: std::time::Duration, /// How far a group may fall behind the live edge before it is skipped, or `None` for no limit. /// - /// The subscription carries it as [`moq_net::track::Subscription::max_delay`]. It bounds - /// lateness only: it never moves the start. + /// The subscription carries it as [`moq_net::track::Subscription::max_delay`]. It bounds a + /// join's lateness too: a backlog that landed before the first read starts at the first group + /// whose first frame is within it, plus any warmup, of the newest content, though the start + /// keeps the group covering the live edge less [`min`](Self::min) and the warmup. pub max: Option, } @@ -562,6 +568,15 @@ impl Consumer { self.hole_timer = None; } + // Until the first item, a backlog that landed whole starts within the budget: nothing + // blocks, so the skip below would play it from its oldest group and stay that far behind + // for good. The start moves past each group whose first frame trails the newest content + // by more than the budget, as `@moq/hang`'s consumer measures, unless that group covers + // the live edge less the reach (see `with_warmup`), which the start promises. + if self.edge.is_none() && self.start_skip(waiter)? { + continue; + } + // Return the next frame from the current group if possible. // If the current group is finished or errored, advance to the next group. if let Some(group) = self.pending.front_mut() @@ -681,31 +696,10 @@ impl Consumer { None }; - // Find the first newer group with data (our skip target) and where it starts. - let mut next_group = None; - for (i, group) in self.pending.iter_mut().enumerate() { - if group.sequence <= self.current { - continue; - } - - if let Poll::Ready(Some(ts)) = group.poll_min_timestamp(waiter, &self.format, false) { - next_group = Some((i, std::time::Duration::from(ts))); - break; - } - } - - // Find the max timestamp across all newer groups. - let mut max_timestamp = std::time::Duration::ZERO; - for group in self.pending.iter_mut().rev() { - if group.sequence <= self.current { - break; - } - - if let Poll::Ready(Some(ts)) = group.poll_max_timestamp(waiter, &self.format) { - max_timestamp = max_timestamp.max(ts.into()); - break; // We know older groups won't be newer than this. - } - } + // The first newer group with data (our skip target) and where it starts, and the newest + // content past the cursor. + let next_group = self.poll_next_group(waiter); + let max_timestamp = self.poll_newest(waiter); // Walk the cursor over missing sequences below the first arrived group. // Groups race on independent QUIC streams (newer ones at higher priority), @@ -762,9 +756,9 @@ impl Consumer { // The current group is blocking. Everything it could still present ends // where the next group begins, so skip once that reach falls a full budget // behind the newest content, the same measure as a missing group. Its own - // first frame is no bound: a group longer than the budget would be cut - // short whenever it blocks behind a newer one, as a join's backlog does - // while the newer groups race ahead on their own streams. Skip early too + // first frame is no bound once reading began: a group longer than the budget + // would be cut short whenever it blocks behind a newer one racing ahead on its + // own stream. Only the start, above, measures the first frame. Skip early too // once it has presented up to where the next group begins (duration // coverage), since nothing is left worth waiting for. // While the reader warms, the start reached the warmup further back than the max delay. @@ -789,26 +783,7 @@ impl Consumer { }; if let Some((new_idx, next_start)) = target { - // Without a start read yet, nothing proves the timeline continues. - let hole = next_start.is_none_or(|start| !pts_contiguous(current_end.or(self.presented_end), start)); - let had_marker = self.pending.iter().take(new_idx).any(GroupBuffer::marker); - // Buffered frames are thrown away, and `current_end` counts them, so contiguity alone would hide them. - let discarded = self - .pending - .iter() - .take(new_idx) - .any(|group| !group.buffered.is_empty()); - let target = self.pending[new_idx].sequence; - self.discard(|group| group.sequence < target)?; - if hole || had_marker || discarded { - self.lose(); - } - let new_current = self.pending.front().map(|g| g.sequence).unwrap(); - - tracing::debug!(old = self.current, new = new_current, "skipping slow groups"); - - self.current = new_current; - self.note_group_edge(); + self.skip_to(new_idx, next_start, current_end)?; continue; } @@ -825,6 +800,113 @@ impl Consumer { } } + // Before the first item, move the cursor past its group when that group's first frame trails the + // newest content by more than the budget and the next group still starts at or before the live + // edge less the reach, so it is not what the start covers, and repeat for the group it lands on. + // Returns whether it moved. + fn start_skip(&mut self, waiter: &kio::Waiter) -> Result { + // The newest content lies in the highest group with a timestamp, which a skip never drops, so + // one read serves every skip and a long backlog is walked once. + let mut newest = None; + let mut moved = false; + while let Some(group) = self.pending.front_mut() { + if group.sequence > self.current { + break; + } + let _ = group.poll_min_timestamp(waiter, &self.format, true); + let Some((frame, ..)) = group.buffered.front() else { + break; + }; + let first = std::time::Duration::from(frame.timestamp); + let current_end = group.max_end; + // The next group that arrived, even one whose first frame is still in flight: that frame + // may land within the budget, so skipping on to a later group could drop the one the start + // belongs on. Until it lands, nothing is skipped, as `@moq/hang`'s consumer waits on its + // successor's start. + let Some(idx) = self.pending.iter().position(|group| group.sequence > self.current) else { + break; + }; + let Poll::Ready(Some(next_start)) = self.pending[idx].poll_min_timestamp(waiter, &self.format, false) + else { + break; + }; + let next_start = std::time::Duration::from(next_start); + let newest = *newest.get_or_insert_with(|| self.poll_newest(waiter)); + // Nothing has been read, so the reader still warms. + if newest.saturating_sub(first) <= self.max_delay.saturating_add(self.warmup) { + break; + } + // The group the start reaches back to is kept: the next one begins past that point. + let reach = self.min_delay.min(self.max_delay).saturating_add(self.warmup); + if !reach.is_zero() && next_start > newest.saturating_sub(reach) { + break; + } + self.skip_to(idx, Some(next_start), current_end)?; + moved = true; + } + Ok(moved) + } + + // The first group past the cursor with a timestamp, the skip target, and where it starts. + fn poll_next_group(&mut self, waiter: &kio::Waiter) -> Option<(usize, std::time::Duration)> { + for (i, group) in self.pending.iter_mut().enumerate() { + if group.sequence <= self.current { + continue; + } + + if let Poll::Ready(Some(ts)) = group.poll_min_timestamp(waiter, &self.format, false) { + return Some((i, ts.into())); + } + } + None + } + + // The max timestamp across the groups past the cursor, or zero without one. + fn poll_newest(&mut self, waiter: &kio::Waiter) -> std::time::Duration { + for group in self.pending.iter_mut().rev() { + if group.sequence <= self.current { + break; + } + + // Older groups won't be newer than this. + if let Poll::Ready(Some(ts)) = group.poll_max_timestamp(waiter, &self.format) { + return ts.into(); + } + } + std::time::Duration::ZERO + } + + // Move the cursor to the pending group at `new_idx`, dropping what lies below it. `next_start` is + // where that group begins, if read, and `current_end` how far the group left behind presented. + fn skip_to( + &mut self, + new_idx: usize, + next_start: Option, + current_end: Option, + ) -> Result<(), F::Error> { + // Without a start read yet, nothing proves the timeline continues. + let hole = next_start.is_none_or(|start| !pts_contiguous(current_end.or(self.presented_end), start)); + let had_marker = self.pending.iter().take(new_idx).any(GroupBuffer::marker); + // Buffered frames are thrown away, and `current_end` counts them, so contiguity alone would hide them. + let discarded = self + .pending + .iter() + .take(new_idx) + .any(|group| !group.buffered.is_empty()); + // `pending` is in sequence order, so what lies below the target is its prefix. + self.discard_front(new_idx)?; + if hole || had_marker || discarded { + self.lose(); + } + let new_current = self.pending.front().map(|g| g.sequence).unwrap(); + + tracing::debug!(old = self.current, new = new_current, "skipping slow groups"); + + self.current = new_current; + self.note_group_edge(); + Ok(()) + } + // Where an unfloored start begins, the lowest group that arrived, or `None` while it waits for // one covering the reach (see `with_warmup`), registering the waiter on whatever would end the wait. fn reach_start(&mut self, waiter: &kio::Waiter, finished: bool) -> Option { @@ -1021,17 +1103,37 @@ impl Consumer { return true; } if fault.is_none() { - fault = match (start, group.min_timestamp) { - (Some((prev, floor)), Some(min)) - if group.sequence > prev && min.as_micros() < floor.as_micros() => - { - Some(TimestampRewind { timestamp: min, floor }.into()) - } - _ => group.fault.take(), - }; + fault = Self::discard_fault(start, group); } false }); + self.discarded(fault) + } + + // `discard` of the lowest `count` pending groups, in time proportional to them rather than to every + // pending group, so a start that skips a long backlog one group at a time stays linear. + fn discard_front(&mut self, count: usize) -> Result<(), F::Error> { + let start = self.start; + let mut fault = None; + for mut group in self.pending.drain(..count) { + if fault.is_none() { + fault = Self::discard_fault(start, &mut group); + } + } + self.discarded(fault) + } + + // The fault a discarded group would hide: its own, or frames below the latest delivered start. + fn discard_fault(start: Option<(u64, Timestamp)>, group: &mut GroupBuffer) -> Option { + match (start, group.min_timestamp) { + (Some((prev, floor)), Some(min)) if group.sequence > prev && min.as_micros() < floor.as_micros() => { + Some(TimestampRewind { timestamp: min, floor }.into()) + } + _ => group.fault.take(), + } + } + + fn discarded(&self, fault: Option) -> Result<(), F::Error> { match fault { Some(err) => { tracing::warn!(track = &*self.name, error = ?err, "discarded a malformed group; ending the reader"); @@ -1970,10 +2072,23 @@ mod tests { track.subscribe(moq_net::track::Subscription::default().with_max_delay(Duration::from_secs(10))); let mut reader = Consumer::new(subscription, Container::Legacy(crate::container::Kind::Audio)); reader.max_delay = Duration::ZERO; - write_group(&mut track, 0, &[ts(0)]); + // Group 0 stays open, and is read before the newer group lands: the skip comes after the start. + let mut group = track.create_group(moq_net::group::Info { sequence: 0 }).unwrap(); + Container::Legacy(crate::container::Kind::Audio) + .write( + &mut group, + &[Frame { + timestamp: ts(0), + payload: Bytes::from_static(&[0xDE, 0xAD]), + keyframe: false, + duration: None, + }], + ) + .unwrap(); + assert!(matches!(reader.read().await.unwrap(), Some(Read::Frame { .. }))); write_group(&mut track, 3, &[ts(1_000_000)]); track.finish().unwrap(); - assert_eq!(items(&mut reader).await, ["0", "gap 0+1000000", "1000000"]); + assert_eq!(items(&mut reader).await, ["gap 0+1000000", "1000000"]); } /// A video group's trailing duration marker is that frame's end, not a declared stop. @@ -2120,11 +2235,24 @@ mod tests { // Keep transport filtering out of this test so it isolates the mux skip logic. consumer.max_delay = Duration::ZERO; - write_group(&mut track, 0, &[ts(0)]); + // Group 0 stays open, and is read before the newer group lands: the skip comes after the start. + let mut group = track.create_group(moq_net::group::Info { sequence: 0 }).unwrap(); + Container::Legacy(crate::container::Kind::Audio) + .write( + &mut group, + &[Frame { + timestamp: ts(0), + payload: Bytes::from_static(&[0xDE, 0xAD]), + keyframe: false, + duration: None, + }], + ) + .unwrap(); + assert!(matches!(consumer.read().await.unwrap(), Some(Read::Frame { .. }))); write_group(&mut track, 3, &[ts(1_000_000)]); track.finish().unwrap(); - assert_eq!(items(&mut consumer).await, ["0", "gap 0+1000000", "1000000"]); + assert_eq!(items(&mut consumer).await, ["gap 0+1000000", "1000000"]); } #[tokio::test] @@ -2230,6 +2358,11 @@ mod tests { ) .unwrap(); + // Read group 0's frame before the later groups land, so they skip a stalled group rather + // than move the start. + let first = consumer.read_frame().await.unwrap().unwrap(); + assert_eq!(first.timestamp, ts(0)); + for g in 1..10u64 { let timestamps: Vec<_> = (0..3).map(|f| ts(g * 50_000 + f * 5_000)).collect(); write_group(&mut track, g, ×tamps); @@ -2242,7 +2375,7 @@ mod tests { }); let frames = read_all(&mut consumer).await.unwrap(); - assert_eq!(frames.len(), 28, "Expected group 0 frame + groups 1-9"); + assert_eq!(frames.len(), 27, "Expected groups 1-9 after group 0's frame"); assert!(!frames.is_empty(), "Expected at least some frames"); finisher.await.expect("finisher task panicked"); } @@ -2267,6 +2400,11 @@ mod tests { ) .unwrap(); + // Read group 0's frame before the later groups land, so they skip a stalled group rather + // than move the start. + let first = consumer.read_frame().await.unwrap().unwrap(); + assert_eq!(first.timestamp, ts(0)); + for g in 1..10u64 { write_group(&mut track, g, &[ts(g * 30_000)]); } @@ -2278,20 +2416,17 @@ mod tests { }); let frames = read_all(&mut consumer).await.unwrap(); - assert!(!frames.is_empty(), "Expected at least some frames"); - assert_eq!(frames.len(), 10, "Expected group 0 frame + groups 1-9"); - assert_eq!(frames[0].timestamp, ts(0)); - - for i in 1..10u64 { - assert_eq!(frames[i as usize].timestamp, ts(i * 30_000)); + assert_eq!(frames.len(), 9, "Expected groups 1-9 after group 0's frame"); + for (i, frame) in (1..10u64).zip(&frames) { + assert_eq!(frame.timestamp, ts(i * 30_000)); } finisher.await.expect("finisher task panicked"); } /// A group longer than the budget that blocks for a moment behind a newer group is /// not cut short while what it could still present (up to where the newer group - /// begins) is within the budget. A join's backlog does exactly this: the newer group - /// races ahead on its own stream while the older one is still arriving. + /// begins) is within the budget: the newer group races ahead on its own stream while + /// the older one is still arriving. #[test] fn a_long_group_blocked_behind_a_newer_one_is_not_cut_short() { let waiter = kio::Waiter::noop(); @@ -2317,15 +2452,17 @@ mod tests { } }; - // A 2.5 s group, half arrived, and the next one already 0.5 s in. + // A 2.5 s group, half arrived, and the next one already 0.5 s in. The reader started + // before the next one landed, so this is a stall, not a join's backlog, which starts + // within the budget instead (see `a_buffered_backlog_starts_within_the_budget`). let mut group0 = track.create_group(moq_net::group::Info { sequence: 0 }).unwrap(); write(&mut group0, ts(0)); write(&mut group0, ts(500_000)); + assert_eq!(read(&mut consumer), Some(ts(0))); let mut group1 = track.create_group(moq_net::group::Info { sequence: 1 }).unwrap(); write(&mut group1, ts(2_500_000)); write(&mut group1, ts(3_000_000)); - assert_eq!(read(&mut consumer), Some(ts(0))); assert_eq!(read(&mut consumer), Some(ts(500_000))); // Group 0's reach (2.5 s) is 0.5 s behind the newest frame: wait for it. assert_eq!(read(&mut consumer), None, "cut group 0 short"); @@ -2344,6 +2481,98 @@ mod tests { group2.finish().unwrap(); } + /// A backlog that lands whole before the first read starts at the first group whose first + /// frame is within the budget of the newest one, though nothing blocks. Five one-second + /// groups of ten frames and a one-frame sixth at 5 s, with a 1.5 s budget, start at the 4 s + /// group, whether the sixth is open or finished. `js/hang`'s `consumer.skips.test.ts` pairs + /// this case. + #[test] + fn a_buffered_backlog_starts_within_the_budget() { + for open in [true, false] { + let waiter = kio::Waiter::noop(); + let mut track = track_producer("test", hang::container::track_info(hang::catalog::PRIORITY.video)); + let mut consumer = container_max_delay_only(track.subscribe(None), Duration::from_millis(1500)); + for g in 0..5u64 { + let timestamps: Vec<_> = (0..10).map(|f| ts(g * 1_000_000 + f * 100_000)).collect(); + write_group(&mut track, g, ×tamps); + } + let mut last = track.create_group(moq_net::group::Info { sequence: 5 }).unwrap(); + Container::Legacy(crate::container::Kind::Data) + .write( + &mut last, + &[Frame { + timestamp: ts(5_000_000), + payload: Bytes::from_static(&[0xDE, 0xAD]), + keyframe: false, + duration: None, + }], + ) + .unwrap(); + if !open { + last.finish().unwrap(); + } + + let mut read = Vec::new(); + while let Poll::Ready(Ok(Some(item))) = consumer.poll_read(&waiter) { + match item { + Read::Frame { frame, .. } => read.push(frame.timestamp), + other => panic!("unexpected read: {other:?}"), + } + } + let expected: Vec<_> = (0..10) + .map(|f| ts(4_000_000 + f * 100_000)) + .chain([ts(5_000_000)]) + .collect(); + assert_eq!(read, expected, "sixth group open: {open}"); + } + } + + /// A backlog join's start skip waits on the next group's first frame, which may land within the + /// budget, rather than skipping on to a later group with data and dropping it. Here the fifth + /// group (4.0 s) arrived with its frames still in flight, so the start keeps the fourth and + /// plays on into the fifth. `js/hang`'s `consumer.skips.test.ts` pairs this case. + #[test] + fn a_backlog_start_waits_on_a_successor_without_frames() { + let waiter = kio::Waiter::noop(); + let mut track = track_producer("test", hang::container::track_info(hang::catalog::PRIORITY.video)); + let mut consumer = container_max_delay_only(track.subscribe(None), Duration::from_millis(1500)); + let frames = |g: u64| -> Vec<_> { (0..10).map(|f| ts(g * 1_000_000 + f * 100_000)).collect() }; + for g in 0..4u64 { + write_group(&mut track, g, &frames(g)); + } + let mut fifth = track.create_group(moq_net::group::Info { sequence: 4 }).unwrap(); + write_group(&mut track, 5, &[ts(5_000_000)]); + + let mut read = Vec::new(); + let mut drain = |consumer: &mut Consumer| { + while let Poll::Ready(Ok(Some(item))) = consumer.poll_read(&waiter) { + match item { + Read::Frame { frame, .. } => read.push(frame.timestamp), + other => panic!("unexpected read: {other:?}"), + } + } + }; + drain(&mut consumer); + for frame in frames(4) { + Container::Legacy(crate::container::Kind::Data) + .write( + &mut fifth, + &[Frame { + timestamp: frame, + payload: Bytes::from_static(&[0xDE, 0xAD]), + keyframe: false, + duration: None, + }], + ) + .unwrap(); + } + fifth.finish().unwrap(); + drain(&mut consumer); + + let expected: Vec<_> = frames(3).into_iter().chain(frames(4)).chain([ts(5_000_000)]).collect(); + assert_eq!(read, expected); + } + // ---- Malformed rewind ---- /// The track refuses a group whose first frame rewinds, but not a later frame that does, @@ -3272,6 +3501,31 @@ mod tests { assert_eq!(micros, vec![4_950_000, 5_000_000], "the warmup is not skipped as stale"); } + /// The start keeps the group covering the reach though its first frame trails the newest + /// content by more than the max delay plus the warmup. `js/hang`'s + /// `consumer.warmup.test.ts` pairs this case. + #[tokio::test] + async fn the_start_keeps_a_group_that_began_before_the_reach_but_covers_it() { + tokio::time::pause(); + let mut track = track_producer("test", hang::container::track_info(hang::catalog::PRIORITY.video)); + let mut consumer = reach_consumer( + &mut track, + Duration::from_millis(200), + Duration::from_millis(200), + Duration::from_millis(300), + ); + + write_group(&mut track, 5, &[ts(5_000_000)]); + // Group 4 begins 600ms before the newest content, past the 500ms reach, yet covers its 4.5s target. + write_group(&mut track, 4, &[ts(4_400_000), ts(4_600_000), ts(4_900_000)]); + let frame = kio::clock::timeout(Duration::from_millis(50), consumer.read_frame()) + .await + .expect("group 4 covers the reach") + .unwrap() + .unwrap(); + assert_eq!(frame.timestamp, ts(4_400_000)); + } + /// The warmup is carved out of the requested budget before the retention clamp, so a max delay /// the track can keep stays whole. #[tokio::test] @@ -4104,13 +4358,14 @@ mod tests { ); // Group 9 pushes the newest content a full budget past what group 5 could still - // present (bounded by group 7's start), expiring it. - write_group(&mut track, 9, &[ts(800_000)]); + // present (bounded by group 7's start), expiring it. Exactly a budget, so group 7's + // first frame is not past it and the start stays there. + write_group(&mut track, 9, &[ts(710_000)]); track.finish().unwrap(); let frames = read_all(&mut consumer).await.unwrap(); let micros: Vec = frames.iter().map(|f| f.timestamp.as_micros()).collect(); - assert_eq!(micros, vec![210_000, 800_000], "the expired frameless group is skipped"); + assert_eq!(micros, vec![210_000, 710_000], "the expired frameless group is skipped"); } /// An aborted frameless group beyond a sequence gap is reaped rather than parked on @@ -4378,6 +4633,9 @@ mod tests { ) .unwrap(); + // Read before group 1 lands, so the skip comes after the start. + assert_eq!(consumer.read_frame().await.unwrap().unwrap().timestamp, ts(0)); + // Group 1: finished, 200ms ahead (well beyond the 100ms max delay) write_group(&mut track, 1, &[ts(200_000)]); track.finish().unwrap(); @@ -4388,7 +4646,7 @@ mod tests { }); let frames = read_all(&mut consumer).await.unwrap(); - assert_eq!(frames.len(), 2, "Expected group 0 frame + group 1 frame"); + assert_eq!(frames.len(), 1, "Expected group 1's frame after group 0's"); finisher.await.unwrap(); } @@ -4402,14 +4660,15 @@ mod tests { let consumer_track = track.subscribe(None); let mut consumer = container_max_delay_only(consumer_track, Duration::from_millis(100)); - // Group 0: finished normally + // Group 0: finished normally, its first frame read before group 2 lands. write_group(&mut track, 0, &[ts(0), ts(20_000)]); + assert_eq!(consumer.read_frame().await.unwrap().unwrap().timestamp, ts(0)); // Group 2: finished (group 1 is missing — sequence gap) write_group(&mut track, 2, &[ts(200_000)]); track.finish().unwrap(); let frames = read_all(&mut consumer).await.unwrap(); - assert_eq!(frames.len(), 3, "Expected group 0 (2 frames) + group 2 (1 frame)"); + assert_eq!(frames.len(), 2, "Expected group 0's second frame + group 2 (1 frame)"); } #[tokio::test] diff --git a/rs/moq-video/src/decode/consumer.rs b/rs/moq-video/src/decode/consumer.rs index 32deba77a08..70b285e6889 100644 --- a/rs/moq-video/src/decode/consumer.rs +++ b/rs/moq-video/src/decode/consumer.rs @@ -1390,8 +1390,9 @@ mod tests { group(&mut track, 1, &[4, 5]).finish().unwrap(); track.finish().unwrap(); - // A budget that keeps every cached group, so both decoders read them all. - let mut consumer = dual(&broadcast, Start::Oldest, WARMUP, probe::BUFFERED_NAME).await; + // A budget past the whole 5 s backlog, so the start keeps every cached group and both + // decoders read them all. + let mut consumer = dual(&broadcast, Start::Oldest, 2 * WARMUP, probe::BUFFERED_NAME).await; let mut shown = Vec::new(); while let Some(frame) = consumer.next_frame().await.unwrap() { shown.push(u64::try_from(frame.timestamp.as_micros()).unwrap() / SECOND);