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/m0/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@ a published `@moq/watch` break.
- [Request caps](/quest/m0/request-caps.md) - lite message sizes, IETF request IDs, and per-session announces and subscriptions are bounded
- [Prefix route fronts](/quest/m0/prefix-route-fronts.md) - a prefix route cannot be made to mint one front per requested path
- [qmux credit](/quest/m0/qmux-credit.md) - qmux returns connection credit for dropped and stopped streams and delivers its close frame, on both lines
- [web-transport releases the qmux fixes](/quest/m0/qmux-credit-upstream.md) - waiting on moq-dev/web-transport#412 and #413 to merge and ship, which qmux credit bumps to
- [Broadcast epochs](/quest/m0/broadcast-epoch/README.md) - every first-party publisher that can restart mints a fresh route epoch, the newest wins a path, and only routes with the same epoch resume a subscription
- [Audio jitter target](/quest/m0/audio-jitter-target/README.md) - the audio playout target is a measured estimate of arrival timing in both languages, not a round-trip guess

Expand Down
12 changes: 8 additions & 4 deletions quest/m0/broadcast-epoch/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,14 @@ A path and the epoch on its route are the only content identity, and no
first-party publisher reuses a pair for different content. Only routes with
the same epoch resume a subscription from the first frame it lacks; a route
without one keeps its subscriptions until it goes. So epochs are what make
failover seamless, and a restart is a new epoch at the same path: the newest
epoch wins new requests and announce consumers see a `Restart` (or an end
and start on older versions), so viewers re-request rather than stall on a
replaced broadcast. Subscriptions already on the old one stay until the
failover seamless. Routes without an epoch never splice (maintainer,
2026-10-08): a `Restart` (or an end and start on older versions) tells every
downstream subscriber to stop using its copy of the old source and
resubscribe fresh; a downstream relay retires its copy for new requests and
forwards the `Restart`. A restart is a new epoch at the same
path: the newest epoch wins new requests and announce consumers see that
`Restart`, so viewers re-request rather than stall on a replaced
broadcast. Subscriptions already on the old one stay until the
application drops them or its route goes. Without an epoch, a restarted
publisher on the same hop chain as its lingering old session wins at once
(the newest announcement breaks the tie), but one on a different chain of
Expand Down
9 changes: 8 additions & 1 deletion quest/m0/broadcast-epoch/apps.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,14 @@ switches to a republish within an RTT. Logs show the epoch.
archive replay, WHEP import, and transcode output; moq-boy; `@moq/publish`,
the clock, and moq-boy's viewer feedback. What remains is below.
- Watch sides handle "the broadcast changed" as a fresh catalog and decoder
reset. Test a republish mid-playback in the browser and native players.
reset. Players (`moq play`, `@moq/watch`, demo/web) start on `Start`,
restart on `Restart`, and stop on `End`, so a re-price or a same-epoch
failover (an `Update`) never restarts playback. #4970, which drove them
from announcements, closed unmerged. Test a republish mid-playback in the
browser and native players.
- Update `doc/bin/cli.md` and every example invocation that shows a published
path.

## Required

- [Restart](/quest/m0/broadcast-epoch/restart.md) - the `Restart` announce event the players follow
15 changes: 11 additions & 4 deletions quest/m0/broadcast-epoch/bindings.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,19 @@

`moq-ffi` and the py, swift, kt, go, and dart wrappers can announce an epoch like Rust, with a minting helper. The generated C and C++
bindings pick it up from moq-ffi; libmoq gets no new API. The epoch on an announced route is
readable, and a publisher can pass an explicit one. The
reconnect counter `session.epoch()` is renamed so "epoch" has one meaning.
readable, and a publisher can pass an explicit one. Every wrapper surfaces
the `Restart` announce event. The reconnect counter `session.epoch()` is
renamed so "epoch" has one meaning.

## Plan

- Expose the parsed epoch (text and time) and an explicit-epoch publish
argument. Keep the surface to what a binding consumer needs.
- Rename `session.epoch()` in every binding (for example to `connects()`).
That is a break.
- Rename the reconnect counter, `moq_tokio::Connection::epoch()` and
`session.epoch()` in every binding (for example to `connects()`). That is
a break.
- `MoqAnnounceEvent::Restart` lands in moq-ffi with
[Restart](/quest/m0/broadcast-epoch/restart.md); each wrapper maps it.
- Update `doc/lib/{py,swift,kt,go,dart}` per the cross-package sync table,
and run `just test smoke --all`.

Expand All @@ -23,3 +27,6 @@ Decided in the 2026-10-05 audit: this lands before the
same wrappers and keeps `epoch()` today. It rebases onto this quest and
adopts the epoch surface and the rename, so the wrappers break once each.

## Required

- [Restart](/quest/m0/broadcast-epoch/restart.md) - adds the `Restart` announce event the wrappers expose
42 changes: 32 additions & 10 deletions quest/m0/broadcast-epoch/restart.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,15 @@ route goes, so the application decides whether to stay on the old broadcast
or follow the new one. New requests resolve the current winner and never join
a front pinned to a replaced route.

Routes without an epoch never splice (maintainer, 2026-10-08). A `Restart`
(or an `End` then `Start` on older wires) tells every downstream subscriber
to stop using its copy of the old source and resubscribe fresh. A downstream
relay retires its copy for new requests and forwards the `Restart`; the
subscriptions already on that copy follow it as their own applications
decide. A copy resumes or splices only across routes with an
identical epoch, so the old copy's cached groups never reach a subscriber of
the new source.

## Plan

Decided in planning (2026-10-07, from #4970's review):
Expand Down Expand Up @@ -59,7 +68,9 @@ Decided in planning (2026-10-07, from #4970's review):
epoch no longer ends subscriptions in flight with `Unroutable`
(`Pick::Superseded`, `front.rs` `supersede`). The front keeps serving its
subscribers until its route goes. A relay keeps its upstream subscription
on the old route while any downstream still holds it. JS `route()`
on the old route while any downstream still holds it, serving only those
subscriptions: it forwards the `Restart` so they resubscribe, and no new
request joins that copy. JS `route()`
(`js/net/src/origin.ts`) closes the old front when it swaps to a better
entry, so it changes too. Update the epoch tests from #4942 and the three
gateway tests that assert `Unroutable` (`a_reconnect_replaces_the_stale_*`
Expand All @@ -71,7 +82,11 @@ Decided in planning (2026-10-07, from #4970's review):
stays on its first route (`pick`'s `Some(None)` arm in `origin.rs`, the
module docs in `model/front.rs`), so a request joins it even after the
winner changed, and a player that re-requests gets the dead broadcast
again. JS already swaps per path.
again. JS already swaps per path. The same holds when the route entry
stays put but its source changed behind it, as for a downstream relay
whose upstream session delivers the `Restart` (or END then START): the
relay retires that copy for new requests and opens a fresh one, never
joining or resuming into the old copy.
- **Wire.** lite-07 (`moq-lite-07-wip`) gains an explicit restart message on
the announce stream. Older lite versions and moq-transport send
`ANNOUNCE_END` then `ANNOUNCE_START` for a source change, a new rule for a
Expand All @@ -86,13 +101,17 @@ Decided in planning (2026-10-07, from #4970's review):
lite-07 changelog's "ends subscriptions to the older one". The rule that a
subscription between routes without an Epoch "stays on its route and ends
with it" holds as written.
- **Players.** `moq play` (#4970) and `@moq/watch` restart on `Restart`
instead of treating every epochless `Update` as a restart, so a re-price
that keeps its winner, or a same-epoch failover, no longer restarts
playback. An epochless drain onto a different entry still does.
`moqsrc` (planned in #4960) switches on `Restart` too. On lite-06 and
- **Players** follow `Restart` in [Apps](/quest/m0/broadcast-epoch/apps.md);
`moqsrc` (planned in #4960) switches on it too. On lite-06 and
moq-transport, a pair not coalesced reaches players as `End` then
`Start`: a stop, then a fresh play.
- **Every Rust consumer** of announce events handles `Restart` in the same
PR, since the enum match is exhaustive: moq-ffi's `MoqAnnounceEvent` gains
`Restart` (its wrappers follow in
[Bindings](/quest/m0/broadcast-epoch/bindings.md)), and moq-c, moq-stats,
moq-relay, moq-room, moq-boy, moq-cli, moq-rtc, moq-tokio, and moq-bench
map it. `rs/hang/examples/subscribe.rs` compiles through its catch-all arm
but must follow a `Restart` rather than bail on it.
- **Rejected** (in #5013): `@moq/watch` resubscribing on `Internal` or
`SessionClosed` (#4999), since players recover on announcements, not
errors; announcing only once the old front dies, since viewers stay blank
Expand All @@ -118,8 +137,11 @@ on `B`. Add a regression case where an epochless replacement at equal cost
and chain length, on a different hop chain whose hash is the larger one (the
pinned `pool/job-0` pair in `origin.rs` has one), competes with the lingering
old route: no `Restart` and new requests stay on the old route until it is
withdrawn, then `Restart` and a re-request lands on the replacement. Run
`just drafts check` and `just test interop --all`.
withdrawn, then `Restart` and a re-request lands on the replacement. With
mocked time, a lite-06 relay chain where an epochless publisher restarts: the
downstream relay's cached groups from the old instance never reach a new
subscriber mixed with the new instance's groups. Run `just drafts check` and
`just test interop --all`.

Docs: update `doc/concept/moq-lite.md` (publisher epochs) and
`doc/lib/{rs,js}` announce sections inline, plus `doc/bin/rtmp.md`,
Expand All @@ -134,4 +156,4 @@ send END then START where they sent UPDATE for a source change.

## Related

- [Apps](/quest/m0/broadcast-epoch/apps.md) - #4970 drives `@moq/watch` and `moq play` from announcements, which this relies on
- [Apps](/quest/m0/broadcast-epoch/apps.md) - the players that follow `Restart`
10 changes: 7 additions & 3 deletions quest/m0/broadcast-epoch/ts-restart.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,9 @@ and a flagged forward jump publishes break markers and carries on.
Decided (maintainer, 2026-09-30):

- A rewind is new content, so it is always a new broadcast at a new epoch,
never a continuation of the old one. Viewers follow it because the newest
epoch wins the path.
never a continuation of the old one. The newest epoch wins the path, and
viewers follow the `Restart` announce it produces (an end and start on
older versions).
- `decode` stops at the flagged rewind and reports it. The caller finishes the
old broadcast (a clean end, not an abort, so its viewers read to its end),
publishes a new broadcast at the same path, minting a fresh epoch, and calls
Expand All @@ -43,7 +44,10 @@ connection carries both epochs. Update `doc/bin/cli.md` and `doc/bin/srt.md`.
Public API: breaking in moq-mux, `ts::Import::decode` reports a restart
and `restart` is new. Wire: none.


## Closes

- [#4582](https://github.com/moq-dev/moq/issues/4582) - a signalled backward TS discontinuity ends the import

## Related

- [Restart](/quest/m0/broadcast-epoch/restart.md) - the announce event viewers follow onto the new epoch
14 changes: 14 additions & 0 deletions quest/m0/qmux-credit-upstream.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# [XS] web-transport releases the qmux credit and close fixes

## Goal

Waiting on moq-dev/web-transport: the qmux credit and close fixes merge and
ship in a 0.6.x release and a 0.5.x release after 0.5.2. Check with
`gh pr view 412 -R moq-dev/web-transport` (0.6, targets `main`), the same for
413 (0.5, targets `qmux-v0.5.x`), and the published `qmux` versions on
crates.io. Advance it by pushing the upstream review along. Delete this quest
once both releases are out.

## Related

- [qmux credit](/quest/m0/qmux-credit.md) - bumps `main` and `release` once these ship
9 changes: 6 additions & 3 deletions quest/m0/qmux-credit.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,16 +43,19 @@ targets `qmux-v0.5.x`):
delivering past its initial window, and a peer reads the close code after a
close issued mid-write.

Remaining: merge both, release patched 0.5.x (after 0.5.2) and 0.6.x
containing them, then bump `main` to that 0.6.x and backport `release`'s pin
to that 0.5.x. `release` stays on 0.5: 0.6 needs web-transport-trait 0.5, a
Remaining here, once both ship: bump `main` to that 0.6.x and backport
`release`'s pin to that 0.5.x. `release` stays on 0.5: 0.6 needs web-transport-trait 0.5, a
breaking change.

Why m0: the WebSocket fallback and the planned edge-to-core `tls://` links
both run on qmux, and MoQ drops streams constantly.

Public API: none. Wire: none.

## Required

- [web-transport releases the fixes](/quest/m0/qmux-credit-upstream.md) - #412 and #413 merge and ship as patched 0.6.x and 0.5.x

## Related

- [qmux on noq-proto](/quest/m2/quic-qmux.md) - replaces these stream maps later
1 change: 1 addition & 0 deletions quest/m1/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -159,6 +159,7 @@ blocks. The quests that gated m0 lines moved under them.
- [MSF caption roles](/quest/m1/captions-msf.md) - an MSF caption or subtitle track survives conversion to a hang catalog
- [Encoder colour](/quest/m1/color-model.md) - every moq-video encode path signals the colour its output actually has, or refuses instead of mislabelling
- [T-STD TS export](/quest/m1/tstd/README.md) - `moq export ts` is a proper remux that passes the T-STD buffer model, starting with a fixed `--delay`
- [Rust non-continuous signal](/quest/m1/rust-continuous.md) - the Rust container consumer reports a frame after a subscribe or discontinuity as non-continuous, like JS, for the tune-in and warmup trims
- [Open-GOP leading pictures](/quest/m1/open-gop-leading-pictures.md) - a viewer joining at a recovery point drops the leading pictures it cannot decode; continuous viewers keep them
- [Watch decode errors](/quest/m1/watch-decode-error.md) - a WebCodecs error ends the subscription and the element reports it
- [Catalog warmup](/quest/m1/catalog-warmup.md) - `warmup` on video and audio renditions, in the catalog and the draft
Expand Down
5 changes: 4 additions & 1 deletion quest/m1/archive/dvr.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,10 @@ timeline (decided 10-05), so an HLS seek past it needs the explicit
no linger (the `hls-linger` quest was dropped, because an unannounced
broadcast can't be FETCHed and a linger would only serve the cache). Test
the handover: a live HLS session keeps its playlist URIs and media sequence
numbers when the name moves from the live publisher to the archive.
numbers when the name moves from the live publisher to the archive, which
announces a fresh epoch ([Replay
catalog](/quest/m1/archive/replay-catalog.md)), so viewers follow a
`Restart` rather than resume.

## Required

Expand Down
10 changes: 10 additions & 0 deletions quest/m1/archive/replay-catalog.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,16 @@ this by hand-building a catalog.
`moq-cli` only passes the URL and the opt-out. Select the catalog track by
catalog format as `export archive` does: hang and hang.z are stamped, MSF
is refused.
- The replay keeps minting a fresh epoch per run (#4942), so a
live-to-archive handover at one path is a `Restart`, not a resume (decided
in the 2026-10-08 audit, after #5043's review). Reusing the recorded
`.info` epoch was rejected for now: the archive writes its own
`<track>.timeline.z` groups under the live names, and this quest rewrites
catalog groups, so the same name, epoch, and group number could carry
different bytes. Revisit only once replayed metadata is byte- and
sequence-identical to live. So `moq import archive` refuses `--epoch`
(`takes_epoch` false for `Archive`), and any `moq-archive` host mints its
own epoch or takes one from its caller, never defaulting to `.info`'s.
- The recorded catalog's `archive` entry describes the source's live
timelines, not the recording's, so replace it with the timelines the reader
replays rather than trusting the recorded ones.
Expand Down
4 changes: 2 additions & 2 deletions quest/m1/assets-release.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ this quest and every `Required` entry that links it.

## Plan

As of 2026-10-02 `main` carries `assets()` and the newest releases predate it
(`@moq/watch` 0.6.1, `@moq/publish` 0.5.1 in the repo). Check with
As of 2026-10-08 `main` carries `assets()` (#4518) but `release` does not, so
the newest releases (`@moq/watch` 0.6.2, `@moq/publish` 0.5.2) still lack it. Check with
`npm view @moq/watch version` and `npm view @moq/publish version` for a newer
version, then confirm its `exports` lists `./assets/*`.
5 changes: 4 additions & 1 deletion quest/m1/audio-encode-audiotoolbox.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,10 @@
## Goal

On macOS and iOS, `Codec::Aac` encodes through AudioToolbox at the input's
layout, up to 7.1, and the result plays in the browser, `moq play`, and OBS.
layout, mono through 5.1 and 7.1, and the result plays in the browser,
`moq play`, and OBS. 6.1 is refused: since #4973 a synthesized ASC names no
program config element. Carrying the converter's magic cookie verbatim would
lift that once a caller needs it.

## Plan

Expand Down
6 changes: 4 additions & 2 deletions quest/m1/audio-warmup.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,8 @@ frames decode independently and set nothing; HE-AAC is out of scope.
publish `warmup` for Opus; `js/publish` does the same for its Opus track.
- `rs/moq-audio/src/decode` already trims Opus `pre_skip` at stream start;
the warmup trim is the same mechanism keyed on the container consumer's
non-continuous signal (added in Rust by the open-GOP quest), and the
non-continuous signal (added in Rust by
[Rust non-continuous signal](/quest/m1/rust-continuous.md)), and the
subscription's maximum age grows by `warmup` as the video consumer quest
does. `js/watch` audio mirrors it.
- The trim replaces `LEGACY_WARMUP_CALLBACKS` in `js/watch/src/audio/decoder.ts`,
Expand All @@ -28,8 +29,9 @@ frames decode independently and set nothing; HE-AAC is out of scope.
## Required

- [Catalog warmup](/quest/m1/catalog-warmup.md) - the field this reads and writes
- [Open-GOP leading pictures](/quest/m1/open-gop-leading-pictures.md) - adds the Rust non-continuous signal the trim keys on
- [Rust non-continuous signal](/quest/m1/rust-continuous.md) - the signal the trim keys on

## Related

- [Open-GOP leading pictures](/quest/m1/open-gop-leading-pictures.md) - trims video at tune-in from the same signal
- [Intra-refresh GOPs](/quest/m2/intra-refresh/README.md) - the video side of the same field
2 changes: 1 addition & 1 deletion quest/m1/bbr-ack-cleanup.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ packet-lifetime comments inline; no new user guide is needed.

## Required

- [Hard fork](/quest/m1/quic/fork/README.md) - lands in `moq-quic`, not the frozen fork
- [Switch](/quest/m1/quic/fork/switch.md) - MoQ runs on `moq-quic`, where this lands; the core and its BBR3 are already in `rs/moq-quic`

## Related

Expand Down
1 change: 1 addition & 0 deletions quest/m1/c/package.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,3 +31,4 @@ under the same names.
## Required

- [FFI shape](/quest/m1/ffi-shape/README.md) - moq-c 0.8.0 ships the reshaped moq-ffi, so C breaks once
- [C++ package](/quest/m1/cpp/README.md) - the `cpp/moq` build, generator pin, and release workflow this mirrors (#4079)
10 changes: 7 additions & 3 deletions quest/m1/c/retire.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,22 @@

## Goal

The hand-written C crate is gone: its last release points users at the
generated `moq-c` 0.8.0, and the source, workflows, and docs that only served
The hand-written C crate is gone: its final `moq-c` 0.7.x release points
users at the generated `moq-c` 0.8.0, and the source, workflows, and docs that only served
it are deleted. `doc/setup/upgrade.md` tells C users how to move.

## Plan

- #4288 renamed libmoq to `moq-c` and left a code-free `rs/libmoq` stub
whose last release points at `moq-c`;
`quest/m1/libmoq-retire.md` deletes that stub. This quest retires the
[Retire the libmoq stub](/quest/m1/libmoq-retire.md) deletes that stub. This quest retires the
hand-written `rs/moq-c` itself, so fold in or delete that quest, whichever
is still open.

## Required

- [C consumers](/quest/m1/c/consumers.md) - nothing in the repository still calls the hand-written ABI

## Related

- [Retire the libmoq stub](/quest/m1/libmoq-retire.md) - deletes the `rs/libmoq` stub under the old name
Loading
Loading