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: 4 additions & 0 deletions quest/m0/broadcast-epoch/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,9 @@ Decided:
[Stats epochs](/quest/m1/stats-epoch.md), which also gates the release
(decided 2026-10-04): a restarted stats node under a reused name stalls its
viewers the same way.
- [Retracted demand release](/quest/m1/unannounce-demand-release.md) also
gates the release (decided 2026-10-05): a regression from #4741 on main that
`release` lacks.
- Derived output mirrors the epoch it came from
(`.pro/transcode/<pid>/foo.hang/@e`, per the
[wildcard](/quest/m0/wildcard/README.md) line's derived-output layout), so
Expand All @@ -80,3 +83,4 @@ This README owns:
- [GStreamer and OBS](/quest/m0/broadcast-epoch/gst-obs.md) - moqsink and the OBS plugin publish each run under a fresh epoch
- [Remove `--hop`](/quest/m0/broadcast-epoch/hop-removal.md) - `moq` takes an optional `--epoch` instead of `--hop`, a plain publisher declares a random Hop ID, and the per-session hop stamp and NO_CAPACITY are gone
- [Stats epochs](/quest/m1/stats-epoch.md) - moq-stats publishes each node under its own epoch, so a restarted node never stalls its viewers
- [Retracted demand release](/quest/m1/unannounce-demand-release.md) - a retracted broadcast's track demand is released when its last subscriber leaves, as before #4741
7 changes: 5 additions & 2 deletions quest/m1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,12 +50,14 @@ QUIC studies there on that rule.
- [DTX timestamps](/quest/m1/opus-dtx-timestamps.md) - Opus DTX keeps the capture timeline, so voice enables it by default again
- [LIFO cleanups](/quest/m1/signals-lifo.md) - signals effects clean up last-in, first-out, so nested teardown runs first
- [Still screen share](/quest/m1/capture-still-frame.md) - video capture keeps its latest frame and replays it, re-stamped, to late subscribers
- [Spent capture budget errors](/quest/m1/capture-exhausted-error.md) - a camera or microphone that runs out of retries sets `out.error` instead of failing silently
- [SUBSCRIBE_DROP](/quest/m1/subscribe-drop.md) - every stream group in a lite subscription arrives or is dropped by name, and lite-07 drops its stream count for it
- [Subscribe ranges](/quest/m1/subscribe-ranges/README.md) - a lite-07 SUBSCRIBE asks for past and live ranges in either order and replaces FETCH; relays fill misses by range, including over moq-transport
- [Live media time](/quest/m1/subscribe-live-time.md) - a lite-07 SUBSCRIBE_OK carries the publisher's current media time, so readers judge a cache against the live edge
- [Cross-relay bursts](/quest/m1/cross-relay-bursts.md) - bursty small-group tracks cross two relays without lost groups, unanswered FETCHes, or stalls
- [Fetched heads stay visible](/quest/m1/lite07-head-fetch-arrival.md) - on lite-07, a relay fetching the head of a group it receives mid-group still delivers that group to new subscribers
- [Late lower groups](/quest/m1/lite-late-lower-group.md) - a moq-lite subscriber with a floor receives a group created below the first served one, as moq-transport does
- [IETF rejoin keeps the open group](/quest/m1/ietf-rejoin-open-group.md) - on moq-transport-19/22, a reader that rejoins mid-group still receives the open group's later frames
- [JS cache window](/quest/m1/js-prune-cache-window.md) - js/net ages idle groups on a cache window and keeps max_age as media-time staleness, as Rust does
- [JSON stream budget](/quest/m1/json-stream-budget.md) - an oversized JSON stream record is refused without ending the log, and a JS subscribe to a gone track answers NotFound
- [A watch and publish release ships assets()](/quest/m1/assets-release.md) - the release that lets the sites host the worklets
Expand All @@ -77,10 +79,11 @@ QUIC studies there on that rule.
- [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
- [JS publishing never invents a timestamp](/quest/m1/js-publish-timestamp.md) - the same in @moq/json, @moq/flate, and @moq/net
- [Untimed model](/quest/m1/untimed-model.md) - moq-net frames and datagrams carry an absent timestamp to every subscriber; no receiver fills in arrival time
- [Typed timedness](/quest/m1/typed-timedness.md) - a track is all timed or all untimed, `Info.timescale` is optional, and `Timed` loses its clock parameter, in Rust, JS, and the bindings
- [Untimed model](/quest/m1/untimed-model.md) - an untimed moq-net track reaches every subscriber untimed; no receiver fills in arrival time
- [Untimed failover](/quest/m1/untimed-failover.md) - a resumed group no route continues is given up even when media time can't judge its drift
- [JS untimed model](/quest/m1/js-untimed-model.md) - the same in @moq/net
- [Untimed lite-07](/quest/m1/lite-untimed.md) - lite-07 encodes an absent timestamp in both languages; lite-05/06 write send time
- [Untimed lite-07](/quest/m1/lite-untimed.md) - lite-07 carries an untimed track in both languages; lite-05/06 write send time
- [Plan: untimed verbatim PES](/quest/m1/plan-ts-pes-untimed.md) - decide how a verbatim TS track carries a PES that has no PTS, then write the implementation quest
- [Data consumer timestamps](/quest/m1/data-consumer-timestamps.md) - json and binary consumers return each value's timestamp, in Rust and every binding; snapshots add `latest()` beside an in-order `next()`
- [JS data consumer timestamps](/quest/m1/js-data-consumer-timestamps.md) - @moq/json and @moq/flate consumers return each value's timestamp, with snapshot `next()` and `latest()`
Expand Down
16 changes: 16 additions & 0 deletions quest/m1/capture-exhausted-error.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# [XS] A spent capture retry budget reports its error

## Goal

When an ended camera or microphone track uses up the `Retry` budget in
js/publish (`js/publish/src/source/{camera,microphone,retry}.ts`), `out.error`
is set to the last error instead of the capture failing silently. A
regression test covers it.

## Plan

An open failure that spends the budget already sets `out.error`. A track that
ends calls `Retry.failed()` from its `ended` handler, and nothing reports it
when that was the last attempt. The gap predates #4827.

Public API: none. Wire: none.
4 changes: 3 additions & 1 deletion quest/m1/cmaf-frame-timestamp.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,9 @@ shifts `trun` data offsets.
Open PR [#4826](https://github.com/moq-dev/moq/pull/4826) implements this. It
lands after [#4822](https://github.com/moq-dev/moq/pull/4822)
([untimed model](/quest/m1/untimed-model.md)), which brings untimed frames to
`main` and itself waits on a typed-timedness mock-up quest.
`main` and itself waits on the [typed timedness](/quest/m1/typed-timedness.md)
mock-up. Timedness is per track there, so the decoder can check the track
rather than each frame.

Test: in Rust and JS, a fragment whose `tfdt` disagrees with its frame
timestamp decodes at the frame timestamp, with B-frame offsets preserved, and
Expand Down
25 changes: 25 additions & 0 deletions quest/m1/ietf-rejoin-open-group.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# [S] A rejoined IETF reader keeps its open group

## Goal

On moq-transport-19 and 22, a client that leaves a track and rejoins while a
group is still open keeps receiving that group's later frames. Today the
rejoined client's open group ends with `Ok(None)` before the next frame.

## Plan

Repro: in `rejoin_mid_group_keeps_the_head_for_later_readers`
(`rs/moq-net/tests/rejoin.rs`, from #4828), write a frame `a1` to the open
group after the later relay reader's head check, and assert the rejoined
reader gets `a1`. It passes on every lite version and fails on IETF 19 and
22. A first subscription on IETF does receive the later frames, so the loss
is specific to the rejoin.

When fixed, keep the later-frame assertion in that test for every version.

Public API: none. Wire: none.

## Related

- [Fetched heads stay visible](/quest/m1/lite07-head-fetch-arrival.md) - another mid-group join that loses part of a group
- [Rejoin after the copy goes idle](/quest/m1/test-flakes-2/rejoin-idle-race.md) - a different IETF rejoin bug, serving a stale cache
4 changes: 4 additions & 0 deletions quest/m1/ietf-timestamp-units.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,10 @@ drafts 14-16 carry timestamps without units. The Rust subscriber ignores them.
Gate the Timestamp property on a timescale actually sent. Check js/net's
`stamped` flag (`js/net/src/ietf/publisher.ts`) for the same gap.

Confirmed 2026-10-05 by [Typed timedness](/quest/m1/typed-timedness.md):
tracks on drafts 14-16 are untimed, so sending none there is the plan, not
an object-scope TIMESCALE beside each Timestamp.

Before landing, check whether an interop peer on draft-14 reads the Timestamp
property without TIMESCALE. If one does, ask whether to keep it.

Expand Down
36 changes: 21 additions & 15 deletions quest/m1/js-untimed-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,9 @@
## Goal

`@moq/net` mirrors [moq-net carries untimed frames
faithfully](/quest/m1/untimed-model.md). A frame or datagram without a
timestamp stays untimed from publisher to consumer, and js/net never fills in
`Timestamp.now()` on receive. Covers `@moq/net` and its in-repo callers
faithfully](/quest/m1/untimed-model.md). An untimed track stays untimed from
publisher to consumer, and js/net never fills in `Timestamp.now()` on
receive. Covers `@moq/net` and its in-repo callers
(`@moq/hang`, `@moq/loc`, `@moq/watch`).

## Plan
Expand All @@ -16,6 +16,10 @@ long-running and would stall the JS timestamp quests. Whichever lands second
absorbs the other. The semantics, the end-marker rule and the reasons are in
the Rust quest; keep the two in step.

Decided (2026-10-05): timedness is per track, in the shape [Typed
timedness](/quest/m1/typed-timedness.md) mirrors into `@moq/net`. Where the
notes below assume a per-frame optional timestamp, that shape wins.

Things to look out for:

- Receive-side fills: lite frames on a track with no timescale, and IETF
Expand All @@ -25,22 +29,24 @@ Things to look out for:
that an untimed track starts at the latest group.
- A track's `Info.timescale` is required today, with a default. Like Rust,
a track that never declared one must not claim a timeline downstream.
- A FETCH keeps timestamps whenever the track or the object gives units.
Only objects with neither are untimed.
- On drafts 14-16, where SUBSCRIBE_OK can't carry TIMESCALE, the publisher
writes an object-scope TIMESCALE beside each Timestamp (the `stamped` path
in `js/net/src/ietf/publisher.ts`), as Rust does once #4822 lands. This
replaces the JS half of [IETF timestamp
units](/quest/m1/ietf-timestamp-units.md), which planned to send none there.
- `Frame.timestamp` and `Datagram.timestamp` become optional. Update callers
in js/hang and js/loc (end markers) and anything in js/watch that reads
them.
- A FETCH is timed only when it learns the track's units when accepted.
- Tracks on drafts 14-16, where SUBSCRIBE_OK can't carry TIMESCALE, are
untimed (decided 2026-10-05), so the publisher sends no Timestamp there, as
[IETF timestamp units](/quest/m1/ietf-timestamp-units.md) plans. This
replaces the earlier plan to write an object-scope TIMESCALE beside each
Timestamp.
- Update callers in js/hang and js/loc (end markers) and anything in
js/watch that reads frame timestamps.

Test: an untimed frame survives a JS subscribe on each receive path. Run
`just test interop --all`.

Public API: breaking. Wire: on drafts 14-16, timed objects gain an
object-scope TIMESCALE beside the Timestamp; nothing else changes.
Public API: breaking. Wire: none beyond what IETF timestamp units
changes.

## Required

- [Typed timedness](/quest/m1/typed-timedness.md) - the per-track types this mirrors

## Related

Expand Down
14 changes: 11 additions & 3 deletions quest/m1/lite-untimed.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,22 @@
# [S] lite-07 encodes an absent timestamp
# [S] lite-07 carries an untimed track

## Goal

On moq-lite-07, an untimed frame or datagram crosses the wire as untimed in
both Rust and JS, so absence survives a lite relay hop. lite-05 and lite-06
On moq-lite-07, an untimed track's frames and datagrams cross the wire as
untimed in both Rust and JS, so absence survives a lite relay hop. lite-05 and lite-06
keep writing the encoder's send time, documented as a downgrade for old
peers. Covers `rs/moq-net`, `js/net` and `drafts/draft-lcurley-moq-lite.md`.

## Plan

Decided (2026-10-05, maintainer): timedness is per track ([Typed
timedness](/quest/m1/typed-timedness.md)), and an untimed track sends no
TIMESCALE and no Timestamp. On lite-07 that likely means an optional
Timescale in TRACK_INFO and no Timestamp fields on an untimed track. The
per-frame shift below was planned for an absent timestamp inside a timed
track, which no longer exists, so re-plan the encoding once Typed timedness
settles the shape, and drop the shift if nothing needs it.

Decided (2026-10-01, maintainer): shift the FRAME Timestamp Delta and the
DATAGRAM Timestamp by one, so 0 means absent. An absent frame doesn't move
the delta baseline. Rejected: a bare 0 as a sentinel, which collides with a
Expand Down
7 changes: 6 additions & 1 deletion quest/m1/plan-ts-pes-untimed.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,12 @@ Both are invented times, which
[moq-net carries untimed frames faithfully](/quest/m1/untimed-model.md) rules
out for moq-net itself.

Making the moq-net timestamp optional isn't enough on its own. Verbatim
Timedness is per track since 2026-10-05 ([Typed
timedness](/quest/m1/typed-timedness.md)): a timed track refuses an untimed
frame, so a PES without a PTS can only go out untimed on an untimed track.
Weigh that in the carriage decision.

An untimed track isn't enough on its own. Verbatim
tracks use the legacy container, whose payload always starts with a
timestamp, and its decoder reads the time from there, not from the frame. So
the decision covers:
Expand Down
7 changes: 5 additions & 2 deletions quest/m1/publish-timestamp.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,11 @@ fill `Timestamp::now()` (moq-net's clock, not the broadcast's), and moq-mux's
data producers fill the broadcast clock's `now()`. The FFI raw
`MoqFrame.timestamp_us` and `MoqDatagram.timestamp_us` default to 0.

- `moq_net::Timed<P, T>` keeps its name and its `at: Option<T>`; only the
meaning of `None` changes. The json/flate consumers return the same type
- `moq_net::Timed` takes the shape [Typed
timedness](/quest/m1/typed-timedness.md) settles, without its clock
parameter `T`. Timedness is per track there (decided 2026-10-05), so an
untimed payload belongs on an untimed track, and one appended to a timed
track is refused. The json/flate consumers return the same type
(see [Data consumer timestamps](/quest/m1/data-consumer-timestamps.md)).
- moq-json (snapshot, stream, and window, whose `push` always stamps now) and
moq-flate producers take `Timed<_, Timestamp>` and write `None` as untimed.
Expand Down
4 changes: 2 additions & 2 deletions quest/m1/subscribe-live-time.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,8 @@ Decided in planning (2026-10-03):
every hop adds shows up honestly.
- **Optional on the wire.** An untimed track (see
[Untimed lite-07](/quest/m1/lite-untimed.md)) has no media time, so the field
is absent, encoded the same way as an absent frame timestamp. A track whose
frames are all untimed never reports one, and no receiver invents one.
is absent, as its frame timestamps are. An untimed track never reports one,
and no receiver invents one.
- **lite-07 only.** It is still WIP (`moq-lite-07-wip`), so the field is added
without negotiation. Older versions keep the gap rule.
- **API: `track::Subscriber::live().await`** resolves once the route answered, to
Expand Down
50 changes: 50 additions & 0 deletions quest/m1/typed-timedness.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
# [S] A track is all timed or all untimed

## Goal

Prototype moq-net types that make a track all-timed or all-untimed, for
example `track::Timed` and `track::Untimed`, and settle the shape that
[#4822](https://github.com/moq-dev/moq/pull/4822) adapts to.

- `track::Info.timescale` becomes an `Option`, where `None` means untimed: no
TIMESCALE and no Timestamp on the wire, and no receiver-made local stamps.
- Appending a frame whose timedness doesn't match its track is refused, as
`Error::TimestampMismatch` already refuses a mismatched timescale.
- `moq_net::Timed` (`rs/moq-net/src/model/timed.rs`) folds into this shape,
dropping its unused clock parameter `T`. That's a breaking change and gets
an upgrade note.

Mirror the shape in `@moq/net` and the bindings.

## Plan

Decided (2026-10-05, maintainer):

- Timedness is a track property. Rejected: `Option<Timestamp>` on every frame
and groups that mix timed and untimed frames ("Option is just really
annoying as an API and revolves into a lot of unwrap()"), and a frame type
generic over its timestamp (`Frame<T>`).
- Rejected: receiver-made arrival stamps on untimed tracks.
- A receiver learns the property when it accepts the track. Drafts and
versions that can't declare it up front are untimed: IETF drafts 14-16, a
standalone FETCH that learns no timescale, and lite-01 to lite-04.
- Mock-up first, then #4822 adapts, so contributors and callers take one
breaking change instead of two. Folding `Timed`'s `T` in here, rather than
a separate quest, keeps that to one break too.

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.
- 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.
14 changes: 9 additions & 5 deletions quest/m1/untimed-failover.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,20 +25,24 @@ Decided 2026-10-05 11:39 +0200:
right after it.
- The rule: when drift can't be measured (no timed live edge, or the
successor is untimed), give up once the serving copy holds a newer group
and no route or recovery fetch can still fill this one. This applies to
mixed tracks too, so there is one rule. No clock is involved.
and no route or recovery fetch can still fill this one. No clock is
involved.
Rejected: a wall-clock deadline of `max_age` after the stall, which stands
wall time in for media time, the substitution the untimed model removed.
Also rejected: leaving it and documenting it.

Since 2026-10-05 timedness is per track ([Typed
timedness](/quest/m1/typed-timedness.md)), so no track mixes timed and
untimed groups. The rule applies to untimed tracks and to a timed track whose
drift can't be measured yet.

Settle what "nothing pending" means against the recovery fetch
(`a_pending_recovery_fetch_does_not_disable_expiry`), so a fetch about to
fill the group isn't cut short. A FETCH reader has no budget and stays as it
is.

Test: a model test in `resume.rs` failing over an all-untimed track with an
abandoned group, plus one where the successor is untimed on a timed track.
Both fail without the fix. Run each against a cold route and against one
Test: a model test in `resume.rs` failing over an untimed track with an
abandoned group. It fails without the fix. Run it against a cold route and against one
whose copy already caches untimed groups past the resumed one, so a cursor
that skips ahead can't hide the stall. #4822 is changing `Cursor::new` so an
explicit start is honoured on untimed tracks; build on that, not on the
Expand Down
Loading
Loading