Skip to content
Merged
1 change: 0 additions & 1 deletion quest/m1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -152,7 +152,6 @@ their end report, so an embedder's drain alert pages on real cuts.
- [Subscribe ranges](/quest/m1/subscribe-ranges/README.md) - a lite-07 SUBSCRIBE asks for past and live ranges with absolute or relative ends, in either order, and replaces FETCH; merged ranges never starve a subscriber; relays fill misses by range, including over moq-transport
- [Drop set](/quest/m1/drop-set.md) - each cursor judges missing groups against its own budget, so a narrow reader drops promptly and a widening re-offers groups already reported dropped on lite-07
- [Datagram tracks](/quest/m1/datagram-tracks/README.md) - a track is datagrams or streams; datagram tracks have their own request and sequence, no ranges, no cache, and map to object ID 0 on moq-transport
- [A step back smaller than the delay keeps the TS export](/quest/m1/ts-small-step-back.md) - audio restarts instead of regressing; video stays within its declared depth
- [A routed JS read wakes when its track aborts](/quest/m1/js-follow-abort-wake.md) - a pending `readFrame()` on a group found through `request()`/`follow()` rejects on `track.abort()`
- [A wedged CARLA truck nobody drives respawns after the stuck timeout](/quest/m1/carla-stuck-handback.md) - find what kept the 300 s stuck respawn off for a truck wedged after a handback, and fix it
- [Finalize moq-lite-07](/quest/m1/lite07-finalize.md) - when the maintainer cuts it, lite-07 negotiates as `moq-lite-07` and the next release ships it
Expand Down
27 changes: 0 additions & 27 deletions quest/m1/ts-small-step-back.md

This file was deleted.

38 changes: 34 additions & 4 deletions rs/moq-mux/benches/export.rs
Original file line number Diff line number Diff line change
Expand Up @@ -258,7 +258,15 @@ async fn prepare_video(
let mut video = catalog.video(track, Container::Legacy(Kind::Video), config).unwrap();
for index in 0..count {
let pts = match pattern {
"pyramid" => ((index / 9 * 9 + [0, 4, 2, 1, 3, 8, 6, 5, 7][index % 9]) * 3_600) as u64,
"pyramid" | "step-back" => {
let pts = ((index / 9 * 9 + [0, 4, 2, 1, 3, 8, 6, 5, 7][index % 9]) * 3_600) as u64;
if pattern == "step-back" && index >= count / 2 {
// Keep the 300 ms rewind in the one group every subscription reads.
pts - 300 * 90
} else {
pts
}
}
"flat" => 90_000,
"backward" => 90_000 - index as u64,
_ => unreachable!(),
Expand Down Expand Up @@ -300,14 +308,36 @@ fn video_reorder(c: &mut Criterion) {
group.sample_size(10);
group.warm_up_time(Duration::from_millis(50));
group.measurement_time(Duration::from_millis(200));
for pattern in ["pyramid", "flat", "backward"] {
for (format, pattern) in [
("mkv", "pyramid"),
("mkv", "flat"),
("mkv", "backward"),
("ts", "pyramid"),
("ts", "step-back"),
] {
let name = if format == "ts" {
format!("ts/{pattern}")
} else {
pattern.into()
};
for count in [64, 256, 1024] {
for size in [256, 16_384] {
group.bench_function(BenchmarkId::new(pattern, format!("{count}x{size}")), |b| {
group.bench_function(BenchmarkId::new(&name, format!("{count}x{size}")), |b| {
b.iter_batched(
|| runtime.block_on(prepare_video(count, size, pattern)),
|(source, stream, fixture)| {
let refused = runtime.block_on(async {
if format == "ts" {
let mut opened = moq_mux::container::ts::Export::new(source, stream);
let mut chunks = 0;
while let Some(frame) = opened.next().await.unwrap() {
std::hint::black_box(frame);
chunks += 1;
}
assert!(chunks > 0);
assert_eq!(opened.discontinuity(), u64::from(pattern == "step-back"));
return false;
}
let mut export = moq_mux::container::mkv::Export::new(source, stream)
.with_fragment_duration(Duration::ZERO);
loop {
Expand All @@ -320,7 +350,7 @@ fn video_reorder(c: &mut Criterion) {
}
}
});
assert_eq!(refused, pattern != "pyramid");
assert_eq!(refused, format == "mkv" && pattern != "pyramid");
fixture
},
BatchSize::PerIteration,
Expand Down
5 changes: 5 additions & 0 deletions rs/moq-mux/src/container/declared.rs
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,11 @@ impl<T> DeclaredClock<T> {
}
}

/// Restart the clock at the same declared depth.
pub(crate) fn restart(self) -> Self {
Self::new(self.depth)
}

/// How many frames are held.
#[cfg(test)]
pub(crate) fn len(&self) -> usize {
Expand Down
43 changes: 21 additions & 22 deletions rs/moq-mux/src/container/ts/export.rs
Original file line number Diff line number Diff line change
Expand Up @@ -443,7 +443,8 @@ impl Track {
self.release(name, jitter, true)?;
self.restart = pending.restart;
self.clock = DecodeClock::default();
self.declared = None;
// The step changes the timeline, not the group's declared reorder bound.
self.declared = self.declared.take().map(DeclaredClock::restart);
self.keyframe = None;
self.leading_floor = None;
}
Expand Down Expand Up @@ -524,8 +525,7 @@ impl Track {
self.release(name, jitter, false)
}

/// Count a frame that steps the track's timeline back with no marker as a marker of its own:
/// presented further below the highest PTS read on the timeline than the export's `delay`,
/// Count a frame that steps the track's timeline back with no marker as a marker of its own,
/// where a reorder bound proves no valid reordering explains it.
///
/// Audio presents in decode order, so any frame below one read before it is out of order.
Expand All @@ -539,17 +539,14 @@ impl Track {
/// and fail the export, and audio with slack left would decode before the frames ahead of it
/// on the same clock, which the output's buffers cannot carry. As a marker, the step restarts
/// the decode clock and opens a new generation, as one the source declared would. A placed
/// frame's timestamp is its arrival rather than its decode time, so it never steps. Without a
/// delay nothing is late, so a step costs nothing there.
fn steps_back(&mut self, pending: &mut Pending, delay: Duration) {
/// frame's timestamp is its arrival rather than its decode time, so it never steps.
fn steps_back(&mut self, pending: &mut Pending) {
if self.kind.placed() {
return;
}
let pts = pending.frame.timestamp;
let high = (self.high).and_then(|(restart, high)| (restart == pending.restart).then_some(high));
let delay = u64::try_from(delay.as_micros() * 90_000 / 1_000_000).unwrap_or(u64::MAX);
let below = delay > 0 && high.is_some_and(|high| to_ticks(pts).saturating_add(delay) < to_ticks(high));
let stepped = below
let stepped = high.is_some_and(|high| pts < high)
&& match self.kind {
Kind::Video(_) => (self.declared)
.as_ref()
Expand Down Expand Up @@ -606,7 +603,7 @@ impl Track {
arrived,
read: kio::clock::now(),
};
self.steps_back(&mut pending, input.jitter.delay());
self.steps_back(&mut pending);
// A new timeline must reach the reset before tune-in alignment can drop it.
if let Some(start) = input.video_start
&& aligned && pending.restart == self.restart
Expand Down Expand Up @@ -5142,11 +5139,11 @@ mod tests {
arrived,
read: arrived,
};
track.steps_back(&mut pending, Duration::from_millis(500));
track.steps_back(&mut pending);
if pending.restart != track.restart {
track.restart = pending.restart;
track.clock = DecodeClock::default();
track.declared = None;
track.declared = track.declared.take().map(super::DeclaredClock::restart);
}
if keyframe {
track.declared = reorder.map(super::DeclaredClock::new);
Expand Down Expand Up @@ -5187,16 +5184,18 @@ mod tests {
0,
"in-bound reordering"
);
assert_eq!(
video_steps(Some(2), &pyramid(10_000, 560, 4)).await,
1,
"a step within a group"
);
assert_eq!(
video_steps(Some(2), &pyramid(10_000, 560, 0)).await,
1,
"a group stepped whole"
);
for step in [300, 560] {
assert_eq!(
video_steps(Some(2), &pyramid(10_000, step, 4)).await,
1,
"a {step} ms step within a group"
);
assert_eq!(
video_steps(Some(2), &pyramid(10_000, step, 0)).await,
1,
"a group stepped whole by {step} ms"
);
}
// Two frames back is within the declared depth, however far back they are presented.
let deep = [(10_000, true), (11_000, false), (11_040, false), (10_040, false)];
assert_eq!(
Expand Down
19 changes: 8 additions & 11 deletions rs/moq-mux/src/container/ts/export_test.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1392,8 +1392,8 @@ async fn trimmed_leading_pictures_keep_their_slots() {
assert_eq!(joined.iter().collect::<Vec<_>>(), shared);
}

/// A declared depth of zero decodes every frame at its presentation, and refuses a frame that
/// reorders, rather than inferring a decode delay.
/// A declared depth of zero decodes every frame at its presentation. A regression proves a
/// timeline step and starts a new clock period instead of inferring a decode delay.
#[tokio::test(start_paused = true)]
async fn export_declared_zero_reorder_decodes_at_presentation() {
let (mut export, _keep) = export_declared(0, &[&[0, 40, 80, 120]]).await;
Expand All @@ -1406,15 +1406,12 @@ async fn export_declared_zero_reorder_decodes_at_presentation() {
assert_eq!(timing.len(), 4);
assert!(timing.iter().all(|(pts, dts)| pts == dts), "{timing:?}");

let (mut export, _keep) = export_declared(0, &[&[0, 80, 40, 120]]).await;
let err = loop {
match kio::clock::timeout(DRAIN, export.next()).await {
Ok(Ok(Some(_))) => {}
Ok(Ok(None)) | Err(_) => panic!("a frame reordered past the declared depth was exported"),
Ok(Err(err)) => break err,
}
};
assert!(err.to_string().contains("declared depth"), "{err}");
let (mut export, _keep) = export_declared(0, &[&[0, 80, 40, 120, 80, 160], &[200, 240]]).await;
let frames = drain_frames(&mut export).await;
let bytes: Vec<u8> = frames.iter().flat_map(|frame| frame.payload.iter().copied()).collect();
let timing = video_pes_timing(&bytes);
assert_eq!(timing, [0, 80, 40, 120, 80, 160, 200, 240].map(|ms| (ms * 90, ms * 90)));
assert_eq!(count_discontinuity(&frames), 2, "each step opens a clock period");
}

/// #2937: the PCR must be a uniform bounded-interval ramp, not a sample of the
Expand Down
69 changes: 60 additions & 9 deletions rs/moq-mux/src/container/ts/export_timing_test.rs
Original file line number Diff line number Diff line change
Expand Up @@ -529,6 +529,8 @@ async fn end_waits_for_catalog_and_media() {
#[derive(Debug, Clone, Copy)]
struct Unit {
pid: u16,
/// PCR clock period, advanced by a flagged PCR.
period: u64,
/// Decode time (DTS, else PTS), 90 kHz, as carried.
decode: u64,
/// Decode time less the PCR of the slot carrying the PES start, in milliseconds: how long
Expand Down Expand Up @@ -559,10 +561,14 @@ fn units(out: &[(Instant, Frame)]) -> Vec<Unit> {
let mut reader = TsPacketReader::new(Cursor::new(bytes));
let mut units = Vec::new();
let mut pcr: Option<u64> = None;
let mut period = 0;
for sent in &slot_of {
let packet = reader.read_ts_packet().unwrap().expect("a packet per slot entry");
if let Some(clock) = packet.adaptation_field.as_ref().and_then(|af| af.pcr) {
if let Some(af) = packet.adaptation_field.as_ref()
&& let Some(clock) = af.pcr
{
pcr = Some(clock.as_u64() / 300);
period += u64::from(af.discontinuity_indicator);
}
if let Some(TsPayload::PesStart(pes)) = &packet.payload
&& let Some(pts) = pes.header.pts
Expand All @@ -571,6 +577,7 @@ fn units(out: &[(Instant, Frame)]) -> Vec<Unit> {
let decode = pes.header.dts.unwrap_or(pts).as_u64();
units.push(Unit {
pid: packet.header.pid.as_u16(),
period,
decode,
lead: diff90(decode, pcr) as f64 / 90.0,
sent: *sent,
Expand Down Expand Up @@ -741,15 +748,17 @@ async fn a_track_sent_later_than_the_delay_loses_nothing() {
/// A changeover between two encoders whose clocks started hours apart steps the whole timeline
/// forward with no marker, mid-group, as in the field. The export re-acquires its clock as at
/// startup, rather than read the step as drift and end, and renders on without a drop. So it
/// does for a step back of more than the delay that lands within the group before its own, on
/// video that declares its `reorder`, which proves the step is no reordering, rather than clamp
/// the video onto the old timeline and drop it as late until the timeline catches up, or fail on
/// a frame reordered deeper than declared. Video that declares none is left as it is. (A step
/// back further than that never reaches it: the reader refuses it.)
/// does for a step back, even smaller than the delay: audio never regresses on one clock, and
/// video that declares its `reorder` restarts when the step exceeds that depth. Video that
/// declares none is left as it is. A step back into an earlier group never reaches the export:
/// the reader refuses it.
#[tokio::test(start_paused = true)]
async fn an_unmarked_step_keeps_the_export_rendering() {
let forward = [16_844_500_000, 2_000_000].map(|step| [(step, false), (step, true)]);
let cases = forward.into_iter().flatten().chain([(-560_000, true)]);
let cases = forward
.into_iter()
.flatten()
.chain([(-300_000, false), (-300_000, true), (-560_000, true)]);
for (step, declared) in cases {
for lag in [0, LAGS[0], LAGS[1]] {
let mut live = Live::new(1.0, lag).await;
Expand All @@ -764,8 +773,15 @@ async fn an_unmarked_step_keeps_the_export_rendering() {

let case = format!("{} s step, declared {declared}, lag {lag}", step as f64 / 1e6);
assert_eq!(leg.export.dropped(), 0, "{case}");
let video = leg
.units()
let units = leg.units();
let audio: Vec<_> = units.iter().filter(|unit| unit.pid == AUDIO_PID).collect();
for pair in audio.windows(2) {
assert!(
pair[0].period != pair[1].period || diff90(pair[1].decode, pair[0].decode) >= 0,
"{case}: audio regressed on one clock: {pair:?}"
);
}
let video = units
.into_iter()
.filter(|unit| unit.pid == VIDEO_PID && unit.sent >= stepped)
.count() as u64;
Expand All @@ -774,6 +790,41 @@ async fn an_unmarked_step_keeps_the_export_rendering() {
}
}

/// The same step back, smaller than the delay, while the export is still acquiring its first
/// clock: what it read before the step and what it reads after cannot share one clock, so
/// audio still never regresses within a clock period, and the export renders on.
#[tokio::test(start_paused = true)]
async fn an_unmarked_step_while_acquiring_keeps_the_export_rendering() {
for declared in [false, true] {
for lag in [0, LAGS[0], LAGS[1]] {
let mut live = Live::new(1.0, lag).await;
// Far enough into the timeline that the step stays on it.
live.offset = 10_000_000;
if declared {
live.reorder();
}
let mut leg = live.join(Duration::ZERO).await;
live.run(4, &mut [&mut leg], |_| false);
let case = format!("declared {declared}, lag {lag}");
assert!(leg.units().is_empty(), "{case}: output began before the step");
live.offset -= 300_000;
live.run(live.tick + 8 * GOP, &mut [&mut leg], |_| false);

assert_eq!(leg.export.dropped(), 0, "{case}");
let units = leg.units();
let audio: Vec<_> = units.iter().filter(|unit| unit.pid == AUDIO_PID).collect();
for pair in audio.windows(2) {
assert!(
pair[0].period != pair[1].period || diff90(pair[1].decode, pair[0].decode) >= 0,
"{case}: audio regressed on one clock: {pair:?}"
);
}
let video = units.iter().filter(|unit| unit.pid == VIDEO_PID).count() as u64;
assert!(video >= 6 * GOP, "{case}: only {video} video units");
}
}
}

// A publisher that dies leaves the last video frames it sent held for their DTS, and nothing
// settles them until frames come again. Where the receiver is not told the source changed (a
// replacement on a protocol under another instance, or the other half of a 1+1 pair), those come on the
Expand Down
Loading
Loading