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
1 change: 1 addition & 0 deletions quest/m1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,7 @@ QUIC studies there on that rule.
- [Ship capture and playback](/quest/m1/cli-packaging.md) - a released moq binary can capture and play, which no distribution currently enables
- [Install with moq.sh](/quest/m1/moq-sh.md) - `curl -fsSL https://moq.sh | sh` installs or upgrades the released `moq` on macOS and Linux
- [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
Expand Down
48 changes: 48 additions & 0 deletions quest/m1/hls-first-catalog.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
# [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 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`
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: 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).
- 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
48 changes: 42 additions & 6 deletions quest/m1/typed-timedness.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# [S] A track is all timed or all untimed
# [M] A track is all timed or all untimed

## Goal

Expand All @@ -16,6 +16,15 @@ 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` 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.
- On a track that declares TIMESCALE, an object without TIMESTAMP makes the
track malformed.

## Plan

Decided (2026-10-05, maintainer):
Expand All @@ -32,19 +41,46 @@ 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`,
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, 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.
- 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), 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
there as timed, with the encoder's send time, as
[Untimed model](/quest/m1/untimed-model.md) decided.
- Callers built on `Timed`: [Publishing never invents a
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.
22 changes: 13 additions & 9 deletions quest/m1/untimed-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
Loading