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
4 changes: 3 additions & 1 deletion doc/bin/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -231,7 +231,9 @@ to `--delay` ahead of its decode time and no further than its decoder buffer
holds. That send-ahead comes out of the delay, so the output trails a TS source
by `--delay`. A frame that cannot arrive in time at the rate fails the export,
as does video whose HRD declares a longer buffer delay than `--delay`; the
error names the `--delay` it needs.
error names the `--delay` it needs. Skipped media within the same broadcast
flags the next PCR as discontinuous without changing the PMT version. Raw
`--passthrough` keeps surviving packets unchanged, including across loss.

## Play

Expand Down
16 changes: 11 additions & 5 deletions quest/m1/ts-reliability/README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# TS fidelity and recovery
# [M] TS fidelity and recovery

## Goal

Expand Down Expand Up @@ -117,14 +117,20 @@ Decided 2026-11-04 (maintainer, design review of
ends, and the initial reservation releases at the first PTS. This is
independent of the handoff.

Decided 2026-11-05 (maintainer, /quest-complete, for
[moq-dev/moq#7785](https://github.com/moq-dev/moq/pull/7785)): ✅ cross-track
loss coalescing keeps only each track's last loss. A slower track can flag
outage A again after a faster track resumed A and then B (three flags for
two outages); state stays bounded by the track count, and the extra flag
lands where loss happened. Not chosen: keeping every loss until all tracks
pass it (unbounded while a track stalls); collapsing losses older than the
release point minus the delay (more code, and assumes muxing in release
order).

PMT fragmentation (#5220), initial mux-rate measurement (#5287), and
decoder-time admission (#5306) have landed, as have PSI runs (#5606) and
catalog linger (#5305).

## Required

- [A skipped group flags the next PCR](/quest/m1/ts-reliability/skip-flag.md) - a within-instance skip reaches the wire as a flagged PCR discontinuity

## Related

- [MSFTS mapping](/quest/m3/msfts-convergence.md) - document the exact equivalence and differences between the carriage modes
Expand Down
41 changes: 0 additions & 41 deletions quest/m1/ts-reliability/skip-flag.md

This file was deleted.

14 changes: 12 additions & 2 deletions rs/moq-mux/benches/ts_schedule.rs
Original file line number Diff line number Diff line change
Expand Up @@ -37,8 +37,14 @@ fn hold_heap() {
}

fn admission(c: &mut Criterion) {
for skipped in [false, true] {
admission_case(c, skipped);
}
}

fn admission_case(c: &mut Criterion, skipped: bool) {
hold_heap();
let mut group = c.benchmark_group("ts_schedule");
let mut group = c.benchmark_group(if skipped { "ts_schedule_skip" } else { "ts_schedule" });
group.measurement_time(Duration::from_secs(1));
group.warm_up_time(Duration::from_millis(200));
group.sample_size(10);
Expand All @@ -63,7 +69,11 @@ fn admission(c: &mut Criterion) {
}
for frame in 0..frames {
for pid in 1..=pids {
let at = (999 + frame * 40) * 1_000_000;
let gap = if skipped && frame >= frames / 2 { 4_000 } else { 0 };
if skipped && frame == frames / 2 {
schedule.skip();
}
let at = (999 + gap + frame * 40) * 1_000_000;
schedule
.push_frames(
pid,
Expand Down
106 changes: 98 additions & 8 deletions rs/moq-mux/src/container/ts/export.rs
Original file line number Diff line number Diff line change
Expand Up @@ -272,6 +272,8 @@ struct Pending {
/// A frame waiting in the jitter buffer, with what it needs from the moment it was read.
struct Queued {
frame: Frame,
/// Delivery skips before this frame, excluding declared timeline boundaries.
gap: u64,
/// When the frame decodes: its DTS, else its PTS.
decode: Timestamp,
/// Where the jitter buffer orders it ([`Track::release_key`]).
Expand Down Expand Up @@ -317,6 +319,14 @@ struct Track {
/// The marker, skip and cut counts of the sources the track read before this one, so the
/// counts keep rising across a resubscription.
base: (u64, u64, u64),
/// Delivery skips before the last frame muxed, so read-ahead cannot flag earlier output.
gap: u64,
/// Furthest presentation time muxed, so overlapping track losses share one break.
last_timestamp: Option<Timestamp>,
/// The last delivery loss the track signalled or joined ([`coalesce`]). Only the last, so
/// state stays bounded by the track count: a slower track can flag an outage again after a
/// faster one moved past it, an extra flag where loss did happen.
lost: Option<Lost>,
/// How many unmarked steps back the track's timeline took ([`Self::steps_back`]), each
/// counted as a marker of its own.
steps: u64,
Expand Down Expand Up @@ -399,6 +409,9 @@ impl Track {
latest: kio::clock::Instant::ZERO,
restart: 0,
base: (0, 0, 0),
gap: 0,
last_timestamp: None,
lost: None,
steps: 0,
high: None,
finished: false,
Expand Down Expand Up @@ -840,6 +853,7 @@ impl Track {
let Pending {
frame,
restart,
skip,
arrived,
read,
..
Expand Down Expand Up @@ -888,6 +902,7 @@ impl Track {
bytes: frame.payload.len() + self.key.name.len(),
item: Queued {
frame,
gap: skip.saturating_sub(restart),
decode,
key,
dts,
Expand Down Expand Up @@ -1224,6 +1239,8 @@ struct PesUnit {
pid: u16,
is_video: bool,
keyframe: bool,
/// Delivery loss precedes this frame, so its scheduled PCR flags the gap.
skipped: bool,
timestamp: Timestamp,
/// Authored decode timestamp for a reordered (B-frame) video frame, in continuous
/// (unwrapped) 90 kHz ticks (wrapped to the wire field in `write_pes`). `Some` only when
Expand Down Expand Up @@ -3016,6 +3033,8 @@ where
psi.led = psi.out.as_ref().map(|laid| laid.pmt.clone());
}
for track in self.program.tracks.values_mut() {
track.last_timestamp = None;
track.lost = None;
track.pack = None;
track.parked.clear();
}
Expand Down Expand Up @@ -3494,13 +3513,29 @@ where
fn mux(&mut self, name: &str, queued: Queued) -> anyhow::Result<()> {
let Queued {
frame,
gap,
decode,
dts,
description,
pes,
..
} = queued;
let kind = &self.program.tracks.get(name).context("missing track")?.kind;
let track = self.program.tracks.get_mut(name).context("missing track")?;
let skipped = gap > track.gap;
track.gap = gap;
// The track's missing interval runs from its furthest media muxed, or from the last
// reset when it has muxed none since, a start every such track shares (`None`).
let start = track.last_timestamp;
let end = frame.timestamp;
track.last_timestamp = Some(start.map_or(end, |start| start.max(end)));
let skipped = skipped && {
let others = self.program.tracks.values().filter_map(|track| track.lost);
let (lost, separate) = coalesce((start, end), others);
self.program.tracks.get_mut(name).context("missing track")?.lost = Some(lost);
separate
Comment thread
kixelated marked this conversation as resolved.
Resolved
};
let track = self.program.tracks.get(name).context("missing track")?;
let kind = &track.kind;
let is_video = matches!(kind, Kind::Video(_));
// Refresh PSI at keyframes, MPEG-1/2 video's carried whole among them, or after the
// interval lapses, and lead with a revision.
Expand Down Expand Up @@ -3561,7 +3596,7 @@ where
// The tables lead the unit that carries this frame, behind whatever went before it.
if kind.placed() {
self.program.psi_due |= psi;
return self.place(name, &frame, out);
return self.place(name, &frame, out, skipped);
}
match es_payload {
// Section-framed verbatim (SCTE-35, ...) rides in private sections, not PES;
Expand All @@ -3575,6 +3610,7 @@ where
pid,
is_video,
keyframe,
skipped,
timestamp: frame.timestamp,
dts,
stream_id: stream_id(&kind),
Expand All @@ -3589,7 +3625,7 @@ where
self.write_pes(&mut out, &unit, &es_payload)?;
}
}
self.push_unit(name, pid, decode, out, keyframe, Vec::new())
self.push_unit(name, pid, decode, out, (keyframe, skipped), Vec::new())
}

/// Queue a whole PES or section unchanged on `name`'s PID behind `tables`, its
Expand All @@ -3600,7 +3636,7 @@ where
/// unit that begins in it, so each one after counts on from there and leaves at its own time.
/// The bytes ahead of the first end a frame an earlier PES began; they leave with it,
/// which only overstates what the buffer holds. A PES without a PTS holds nothing there.
fn place(&mut self, name: &str, frame: &Frame, tables: Vec<u8>) -> anyhow::Result<()> {
fn place(&mut self, name: &str, frame: &Frame, tables: Vec<u8>, skipped: bool) -> anyhow::Result<()> {
let track = self.program.tracks.get(name).context("missing track")?;
let pes = match track.kind {
Kind::PesPacket { stream_type } => Some(
Expand Down Expand Up @@ -3640,6 +3676,9 @@ where
self.program.schedule.set_buffer(pid, buffer);
}
self.lead_tables()?;
if skipped {
self.program.schedule.skip();
}
self.program.schedule.push_placed(
pid,
(place, decode.unwrap_or(place)),
Expand Down Expand Up @@ -3677,7 +3716,8 @@ where
let (size, fit) = track.fit(payload.len());
let place = place(unit.timestamp, samples, rate);
// A PTS is a whole 90 kHz tick, so the frames run on within one of where they end.
let joins = start.is_some()
let joins = !unit.skipped
&& start.is_some()
&& track.pack.as_ref().is_some_and(|pack| {
pack.start == start
&& pack.rate == rate
Expand Down Expand Up @@ -3724,7 +3764,7 @@ where
} = pack;
let mut out = Vec::new();
self.write_pes(&mut out, &unit, &payload)?;
self.push_unit(name, unit.pid, decode, out, unit.keyframe, frames)
self.push_unit(name, unit.pid, decode, out, (unit.keyframe, unit.skipped), frames)
}

/// Send on, in decode order, the packed frames of each track for which `done` holds, given
Expand Down Expand Up @@ -3756,7 +3796,7 @@ where
pid: u16,
decode: Timestamp,
out: Vec<u8>,
keyframe: bool,
(keyframe, skipped): (bool, bool),
frames: Vec<(u128, usize)>,
) -> anyhow::Result<()> {
let mut tables = std::mem::take(&mut self.program.tables);
Expand Down Expand Up @@ -3786,6 +3826,9 @@ where
}
let by = decode.as_nanos().saturating_sub(track.drain().as_nanos());
self.lead_tables()?;
if skipped {
self.program.schedule.skip();
}
self.program.schedule.push_frames(
pid,
super::schedule::Timing {
Expand Down Expand Up @@ -3920,7 +3963,7 @@ where
let mut payload = slot.layout(&clock, pmt_pid, &NULL_PACKET);
// The slot opens with its PCR, in the clock packet or the clock PID's packet that
// carries it, whose adaptation field flags the break.
let discontinuity = std::mem::take(&mut self.program.pcr_discontinuity);
let discontinuity = std::mem::take(&mut self.program.pcr_discontinuity) || slot.discontinuity;
if discontinuity {
payload[5] |= 0x80;
}
Expand Down Expand Up @@ -4292,6 +4335,30 @@ fn dolby_removals(codec: Dolby, payload: &[u8], decode: u128) -> Vec<(u128, usiz
frames
}

/// A delivery loss's presentation interval: from the furthest media its track muxed before,
/// `None` when it had muxed none since the last reset, to the frame it resumed at.
type Lost = (Option<Timestamp>, Timestamp);

/// Merge `lost` with every interval in `others` it overlaps, and whether it overlapped none,
/// so it needs a PCR flag of its own.
///
/// Tracks resume the same outage in different release slots, and in any order. One flag covers
/// their overlapping intervals, including a later read on another track that extends one
/// already signalled. Presentation time shares the content's timeline across their different
/// decode reserves, and every track that muxed nothing since the last reset starts its loss
/// there.
fn coalesce((start, end): Lost, others: impl IntoIterator<Item = Lost>) -> (Lost, bool) {
let shared: Vec<Lost> = others
.into_iter()
.filter(|&(first, last)| start.is_none_or(|start| start < last) && first.is_none_or(|first| first < end))
.collect();
// `None` sorts first, so a merge keeps an unbounded start.
let lost = shared.iter().fold((start, end), |(start, end), &(first, last)| {
(start.min(first), end.max(last))
});
(lost, shared.is_empty())
}

/// Whether `timestamp` has crossed into a later repetition slot than `last`.
///
/// Slots are absolute on the media timeline (`floor(timestamp / interval)`) rather than
Expand Down Expand Up @@ -5047,6 +5114,29 @@ mod tests {
due, is_complete_section, si_due, slot, unwrap_pts, verbatim_buffer,
};

/// Losses resumed out of presentation order flag each outage once, however they interleave.
#[test]
fn coalesce_flags_each_outage_once() {
let ms = |ms: u64| Timestamp::from_millis(ms).unwrap();
let a = (Some(ms(10_200)), ms(10_400));
let b = (Some(ms(9_800)), ms(10_000));
assert_eq!(super::coalesce(a, []), (a, true));
assert_eq!(super::coalesce(b, [a]), (b, true), "a disjoint earlier outage");
assert_eq!(super::coalesce(a, [a, b]), (a, false), "the first outage again");
let wider = (Some(ms(9_900)), ms(10_300));
assert_eq!(
super::coalesce(wider, [a, b]),
((Some(ms(9_800)), ms(10_400)), false),
"spanning both"
);
let reset = (None, ms(24_280));
assert_eq!(
super::coalesce((None, ms(24_216)), [reset]),
((None, ms(24_280)), false),
"both since a reset"
);
}

/// The tables as they stand take the version after the last laid, whatever was set on the
/// schedule meanwhile, and the last laid's own when they come back to it. The PAT keeps its
/// own version until its network entry or PMT PID changes.
Expand Down
Loading
Loading