From 0bb78f8e7ea9b34aacadf6ab10a85f41d3b04770 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 5 Oct 2026 11:02:21 -0700 Subject: [PATCH 1/3] quest: settle typed-timedness object stamps, plan the HLS first catalog Co-Authored-By: Claude Opus 5.5 --- quest/m1/README.md | 1 + quest/m1/hls-first-catalog.md | 45 +++++++++++++++++++++++++++++++++++ quest/m1/typed-timedness.md | 42 ++++++++++++++++++++++++++++---- quest/m1/untimed-model.md | 22 ++++++++++------- 4 files changed, 96 insertions(+), 14 deletions(-) create mode 100644 quest/m1/hls-first-catalog.md diff --git a/quest/m1/README.md b/quest/m1/README.md index fe566282855..4408582611f 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -75,6 +75,7 @@ QUIC studies there on that rule. - [Capture by default](/quest/m1/capture-default.md) - moq-video and moq-audio build `capture` by default, so pre-merge checks test it and the capture gate goes away - [Ship capture and playback](/quest/m1/cli-packaging.md) - a released moq binary can capture and play, which no distribution currently enables - [Import at the first frame](/quest/m1/import-first-frame.md) - fMP4, MKV, and MPEG-TS imports publish the catalog at their first frame, so a lone importer's root clock never moves +- [HLS first catalog](/quest/m1/hls-first-catalog.md) - moq-hls import's first catalog lists every rendition from the master playlist, not only the first - [CMAF frame timestamp](/quest/m1/cmaf-frame-timestamp.md) - CMAF decoders time samples from the moq-lite frame timestamp, using `tfdt` only within the fragment - [Shared import clock](/quest/m1/shared-clock.md) - an importer joining a clock already in use offsets its PTS instead of moving it, so captures and imports share one timeline - [Publishing never invents a timestamp](/quest/m1/publish-timestamp.md) - no Rust or binding publish API fills in a timestamp; an untimed payload goes out untimed diff --git a/quest/m1/hls-first-catalog.md b/quest/m1/hls-first-catalog.md new file mode 100644 index 00000000000..9ef9548f54c --- /dev/null +++ b/quest/m1/hls-first-catalog.md @@ -0,0 +1,45 @@ +# [XS] moq-hls import publishes every rendition in its first catalog + +## Goal + +moq-hls import holds its first catalog until every rendition selected from +the master playlist has reserved its tracks, so a consumer never sees a first +catalog with only the first rendition. + +Today each rendition's importer, and its `catalog.reserve()`, is created +lazily in `TrackState::ensure_map` (`rs/moq-hls/src/import.rs`) while `step` +ingests renditions one at a time. The first rendition's reservation can +release before the others exist, so the catalog publishes with one rendition +and grows on later updates. Reported by Dryvnt in +[#4824](https://github.com/moq-dev/moq/pull/4824). + +## Plan + +Decided (2026-10-05, maintainer): m1, [XS], ranked right after [Import at the +first frame](/quest/m1/import-first-frame.md). That quest moves each +importer's release to its first frame, which still lands before the next +rendition is reserved. + +Guidance: + +- `step` already holds a pass-wide timeline reservation for the same reason + ("a record flushed mid-pass would omit every rendition that hasn't loaded + its init segment yet"). A catalog `Reserved` held the same way, at least + across the first pass, is the likely shape. +- Don't let a hold outlive its pass. A rendition that fails at startup under + `OnError::Warn` must not withhold the catalog for the whole import, and a + live `Reserved` withholds it (see [Shared import + clock](/quest/m1/shared-clock.md), which rejected sharing offsets through + one for that reason). +- Regression test (fails on `main`): a master playlist with two or more + renditions, for example a video variant and a separate audio rendition + from `file://` fixtures as the existing import tests use. The catalog + consumer's first snapshot lists every rendition. + +Public API: none. Wire: none. A multi-rendition HLS import's first catalog +lists every rendition instead of only the first. + +## Related + +- [Import at the first frame](/quest/m1/import-first-frame.md) - moves each importer's catalog release to its first frame +- [Shared import clock](/quest/m1/shared-clock.md) - moq-hls renditions share one `catalog::Input`, whose `reserve()` this hold may use diff --git a/quest/m1/typed-timedness.md b/quest/m1/typed-timedness.md index 0750323fc5f..1d9d0d418ae 100644 --- a/quest/m1/typed-timedness.md +++ b/quest/m1/typed-timedness.md @@ -16,6 +16,14 @@ example `track::Timed` and `track::Untimed`, and settle the shape that Mirror the shape in `@moq/net` and the bindings. +The IETF receive path follows the same rule, and +`drafts/draft-lcurley-moq-timestamp.md` says so: + +- On a track accepted without TIMESCALE, an object's own object-scope + TIMESCALE and Timestamp are ignored, and the track stays untimed. +- On a track that declares TIMESCALE, an object without TIMESTAMP makes the + track malformed. + ## Plan Decided (2026-10-05, maintainer): @@ -32,13 +40,35 @@ Decided (2026-10-05, maintainer): breaking change instead of two. Folding `Timed`'s `T` in here, rather than a separate quest, keeps that to one break too. +Decided (2026-10-05, maintainer, settling the open question on object +stamps): + +- Timestamps are all-or-nothing per track on the wire too. On a track + accepted without TIMESCALE, objects that carry their own object-scope + TIMESCALE and Timestamp (imquic does) are ignored: the track stays untimed + and the stamps are dropped, so peers that play today keep playing. + Rejected: refusing them, and deferring the call to the mock-up. +- On a track that declares TIMESCALE, an object with no TIMESTAMP is + malformed. The receiver handles it under moq-transport's malformed-track + rules rather than inventing a time. Rejected: repeating the latest + timestamp, and falling back to arrival time. +- Object-scope TIMESCALE overrides are no longer applied on any track. +- The draft changes ship in this quest's PR, with the implementation, not in + a separate draft PR first. In `drafts/draft-lcurley-moq-timestamp.md`, + three rules change: a publisher stamping every object on a TIMESCALE track + becomes a requirement rather than a SHOULD, a missing Timestamp is + malformed instead of falling back to arrival time, and receivers stop + applying object-scope TIMESCALE overrides. Check the lite draft's per-track + rule too, and update it if it differs. + Look out for: - Where an untimed track's frames still need ordering or "has a frame" answers (group start, expiry, the live edge), without a timestamp to read. -- What a receiver does with timing that arrives on a track it accepted as - untimed, such as an IETF object-scope TIMESCALE and Timestamp (imquic - publishes this way). Refusing would break peers that play today. +- Which objects the malformed rule covers. Status-only objects (End of + Group, End of Track) and an empty LOC end marker carry no media time. + Before landing, check that our publishers and any interop peer that sends + TIMESCALE stamp every object the rule covers. - lite-05 and lite-06 always send a Timescale, so an untimed track goes out there as timed, with the encoder's send time, as [Untimed model](/quest/m1/untimed-model.md) decided. @@ -46,5 +76,7 @@ Look out for: timestamp](/quest/m1/publish-timestamp.md), its JS mirror, and the data consumer quests. -Public API: breaking (`track::Info.timescale`, `Timed`). Wire: none until -the untimed quests use it. +Public API: breaking (`track::Info.timescale`, `Timed`). Wire: no encoding +change. Receive semantics on published IETF drafts change: object-scope +stamps on an untimed track are ignored, and a TIMESCALE track missing a +TIMESTAMP is malformed. diff --git a/quest/m1/untimed-model.md b/quest/m1/untimed-model.md index 4875d9e34fd..ecee372f9ab 100644 --- a/quest/m1/untimed-model.md +++ b/quest/m1/untimed-model.md @@ -40,10 +40,11 @@ content out, and the pool's wall-clock expiry is the bound). Decided (2026-10-02, planning this split): -- Superseded 2026-10-05: an IETF object carrying its own TIMESCALE and - Timestamp no longer makes it timed on a track accepted without TIMESCALE; - the track decides. imquic's LOC examples publish this way, so they arrive - untimed. +- Superseded 2026-10-05 by [Typed timedness](/quest/m1/typed-timedness.md): + on a track accepted without TIMESCALE, an object's own object-scope + TIMESCALE and Timestamp are ignored, and the track stays untimed. imquic's + LOC examples publish this way, so they arrive untimed and keep playing. + Object-scope units are never applied, on any track. - A legacy or LOC end marker (an empty frame) that arrives untimed is ignored. The group then ends without a precise end bound. Its frames still play from their payload timestamps, and only the last frame's duration is @@ -101,14 +102,17 @@ Interop facts (2026-10-02): - In the community runner: - moxygen sends neither TIMESCALE nor Timestamp, so all its objects become untimed. - - imquic uses the object scope. + - imquic uses the object scope, which is ignored, so its objects arrive + untimed. - libquicr sends neither. - MOQtail is undetermined. -Draft: rewrite the arrival-time mandates in -`draft-lcurley-moq-timestamp.md` (no TIMESCALE, before track properties -arrive, an object without a Timestamp) as "untimed". An untimed object has no -media time, is never media-stale, starts at the latest group, and is +Draft: [Typed timedness](/quest/m1/typed-timedness.md) rewrites the +per-object rules in `draft-lcurley-moq-timestamp.md` (every object on a +TIMESCALE track is stamped, a missing Timestamp is malformed, object-scope +TIMESCALE is ignored). Rewrite the remaining arrival-time mandates (no +TIMESCALE, before track properties arrive) as "untimed". An untimed object +has no media time, is never media-stale, starts at the latest group, and is forwarded as untimed. Tests: each receive path (lite before lite-05, IETF subgroup, fetch and From 4168258a41607f3a55c12f185cdfe2d8831fd052 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 5 Oct 2026 11:37:41 -0700 Subject: [PATCH 2/3] quest: size typed-timedness [M] It now carries the IETF receive rules and the timestamp-draft edits on top of the type mock-up. Co-Authored-By: Claude Opus 5.5 --- quest/m1/typed-timedness.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/quest/m1/typed-timedness.md b/quest/m1/typed-timedness.md index 1d9d0d418ae..4f4d30c7195 100644 --- a/quest/m1/typed-timedness.md +++ b/quest/m1/typed-timedness.md @@ -1,4 +1,4 @@ -# [S] A track is all timed or all untimed +# [M] A track is all timed or all untimed ## Goal From ce5d4a490db0a761e3e895d1edc2c2a44aeab110 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 5 Oct 2026 12:01:58 -0700 Subject: [PATCH 3/3] quest: tighten typed-timedness and hls-first-catalog per review Co-Authored-By: Claude Opus 5.5 --- quest/m1/hls-first-catalog.md | 13 ++++++++----- quest/m1/typed-timedness.md | 16 ++++++++++------ 2 files changed, 18 insertions(+), 11 deletions(-) diff --git a/quest/m1/hls-first-catalog.md b/quest/m1/hls-first-catalog.md index 9ef9548f54c..af5b35af1fd 100644 --- a/quest/m1/hls-first-catalog.md +++ b/quest/m1/hls-first-catalog.md @@ -3,8 +3,9 @@ ## Goal moq-hls import holds its first catalog until every rendition selected from -the master playlist has reserved its tracks, so a consumer never sees a first -catalog with only the first rendition. +the master playlist that loads its init segment in the first pass has +reserved its tracks, so a consumer never sees a first catalog with only the +first rendition. Today each rendition's importer, and its `catalog.reserve()`, is created lazily in `TrackState::ensure_map` (`rs/moq-hls/src/import.rs`) while `step` @@ -25,9 +26,11 @@ Guidance: - `step` already holds a pass-wide timeline reservation for the same reason ("a record flushed mid-pass would omit every rendition that hasn't loaded its init segment yet"). A catalog `Reserved` held the same way, at least - across the first pass, is the likely shape. -- Don't let a hold outlive its pass. A rendition that fails at startup under - `OnError::Warn` must not withhold the catalog for the whole import, and a + across the first pass, is the likely shape: taken after `ensure_tracks` + and before the first `ingest`, beside the timeline reservation. +- Don't let a hold outlive its pass. A rendition with no segments yet never + reaches `ensure_map`, and one whose init fetch fails under `OnError::Warn` + never reserves. Neither may withhold the catalog for the whole import, and a live `Reserved` withholds it (see [Shared import clock](/quest/m1/shared-clock.md), which rejected sharing offsets through one for that reason). diff --git a/quest/m1/typed-timedness.md b/quest/m1/typed-timedness.md index 4f4d30c7195..65684be1f94 100644 --- a/quest/m1/typed-timedness.md +++ b/quest/m1/typed-timedness.md @@ -17,7 +17,8 @@ example `track::Timed` and `track::Untimed`, and settle the shape that Mirror the shape in `@moq/net` and the bindings. The IETF receive path follows the same rule, and -`drafts/draft-lcurley-moq-timestamp.md` says so: +`drafts/draft-lcurley-moq-timestamp.md` must say so (today it says the +opposite): - On a track accepted without TIMESCALE, an object's own object-scope TIMESCALE and Timestamp are ignored, and the track stays untimed. @@ -55,18 +56,21 @@ stamps): - Object-scope TIMESCALE overrides are no longer applied on any track. - The draft changes ship in this quest's PR, with the implementation, not in a separate draft PR first. In `drafts/draft-lcurley-moq-timestamp.md`, - three rules change: a publisher stamping every object on a TIMESCALE track + four rules change: a publisher stamping every object on a TIMESCALE track becomes a requirement rather than a SHOULD, a missing Timestamp is - malformed instead of falling back to arrival time, and receivers stop - applying object-scope TIMESCALE overrides. Check the lite draft's per-track - rule too, and update it if it differs. + malformed instead of falling back to arrival time, receivers stop + applying object-scope TIMESCALE overrides, and a LOC receiver may no + longer read a bare Timestamp on a track without TIMESCALE as + microseconds. Check the lite draft's per-track rule too, and update it if + it differs. Look out for: - Where an untimed track's frames still need ordering or "has a frame" answers (group start, expiry, the live edge), without a timestamp to read. - Which objects the malformed rule covers. Status-only objects (End of - Group, End of Track) and an empty LOC end marker carry no media time. + Group, End of Track), an empty LOC end marker, and the keep-alives and gap + markers the draft exempts today carry no media time. Before landing, check that our publishers and any interop peer that sends TIMESCALE stamp every object the rule covers. - lite-05 and lite-06 always send a Timescale, so an untimed track goes out