From 913a692f15798bf0f8fb0069aa7f069f235d7abd Mon Sep 17 00:00:00 2001 From: Matt McClure Date: Wed, 2 Sep 2026 23:43:23 +0000 Subject: [PATCH 1/6] docs(spf): vendor MoQ draft texts and plan the moqt-20 migration Vendor draft-ietf-moq-transport-20, draft-ietf-moq-loc-04 and draft-ietf-moq-msf-01 under internal/specs/moq with provenance, point AGENTS.md at them, and record the draft-19 to draft-20 migration plan grounded in moq-relay 0.14.14's implementation. --- .agents/plans/moq-engine-implementation.md | 5 +- .agents/plans/moq-transport-20-migration.md | 392 + AGENTS.md | 1 + internal/specs/moq/README.md | 29 + internal/specs/moq/draft-ietf-moq-loc-04.txt | 1120 +++ internal/specs/moq/draft-ietf-moq-msf-01.txt | 4144 ++++++++ .../specs/moq/draft-ietf-moq-transport-20.txt | 8848 +++++++++++++++++ 7 files changed, 14538 insertions(+), 1 deletion(-) create mode 100644 .agents/plans/moq-transport-20-migration.md create mode 100644 internal/specs/moq/README.md create mode 100644 internal/specs/moq/draft-ietf-moq-loc-04.txt create mode 100644 internal/specs/moq/draft-ietf-moq-msf-01.txt create mode 100644 internal/specs/moq/draft-ietf-moq-transport-20.txt diff --git a/.agents/plans/moq-engine-implementation.md b/.agents/plans/moq-engine-implementation.md index 7e74a370f7..7085c1f851 100644 --- a/.agents/plans/moq-engine-implementation.md +++ b/.agents/plans/moq-engine-implementation.md @@ -23,7 +23,10 @@ Size baseline (2026-07-17): MoQ entry 18.16 KB min+gzip (90.8% of the Implemented against the actual spec texts (fetched 2026-07-17): `draft-ietf-moq-transport-19`, `draft-ietf-moq-msf-01`, -`draft-ietf-moq-loc-02`. Notable corrections to the plan's assumptions: +`draft-ietf-moq-loc-02` (LOC moved to loc-04 in PR #9). The spec texts are +now vendored under `internal/specs/moq/` (transport-20, loc-04, msf-01 as of +2026-09-02); the draft-20 migration plan is `moq-transport-20-migration.md` +beside this file. Notable corrections to the plan's assumptions: - **Varint is NOT the QUIC RFC 9000 varint.** Draft-15+ uses a leading-ones vi64 (1–9 bytes). Spec Table 2 vectors are test fixtures. diff --git a/.agents/plans/moq-transport-20-migration.md b/.agents/plans/moq-transport-20-migration.md new file mode 100644 index 0000000000..7d4ebdcfb9 --- /dev/null +++ b/.agents/plans/moq-transport-20-migration.md @@ -0,0 +1,392 @@ +# MoQ transport draft-20 migration plan + +Planning pass dated 2026-09-02. `draft-ietf-moq-transport-20` was published +2026-08-31 and is vendored at `internal/specs/moq/draft-ietf-moq-transport-20.txt` +(its Appendix A.1 is the authoritative change list). The code on `mmcc/moq` +and `mmcc/moq-publisher` pins draft-19 (`MOQT_PROTOCOL_ID = 'moqt-19'`). +LOC-04 and MSF-01 did not change; loc.ts already uses the loc-04 property IDs +that draft-20 §15.8 now mirrors, so no LOC/MSF code moves. + +The relay fleet (mux.global and relay.mux.dev, both updated 2026-09-02) runs +moq-relay 0.14.14, released 2026-09-01, which added `moqt-20` in moq-dev/moq +PR #3255. The update does not affect our draft-19 sessions: the relay keeps +its old behavior on `moqt-19` (current-group replay, no LARGEST_OBJECT). That implementation is the +only draft-20 peer we talk to, so this plan follows its wire behavior where +the spec text is ambiguous, and calls out each place it does. + +Temporary implementation notes — delete before merge per `AGENTS.md`. + +## What changed on the wire (draft-19 → draft-20) + +Section numbers are draft-20's. Everything after §10.9 shifted by one +because §10.10 PUBLISH_STATE_NOTIFY was inserted; §5.1.3 Fill Semantics +shifted §5.1.3–5.1.5 too. + +| Change | Spec | Kind | Affected code | +| --- | --- | --- | --- | +| ALPN / `WT-Available-Protocols` value becomes `moqt-20` | §3.1 | breaking | `MOQT_PROTOCOL_ID`; `moq-session.ts` actor passes it to `WebTransport` | +| LOCATION_FILTER re-encoded: no Filter Type; length-counted optional `StartGroup, StartObject, EndGroupDelta, EndObject` | §5.1.2, §10.2.9 | breaking | `LocationFilter`, `encodeLocationFilter`, `decodeLocationFilter` | +| Publishers honor filters to the object: a Next Object subscription starts mid-group; a subscription no longer ends when Largest Object passes its end | §5.1.2 | behavior | catalog and audio joins that relied on relays replaying the current group (see below) | +| FETCH loses Fetch Type + Standalone/Joining structures; body is `Request ID, Namespace, Name, Parameters`; range travels in LOCATION_FILTER | §10.13 | breaking | `FetchRequest`, `encodeFetch`, FETCH decoder, `MoqtFetchOptions`, `session.fetch()` | +| Joining FETCH replaced by **fill fetch streams** requested with `FILL_PARAMETERS` (0x23) | §5.1.3, §10.2.15 | breaking (behavior) | `resolve-catalog.ts` catalog join; `session.ts` if we ever request fills | +| New `PUBLISH_STATE_NOTIFY` (0x22) on subscription streams, parameters-only, no reply | §10.10 | additive but fatal if unknown | `MESSAGE_TYPE`, decoder, `#handleSubscriptionMessage` | +| New `INCLUDE_PROPERTIES` (0x35) | §10.2.21 | additive but fatal if unknown | `PARAMETER_TYPE`, `MessageParameters` codec | +| `LARGEST_OBJECT` becomes something the relay actually sends in SUBSCRIBE_OK | §10.2.17 | interop | `decodeMessageParameters` framing (see relay facts) | +| FETCH_OK End Location is "the end of the range covered", from the request's Location Filter (inclusive) | §10.14 | semantic | `FetchOk.endLocation` consumers (none in playback) | +| Fetch stream `End of Timed-Out Range` (0x20C) joins 0x8C / 0x10C | §11.4.4, §10.2.5 | additive but fatal if unknown | `readFetchEntries`, `FetchStreamEntry.status` | +| SUBGROUP_HEADER / OBJECT_DATAGRAM types described as Type Flags; ≥128 or any unspecified bit is PROTOCOL_VIOLATION | §11.3.1, §11.4.2 | none (already equivalent) | comments in `object-stream.ts`, `subgroup-writer.ts` | +| PUBLISH_DONE: `SUBSCRIPTION_ENDED` (0x3) removed; unknown Stream Count sentinel is 2^64−1; count includes fill streams | §10.12 | semantic | `PUBLISH_DONE_STATUS`, Stream Count decode | +| REQUEST_ERROR `INVALID_JOINING_REQUEST_ID` (0x32) removed | §15.11.2 | cleanup | `REQUEST_ERROR_CODE`, `PERMANENT_REQUEST_ERROR_CODES` | +| Session error `VERSION_NEGOTIATION_FAILED` (0x15) removed | §3.5 | cleanup | `SESSION_ERROR` | +| PUBLISH may carry initial subscription parameters; PUBLISH_OK carries none; the subscriber changes them via REQUEST_UPDATE | §10.11, §10.20.1 | semantic | incoming-PUBLISH `accept(parameters)` path | +| REDIRECT: Retry Interval 0 means "do not retry as sent", following the redirect is still allowed | §10.6.2 | semantic | unchanged (REDIRECT treated as permanent) | +| OBJECT_DELIVERY_TIMEOUT starts at the last header byte | §12.2 | semantic | publisher-side timers only | +| Track Alias reuse guidance for publishers | §11.1 | semantic | review `duplicate track alias` fatal and `#waitForAlias` | + +### LOCATION_FILTER field rules (§5.1.2) + +``` +LOCATION_FILTER Parameter { + Parameter Type (vi64) = 0x21, + Length (vi64), + [StartGroup (vi64),] + [StartObject (vi64),] + [EndGroupDelta (vi64),] + [EndObject (vi64),] +} +``` + +- Length 0: no filter (used in REQUEST_UPDATE to clear). +- 1 field: relative. Start = `{Largest.Group + 1 − StartGroup, 0}`. `0` = Next + Group, `1` = start of the current group, `N` = N−1 groups before it. Clamped + to `[0, 2^64−1]`. +- 2 fields: absolute start. `{0,0}` means **Next Object** (the old + Largest Object filter), not "from the beginning" — an unfiltered request + omits the parameter entirely. +- 3 fields: absolute start plus `EndGroupDelta` (end group is absolute + `StartGroup + EndGroupDelta`, whole end group included; overflow is a + PROTOCOL_VIOLATION). +- 4 fields: plus `EndObject`. +- Subscriptions with no end are open-ended; fetches with no end stop at + Largest Object. + +Mapping from today's `LocationFilter` union: `largest-object` → 2 fields +`{0,0}`; `next-group-start` → 1 field `0`; `absolute-start` → 2 fields; +`absolute-range` → 3 fields. Playback only uses the first two +(`track-subscriber.ts`, `subscribe-selected-tracks.ts`, `resolve-catalog.ts`). + +### FILL_PARAMETERS (§10.2.15), for reference + +Length-prefixed; value is `Number of Parameters (vi64)` + delta-typed +parameters. Allowed inside: FILL_TIMEOUT 0x0A, SUBSCRIBER_PRIORITY 0x20, +LOCATION_FILTER 0x21, GROUP_ORDER 0x22, range filters 0x25–0x28; anything +else is PROTOCOL_VIOLATION. Not sticky. Omitted inner parameters inherit the +subscription's. The publisher answers on a uni stream beginning with +`FETCH_HEADER` whose Request ID is the SUBSCRIBE's (or the REQUEST_UPDATE's); +no FETCH_OK; failure is a RESET; an empty range opens nothing. MSF-01's +"SUBSCRIBE with a Joining FETCH (offset 0)" (msf-01 §5) becomes, in spec +terms, a Next Object subscription plus a `StartGroup=1` fill (§5.1.6). + +We do not need fills for the relay path (next section), so requesting them +is deferred work. + +## What moq-relay 0.14.14 does (moq-dev/moq PR #3255) + +Verified against `rs/moq-net/src/ietf/{filter,subscribe,fetch,parameters, +publisher,subscriber}.rs` and `js/net/src/ietf/{filter,parameters}.ts` on +`main` at 2026-09-02. + +- **Negotiation.** Server accepts `moqt-20` through `moqt-14` plus the moq-lite + ALPNs and picks by the client's offered ALPN. moq-dev's JS client offers a + list and reads the negotiated value from `session.protocol` (cast around a + missing type; Chrome exposes it). +- **LOCATION_FILTER** is encoded per the spec rules above. An open-ended + absolute `{0,0}` is normalized to "omit the parameter". +- **Filters are honored to the object on draft-20.** `Next Object` starts at + `{Largest.Group, Largest.Object + 1}` — the already-published head of the + current group is **no longer replayed**. `Relative(N)` is served from the + group cache: `Relative(1)` replays the current group from object 0 then + continues live, on the ordinary subgroup stream. `Unfiltered` behaves like + moq-lite (start of the latest group). On draft-19 and earlier the relay keeps + its old behavior (whole current group replayed for Next Object; absolute + filters ignored). +- **The relay's own subscriber joins upstream publishers with `Relative(1)`** + and no fill, and refuses any fetch stream it did not ask for. +- **Fills are served, single-group only.** A `FILL_PARAMETERS` whose range + resolves to one group is served from the cache as a real fetch stream + (`FETCH_HEADER` + objects with absolute first IDs and timestamp properties + + FIN). Multi-group or range-filtered fills open the stream and reset it. An + omitted inner LOCATION_FILTER inherits the subscription's, so `Next Object` + + fill-without-filter is an empty fill. `LARGEST_OBJECT` is sent in + SUBSCRIBE_OK on draft-20 once the track has content. +- **FETCH is still decoded in the draft-19 shape on every version** (the PR + did not touch `fetch.rs`). Only `RelativeJoining` with offset 0 is + "accepted", and the response is FETCH_OK/REQUEST_OK plus an **empty** fetch + stream (`FETCH_HEADER`, FIN). Standalone and absolute-joining are rejected. + A spec-shaped draft-20 FETCH would be misparsed. **Never send FETCH to the + relay on draft-20.** (This also means our current catalog joining FETCH has + never returned data from this relay; the catalog resolves today only because + the relay replays the current group for Next Object subscriptions on + draft-19.) +- **SUBSCRIBE parameters accepted:** 0x02, 0x04, 0x06, 0x10, 0x20, 0x21, 0x22, + 0x23, 0x35. Any other parameter closes the session — including + AUTHORIZATION_TOKEN (0x03), so the URL-token-only auth rule still holds. + REQUEST_UPDATE accepts 0x02, 0x06, 0x10, 0x20, 0x21, 0x23. `forward: 0` is + rejected. +- **`LARGEST_OBJECT` (0x09) is framed length-prefixed** — a varint length then + two varints — on every draft, and its decoder requires that framing. The + spec text (§10.2) says a Location parameter is two bare varints. moq-dev + argues odd parameter types get a length by the Key-Value-Pair parity rule + and lists this as a spec conflict. Because the relay only sends it on + draft-20, our draft-19 sessions are unaffected today; on draft-20 our bare + decode would desync the parameter list and kill every SUBSCRIBE_OK with + content. +- **`INCLUDE_PROPERTIES` (0x35) is framed length-prefixed with a single byte + inside**, again by parity, although §10.2.21 calls it a uint8. The relay + obeys it as a publisher and sends it only to opt out (which its upstream + subscriber does not do today). +- Range filters 0x26/0x28 are length-prefixed (matches the spec's explicit + Length field and our codec). +- Draft-20 PUBLISH_OK (REQUEST_OK) carries no parameters. +- PUBLISH_DONE Stream Count is always 0. +- **Subgroup streams are checked against the Object ID:** the first object's + delta must be its absolute ID and later deltas must be contiguous. A stream + that starts partway through a group, or has a gap, is dropped per-stream. +- Not implemented by the relay: PUBLISH_STATE_NOTIFY, requesting fills as a + subscriber, multi-group fills. + +## Consequences for our engine + +1. **Catalog join must change or the catalog stops resolving.** Today + `resolve-catalog.ts` subscribes with `largest-object` and issues a + relative-joining FETCH (offset 0); the FETCH returns nothing, and the + independent catalog object arrives because the relay replays the current + group. On draft-20 a Next Object subscription delivers deltas only, which + the resolver drops until the next independent object. Join with + `Relative(1)` instead: the relay serves the current group from object 0 on + the subscription stream, then live. No FETCH at all. The live-object + buffering and settle timer that exist to order fetch replay against live + deltas are unnecessary on this path. +2. **Audio (`largest-object`) starts at the live edge instead of the current + group's start.** Correct for audio (every frame decodable) and less + pre-roll, but `joinAnchorUs` in `media/moq/timeline.ts` documents the old + replay assumption; verify `sync-latency` / `adapt-latency-target` converge + with a shorter initial buffer. +3. **Video (`next-group-start` → `Relative(0)`) and switch handoffs are + unchanged.** Optional improvement: join video with `Relative(1)` for an + instant, decodable start; the renderer already fast-forwards a backlog + behind the edge. +4. **`LARGEST_OBJECT` decode must be length-prefixed on draft-20** or the + session dies on the first SUBSCRIBE_OK with content. Use the relay's framing + on every draft (we never send it as a subscriber; nothing else sends it on + 19) and cite the conflict in the codec comment. +5. **Fills are not needed** for playback against the relay. Decode + `FILL_PARAMETERS` and `INCLUDE_PROPERTIES` so a peer sending them does not + kill a session (the publisher branch receives SUBSCRIBE), but requesting + fills and routing fill streams is deferred. +6. **FETCH stays draft-19-only** in practice: keep the joining FETCH on the 19 + path, send none on 20. Implement the spec-shaped draft-20 encoder/decoder + for completeness and tests, not for the relay. +7. **Publisher branch:** the relay will subscribe upstream with `Relative(1)`. + If the publisher only delivers from the next object, the relay drops that + mid-group stream and the join degrades to the next group boundary. Serving + the current group from object 0 (retaining the in-progress group's frames) + restores the instant join. The publisher must also send `LARGEST_OBJECT` + (length-prefixed) in SUBSCRIBE_OK on draft-20 (spec MUST once content + exists; the relay decodes it that way) and accept 0x23/0x35 on inbound + SUBSCRIBE. + +## Rollout + +The whole fleet speaks `moqt-20`, so a hard cutover is viable and is the +smaller change. Offering `['moqt-20', 'moqt-19']` and reading the negotiated +`transport.protocol`, the way moq-dev's JS client does, is worth it only if +third-party relays (Varnish lab, other draft-19 deployments) must keep +working during the transition; it costs the five branch points below and a +second test matrix. Decide before Phase 1; the codec work is the same either +way, the difference is whether the 19 paths are deleted or kept behind a +switch. + +**Decision (2026-09-02): cut over.** `feat/moq-transport-20` (off `mmcc/moq`) +speaks `moqt-20` only and deletes the draft-19 filter tags, Fetch Type +structures, and the catalog joining FETCH. The five branch points below are +kept as the list of what changes, not as runtime switches. + +Branch points on a `draft: 19 | 20` value in `createMoqtSession` config: + +1. LOCATION_FILTER encode/decode (tag form vs field list). +2. FETCH body shape (only sent on 19). +3. Catalog join: `largest-object` + joining FETCH (19) vs `Relative(1)`, no + FETCH (20). +4. Whether to expect `LARGEST_OBJECT` in SUBSCRIBE_OK (informational; framing + is the same on both). +5. Whether `FILL_PARAMETERS` / `INCLUDE_PROPERTIES` are legal on inbound + messages (publisher branch; the relay rejects them on 19 and so should we). + +## Work items + +### Phase 1 — codec (`packages/spf/src/network/moqt/`) + +`control-messages.ts` + +- Export `MOQT_PROTOCOL_IDS = ['moqt-20', 'moqt-19']`, a `MoqtDraft` type, and + a lookup from negotiated protocol string to draft. +- `MESSAGE_TYPE`: add `PUBLISH_STATE_NOTIFY: 0x22`. +- `PARAMETER_TYPE`: add `FILL_PARAMETERS: 0x23`, `INCLUDE_PROPERTIES: 0x35`. +- `REQUEST_ERROR_CODE`: drop `INVALID_JOINING_REQUEST_ID` and its entry in + `PERMANENT_REQUEST_ERROR_CODES`. +- `PUBLISH_DONE_STATUS`: drop `SUBSCRIPTION_ENDED`. +- `LocationFilter`: new union — `{ type: 'next-object' }`, + `{ type: 'relative-group'; groupsBeforeNext: number }`, + `{ type: 'absolute'; start: Location; endGroupDelta?: number; endObject?: number }`. + Encoder normalizes open-ended absolute `{0,0}` to "omit the parameter" (as + the relay does). Draft-19 tag form: `next-object` → 0x2, `relative-group 0` + → 0x1, `relative-group N>0` → throw (no tag can express it), `absolute` → + 0x3/0x4, `endObject` → throw on 19. +- `LARGEST_OBJECT`: encode and decode as length-prefixed `{group, object}` + varints on every draft; comment cites the §10.2 conflict and PR #3255. +- `MessageParameters`: add `fillParameters?: MessageParameters` (nested + `encodeMessageParameters`; decoder enforces the allow-list and rejects it on + draft-19) and `includeProperties?: 0 | 1` (length-prefixed single byte; + reject values other than 0/1; reject on draft-19). +- `FetchRequest` on 20 collapses to `{ requestId, trackNamespace, trackName, + parameters }` with the range in `parameters.locationFilter`; the 19 shapes + stay behind the draft switch. +- `ControlMessage`: add `{ kind: 'publish-state-notify'; parameters }`. +- Re-cite every `§10.x` ≥ 10.10 in comments (32 citations in this file; 12 in + `session.ts`, 6 in `object-stream.ts`, 6 in `resolve-catalog.ts`). + +`errors.ts`: drop `VERSION_NEGOTIATION_FAILED`. + +`object-stream.ts`: add `FETCH_END_OF_TIMED_OUT_RANGE = 0x20c` → +`status: 'timed-out'`; update Type Flags comments (behavior already matches). + +Tests: golden vectors for each LOCATION_FILTER field count and the +`{0,0}`-omission rule; length-prefixed LARGEST_OBJECT byte-pinned against +moq-dev's vector `[0x01, 0x09, 0x04, 0x80, 0xff, 0x80, 0x80]` for +`{255, 128}`; INCLUDE_PROPERTIES framing and range check; FILL_PARAMETERS +nesting and allow-list violation; draft-20 FETCH round-trip; +PUBLISH_STATE_NOTIFY decode; 0x20C entries. + +### Phase 2 — session driver (`session.ts`) + +- `MoqtSessionConfig.draft`; `MoqtFetchOptions` gains the draft-20 shape. +- `#handleSubscriptionMessage`: accept `'publish-state-notify'` → + `onStateNotify?(parameters)`, no reply; fatal on fetch and track-status + streams (§10.10). +- `Subscription.update()` allocates a fresh Request ID (§10.1; see + pre-existing bugs). +- PUBLISH_DONE Stream Count: saturating read so the 2^64−1 sentinel does not + kill the session (the relay sends 0, so low urgency). +- Fill-stream routing (FETCH_HEADER carrying a SUBSCRIBE or REQUEST_UPDATE + Request ID): deferred to Phase 6; until then an unexpected fetch stream for a + subscription id is cancelled, not fatal. +- Tests: PUBLISH_STATE_NOTIFY on a subscription vs a fetch stream; + REQUEST_UPDATE id uniqueness; length-prefixed LARGEST_OBJECT in SUBSCRIBE_OK + reaches `onOk`. + +### Phase 3 — playback (`packages/spf/src/playback/`) + +- `behaviors/resolve-catalog.ts`: on draft-20 subscribe with + `{ type: 'relative-group', groupsBeforeNext: 1 }` and issue no FETCH; apply + objects directly (they arrive in order on one stream). Keep the 19 path + (`largest-object` + joining FETCH + settle buffering) behind the switch and + delete it with the 19 branches. Recovery restarts keep the same filter. +- `actors/track-subscriber.ts`, `behaviors/subscribe-selected-tracks.ts`: + rename literals (`largest-object` → `next-object`, `next-group-start` → + `relative-group 0`). Decide whether video's initial join moves to + `relative-group 1`. +- Verify the audio join: with no current-group replay the first buffered + frame is the live edge; check `joinAnchorUs` callers and the latency + controller's initial depth. +- `actors/moq-session.ts`: offer both protocols, read `transport.protocol` + (cast, as moq-dev does), surface the draft on the session context and pass + it to `createMoqtSession`; refresh the draft-19 auth comments. +- Tests: `resolve-catalog.test.ts` (8 joining-fetch expectations become + draft-19-only; add the draft-20 direct-apply path), `engine.test.ts`, + `moq-session.test.ts`, `track-subscriber.test.ts`, + `subscribe-selected-tracks.test.ts` filter literals. + +### Phase 4 — sandbox templates and prose + +- `apps/sandbox/templates/spf-moq-player/loopback-relay.ts` (and the + publisher branch's `moq-publisher/loopback-relay.ts`): both hand-roll + draft-19 SETUP / SUBSCRIBE / SUBSCRIBE_OK / FETCH-reject and already replay + the newest buffered group. Under 20: parse the field-list LOCATION_FILTER, + replay the current group only for `Relative(≥1)` (mirror the relay's strict + Next Object), tolerate 0x23/0x35, send length-prefixed LARGEST_OBJECT, and + drop the FETCH branch. Update the `moqt-19` / draft-19 comments in + `spf-moq-player/main.ts`, `index.html`, `moq-relay-interop/main.ts`, + `adapt-latency-target.ts`, and the `moq-session.ts` header. +- `moq-relay-interop/main.ts`: its `relay.mux.dev` default is on 0.14.14, so + it doubles as the draft-20 smoke test once the header comment and expected + `serverImplementation` are refreshed. + +### Phase 5 — publisher branch (`mmcc/moq-publisher`) + +`packages/spf/src/publish/session/publish-session.ts` is a second session +driver on the shared codec, so Phase 1 lands the decode. Publisher-specific: + +- Serve `Relative(1)` (and `Relative(0)`, `Next Object`) per the draft-20 + rules: retain the in-progress group's frames in `track-publisher.ts` so a + `Relative(1)` subscriber gets the group from object 0 with contiguous IDs + (the relay drops a stream that starts partway through). Without this the + relay's upstream join degrades to the next group. +- Send `LARGEST_OBJECT` (length-prefixed) in SUBSCRIBE_OK on draft-20 once + the track has content. +- Inbound `FILL_PARAMETERS`: honest minimum is open-and-reset (§5.1.3.1); the + relay never sends one today. +- Inbound FETCH decode shape follows the draft; keep rejecting. +- REQUEST_UPDATE now consumes its own Request ID: the "every inbound request + ID ever seen" check must accept it as a new id. +- `subgroup-writer.ts` / `track-publisher.ts`: numbering from 0 without gaps + already satisfies the relay's check; comment updates only. +- Optional: PUBLISH_STATE_NOTIFY with LARGEST_OBJECT on capture-source + switches (the relay ignores it today). + +### Phase 6 — deferred: fills as a subscriber + +Route FETCH_HEADER streams by SUBSCRIBE / REQUEST_UPDATE Request ID to +`onFillEntry` / `onFillEnd` / `onFillReset` on the subscription, request +`FILL_PARAMETERS` with `Relative(1)` for a spec-canonical exactly-once join, +and decode End of Timed-Out Range into the fill path. Only worth doing when a +strict publisher (one that does not replay `Relative(1)` from cache) matters. + +## Pre-existing bugs this pass surfaced + +1. **REQUEST_UPDATE reuses the subscription's Request ID.** + `Subscription.update()` calls `encodeRequestUpdate(requestId, …)` with the + SUBSCRIBE's id. §10.1 (unchanged since draft-19) lists REQUEST_UPDATE + among the messages that consume a Request ID, and a duplicate id MUST close + the session with INVALID_REQUEST_ID. Latent today (no playback caller + sends REQUEST_UPDATE). +2. **PUBLISH_DONE Stream Count sentinel is undecodable.** 2^62−1 (draft-19) + and 2^64−1 (draft-20) both exceed `MAX_VARINT_VALUE` (2^53−1), so + `decodeVarint` throws and the session dies on a legitimate PUBLISH_DONE. + The relay sends 0, so this is dormant against the fleet. +3. **The catalog join depends on non-conformant relay behavior.** Our joining + FETCH has never returned data from moq-relay; the catalog resolves because + draft-19 relays replay the current group for Next Object subscriptions. + Draft-20 removes that replay, which is why item 1 under Consequences is + mandatory, not a cleanup. + +## Open questions + +- Confirm `WebTransport.protocol` is populated in the Chrome builds the + sandbox targets (moq-dev's JS relies on it with a cast). Fallback: a URL flag + selecting a single offered protocol. +- Video initial join: keep `Relative(0)` (wait for the next group, no + fast-forward) or move to `Relative(1)` (instant, decoder catches up)? Both + are served by the relay; this is a latency/CPU trade the sandbox can + measure. +- MSF-01 still mandates a Joining FETCH for the catalog; track the msf + revision so the `Relative(1)` join stays defensible against other relays. +- FETCH_OK End Location inclusivity only matters if Phase 6 or a real FETCH + path lands. + +## Estimated size + +Codec ≈ 350 lines changed, session ≈ 100, playback ≈ 150, tests ≈ 300 across +six files, each sandbox loopback ≈ 120, publisher session + track-publisher +≈ 200. Two PRs: codec + session + playback + player sandbox on `mmcc/moq`, then +the publisher follow-up on `mmcc/moq-publisher` after rebasing onto it. diff --git a/AGENTS.md b/AGENTS.md index 5102a5250e..4e1b8384e5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,6 +11,7 @@ Use this file for durable repository rules. Prefer retrieval-led reasoning: insp - Current behavior: implementation and colocated tests - Public package behavior: package source, exports, and README files - Architecture rationale: `internal/design/`, `internal/decisions/`, and `rfc/` +- Protocol drafts the MoQ stack implements: `internal/specs/moq/` (vendored IETF texts; its README lists the pinned revisions) When prose conflicts with executable sources, follow the executable source and update stale prose in the same change. diff --git a/internal/specs/moq/README.md b/internal/specs/moq/README.md new file mode 100644 index 0000000000..dedbcf8203 --- /dev/null +++ b/internal/specs/moq/README.md @@ -0,0 +1,29 @@ +# Vendored MoQ specifications + +Verbatim IETF Internet-Draft texts for the protocols the MoQ stack in `packages/spf` implements. They are vendored so reviewers and agents can cite sections without network access, and so a revision bump is a reviewable diff. + +The version the code actually speaks is declared in code: `MOQT_PROTOCOL_ID` in `packages/spf/src/network/moqt/control-messages.ts` for the transport, and the header comments of `packages/spf/src/media/moq/loc.ts` and `parse-catalog.ts` for LOC and MSF. When the vendored text is newer than the code pin, the gap is tracked by a migration plan under `.agents/plans/`. + +| Draft | Revision | Published | Implemented in | +| --- | --- | --- | --- | +| Media over QUIC Transport | `draft-ietf-moq-transport-20` | 2026-08-31 | `packages/spf/src/network/moqt/` | +| Low Overhead Media Container (LOC) | `draft-ietf-moq-loc-04` | 2026-07-20 | `packages/spf/src/media/moq/loc.ts` | +| MOQT Streaming Format (MSF) | `draft-ietf-moq-msf-01` | 2026-06-02 | `packages/spf/src/media/moq/parse-catalog.ts`, `parse-source.ts` | + +## Provenance + +Fetched 2026-09-02 from the IETF archive at `https://www.ietf.org/archive/id/.txt`, unmodified. + +| File | SHA-256 | +| --- | --- | +| `draft-ietf-moq-transport-20.txt` | `96a3a4467da53cd71bb4d1c334ac7ab13887f02b2e27335e715f75889fa9a1c6` | +| `draft-ietf-moq-loc-04.txt` | `fb29e2805be0511a188683b60fc830fb7fd3ecf19931968755d60d83707c3b47` | +| `draft-ietf-moq-msf-01.txt` | `c3e68aac09c36ae1db4afde6fd0600a949e7265348f592520304a31e993c35af` | + +Working-group sources: [moq-wg/moq-transport](https://github.com/moq-wg/moq-transport), [moq-wg/loc](https://github.com/moq-wg/loc), [moq-wg/msf](https://github.com/moq-wg/msf). Each transport revision carries a change log in Appendix A; a rendered diff against the prior revision is available at `https://author-tools.ietf.org/iddiff?url1=&url2=`. + +## Updating a draft + +1. Download the new `.txt` from the IETF archive into this directory and delete the superseded revision. +2. Update the tables above (revision, date, checksum). +3. Either update the code pin and its section citations in the same change, or write the migration plan under `.agents/plans/` and link it from the commit. diff --git a/internal/specs/moq/draft-ietf-moq-loc-04.txt b/internal/specs/moq/draft-ietf-moq-loc-04.txt new file mode 100644 index 0000000000..79ea22aeab --- /dev/null +++ b/internal/specs/moq/draft-ietf-moq-loc-04.txt @@ -0,0 +1,1120 @@ + + + + +Media Over QUIC M. Zanaty +Internet-Draft S. Nandakumar +Intended status: Standards Track Cisco +Expires: 21 January 2027 P. Thatcher + Microsoft + 20 July 2026 + + + Low Overhead Media Container + draft-ietf-moq-loc-04 + +Abstract + + This specification describes a Low Overhead Media Container (LOC) + format for encoded and encrypted audio and video media data to be + used primarily for interactive Media over QUIC Transport (MOQT). It + may be used in the MOQT Streaming Format (MSF) specification, which + defines a catalog format for publishers to declare and describe their + LOC tracks and for subscribers to consume them. Examples are also + provided for building media applications using LOC and MOQT. + +About This Document + + This note is to be removed before publishing as an RFC. + + The latest revision of this draft can be found at https://moq- + wg.github.io/loc/draft-ietf-moq-loc.html. Status information for + this document may be found at https://datatracker.ietf.org/doc/draft- + ietf-moq-loc/. + + Discussion of this document takes place on the Media Over QUIC + Working Group mailing list (mailto:moq@ietf.org), which is archived + at https://mailarchive.ietf.org/arch/browse/moq/. Subscribe at + https://www.ietf.org/mailman/listinfo/moq/. + + Source for this draft and an issue tracker can be found at + https://github.com/moq-wg/loc. + +Status of This Memo + + This Internet-Draft is submitted in full conformance with the + provisions of BCP 78 and BCP 79. + + Internet-Drafts are working documents of the Internet Engineering + Task Force (IETF). Note that other groups may also distribute + working documents as Internet-Drafts. The list of current Internet- + Drafts is at https://datatracker.ietf.org/drafts/current/. + + + + +Zanaty, et al. Expires 21 January 2027 [Page 1] + +Internet-Draft media-container July 2026 + + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as "work in progress." + + This Internet-Draft will expire on 21 January 2027. + +Copyright Notice + + Copyright (c) 2026 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents (https://trustee.ietf.org/ + license-info) in effect on the date of publication of this document. + Please review these documents carefully, as they describe your rights + and restrictions with respect to this document. Code Components + extracted from this document must include Revised BSD License text as + described in Section 4.e of the Trust Legal Provisions and are + provided without warranty as described in the Revised BSD License. + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 + 1.1. Requirements Notation and Conventions . . . . . . . . . . 4 + 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 + 2. Payload Format . . . . . . . . . . . . . . . . . . . . . . . 4 + 2.1. Video Payload Format . . . . . . . . . . . . . . . . . . 5 + 2.1.1. Parameter Sets In Payload . . . . . . . . . . . . . . 5 + 2.1.2. Parameter Sets in Headers . . . . . . . . . . . . . . 5 + 2.1.3. Length Prefixes in Payload . . . . . . . . . . . . . 5 + 2.1.4. Start Code Prefixes in Payload . . . . . . . . . . . 5 + 2.2. MOQ Object Mapping . . . . . . . . . . . . . . . . . . . 6 + 2.3. LOC Properties . . . . . . . . . . . . . . . . . . . . . 6 + 2.3.1. Common Properties . . . . . . . . . . . . . . . . . . 7 + 2.3.2. Video Properties . . . . . . . . . . . . . . . . . . 8 + 2.3.3. Audio Properties . . . . . . . . . . . . . . . . . . 8 + 3. Payload Encryption . . . . . . . . . . . . . . . . . . . . . 9 + 3.1. Secure Objects Integration . . . . . . . . . . . . . . . 9 + 3.1.1. Key Identification . . . . . . . . . . . . . . . . . 9 + 3.1.2. Immutable Properties . . . . . . . . . . . . . . . . 10 + 3.1.3. Private Properties for Sensitive Metadata . . . . . . 10 + 3.1.4. Cipher Suite Requirements . . . . . . . . . . . . . . 10 + 3.1.5. AAD Construction . . . . . . . . . . . . . . . . . . 11 + 4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 4.1. Application with one audio track . . . . . . . . . . . . 12 + 4.2. Application with one single quality video track . . . . . 12 + + + + +Zanaty, et al. Expires 21 January 2027 [Page 2] + +Internet-Draft media-container July 2026 + + + 4.3. Application with single video track with temporal + layers . . . . . . . . . . . . . . . . . . . . . . . . . 13 + 4.4. Application with mutiple dependent video tracks . . . . . 13 + 4.5. Application with mutiple dependent video tracks with dyadic + framerate levels. . . . . . . . . . . . . . . . . . . . . 14 + 4.6. Application with multiple simulcast qualities video + tracks . . . . . . . . . . . . . . . . . . . . . . . . . 15 + 5. Security and Privacy Considerations . . . . . . . . . . . . . 16 + 5.1. Protecting Sensitive Metadata . . . . . . . . . . . . . . 16 + 5.2. Immutable Property Considerations . . . . . . . . . . . . 16 + 5.3. Relay Trust Model . . . . . . . . . . . . . . . . . . . . 17 + 5.4. Deletion Detection . . . . . . . . . . . . . . . . . . . 17 + 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 + 6.1. MOQ Properties Registry . . . . . . . . . . . . . . . . . 17 + 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 + 7.1. Normative References . . . . . . . . . . . . . . . . . . 18 + 7.2. Informative References . . . . . . . . . . . . . . . . . 19 + Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 19 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19 + +1. Introduction + + This specification describes a low-overhead media container (LOC) + format for encoded and encrypted audio and video media data. + + "Low-overhead" refers to minimal extra encapsulation as well as + minimal application overhead when interfacing with WebCodecs + [WebCodecs]. + + The container format description is specified for all audio and video + codecs defined in the WebCodecs Codec Registry + [WEBCODECS-CODEC-REGISTRY]. The audio and video payload bitstream is + identical to the "internal data" inside an EncodedAudioChunk and + EncodedVideoChunk, respectively, specified in the registry. + + (Note: Do we need to support timed text tracks such as Web Video Text + Tracks (WebVTT) ?) + + In addition to the media payloads, critical metadata called + properties are also specified for audio and video payloads. + + A primary motivation is to align with media formats used in WebCodecs + to minimize extra encapsulation and application overhead when + interfacing with WebCodecs. Other container formats like CMAF or RTP + would require more extensive application overhead in format + conversions, as well as larger encapsultion overhead which may burden + some use cases like low bitrate audio scenarios. + + + + +Zanaty, et al. Expires 21 January 2027 [Page 3] + +Internet-Draft media-container July 2026 + + + This specification can also be used by applications outside the + context of WebCodecs or a web browser. While the media payloads are + defined by referring to the "internal data" of an EncodedAudioChunk + or EncodedVideoChunk in the WebCodecs Codec Registry, this "internal + data" is the elementary bitstream format of codecs without any + encapsulation. Referring to the WebCodecs Codec Registry avoids + duplicating it in an identical IANA registry. + + * Section 2 defines the core media payload formats. + + * Section 2.3 defines the metadata, called properties, associated + with audio and video payloads. + + * Section 3 defines the usage of end-to-end encrypted LOC payloads. + + * Section 4 provides examples with details for building audio and + video applications using LOC over MOQ. + +1.1. Requirements Notation and Conventions + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and + "OPTIONAL" in this document are to be interpreted as described in + BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all + capitals, as shown here. + +1.2. Terminology + + Track, Group, Subgroup, Object, and their corresponding identifiers + (ID or alias) are defined in [MoQTransport] and used here to refer to + those aspects of the MOQT Object Model. + +2. Payload Format + + The WebCodecs Codec Registry defines the contents of an + EncodedAudioChunk and EncodedVideoChunk for the audio and video codec + formats in the registry. The "internal data" in these chunks is used + directly in this specification as the "LOC Payload" bitstream. This + "internal data" is the elementary bitstream format of each codec + without any encapsulation. + + + + + + + + + + + +Zanaty, et al. Expires 21 January 2027 [Page 4] + +Internet-Draft media-container July 2026 + + +2.1. Video Payload Format + + For video formats with multiple bitstream formats in the WebCodecs + Registry, such as H.264/AVC or H.265/HEVC, the LOC Payload can use + either the "canonical" format ("avc" or "hevc") often used in storage + containers like MP4 / ISO BMFF, or the "annexB" format used in some + non-MP4 applications. These formats differ in how they carry + initialization and configuration information called parameter sets as + well as how parts of a video frame are delimited with length prefixes + or start codes. + +2.1.1. Parameter Sets In Payload + + Parameter sets can be sent in the bitstream payload before key + frames, similar to "annexB" formats. Newer "canonical" formats such + as "avc3" and "hev1" codec strings also support parameter sets in the + bitstream payload or outside it in "extradata" metadata headers. + +2.1.2. Parameter Sets in Headers + + Parameter sets can be sent in headers before key frames, as described + in the Video Config LOC Property Section 2.3.2.1, similar to the + original "canonical" formats such as "avc1" and "hvc1" codec strings. + The Video Config contents are the "extradata" bytes defined by the + corresponding codec specification, which map to the WebCodecs + VideoDecoderConfig description property in the + EncodedVideoChunkMetadata. + +2.1.3. Length Prefixes in Payload + + A 4-byte length prefix can be sent before each NAL Unit, similar to + "canonical" ("avc" or "hevc") formats. A length value of 1 SHOULD be + interpreted as a start code rather than a length. The length is in + network byte order, i.e. big endian, and SHOULD be 4 bytes long to + disambiguate from start code prefixes. A length prefix less than 4 + bytes long, which is uncommon, MAY be specified in the Video Config + Section 2.3.2.1. + +2.1.4. Start Code Prefixes in Payload + + A 4-byte start code can be sent before each NAL Unit, similar to + "annexB" formats. The start code value is 1 in network byte order, + i.e. big endian, and SHOULD be 4 bytes long to disambiguate from + length prefixes. A 3-byte start code, which is uncommon, MAY be used + if the track never uses length prefixes or any Video Config + Section 2.3.2.1. + + + + + +Zanaty, et al. Expires 21 January 2027 [Page 5] + +Internet-Draft media-container July 2026 + + +2.2. MOQ Object Mapping + + An application object when transported as a [MoQTransport] object is + composed of a MOQ Object Header, with optional Properties, and a + Payload. Media objects encoded using the container format defined in + this specification populate the MOQ Object Properties with the LOC + Public Properties, and populate the MOQ Object Payload with LOC + Private Properties followed by the LOC Payload, as shown below. + + The LOC Payload is the "internal data" of an EncodedAudioChunk or + EncodedVideoChunk. + + The LOC Public and Private Properties carry optional metadata related + to the Payload, where Public Properties are visible to relays while + Private Properties can be encypted end to end with the Payload. + + <----------- MOQ Object ------------> + +----------+--------------+-----------+ + | MOQ | MOQ Header | MOQ | + | Header | Properties | Payload | + +----------+--------------+-----------+ + | | + | | + +--------------+---------------------------+ + | LOC Public | LOC Private | LOC | + | Properties | Properties | Payload | + +--------------+---------------+-----------+ + + LOC Public Properties = some MOQ Object Properties + LOC Private Properties + LOC Payload = all MOQ Object Payload + LOC Payload = "internal data" of EncodedAudio/VideoChunk + +2.3. LOC Properties + + The LOC Public and Private Properties carry optional metadata for the + corresponding LOC Payload. The LOC Public Properties are contained + within the MOQ Object Properties. This metadata provides necessary + information for end subscribers, relays and other intermediaries to + perform their operations without accessing the media payload. For + example, media switches can use this metadata to perform their media + switching decisions without accessing the payload which may be + encrypted end-to-end (from original publisher to end subscribers). + The LOC Private Properties are contained within the MOQ Object + Payload, and are not intended to be processed by relays. + + The following sections define specific metadata as LOC Public and + Private Properties and register them in the IANA registry for MOQ + Properties. + + + +Zanaty, et al. Expires 21 January 2027 [Page 6] + +Internet-Draft media-container July 2026 + + + Other specifications can define other metadata as LOC Public and + Private Properties and register them in the same registry. Each + property must specify the following information in the IANA registry. + + * Name: Short name for the metadata (not sent on the wire) + + * Description: Detailed description (not sent on the wire) + + * ID: Identifier assigned by the registry (vi64) + + * Length: Length of metadata Value in bytes (vi64 if ID is odd, + omitted if ID is even) + + * Value: Value of metadata (vi64 if ID is even, Length bytes if ID + is odd) + +2.3.1. Common Properties + +2.3.1.1. Timestamp + + * Name: Timestamp + + * Description: Timestamp of the encoded media frame encoded as vi64. + The unit of the timestamp is determined by the Timescale property + Section 2.3.1.2. If no timescale property is present, the + timestamp is interpreted as wall-clock time in microseconds since + the Unix epoch. + + * ID: 0x10 + + * Length: Omitted (ID is even) + + * Value: vi64 (1-9 bytes) + +2.3.1.2. Timescale + + * Name: Timescale + + * Description: The number of Timestamp units per second, encoded as + vi64. This property defines the unit for interpreting timestamp + values in the Timestamp property. Common values include 1000000 + for microseconds, 48000 for audio at 48kHz sample rate, 90000 for + video at 90kHz clock rate. When this property is present, the + Timestamp represents media time rather than wall-clock time. The + epoch or anchor point for the timestamp is application-defined. + If this property is not present, timestamps default to + microseconds since Unix epoch. + + + + +Zanaty, et al. Expires 21 January 2027 [Page 7] + +Internet-Draft media-container July 2026 + + + * ID: 0x08 + + * Length: Omitted (ID is even) + + * Value: vi64 (1-9 bytes) + +2.3.2. Video Properties + +2.3.2.1. Video Config + + * Name: Video Config + + * Description: Video codec configuration "extradata", as defined by + the corresponding codec specification, which maps to the WebCodecs + VideoDecoderConfig description property in the + EncodedVideoChunkMetadata. + + * ID: 0x0D + + * Length: Varies + + * Value: Varies + +2.3.2.2. Video Frame Marking + + * Name: Video Frame Marking + + * Description: Flags for video frames which are independent, + discardable, or base layer sync points, as well as temporal and + spatial layer identification, as defined in [RFC9626], encoded + with a length prefix. + + * ID: 0x09 + + * Length: Varies (1-4 bytes) + + * Value: Varies + +2.3.3. Audio Properties + +2.3.3.1. Audio Config + + * Name: Audio Config + + * Description: Audio codec configuration, as defined by the + corresponding codec specification, which maps to the WebCodecs + AudioDecoderConfig description property in the + EncodedAudioChunkMetadata. + + + +Zanaty, et al. Expires 21 January 2027 [Page 8] + +Internet-Draft media-container July 2026 + + + * ID: 0x0F + + * Length: Varies + + * Value: Varies + +2.3.3.2. Audio Level + + * Name: Audio Level + + * Description: The magnitude of the audio level of the corresponding + audio frame as well as a voice activity indicator as defined in + section 3 of [RFC6464], encoded in the least significant 8 bits of + a vi64. + + * ID: 0x0C + + * Length: Omitted (ID is even) + + * Value: vi64 (1-2 bytes to encode values 0x00-0xFF) + +3. Payload Encryption + + When end to end encryption is supported, the encoded payload is + encrypted with symmetric keys derived from key establishment + mechanisms, such as [MOQ-MLS], and the payload itself is protected + using mechanisms defined in [SecureObjects]. + +3.1. Secure Objects Integration + + [SecureObjects] defines a comprehensive framework for end-to-end + encryption of MOQT objects. When using Secure Objects with LOC, the + following considerations apply: + +3.1.1. Key Identification + + The Secure Object Key ID property (type 0x2 in [SecureObjects]) MUST + be included as an immutable property to identify the keying material + used for encryption. This property is authenticated but not + encrypted, allowing relays to forward objects without decryption + while ensuring subscribers can identify the correct decryption key. + + + + + + + + + + +Zanaty, et al. Expires 21 January 2027 [Page 9] + +Internet-Draft media-container July 2026 + + +3.1.2. Immutable Properties + + LOC Properties that should be immutable but visible to relays SHOULD + be encoded as Immutable Properties as defined in [MoQTransport] to + ensure they cannot be modified by relays and are included in the + authenticated associated data (AAD) during encryption. This + specification does not define any Immutable Properties, but other + specifications may define some for use with LOC. + +3.1.3. Private Properties for Sensitive Metadata + + Some LOC metadata may be sensitive and should not be visible to + relays. [SecureObjects] defines a Private properties mechanism (type + 0xA) that allows metadata to be encrypted alongside the payload. + + The following LOC properties MAY be carried as Private properties + when end-to-end confidentiality is required: + + * Timestamp and Timescale - reveals timing information about the + source + + * Audio Level - reveals voice activity and audio characteristics + + * Video Frame Marking - reveals encoding structure details + + * Video Config - reveals encoding configuration details + + When using Private properties: + + 1. The LOC property is encoded as a key-value pair within the + Private properties payload + + 2. The Private properties are concatenated with the media payload + before encryption + + 3. Upon decryption, the receiver extracts the Private properties and + reconstructs the LOC metadata + + This approach allows sensitive metadata to remain confidential from + relays while still being available to authorized end subscribers. + +3.1.4. Cipher Suite Requirements + + Implementations using LOC with Secure Objects MUST support the + AES_128_GCM_SHA256_128 cipher suite (0x0004). Other cipher suites + defined in [SecureObjects] MAY be used based on application + requirements for authentication tag size versus bandwidth overhead. + + + + +Zanaty, et al. Expires 21 January 2027 [Page 10] + +Internet-Draft media-container July 2026 + + +3.1.5. AAD Construction + + The authenticated associated data (AAD) for AEAD encryption includes: + + * Key ID + + * Group ID and Object ID + + * Track namespace and name + + * Serialized immutable properties + + This binding ensures objects cannot be replayed across different + tracks or contexts. + +4. Examples + + This section provides examples with details for building audio and + video applications using MOQ and LOC; more specifically, it provides + information on: + + * Using a MSF catalog [MoQCatalog] to describe track information, + + * Packaging media into LOC streaming format, and + + * Mapping application media objects to the MOQT object model and + transport. + + The figure below shows the conceptual model for mapping media + application data to the MOQT object model and underlying QUIC + transport. + + +------------------------------+ + | Media Application | + | Audio, Video Frames | + +---------------+--------------+ + | + | + +---------------v--------------------+ + | MOQT Object Model | + | Tracks, Groups, Subgroups, Objects | + +---------------+--------------------+ + | + | + +---------------v--------------+ + | QUIC | + | Streams, Datagrams | + +------------------------------+ + + + +Zanaty, et al. Expires 21 January 2027 [Page 11] + +Internet-Draft media-container July 2026 + + +4.1. Application with one audio track + + An example is shown below for an Opus mono channel audio track at + 48Khz. + + codec: "opus" + bitrate: 24000 + samplerate: 480000 + channelConfig: "mono" + lang: "en" + + When ready for publishing, each encoded audio chunk, say 10ms, + represents a MOQT Object. In this setup, there is one MOQT Object + per MOQT Group, where the GroupID in the object header is increment + by one for each encoded audio chunk and the ObjectID is defaulted to + value 0. + + These objects can be sent as QUIC streams or datagrams. When mapped + to QUIC datagrams, each object must fit entirely within a QUIC + datagram, and when mapped to QUIC Streams, each such unitary group is + sent over an individual unidirectional QUIC stream since there is + just one SubGroup per each MOQT Group. + +4.2. Application with one single quality video track + + An example is shown below for an H.264 video track with 1280x720p + resolution and 30 fps frame rate at 1 Mbps bitrate. + + codec: "avc3.42E01E" + bitrate: 1000000 + framerate: 30 + width: 1280 + height: 720 + + When ready for publishing, each encoded video chunk is considered as + input to MOQT Object payload. If encrypted, the output of encryption + will serve as the object's payload. The GroupID is incremented by 1 + at IDR Frame boundaries. The ObjectID is increment by 1 for each + encoded video frame, starting at 0 and resetting to 0 at the start of + a new group. The first encoded video frame, MOQT Object with + ObjectID 0, shall be the Independent (IDR) frame and the rest of the + encoded video frames corresponds to dependent (delta) frames, + organized in the decode order. + + When mapping to QUIC for sending, one unidirectional QUIC stream is + setup to deliver all the encoded video chunks within a MOQT group. + + + + + +Zanaty, et al. Expires 21 January 2027 [Page 12] + +Internet-Draft media-container July 2026 + + + When decoding at the 'End Consumer', the objects from each of the + QUIC streams are fed in the GroupID then ObjectID order to the + decoder for the track. + +4.3. Application with single video track with temporal layers + + An example is shown below for an H.264 video track with 1280x720p + resolution and 2 temporal layers at 30 fps and 60 fps frame rate. + + codec: "avc3.42E01F" + bitrate: 1500000 + framerate: 60 + width: 1280 + height: 720 + + When ready for publishing, each encoded video chunk is considered as + input to MOQT Object payload. If encrypted, the output of encryption + will serve as the object's payload. The GroupID is incremented by 1 + at Independent (IDR) frame boundaries. Each MOQT group shall contain + 2 SubGroups corresponding to the 2 temporal layers as shown below: + + Layer:0/30fps Subgroup: 0 ObjectID: even + Layer:1/60fps Subgroup: 1 ObjectID: odd + + Within the MOQT group, ObjectID is increment by 1 for each encoded + video frame, starting at 0 and resetting to 0 at the start of a new + group. The first encoded video frame, MOQT Object with ObjectID 0, + shall be the Indepedent (IDR) frame and the rest of the encoded video + frames corresponds to dependent (delta) frames, organized in the + decode order. When mapping to QUIC for sending, one unidirectional + QUIC stream is used per SubGroup, thus resulting in 2 QUIC streams + per MOQT group. + + When decoding at the 'End Consumer' for a given MOQT group, the + objects must be fed in the GroupID then ObjectID order. This implies + that the consumer media application needs to order objects across the + SubGroup QUIC streams. + +4.4. Application with mutiple dependent video tracks + + An example is shown below for an H.264 video track with 2 spatial + qualities at 360p and 720p each at 30 fps + + + + + + + + + +Zanaty, et al. Expires 21 January 2027 [Page 13] + +Internet-Draft media-container July 2026 + + + Video Track 1 + codec: "avc3.42E01E" + bitrate: 500000 + framerate: 30 + width: 640 + height: 360 + + Video Track 2 + codec: "svc1.56401F" + bitrate: 1000000 + framerate: 30 + width: 1280 + height: 720 + + When ready for publishing, the mapping to the MOQT object model and + to underlying QUIC, follows the same procedures as described in + Section 4.2 for each video track. + + When decoding at the 'End Consumer' for a given MOQT group, the + objects must be fed in the GroupID then ObjectID order in the + ascending quality track order. + + For the example in the section, this would imply following pattern + when decoding group 5. + + Track 1 Group 5 Object 0 + Track 2 Group 5 Object 0 + Track 1 Group 5 Object 1 + Track 2 Group 5 Object 1 + .... + +4.5. Application with mutiple dependent video tracks with dyadic + framerate levels. + + An example is shown below for an H.264 video track with 2 spatial + qualities at 360p and 720p, however, the framerate between tracks + vary dyadically. + + + + + + + + + + + + + + +Zanaty, et al. Expires 21 January 2027 [Page 14] + +Internet-Draft media-container July 2026 + + + Video Track 1 + codec: "avc3.42E01E" + bitrate: 500000 + framerate: 30 + width: 640 + height: 360 + + Video Track 2 + codec: "svc1.56E01F" + bitrate: 1000000 + framerate: 60 + width: 1280 + height: 720 + + When ready for publishing, the mapping to the MOQT object model and + to underlying QUIC, follows the same procedures as described in + Section 4.2 for each video track. + + When decoding at the 'End Consumer' for a given MOQT group, the + objects from across the tracks must be fed in the timestamp order to + the decoder, if no frame reordering is present in the encoding. + + If the encoding uses frame reordering, or if timestamp cannot be + obtained, the object to choose next shall follow the below formula. + + Object Decode Order = ObjectID * multiplier + offset + + multiplier = 2^(maxlayer-max(0,layer-1)) + offset = 2^(maxlayer-layer) MOD multiplier + +4.6. Application with multiple simulcast qualities video tracks + + An example is shown below for an H.264 video track with 2 simulcast + spatial qualities at 360p and 720p each at 30 fps. + + Video Track 1 + codec: "avc3.42E01E" + bitrate: 500000 + framerate: 30 + width: 640 + height: 360 + + Video Track 2 + codec: "avc3.42E01F" + bitrate: 1000000 + framerate: 30 + width: 1280 + height: 720 + + + +Zanaty, et al. Expires 21 January 2027 [Page 15] + +Internet-Draft media-container July 2026 + + + When ready for publishing, the mapping to the MOQT object model and + to underlying QUIC, follows the same procedures as described in + Section 4.2 for each video track. + + When decoding at the 'End Consumer', the objects from the QUIC stream + are fed in the GroupID then ObjectID order to the decoders setup for + the corresponding video tracks. + +5. Security and Privacy Considerations + + The metadata in LOC Properties is visible to relays, since the MOQ + Object Properties are often not encrypted end-to-end (from original + publisher to end subscribers) in common schemes. In some cases, this + may be an intentional design intent for proper relay operation. In + other cases, this may be unintentional or undesirable leaking of the + metadata to relays. Each metadata that is defined should consider + the security and privacy aspects of granting relays visibility to the + metadata. + +5.1. Protecting Sensitive Metadata + + The metadata defined and registered in this specification (Timestamp, + Timescale, Config, Video Frame Marking, and Audio Level) may be + sensitive metadata that should be encrypted end-to-end. Applications + requiring confidentiality of this metadata SHOULD use the Private + properties mechanism described in Section 3.1.3 to encrypt sensitive + metadata alongside the payload. + + When using [SecureObjects] for end-to-end encryption: + + * Sensitive metadata (timestamps, audio levels, frame marking) can + be encrypted using Private properties + + * Immutable properties are authenticated but visible to relays + + * Media switches that need metadata access require appropriate key + material + +5.2. Immutable Property Considerations + + Properties marked as immutable via the IMMUTABLE_PROPERTIES mechanism + in [MoQTransport] provide integrity protection - relays cannot modify + these values without detection. However, immutable properties are + NOT encrypted and remain visible to relays. Applications must + carefully consider which properties require: + + * Confidentiality (use Private properties) + + + + +Zanaty, et al. Expires 21 January 2027 [Page 16] + +Internet-Draft media-container July 2026 + + + * Integrity without confidentiality (use Immutable properties) + + * Neither (standard mutable properties suitable for relay operation) + +5.3. Relay Trust Model + + Different deployment scenarios have different trust models for + relays: + + * Untrusted relays: Use Private properties for all sensitive + metadata + + * Semi-trusted relays (media switches): May have access to metadata + keys but not payload keys, enabling switching decisions without + content access + + * Trusted relays: May have full key access for transcoding or + processing + + Applications should select the appropriate protection mechanisms + based on their relay trust model and privacy requirements. + +5.4. Deletion Detection + + When using end-to-end encryption, relays cannot modify encrypted + payloads but could selectively delete or withhold objects. + [MoQTransport] defines PRIOR_GROUP_ID_GAP and PRIOR_OBJECT_ID_GAP + properties that publishers can include to indicate intentional gaps + in sequences. Subscribers can use these to distinguish between + publisher-intended gaps and potential relay deletion. + [SecureObjects] provides additional mechanisms for detecting such + attacks. + +6. IANA Considerations + +6.1. MOQ Properties Registry + + This document registers the following entries in the MOQ Properties + registry established by [MoQTransport]: + + + + + + + + + + + + +Zanaty, et al. Expires 21 January 2027 [Page 17] + +Internet-Draft media-container July 2026 + + + +======+=====================+===============+=================+ + | Type | Name | Scope | Specification | + +======+=====================+===============+=================+ + | 0x10 | TIMESTAMP | Object | Section 2.3.1.1 | + +------+---------------------+---------------+-----------------+ + | 0x08 | TIMESCALE | Track, Object | Section 2.3.1.2 | + +------+---------------------+---------------+-----------------+ + | 0x09 | VIDEO_FRAME_MARKING | Object | Section 2.3.2.2 | + +------+---------------------+---------------+-----------------+ + | 0x0C | AUDIO_LEVEL | Object | Section 2.3.3.2 | + +------+---------------------+---------------+-----------------+ + | 0x0D | VIDEO_CONFIG | Track, Object | Section 2.3.2.1 | + +------+---------------------+---------------+-----------------+ + | 0x0F | AUDIO_CONFIG | Track, Object | Section 2.3.3.1 | + +------+---------------------+---------------+-----------------+ + + Table 1 + +7. References + +7.1. Normative References + + [MoQTransport] + Nandakumar, S., Vasiliev, V., Swett, I., and A. Frindell, + "Media over QUIC Transport", Work in Progress, Internet- + Draft, draft-ietf-moq-transport-19, 6 July 2026, + . + + [WebCodecs] + "WebCodecs", July 2023, + . + + [WEBCODECS-CODEC-REGISTRY] + "WebCodecs Codec Registry", July 2023, + . + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + . + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, . + + + + + + +Zanaty, et al. Expires 21 January 2027 [Page 18] + +Internet-Draft media-container July 2026 + + + [RFC9626] Zanaty, M., Berger, E., and S. Nandakumar, "Video Frame + Marking RTP Header Extension", RFC 9626, + DOI 10.17487/RFC9626, March 2025, + . + + [RFC6464] Lennox, J., Ed., Ivov, E., and E. Marocco, "A Real-time + Transport Protocol (RTP) Header Extension for Client-to- + Mixer Audio Level Indication", RFC 6464, + DOI 10.17487/RFC6464, December 2011, + . + +7.2. Informative References + + [MoQCatalog] + Law, W. and S. Nandakumar, "MOQT Streaming Format", Work + in Progress, Internet-Draft, draft-ietf-moq-msf-01, 2 June + 2026, . + + [SecureObjects] + Jennings, C. F., Nandakumar, S., and R. Barnes, "End-to- + End Secure Objects for Media over QUIC Transport", Work in + Progress, Internet-Draft, draft-ietf-moq-secure-objects- + 01, 6 July 2026, . + + [MOQ-MLS] Jennings, C. F., Nandakumar, S., and R. Barnes, "End-to- + end Security for Media over QUIC", Work in Progress, + Internet-Draft, draft-jennings-moq-e2ee-mls-03, 30 June + 2025, . + +Appendix A. Acknowledgements + + Thanks to Cullen Jennings, Luke Curley, Upendra Sharma, and Yu You + for suggestions and review. + +Authors' Addresses + + Mo Zanaty + Cisco + Email: mzanaty@cisco.com + + + Suhas Nandakumar + Cisco + Email: snandaku@cisco.com + + + + +Zanaty, et al. Expires 21 January 2027 [Page 19] + +Internet-Draft media-container July 2026 + + + Peter Thatcher + Microsoft + Email: pthatcher@microsoft.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Zanaty, et al. Expires 21 January 2027 [Page 20] diff --git a/internal/specs/moq/draft-ietf-moq-msf-01.txt b/internal/specs/moq/draft-ietf-moq-msf-01.txt new file mode 100644 index 0000000000..f5a8d2e0d8 --- /dev/null +++ b/internal/specs/moq/draft-ietf-moq-msf-01.txt @@ -0,0 +1,4144 @@ + + + + +Media Over QUIC W. Law +Internet-Draft Akamai +Intended status: Informational S. Nandakumar +Expires: 4 December 2026 Cisco + 2 June 2026 + + + MOQT Streaming Format + draft-ietf-moq-msf-01 + +Abstract + + This document specifies the MOQT Streaming Format, designed to + operate on Media Over QUIC Transport. + +About This Document + + This note is to be removed before publishing as an RFC. + + The latest revision of this draft can be found at https://moq- + wg.github.io/msf/ draft-ietf-moq-msf.html. Status information for + this document may be found at https://datatracker.ietf.org/doc/draft- + ietf-moq-msf/. + + Discussion of this document takes place on the Media Over QUIC + Working Group mailing list (mailto:moq@ietf.org), which is archived + at https://mailarchive.ietf.org/arch/browse/moq/. Subscribe at + https://www.ietf.org/mailman/listinfo/moq/. + + Source for this draft and an issue tracker can be found at + https://github.com/moq-wg/msf. + +Status of This Memo + + This Internet-Draft is submitted in full conformance with the + provisions of BCP 78 and BCP 79. + + Internet-Drafts are working documents of the Internet Engineering + Task Force (IETF). Note that other groups may also distribute + working documents as Internet-Drafts. The list of current Internet- + Drafts is at https://datatracker.ietf.org/drafts/current/. + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as "work in progress." + + This Internet-Draft will expire on 4 December 2026. + + + +Law & Nandakumar Expires 4 December 2026 [Page 1] + +Internet-Draft MOQT Streaming Format June 2026 + + +Copyright Notice + + Copyright (c) 2026 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents (https://trustee.ietf.org/ + license-info) in effect on the date of publication of this document. + Please review these documents carefully, as they describe your rights + and restrictions with respect to this document. Code Components + extracted from this document must include Revised BSD License text as + described in Section 4.e of the Trust Legal Provisions and are + provided without warranty as described in the Revised BSD License. + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 + 2. Conventions and Definitions . . . . . . . . . . . . . . . . . 5 + 3. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 + 4. Media packaging . . . . . . . . . . . . . . . . . . . . . . . 7 + 4.1. LOC packaging . . . . . . . . . . . . . . . . . . . . . . 7 + 4.2. Time-alignment . . . . . . . . . . . . . . . . . . . . . 7 + 4.3. Content protection and encryption . . . . . . . . . . . . 8 + 4.3.1. Encryption scheme signaling . . . . . . . . . . . . . 8 + 4.3.2. Key management . . . . . . . . . . . . . . . . . . . 8 + 4.3.3. Recommended encryption scheme . . . . . . . . . . . . 9 + 4.3.4. Encrypted object structure . . . . . . . . . . . . . 9 + 5. Catalog . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 + 5.1. Root Catalog Fields . . . . . . . . . . . . . . . . . . . 10 + 5.1.1. MSF version . . . . . . . . . . . . . . . . . . . . . 11 + 5.1.2. Generated at . . . . . . . . . . . . . . . . . . . . 11 + 5.1.3. Is Complete . . . . . . . . . . . . . . . . . . . . . 11 + 5.1.4. Tracks . . . . . . . . . . . . . . . . . . . . . . . 12 + 5.1.5. Publish tracks . . . . . . . . . . . . . . . . . . . 12 + 5.1.6. Delta update . . . . . . . . . . . . . . . . . . . . 12 + 5.1.7. Initialization Data List . . . . . . . . . . . . . . 13 + 5.2. Track Object Fields . . . . . . . . . . . . . . . . . . . 13 + 5.2.1. Tracks object . . . . . . . . . . . . . . . . . . . . 15 + 5.2.2. Track namespace . . . . . . . . . . . . . . . . . . . 15 + 5.2.3. Track name . . . . . . . . . . . . . . . . . . . . . 15 + 5.2.4. Packaging . . . . . . . . . . . . . . . . . . . . . . 16 + 5.2.5. Event timeline type . . . . . . . . . . . . . . . . . 16 + 5.2.6. Track role . . . . . . . . . . . . . . . . . . . . . 16 + 5.2.7. Is Live . . . . . . . . . . . . . . . . . . . . . . . 18 + 5.2.8. Target latency . . . . . . . . . . . . . . . . . . . 18 + 5.2.9. Buffers . . . . . . . . . . . . . . . . . . . . . . . 18 + 5.2.10. Track label . . . . . . . . . . . . . . . . . . . . . 19 + 5.2.11. Render group . . . . . . . . . . . . . . . . . . . . 19 + + + +Law & Nandakumar Expires 4 December 2026 [Page 2] + +Internet-Draft MOQT Streaming Format June 2026 + + + 5.2.12. Alternate group . . . . . . . . . . . . . . . . . . . 19 + 5.2.13. Initialization reference . . . . . . . . . . . . . . 19 + 5.2.14. Dependencies . . . . . . . . . . . . . . . . . . . . 20 + 5.2.15. Template . . . . . . . . . . . . . . . . . . . . . . 20 + 5.2.16. Temporal ID . . . . . . . . . . . . . . . . . . . . . 20 + 5.2.17. Spatial ID . . . . . . . . . . . . . . . . . . . . . 20 + 5.2.18. Codec . . . . . . . . . . . . . . . . . . . . . . . . 20 + 5.2.19. Mimetype . . . . . . . . . . . . . . . . . . . . . . 21 + 5.2.20. Framerate . . . . . . . . . . . . . . . . . . . . . . 21 + 5.2.21. Timescale . . . . . . . . . . . . . . . . . . . . . . 21 + 5.2.22. Maximum Bitrate . . . . . . . . . . . . . . . . . . . 21 + 5.2.23. Average Bitrate . . . . . . . . . . . . . . . . . . . 21 + 5.2.24. Maximum GOP Duration . . . . . . . . . . . . . . . . 21 + 5.2.25. Maximum Group Duration . . . . . . . . . . . . . . . 22 + 5.2.26. Width . . . . . . . . . . . . . . . . . . . . . . . . 22 + 5.2.27. Height . . . . . . . . . . . . . . . . . . . . . . . 22 + 5.2.28. Audio sample rate . . . . . . . . . . . . . . . . . . 22 + 5.2.29. Channel configuration . . . . . . . . . . . . . . . . 22 + 5.2.30. Display width . . . . . . . . . . . . . . . . . . . . 22 + 5.2.31. Display height . . . . . . . . . . . . . . . . . . . 23 + 5.2.32. Language . . . . . . . . . . . . . . . . . . . . . . 23 + 5.2.33. Parent name . . . . . . . . . . . . . . . . . . . . . 23 + 5.2.34. Parent namespace . . . . . . . . . . . . . . . . . . 23 + 5.2.35. Track duration . . . . . . . . . . . . . . . . . . . 23 + 5.2.36. Connection URI . . . . . . . . . . . . . . . . . . . 23 + 5.2.37. Token . . . . . . . . . . . . . . . . . . . . . . . . 24 + 5.2.38. Encryption scheme . . . . . . . . . . . . . . . . . . 24 + 5.2.39. Cipher suite . . . . . . . . . . . . . . . . . . . . 24 + 5.2.40. Key ID . . . . . . . . . . . . . . . . . . . . . . . 25 + 5.2.41. Track Base Key . . . . . . . . . . . . . . . . . . . 26 + 5.2.42. Authorization Info . . . . . . . . . . . . . . . . . 26 + 5.2.43. Token Delivery via URI . . . . . . . . . . . . . . . 27 + 5.2.44. Accessibility . . . . . . . . . . . . . . . . . . . . 27 + 5.3. Delta updates . . . . . . . . . . . . . . . . . . . . . . 28 + 5.4. Variable Substitution . . . . . . . . . . . . . . . . . . 29 + 5.4.1. Variable Syntax . . . . . . . . . . . . . . . . . . . 29 + 5.4.2. Variable Resolution . . . . . . . . . . . . . . . . . 29 + 5.5. Catalog Compression . . . . . . . . . . . . . . . . . . . 30 + 5.6. Catalog Examples . . . . . . . . . . . . . . . . . . . . 30 + 5.6.1. Time-aligned Audio/Video Tracks with single + quality . . . . . . . . . . . . . . . . . . . . . . . 30 + 5.6.2. Simulcast video tracks - 3 alternate qualities along + with audio . . . . . . . . . . . . . . . . . . . . . 31 + 5.6.3. SVC video tracks with 2 spatial and 2 temporal + qualities . . . . . . . . . . . . . . . . . . . . . . 33 + 5.6.4. Delta update - adding two tracks . . . . . . . . . . 35 + 5.6.5. Delta update removing tracks . . . . . . . . . . . . 36 + + + + +Law & Nandakumar Expires 4 December 2026 [Page 3] + +Internet-Draft MOQT Streaming Format June 2026 + + + 5.6.6. Time-aligned Audio/Video Tracks with custom field + values . . . . . . . . . . . . . . . . . . . . . . . 37 + 5.6.7. Time-aligned VOD Audio/Video Tracks . . . . . . . . . 38 + 5.6.8. Encrypted Audio/Video Tracks . . . . . . . . . . . . 39 + 5.6.9. Media timeline and Event timeline . . . . . . . . . . 40 + 5.6.10. Media timeline template . . . . . . . . . . . . . . . 42 + 5.6.11. Video track with embedded captions and SCTE-35 + events . . . . . . . . . . . . . . . . . . . . . . . 43 + 5.6.12. Video track with CEA-708 captions . . . . . . . . . . 45 + 5.6.13. Terminating a live broadcast . . . . . . . . . . . . 45 + 5.6.14. Variable Substitution for personalized delivery . . . 46 + 5.6.15. Time-aligned Audio/Video Tracks with Authorization . 47 + 5.6.16. Publish tracks for logs and metrics . . . . . . . . . 48 + 6. Media transmission . . . . . . . . . . . . . . . . . . . . . 50 + 6.1. Group numbering . . . . . . . . . . . . . . . . . . . . . 50 + 6.2. Object Numbering . . . . . . . . . . . . . . . . . . . . 50 + 7. Media Timeline track . . . . . . . . . . . . . . . . . . . . 51 + 7.1. Media Timeline track payload . . . . . . . . . . . . . . 51 + 7.1.1. Explicit entry format . . . . . . . . . . . . . . . . 51 + 7.2. Media Timeline Catalog requirements . . . . . . . . . . . 52 + 7.3. Media Timeline track updating . . . . . . . . . . . . . . 52 + 7.4. Media Timeline Template . . . . . . . . . . . . . . . . . 52 + 7.4.1. Template Format . . . . . . . . . . . . . . . . . . . 52 + 7.4.2. Template Immutability . . . . . . . . . . . . . . . . 53 + 8. Event Timeline track . . . . . . . . . . . . . . . . . . . . 54 + 8.1. Event Timeline data format . . . . . . . . . . . . . . . 54 + 8.2. Event Timeline Catalog requirements . . . . . . . . . . . 54 + 8.3. Event Timeline track updating . . . . . . . . . . . . . . 55 + 8.4. Event timeline track examples . . . . . . . . . . . . . . 55 + 8.4.1. Event timeline track with wallclock time indexing . . 55 + 8.4.2. Event timeline track with MOQT Location indexing . . 56 + 9. Log track . . . . . . . . . . . . . . . . . . . . . . . . . . 56 + 9.1. Log track payload . . . . . . . . . . . . . . . . . . . . 56 + 9.2. Log track namespace and name . . . . . . . . . . . . . . 56 + 9.3. Log track Group ID and Object ID . . . . . . . . . . . . 57 + 9.4. Log track catalog requirements . . . . . . . . . . . . . 57 + 10. Metrics track . . . . . . . . . . . . . . . . . . . . . . . . 57 + 10.1. Metrics track payload . . . . . . . . . . . . . . . . . 57 + 10.2. Metrics track namespace and name . . . . . . . . . . . . 58 + 10.3. Metrics track Group ID and Object ID . . . . . . . . . . 58 + 10.4. Metrics track catalog requirements . . . . . . . . . . . 58 + 10.5. Well-known event timeline types . . . . . . . . . . . . 59 + 11. Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . 59 + 11.1. URL construction and interpretation . . . . . . . . . . 59 + 11.1.1. Reserved fragment parameters . . . . . . . . . . . . 62 + 11.1.2. MSF Namespace-Name String Encoding . . . . . . . . . 63 + 11.1.3. Example MSF URLs . . . . . . . . . . . . . . . . . . 64 + 11.2. Initiating a broadcast . . . . . . . . . . . . . . . . . 65 + + + +Law & Nandakumar Expires 4 December 2026 [Page 4] + +Internet-Draft MOQT Streaming Format June 2026 + + + 11.3. Ending a live broadcast . . . . . . . . . . . . . . . . 65 + 11.4. Authorization . . . . . . . . . . . . . . . . . . . . . 65 + 11.4.1. Discovering Authorization Requirements . . . . . . . 65 + 11.4.2. Token Acquisition . . . . . . . . . . . . . . . . . 66 + 11.4.3. Presenting Authorization . . . . . . . . . . . . . . 66 + 11.4.4. Handling Authorization Failures . . . . . . . . . . 67 + 12. MSF Properties . . . . . . . . . . . . . . . . . . . . . . . 67 + 12.1. Compression Signaling . . . . . . . . . . . . . . . . . 67 + 12.1.1. MSF_COMPRESSION Track Property . . . . . . . . . . . 68 + 12.1.2. MSF_COMPRESSION Object Property . . . . . . . . . . 69 + 13. Security Considerations . . . . . . . . . . . . . . . . . . . 69 + 14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 69 + 14.1. "MOQT URI Fragment Types" registry . . . . . . . . . . . 69 + 14.2. "MSF Event Timeline Types" registry . . . . . . . . . . 69 + 14.3. MSF_COMPRESSION Track Property . . . . . . . . . . . . . 70 + 14.4. MSF_COMPRESSION Object Property . . . . . . . . . . . . 70 + 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 71 + 15.1. Normative References . . . . . . . . . . . . . . . . . . 71 + 15.2. Informative References . . . . . . . . . . . . . . . . . 73 + Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 74 + Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 74 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 74 + +1. Introduction + + MOQT Streaming Format (MSF) is a media format designed to deliver LOC + [LOC] compliant media content over Media Over QUIC Transport (MOQT) + [MoQTransport]. MSF works by fragmenting the bitstream into objects + that can be independently transmitted. MSF leverages a catalog + format to describe the output of the original publisher. MSF + specifies how content should be packaged and signaled, defines how + the catalog communicates the content, specifies prioritization + strategies for real-time and workflows for beginning and terminating + broadcasts. MSF also details how end-subscribers may perform + adaptive bitrate switching. MSF is targeted at real-time and + interactive levels of live latency, as well as VOD content. + + This document describes version 1 of the streaming format. + +2. Conventions and Definitions + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and + "OPTIONAL" in this document are to be interpreted as described in + BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all + capitals, as shown here. + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 5] + +Internet-Draft MOQT Streaming Format June 2026 + + + This document uses the conventions detailed in Section 1.3 of + [RFC9000] when describing the binary encoding. + +3. Scope + + The purpose of MSF is to provide an interoperable media streaming + format operating over [MoQTransport]. Interoperability implies that: + + * An original publisher can package incoming media content into + tracks, prepare a catalog and announce the availability of the + content to an MOQT relay. Media content refers to audio and video + data, as well as ancillary data such as captions, subtitles, + accessibility and other timed-text data. + + * An MOQT relay can process the announcement as well as cache and + propagate the tracks, both to other relays or to the final + subscriber. + + * A final subscriber can parse the catalog, request tracks, decode + and render the received media data. + + MSF is intended to provide a format for delivering commercial media + content. To that end, the following features are within scope: + + * Video codecs - all codecs supported by [LOC] + + * Audio codecs - all audio codecs supported by [LOC] + + * Catalog track - describes the availability and characteristics of + content produced by the original publisher. + + * Timeline track - describes the relationship between MOQT Group and + Object IDs to media time. + + * Token-based authorization and access control + + * Captions + Subtitles - support for [WEBVTT] and [IMSC1] + transmission + + * Latency support across multiple regimes (thresholds are + informative only and describe the delay between the original + publisher placing the content on the wire and the final subscriber + rendering it) + + * Real-time - less than 500ms + + * Interactive - between 500ms and 2500ms + + + + +Law & Nandakumar Expires 4 December 2026 [Page 6] + +Internet-Draft MOQT Streaming Format June 2026 + + + * Standard - above 2500ms + + * VOD latency - content that was previously produced, is no longer + live and is available indefinitely. + + * Content encryption + + * ABR between time-synced tracks - subscribers may switch between + tracks at different quality levels in order to maximize visual or + audio quality under conditions of throughput variability. + + * Capable of delivering interstitial advertising. + + * Logs and analytics management - support for the reporting of + client-side QoE and relay delivery actions via publish tracks + using [MOQLOG] and [MOQMETRICS]. + + Initial versions of MSF will prioritize basic features necessary to + exercise interoperability across delivery systems. Later versions + will add commercially necessary features. + +4. Media packaging + + MSF delivers LOC [LOC] packaged media bitstreams. + +4.1. LOC packaging + + This specification references Low Overhead Container (LOC) [LOC] to + define how audio and video content is packaged. With this packaging + mode, each EncodedAudioChunk or EncodedVideoChunk sample is placed in + a separate MOQT Object. Samples that belong to the same Group of + Pictures (GOP) MUST be placed within the same MOQT Group. + + When LOC packaging is used for a track, the catalog packaging + attribute (Section 5.2.4) MUST be present and it MUST be populated + with a value of "loc". + +4.2. Time-alignment + + MSF Tracks MAY be time-aligned. Those that are, are subject to the + following requirements: + + * Tracks advertised in the catalog as belonging to a common + alternate group MUST be time-aligned. + + * The render duration of the first media object of each equally + numbered MOQT Group, after decoding, SHOULD have overlapping + presentation time. + + + +Law & Nandakumar Expires 4 December 2026 [Page 7] + +Internet-Draft MOQT Streaming Format June 2026 + + + A consequence of this restriction is that an MSF receiver SHOULD be + able to cleanly switch between time-aligned media tracks at group + boundaries. + + If time-aligned media tracks do not have overlapping presentation + time at equally-numbered group boundaries, then an alternate + mechanism, not defined by this specification, must be provided to the + client to enable it to switch smoothly between time-aligned, but + numerically dissimilar, Group IDs. + +4.3. Content protection and encryption + + MSF supports end-to-end encryption of media content using MoQ Secure + Objects [SecureObjects]. When encryption is enabled, the payload of + LOC-packaged media objects is encrypted and authenticated, while + relays can still route content based on unencrypted header + information. + +4.3.1. Encryption scheme signaling + + The encryption scheme and parameters are signaled in the catalog + using the following track-level fields: + + * encryptionScheme Section 5.2.38 - identifies the encryption + mechanism + + * cipherSuite Section 5.2.39 - specifies the AEAD algorithm + + * keyId Section 5.2.40 - identifies the key material for decryption + + * trackBaseKey Section 5.2.41 - the base key material for this track + + When the encryptionScheme field is present in a track definition, + subscribers MUST decrypt the object payload using the specified + scheme before processing. + +4.3.2. Key management + + The keyId and trackBaseKey values are obtained from an external key + management system and the mechanism for obtaining these values is out + of scope for this specification. Examples of key management systems + include MLS-based key distribution [E2EE-MLS] or other out-of-band + key exchange mechanisms. + + Depending on the key management mechanism in use, a keyId MAY be + scoped to: + + * A single track + + + +Law & Nandakumar Expires 4 December 2026 [Page 8] + +Internet-Draft MOQT Streaming Format June 2026 + + + * A single MoQ Session + + * Multiple tracks across one or more MoQ sessions + + Publishers and subscribers MUST use the same key management system + and agree on the keyId scope semantics for interoperable operation. + +4.3.3. Recommended encryption scheme + + The RECOMMENDED encryption scheme for MSF is "moq-secure-objects". + Implementations supporting content encryption MUST implement the + "moq-secure-objects" scheme as defined in [SecureObjects]. + + When using the "moq-secure-objects" scheme: + + * The cipherSuite field MUST be present and set to a supported + cipher suite value + + * The keyId field MUST be present to identify the key material + + * The trackBaseKey field MUST be present to provide the base key + material + +4.3.4. Encrypted object structure + + For LOC-packaged tracks with encryption enabled (see [SecureObjects], + Section 4): + + * The immutable header extensions (including Group ID and Object ID) + remain in plaintext and are authenticated + + * The object payload is encrypted and authenticated using the + specified cipher + + * Private header extensions (type 0xA) are encrypted alongside the + payload + +5. Catalog + + A Catalog is an MOQT Track that provides information about the other + tracks being produced by a MSF publisher. A Catalog is used by MSF + publishers for advertising their output and for subscribers in + consuming that output. The payload of the Catalog object is opaque + to Relays and can be end-to-end encrypted. The Catalog provides the + names and namespaces of the tracks being produced, along with the + relationship between tracks, properties of the tracks that consumers + may use for selection and any relevant initialization data. + + + + +Law & Nandakumar Expires 4 December 2026 [Page 9] + +Internet-Draft MOQT Streaming Format June 2026 + + + The catalog track MUST have a case-sensitive Track Name of "catalog". + + A catalog object MAY be independent of other catalog objects or it + MAY represent a delta update of a prior catalog object. The first + catalog object published within a new group MUST be independent and + MUST provide a complete catalog that does not require any prior + catalog object for interpretation. Any catalog updates that precede + the first Object of the latest Group MUST be ignored. + + A catalog object SHOULD be published only when the availability of + tracks changes, or after a period of time has passed such that the + catalog object might fall out of cache in a delivery network. + + Each catalog update MUST be mapped to an MOQT Object. All catalog + updates, both independent and delta, MUST be mapped to MOQT sub-group + 0. The first Object (with Object ID 0) in any Group in a catalog + track MUST hold an independent copy of the catalog. All subsequent + Objects within that Group (i.e Objects IDs >= 1) MUST hold a delta + update. As soon as an independent update is produced, it MUST be + placed at the start of a new Group. + + Subscribers accessing the catalog MUST use SUBSCRIBE with a Joining + FETCH (offset = 0) in order to obtain the latest complete catalog + along with all subsequent catalog objects, including delta updates, + that follow. + + A catalog is a JSON [JSON] document, comprised of a series of + mandatory and optional fields. At a minimum, a catalog MUST provide + all mandatory fields. Some fields are conditional depending on the + type of content carried. A producer MAY add additional fields to the + ones described in this draft. Custom field names MUST NOT collide + with field names described in this draft. + + A parser MUST ignore fields it does not understand. + +5.1. Root Catalog Fields + + Table 1 lists the fields defined at the root of the catalog JSON + object. + + + + + + + + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 10] + +Internet-Draft MOQT Streaming Format June 2026 + + + +==========================+===============+===============+ + | Field | Name | Definition | + +==========================+===============+===============+ + | MSF version | version | Section 5.1.1 | + +--------------------------+---------------+---------------+ + | Generated at | generatedAt | Section 5.1.2 | + +--------------------------+---------------+---------------+ + | Is Complete | isComplete | Section 5.1.3 | + +--------------------------+---------------+---------------+ + | Tracks | tracks | Section 5.1.4 | + +--------------------------+---------------+---------------+ + | Publish tracks | publishTracks | Section 5.1.5 | + +--------------------------+---------------+---------------+ + | Delta update | deltaUpdate | Section 5.1.6 | + +--------------------------+---------------+---------------+ + | Initialization Data List | initDataList | Section 5.1.7 | + +--------------------------+---------------+---------------+ + + Table 1 + +5.1.1. MSF version + + Required: Yes JSON Type: String Location: Root Catalog + + Specifies the version of MSF referenced by this catalog. There is no + guarantee that future catalog versions are backwards compatible and + field definitions and interpretation may change between versions. A + subscriber MUST NOT attempt to parse a catalog version which it does + not understand. + + For usage against IETF Internet-Draft releases, follow the convention + of specifying the version as "draft-XX". For example "draft-03" + refers to the -03 draft release. + +5.1.2. Generated at + + Required: Optional JSON Type: Number Location: Root Catalog + + The wallclock time at which this catalog instance was generated, + expressed as the number of milliseconds that have elapsed since + January 1, 1970 (midnight UTC/GMT). This field SHOULD NOT be + included if the isLive field is false. + +5.1.3. Is Complete + + Required: Optional JSON Type: Boolean Location: Root Catalog + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 11] + +Internet-Draft MOQT Streaming Format June 2026 + + + A catalog-level indication that the broadcast is complete. This is a + commitment that all tracks are complete, no new tracks will be added + to the catalog, and no new content will be published on any track. + Note that even if all individual tracks have isLive Section 5.2.7 set + to FALSE, new tracks could still be added to the catalog until + isComplete is set to TRUE. This field MUST NOT be included if it is + FALSE. This field MUST NOT be removed from a catalog once it has + been added. + +5.1.4. Tracks + + Required: Yes JSON Type: Array Location: Root Catalog + + An array of track objects Section 5.2.1. + +5.1.5. Publish tracks + + Location: R Required: Optional JSON Type: Array + + An array of publish track objects. Publish tracks define tracks to + which the subscriber can publish data, such as logs, metrics, or + other QoE data. This enables bi-directional communication where the + subscriber acts as a publisher for specific tracks. Each publish + track object follows the same structure as a regular track object + Section 5.2.1 but is used for the reverse direction of data flow. + +5.1.6. Delta update + + Required: Optional JSON Type: Array Location: Root Catalog + + An ordered Array of operation objects that specify changes to apply + to the catalog. If this field is present, the catalog represents a + delta (or partial) update with a restricted set of fields and special + processing rules - see Section 5.3. If this field is absent, the + catalog is independent. + + Operations are applied sequentially in the order they appear in the + array. Each operation object MUST contain an "op" field indicating + the operation type, and a "tracks" field containing an Array of track + objects Section 5.2.1. The following operation types are defined: + + * "add" - Add new tracks that have not previously been declared. + The value of the "tracks" field is an Array of track objects + Section 5.2.1. + + + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 12] + +Internet-Draft MOQT Streaming Format June 2026 + + + * "remove" - Remove tracks that have been previously declared. The + value of the "tracks" field is an Array of track objects + Section 5.2.1. Each track object MUST include a Track Name + Section 5.2.3 field, MAY include a Track Namespace Section 5.2.2 + field, and MUST NOT hold any other fields. + + * "clone" - Clone new tracks from previously declared tracks. The + value of the "tracks" field is an Array of track objects + Section 5.2.1. Each track object MUST include a Parent Name + Section 5.2.33 field and MAY include a Parent namespace + Section 5.2.34 field. The cloned track inherits all attributes + from the parent except the Track Name which MUST be new. + Attributes redefined in the track object override inherited + values. + +5.1.7. Initialization Data List + + Required: Optional JSON Type: Array Location: Root Catalog + + An array of initialization reference objects. Each initialization + reference object has the following fields: + + * id : a string defining a reference to this initialization data + which is unique within the scope of the catalog. + + * type: as string defining the type of reference. This version of + the specification defines a single allowed type, per the table + below + + +========+=============================================+ + | Type | Data field definition | + +========+=============================================+ + | inline | Base64 [BASE64] encoded initialization data | + +--------+---------------------------------------------+ + + Table 2 + + * data: a string holding the init payload as defined by the type. + + The Initialization Data List, if present, MUST be located after the + tracks array in the root of the JSON catalog. The purpose of this is + to improve the human readability of the catalog tracks by moving the + verbose init data towards the end of the document. + +5.2. Track Object Fields + + Table 2 lists the fields defined within each track object. + + + + +Law & Nandakumar Expires 4 December 2026 [Page 13] + +Internet-Draft MOQT Streaming Format June 2026 + + + +========================+==================+================+ + | Field | Name | Definition | + +========================+==================+================+ + | Track namespace | namespace | Section 5.2.2 | + +------------------------+------------------+----------------+ + | Track name | name | Section 5.2.3 | + +------------------------+------------------+----------------+ + | Packaging | packaging | Section 5.2.4 | + +------------------------+------------------+----------------+ + | Event timeline type | eventType | Section 5.2.5 | + +------------------------+------------------+----------------+ + | Is Live | isLive | Section 5.2.7 | + +------------------------+------------------+----------------+ + | Target latency | targetLatency | Section 5.2.8 | + +------------------------+------------------+----------------+ + | Buffers | buffers | Section 5.2.9 | + +------------------------+------------------+----------------+ + | Track role | role | Section 5.2.6 | + +------------------------+------------------+----------------+ + | Track label | label | Section 5.2.10 | + +------------------------+------------------+----------------+ + | Render group | renderGroup | Section 5.2.11 | + +------------------------+------------------+----------------+ + | Alternate group | altGroup | Section 5.2.12 | + +------------------------+------------------+----------------+ + | Initialization ref | initRef | Section 5.2.13 | + +------------------------+------------------+----------------+ + | Dependencies | depends | Section 5.2.14 | + +------------------------+------------------+----------------+ + | Temporal ID | temporalId | Section 5.2.16 | + +------------------------+------------------+----------------+ + | Spatial ID | spatialId | Section 5.2.17 | + +------------------------+------------------+----------------+ + | Codec | codec | Section 5.2.18 | + +------------------------+------------------+----------------+ + | Mime type | mimeType | Section 5.2.19 | + +------------------------+------------------+----------------+ + | Framerate | framerate | Section 5.2.20 | + +------------------------+------------------+----------------+ + | Timescale | timescale | Section 5.2.21 | + +------------------------+------------------+----------------+ + | Maximum Bitrate | bitrate | Section 5.2.22 | + +------------------------+------------------+----------------+ + | Average Bitrate | avgBitrate | Section 5.2.23 | + +------------------------+------------------+----------------+ + | Maximum GOP Duration | maxGopDuration | Section 5.2.24 | + +------------------------+------------------+----------------+ + | Maximum Group Duration | maxGroupDuration | Section 5.2.25 | + + + +Law & Nandakumar Expires 4 December 2026 [Page 14] + +Internet-Draft MOQT Streaming Format June 2026 + + + +------------------------+------------------+----------------+ + | Width | width | Section 5.2.26 | + +------------------------+------------------+----------------+ + | Height | height | Section 5.2.27 | + +------------------------+------------------+----------------+ + | Audio sample rate | samplerate | Section 5.2.28 | + +------------------------+------------------+----------------+ + | Channel configuration | channelConfig | Section 5.2.29 | + +------------------------+------------------+----------------+ + | Display width | displayWidth | Section 5.2.30 | + +------------------------+------------------+----------------+ + | Display height | displayHeight | Section 5.2.31 | + +------------------------+------------------+----------------+ + | Language | lang | Section 5.2.32 | + +------------------------+------------------+----------------+ + | Parent name | parentName | Section 5.2.33 | + +------------------------+------------------+----------------+ + | Parent namespace | parentNamespace | Section 5.2.34 | + +------------------------+------------------+----------------+ + | Track duration | trackDuration | Section 5.2.35 | + +------------------------+------------------+----------------+ + | Authorization Info | authInfo | Section 5.2.42 | + +------------------------+------------------+----------------+ + | Accessibility | accessibility | Section 5.2.44 | + +------------------------+------------------+----------------+ + + Table 3 + +5.2.1. Tracks object + + A track object is a JSON Object containing a collection of fields + whose location is specified in Table 2. + +5.2.2. Track namespace + + Required: Optional JSON Type: String Location: Track Object + + The name space under which the track name is defined. See section + 2.3 of [MoQTransport]. The track namespace is optional. If it is + not declared within a track, then each track MUST inherit the + namespace of the catalog track. A namespace declared in a track + object overrides any inherited name space. + +5.2.3. Track name + + Required: Yes JSON Type: String Location: Track Object + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 15] + +Internet-Draft MOQT Streaming Format June 2026 + + + A string defining the name of the track. See section 2.3 of + [MoQTransport]. Within the catalog, track names MUST be unique per + namespace. + +5.2.4. Packaging + + Required: Yes JSON Type: String Location: Track Object + + A string defining the type of payload encapsulation. Allowed values + are strings as defined in Table 3. + + +================+===============+==================+ + | Name | Value | Reference | + +================+===============+==================+ + | LOC | loc | See RFC XXXX | + +----------------+---------------+------------------+ + | Media Timeline | mediatimeline | See Section 7 | + +----------------+---------------+------------------+ + | Event Timeline | eventtimeline | See Section 8 | + +----------------+---------------+------------------+ + | MoQ Log | moqlog | See [MOQLOG] | + +----------------+---------------+------------------+ + | MoQ Metrics | moqmetrics | See [MOQMETRICS] | + +----------------+---------------+------------------+ + + Table 4 + + Table 3: Allowed packaging values + +5.2.5. Event timeline type + + Required: Optional JSON Type: String Location: Track Object + + A String defining the type & structure of the data contained within + the data field of the Event timeline track. Types are defined by the + application provider and are not centrally registered. Implementers + are encouraged to use a unique naming scheme, such as Reverse Domain + Name Notation, where domain name components are listed in reverse + order (e.g., "com.example.myeventtype"), to avoid naming collisions. + This field is required if the Section 5.2.4 value is "eventtimeline". + This field MUST NOT be used if the packaging value is not + "eventtimeline". + +5.2.6. Track role + + Required: Optional JSON Type: String Location: Track Object + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 16] + +Internet-Draft MOQT Streaming Format June 2026 + + + A string defining the role of content carried by the track. + Specified roles are described in Table 4. These role values are + case-sensitive. + + This role field MAY be used in conjunction with the Mimetype + Section 5.2.19 to fully describe the content of the track. + + Table 4: Reserved track roles + + +==================+==========================+ + | Role | Description | + +==================+==========================+ + | audiodescription | An audio description for | + | | visually impaired users | + +------------------+--------------------------+ + | video | Visual content | + +------------------+--------------------------+ + | audio | Audio content | + +------------------+--------------------------+ + | mediatimeline | An MSF media timeline | + | | Section 7 | + +------------------+--------------------------+ + | eventtimeline | An MSF event timeline | + | | Section 8 | + +------------------+--------------------------+ + | caption | A textual representation | + | | of the audio track | + +------------------+--------------------------+ + | subtitle | A transcription of the | + | | spoken dialogue | + +------------------+--------------------------+ + | signlanguage | A visual track for | + | | hearing impaired users. | + +------------------+--------------------------+ + | log | A log publishing track | + | | per [MOQLOG]. | + +------------------+--------------------------+ + | metrics | A metrics publishing | + | | track per [MOQMETRICS]. | + +------------------+--------------------------+ + + Table 5 + + Custom roles MAY be used as long as they do not collide with the + specified roles. + + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 17] + +Internet-Draft MOQT Streaming Format June 2026 + + +5.2.7. Is Live + + Required: Yes JSON Type: Boolean Location: Track Object + + A track-level indication of whether new Objects will be added to this + specific track. True if new Objects will be added to the track. + False if no new Objects will be added to the track. A False value is + sent under two possible conditions: * the publisher of a previously + live track has ended the track. * the track is Video-On-Demand (VOD) + and was never live. A True value MUST never follow a False value. + +5.2.8. Target latency + + Required: Optional JSON Type: Number Location: Track Object + + The target latency in milliseconds. Target latency is defined as the + offset in wallclock time between when content was encoded and when it + is displayed to the end user. For example, if a frame of video is + encoded at 10:08:32.638 UTC and the target latency is 5000, then that + frame should be rendered to the end-user at 10:08:37.638 UTC. If + isLive is FALSE, this field MUST be ignored. All tracks belonging to + the same render group MUST have identical target latencies. All + tracks belonging to the same alternate group MUST have identical + target latencies. If this field is absent from the track definition, + and isLive is TRUE, then the player MAY choose the latency with which + it renders the content. + + This property MUST NOT be present if the buffers Section 5.2.9 + property is present within a track definition. + +5.2.9. Buffers + + Required: Optional JSON Type: Object Location: Track Object + + An object defining a set of target buffers. Buffer is defined as the + duration of media data that MUST be buffered before decoding + commences. This is typically known as a forward or jitter-buffer in + a media player.Players with identical buffer lengths are likely to be + synchronized. The target buffer object has these keys: + + * target : defines the target buffer in integer milliseconds. + Players SHOULD attempt to stabilize playback at this value. + + * min : defines the minimum buffer in milliseconds. Players SHOULD + NOT operate below this value. + + * max : defines the maximum buffer in milliseconds. Players SHOULD + NOT operate above this value. + + + +Law & Nandakumar Expires 4 December 2026 [Page 18] + +Internet-Draft MOQT Streaming Format June 2026 + + + Keys are optional. Unknown keys in the target buffer object MUST be + ignored. + + If isLive is FALSE, this target buffer property MUST be ignored. All + tracks belonging to the same render group MUST have identical target + buffers. All tracks belonging to the same alternate group MUST have + identical target buffers. If this field is absent from the track + definition, and isLive is TRUE, then the player MAY choose the + buffers with which it conducts playback. + + This property MUST NOT be present if the target latency Section 5.2.8 + property is present within a track definition. + +5.2.10. Track label + + Required: Optional JSON Type: String Location: Track Object + + A string defining a human-readable label for the track. Examples + might be "Overhead camera view" or "Deutscher Kommentar". Note that + the [JSON] spec requires UTF-8 support by decoders. + +5.2.11. Render group + + Required: Optional JSON Type: Number Location: Track Object + + An integer specifying a group of tracks which are designed to be + rendered together. Tracks with the same group number SHOULD be + rendered simultaneously and are designed to accompany one another. A + common example would be tying together audio and video tracks. + +5.2.12. Alternate group + + Required: Optional JSON Type: Number Location: Track Object + + An integer specifying a group of tracks which are alternate versions + of one-another. Alternate tracks represent the same media content, + but differ in their selection properties. Alternate tracks MUST have + matching media time sequences. A subscriber typically subscribes to + one track from a set of tracks specifying the same alternate group + number. A common example would be a set video tracks of the same + content offered in alternate bitrates. + +5.2.13. Initialization reference + + Required: Optional JSON Type: String Location: Track Object + + A string pointing at the id field of an entry in the Initialization + Data List Section 5.1.7. + + + +Law & Nandakumar Expires 4 December 2026 [Page 19] + +Internet-Draft MOQT Streaming Format June 2026 + + +5.2.14. Dependencies + + Required: Optional JSON Type: Array Location: Track Object + + Certain tracks may depend on other tracks for decoding. Dependencies + holds an array of track names Section 5.2.3 on which the current + track is dependent. Since only the track name is signaled, the + namespace of the dependencies is assumed to match that of the track + declaring the dependencies. + +5.2.15. Template + + Required: Optional JSON Type: Array Location: Track Object + + A media timeline template for tracks with fixed-duration segments. + It specifies the relationship between media time, MOQT Location, and + wallclock time through starting points and intervals. See + Section 7.4 for the complete format specification, field definitions, + and computation formulas. + + Tracks that include a template field SHOULD NOT also have a separate + media timeline track, as the template provides equivalent + functionality. Different tracks (e.g., audio and video) MAY have + independent template values to accommodate different group durations. + +5.2.16. Temporal ID + + Required: Optional JSON Type: Number Location: Track Object + + A number identifying the temporal layer/sub-layer encoding of the + track, starting with 0 for the base layer, and increasing by 1 for + the next higher temporal fidelity. + +5.2.17. Spatial ID + + Required: Optional JSON Type: Number Location: Track Object + + A number identifying the spatial layer encoding of the track, + starting with 0 for the base layer, and increasing by 1 for the next + higher fidelity. + +5.2.18. Codec + + Required: Conditional JSON Type: String Location: Track Object + + A string defining the codec used to encode the track. For LOC + packaged content, the string codec registrations are defined in Sect + 3 and Section 4 of [WEBCODECS-CODEC-REGISTRY]. This property MUST be + + + +Law & Nandakumar Expires 4 December 2026 [Page 20] + +Internet-Draft MOQT Streaming Format June 2026 + + + specified for tracks which have an inherent codec associated with + them (e.g., audio and video tracks). It is not required for raw data + tracks or event streams. + +5.2.19. Mimetype + + Required: Optional JSON Type: String Location: Track Object + + A string defining the mime type [MIME] of the track. + +5.2.20. Framerate + + Required: Optional JSON Type: Number Location: Track Object + + A number defining the framerate of the track, expressed as frames per + second. This property SHOULD only accompany video or other frame- + based content. + +5.2.21. Timescale + + Required: Optional JSON Type: Number Location: Track Object + + The number of time units that pass per second. + +5.2.22. Maximum Bitrate + + Required: Conditional JSON Type: Number Location: Track Object + + A number defining the maximum bitrate of the track, expressed in bits + per second. This property MUST be specified for audio and video + tracks. + +5.2.23. Average Bitrate + + Required: Optional JSON Type: Number Location: Track Object + + A number defining the average bitrate of the track, over the lifetime + of the track, expressed in bits per second. + +5.2.24. Maximum GOP Duration + + Required: Optional JSON Type: Number Location: Track Object + + A number defining the maximum duration, expressed in milliseconds, + between successive independently decodable points (random access + points) in the media track. This property SHOULD only accompany + video tracks. + + + + +Law & Nandakumar Expires 4 December 2026 [Page 21] + +Internet-Draft MOQT Streaming Format June 2026 + + +5.2.25. Maximum Group Duration + + Required: Optional JSON Type: Number Location: Track Object + + A number defining the maximum duration, expressed in milliseconds, of + any MOQT Group in this track. This value helps subscribers estimate + buffer requirements for the track. + +5.2.26. Width + + Required: Optional JSON Type: Number Location: Track Object + + A number expressing the maximum encoded width of the video frames in + pixels. This property SHOULD accompany tracks which have a visual + representation. + +5.2.27. Height + + Required: Optional JSON Type: Number Location: Track Object + + A number expressing the maximum encoded height of the video frames in + pixels. This property SHOULD accompany tracks which have a visual + representation. + +5.2.28. Audio sample rate + + Required: Conditional JSON Type: Number Location: Track Object + + The number of audio frame samples per second. This property MUST + accompany tracks for which audio codecs are specified. + +5.2.29. Channel configuration + + Required: Conditional JSON Type: String Location: Track Object + + A string specifying the audio channel configuration. A string is + used in order to provide the flexibility to describe complex channel + configurations for multi-channel and Next Generation Audio schemas. + This property MUST accompany tracks for which audio codecs are + specified. + +5.2.30. Display width + + Required: Optional JSON Type: Number Location: Track Object + + A number expressing the intended display width of the track content + in pixels. This property SHOULD only accompany tracks which have a + visual representation. + + + +Law & Nandakumar Expires 4 December 2026 [Page 22] + +Internet-Draft MOQT Streaming Format June 2026 + + +5.2.31. Display height + + Required: Optional JSON Type: Number Location: Track Object + + A number expressing the intended display height of the track content + in pixels. This property SHOULD only accompany tracks which have a + visual representation. + +5.2.32. Language + + Required: Optional JSON Type: String Location: Track Object + + A string defining the dominant language of the track. The string + MUST be one of the standard Tags for Identifying Languages as defined + by [LANG]. + +5.2.33. Parent name + + Required: Optional JSON Type: String Location: Track Object + + A string defining the parent track name Section 5.2.3 to be cloned. + This field MUST only be included inside a clone operation in a delta + update Section 5.1.6. + +5.2.34. Parent namespace + + Required: Optional JSON Type: String Location: Track Object + + A string defining the parent track namespace Section 5.2.2 to be + cloned. This field MUST only be included inside a clone operation in + a delta update Section 5.1.6. If this field is missing from a clone + operation, then the namespace of the catalog is assumed. + +5.2.35. Track duration + + Required: Optional JSON Type: Number Location: Track Object + + The duration of the track expressed in integer milliseconds. This + field MUST NOT be included if the isLive Section 5.2.7 field value is + true. + +5.2.36. Connection URI + + Required: Optional JSON Type: String Location: Track Object + + + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 23] + +Internet-Draft MOQT Streaming Format June 2026 + + + A string containing the MOQT connection endpoint URI for the publish + track. When specified, the subscriber MUST establish a new MOQT + connection to this URI for publishing the track data. If this field + is absent, the subscriber SHOULD reuse the existing MOQT connection + that was used to receive the catalog. + + The URI MUST be a valid MOQT endpoint URI as defined by + [MoQTransport] (Sect 3.1.1). Examples include + "moqt://logs.example.com:4443", "moqt://metrics.example.com:8443", or + "https://logs.example.com/moqt". + +5.2.37. Token + + Required: Optional JSON Type: String Location: Track Object + + A string containing an authentication token or credential for the + track. For publish tracks, this token authorizes the subscriber to + publish data to the specified track. The format and validation of + the token is application-specific. + +5.2.38. Encryption scheme + + Required: Optional JSON Type: String Location: Track Object + + A string identifying the encryption scheme used to protect the track + content. The default and RECOMMENDED value is "moq-secure-objects" + as defined in [SecureObjects]. If this field is absent, the track + content is unencrypted. + + Table 5: Registered encryption schemes + + +====================+====================+=================+ + | Name | Value | Reference | + +====================+====================+=================+ + | MoQ Secure Objects | moq-secure-objects | [SecureObjects] | + +--------------------+--------------------+-----------------+ + + Table 6 + + Custom encryption schemes MAY be used. Custom scheme names SHOULD + use Reverse Domain Name Notation to avoid collisions (e.g., + "com.example.custom-encryption"). + +5.2.39. Cipher suite + + Required: Optional JSON Type: String Location: Track Object + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 24] + +Internet-Draft MOQT Streaming Format June 2026 + + + A string identifying the AEAD cipher suite used for encryption. This + field MUST be present when encryptionScheme is specified. For the + "moq-secure-objects" scheme, the following cipher suites are defined: + + Table 6: Cipher suites for moq-secure-objects + + +============================+============================+======+ + | Name | Value | Tag | + | | | Size | + +============================+============================+======+ + | AES-128-GCM-SHA256 | aes-128-gcm-sha256 | 128 | + | | | bits | + +----------------------------+----------------------------+------+ + | AES-256-GCM-SHA512 | aes-256-gcm-sha512 | 128 | + | | | bits | + +----------------------------+----------------------------+------+ + | AES-128-CTR-HMAC-SHA256-80 | aes-128-ctr-hmac-sha256-80 | 80 | + | | | bits | + +----------------------------+----------------------------+------+ + + Table 7 + + Implementations MUST support "aes-128-gcm-sha256". Implementations + SHOULD support "aes-128-ctr-hmac-sha256-80" for scenarios requiring + smaller authentication tags. + +5.2.40. Key ID + + Required: Optional JSON Type: String Location: Track Object + + A string identifying the key material used for encryption. This + value is transmitted in the Secure Object KID extension header as + defined in ([SecureObjects], Section 4.2) of each encrypted object. + + The keyId and associated trackBaseKey are obtained from an external + key management system. The mechanism for obtaining these values is + out of scope for this specification. Examples include MLS-based key + distribution [E2EE-MLS] or other out-of-band key exchange mechanisms. + + The scope of a keyId is determined by the key management system in + use. A keyId MAY be scoped to a single track, a single MSF session, + or multiple tracks and sessions. When multiple tracks share the same + Key ID, they MAY share the same base key material, though per-track + keys are derived using the track name as defined in ([SecureObjects], + Section 5). + + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 25] + +Internet-Draft MOQT Streaming Format June 2026 + + +5.2.41. Track Base Key + + Required: Optional JSON Type: String Location: Track Object + + A base64-encoded [BASE64] string containing the base key material for + this track, as defined in ([SecureObjects], Section 5). This field + works in conjunction with keyId to provide the cryptographic material + needed for decryption. The trackBaseKey is obtained from the same + key management system that provides the keyId. + + When present, this field contains the raw key material that, together + with the track name and other parameters defined in ([SecureObjects], + Section 5), is used to derive the actual encryption keys. Publishers + and subscribers MUST use matching trackBaseKey values for successful + decryption. + +5.2.42. Authorization Info + + Required: Optional JSON Type: Object Location: Track Object + + An object indicating that authorization is required to access this + track. The presence of this field signals to subscribers that they + must obtain and present valid authorization tokens when subscribing + to this track. + + The keys of this object are authorization scheme identifiers. + Registered schemes are defined in Table 7. The values are scheme- + specific configuration objects defined by the referenced + specifications. + + Table 7: Registered Authorization Schemes + + +==============+==============+===================+ + | Scheme | Value | Reference | + +==============+==============+===================+ + | Privacy Pass | privacy-pass | [PrivacyPassAuth] | + +--------------+--------------+-------------------+ + | CAT | cat | [C4M] | + +--------------+--------------+-------------------+ + + Table 8 + + Custom authorization schemes MAY be used. Custom scheme names MUST + use a unique naming convention, such as Reverse Domain Name Notation + (e.g., "com.example.custom-auth"), to avoid naming collisions. + + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 26] + +Internet-Draft MOQT Streaming Format June 2026 + + + Subscribers inspect the authInfo field to determine which + authorization scheme to use and then obtain tokens through out-of- + band mechanisms. The specific token format, acquisition process, and + presentation method are defined by the authorization scheme + specification. + +5.2.43. Token Delivery via URI + + Tokens can be delivered to subscribers through the catalog request + URI using variable substitution. Fragment parameters (following the + # character) are processed client-side and can be substituted into + catalog fields using the variable substitution mechanism defined in + Section 5.4. + + For example, given a URI: + + moqt://relay.example.com/live#namespace--name&token=XYZ789 + + A catalog with: + + "authInfo": { + "cat": "%token%" + } + + Would be resolved by the subscriber to include "cat": "XYZ789", which + is then presented in control messages as specified by the + authorization scheme. + +5.2.44. Accessibility + + Required: Optional JSON Type: Array Location: Track Object + + An array of accessibility descriptors indicating accessibility + features embedded within the track. Each descriptor is a JSON Object + containing: + + * A required 'scheme' field (String) identifying the accessibility + scheme. + + * A required 'value' field (String) specifying the accessibility + channels or features available. + + Table 6: Registered accessibility schemes + + + + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 27] + +Internet-Draft MOQT Streaming Format June 2026 + + + +===============================+=========================+ + | Scheme | Description | + +===============================+=========================+ + | urn:scte:dash:cc:cea-608:2015 | CEA-608 closed captions | + +-------------------------------+-------------------------+ + | urn:scte:dash:cc:cea-708:2015 | CEA-708 closed captions | + +-------------------------------+-------------------------+ + + Table 9 + + The 'value' field for CEA-608/708 schemes uses the format defined by + [SCTE214-1], where caption service channels are specified as + semicolon-separated pairs of channel identifier and language code + (e.g., "CC1=eng;CC3=spa"). + + A subscriber MAY use this information to determine caption + availability and configure an appropriate caption decoder. + +5.3. Delta updates + + A catalog update might contain incremental changes. This is a useful + property if many tracks may be initially declared but then there are + small changes to a subset of tracks. The producer can issue a delta + update to describe these changes. Changes are described + incrementally, meaning that a delta update can itself modify a prior + delta update. + + A restricted set of operations are allowed with each delta update: * + Add a new track that has not previously been declared. * Add a new + track by cloning a previously declared track. * Remove a track that + has been previously declared. + + The following rules are to be followed in constructing and processing + delta updates: + + * A delta update MUST include the Delta Update Section 5.1.6 field + with at least one operation. It MUST NOT contain an instance of a + Tracks Section 5.1.4 field or an MSF version Section 5.1.1 field. + + * Operations are applied sequentially in the order they appear in + the deltaUpdate array. Each operation is applied to the target + document; the resulting document becomes the target of the next + operation. Evaluation continues until all operations are + successfully applied. + + + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 28] + +Internet-Draft MOQT Streaming Format June 2026 + + + * The tuple of Track Namespace and Track Name defines a fixed set of + Track attributes which MUST NOT be modified after being declared. + To modify any attribute, a new track with a different + Namespace|Name tuple is created by Adding or Cloning and then the + old track is removed. + + * Producers that publish frequent delta updates SHOULD periodically + publish a new independent catalog in a new MOQT Group in order to + bound the amount of delta processing required for joining + subscribers. + +5.4. Variable Substitution + + Catalog field values MAY contain variables that are substituted at + delivery time. This mechanism enables a single cached catalog to be + customized for each viewer, supporting use cases such as personalized + advertising, A/B watermarking, QoE reporting endpoints, and logging + identifiers. + +5.4.1. Variable Syntax + + Variables are denoted by enclosing the variable name in percent + characters (%). Variable names MUST consist of alphanumeric + characters, hyphens, and underscores. Variable names are case- + sensitive. + + The percent character (%) MUST NOT appear in catalog field values + except as part of a variable reference. Literal percent characters + are not permitted. + + Variable values MUST consist only of alphanumeric characters, + hyphens, underscores, and the at sign (@). Special characters + including commas, semicolons, quotes, ampersands, and other + punctuation MUST NOT appear in variable values. This restriction + prevents injection attacks and ensures safe substitution into catalog + field values. + +5.4.2. Variable Resolution + + Variables are resolved from the fragment identifier of the URI used + to access the catalog. The fragment identifier is the portion + following the # character and is processed entirely client-side, + making it suitable for per-viewer customization without affecting + server-side caching. + + Query parameters (following the ? character) are reserved for server- + side processing and MUST NOT be used for variable substitution. + + + + +Law & Nandakumar Expires 4 December 2026 [Page 29] + +Internet-Draft MOQT Streaming Format June 2026 + + + When a subscriber requests a catalog using a URI containing a + fragment identifier, the fragment is parsed as key-value pairs (using + & as delimiter and = as separator). Each key becomes available as a + variable name, and the variable is replaced with the corresponding + value. + +5.5. Catalog Compression + + Catalogs can contain significant redundancy, particularly when + initialization data is included. To reduce payload size, catalog + objects MAY be compressed using the MSF_COMPRESSION property + (Section 12.1). If all catalog objects are compressed, the track + property (Section 12.1.1) is used. If only some catalog objects are + compressed (for example, the complete catalog is compressed while + delta updates are not), the object property (Section 12.1.2) is used + on each compressed object. + +5.6. Catalog Examples + + The following section provides non-normative JSON examples of various + catalogs compliant with this draft. + +5.6.1. Time-aligned Audio/Video Tracks with single quality + + This example shows a catalog for a media producer capable of sending + LOC packaged, time-aligned audio and video tracks. + + + + + + + + + + + + + + + + + + + + + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 30] + +Internet-Draft MOQT Streaming Format June 2026 + + + { + "version": "1", + "generatedAt": 1746104606044, + "tracks": [ + { + "name": "1080p-video", + "namespace": "conference.example.com/conference123/alice", + "packaging": "loc", + "isLive": true, + "targetLatency": 2000, + "role": "video", + "renderGroup": 1, + "codec":"av01.0.08M.10.0.110.09", + "width":1920, + "height":1080, + "framerate":30, + "bitrate":1500000 + }, + { + "name": "audio", + "namespace": "conference.example.com/conference123/alice", + "packaging": "loc", + "isLive": true, + "targetLatency": 2000, + "role": "audio", + "renderGroup": 1, + "codec":"opus", + "samplerate":48000, + "channelConfig":"2", + "bitrate":32000 + } + ] + } + +5.6.2. Simulcast video tracks - 3 alternate qualities along with audio + + This example shows a catalog for a media producer capable of sending + 3 time-aligned video tracks for high definition, low definition and + medium definition video qualities, along with an audio track. In + this example the namespace is absent, which infers that each track + must inherit the namespace of the catalog. + + { + "version": "1", + "generatedAt": 1746104606044, + "tracks":[ + { + "name": "hd", + + + +Law & Nandakumar Expires 4 December 2026 [Page 31] + +Internet-Draft MOQT Streaming Format June 2026 + + + "renderGroup": 1, + "packaging": "loc", + "isLive": true, + "targetLatency": 1500, + "role": "video", + "codec":"av01", + "width":1920, + "height":1080, + "bitrate":5000000, + "framerate":30, + "altGroup":1 + }, + { + "name": "md", + "renderGroup": 1, + "packaging": "loc", + "isLive": true, + "targetLatency": 1500, + "role": "video", + "codec":"av01", + "width":720, + "height":640, + "bitrate":3000000, + "framerate":30, + "altGroup":1 + }, + { + "name": "sd", + "renderGroup": 1, + "packaging": "loc", + "isLive": true, + "targetLatency": 1500, + "role": "video", + "codec":"av01", + "width":192, + "height":144, + "bitrate":500000, + "framerate":30, + "altGroup":1 + }, + { + "name": "audio", + "renderGroup": 1, + "packaging": "loc", + "isLive": true, + "targetLatency": 1500, + "role": "audio", + "codec":"opus", + + + +Law & Nandakumar Expires 4 December 2026 [Page 32] + +Internet-Draft MOQT Streaming Format June 2026 + + + "samplerate":48000, + "channelConfig":"2", + "bitrate":32000 + } + ] + } + +5.6.3. SVC video tracks with 2 spatial and 2 temporal qualities + + This example shows a catalog for a media producer capable of sending + scalable video codec with 2 spatial and 2 temporal layers with a + dependency relation as shown below: + + +----------+ + +----------->| S1T1 | + | | 1080p30 | + | +----------+ + | ^ + | | + +----------+ | + | S1TO | | + | 1080p15 | | + +----------+ +-----+----+ + ^ | SOT1 | + | | 480p30 | + | +----------+ + | ^ + +----------+ | + | SOTO | | + | 480p15 |---------+ + +----------+ + + The corresponding catalog uses "depends" attribute to express the + track relationships. + + { + "version": "1", + "generatedAt": 1746104606044, + "tracks":[ + { + "name": "480p15", + "namespace": "conference.example.com/conference123/alice", + "renderGroup": 1, + "packaging": "loc", + "isLive": true, + "buffers": {"target":2000}, + "role": "video", + "codec":"av01.0.01M.10.0.110.09", + + + +Law & Nandakumar Expires 4 December 2026 [Page 33] + +Internet-Draft MOQT Streaming Format June 2026 + + + "width":640, + "height":480, + "bitrate":3000000, + "framerate":15 + }, + { + "name": "480p30", + "namespace": "conference.example.com/conference123/alice", + "renderGroup": 1, + "packaging": "loc", + "isLive": true, + "buffers": {"target":2000}, + "role": "video", + "codec":"av01.0.04M.10.0.110.09", + "width":640, + "height":480, + "bitrate":3000000, + "framerate":30, + "depends": ["480p15"] + }, + { + "name": "1080p15", + "namespace": "conference.example.com/conference123/alice", + "renderGroup": 1, + "packaging": "loc", + "isLive": true, + "buffers": {"target":2000}, + "role": "video", + "codec":"av01.0.05M.10.0.110.09", + "width":1920, + "height":1080, + "bitrate":3000000, + "framerate":15, + "depends":["480p15"] + }, + + { + "name": "1080p30", + "namespace": "conference.example.com/conference123/alice", + "renderGroup": 1, + "packaging": "loc", + "isLive": true, + "buffers": {"target":2000}, + "role": "video", + "codec":"av01.0.08M.10.0.110.09", + "width":1920, + "height":1080, + "bitrate":5000000, + + + +Law & Nandakumar Expires 4 December 2026 [Page 34] + +Internet-Draft MOQT Streaming Format June 2026 + + + "framerate":30, + "depends": ["480p30", "1080p15"] + }, + { + "name": "audio", + "namespace": "conference.example.com/conference123/alice", + "renderGroup": 1, + "packaging": "loc", + "isLive": true, + "buffers": {"target":2000}, + "role": "audio", + "codec":"opus", + "samplerate":48000, + "channelConfig":"2", + "bitrate":32000 + } + ] + } + +5.6.4. Delta update - adding two tracks + + This example shows the catalog delta update for a media producer + adding two tracks to an established video conference. One track is + newly declared, the other is cloned from a previous track. + + + + + + + + + + + + + + + + + + + + + + + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 35] + +Internet-Draft MOQT Streaming Format June 2026 + + + { + "generatedAt": 1746104606044, + "deltaUpdate": [ + { + "op": "add", + "tracks": [ + { + "name": "slides", + "isLive": true, + "role": "video", + "codec": "av01.0.08M.10.0.110.09", + "width": 1920, + "height": 1080, + "framerate": 15, + "bitrate": 750000, + "renderGroup": 1 + } + ] + }, + { + "op": "clone", + "tracks": [ + { + "parentName": "video-1080", + "parentNamespace": "example.com/custom", + "name": "video-720", + "width": 1280, + "height": 720, + "bitrate": 600000 + } + ] + } + ] + } + +5.6.5. Delta update removing tracks + + This example shows a delta update for a media producer removing two + tracks from an established video conference. + + + + + + + + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 36] + +Internet-Draft MOQT Streaming Format June 2026 + + + { + "generatedAt": 1746104606044, + "deltaUpdate": [ + { + "op": "remove", + "tracks": [{"name": "video"}, {"name": "slides"}] + } + ] + } + +5.6.6. Time-aligned Audio/Video Tracks with custom field values + + This example shows a catalog for a media producer capable of sending + LOC packaged, time-aligned audio and video tracks along with custom + fields in each track description. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 37] + +Internet-Draft MOQT Streaming Format June 2026 + + + { + "version": "1", + "generatedAt": 1746104606044, + "tracks": [ + { + "name": "1080p-video", + "namespace": "conference.example.com/conference123/alice", + "packaging": "loc", + "isLive": true, + "buffers": {"target":2000, "min": 1500, "max": 5000}, + "role": "video", + "renderGroup": 1, + "codec":"av01.0.08M.10.0.110.09", + "width":1920, + "height":1080, + "framerate":30, + "bitrate":1500000, + "com.example-billing-code": 3201, + "com.example-tier": "premium", + "com.example-debug": "h349835bfkjfg82394d945034jsdfn349fns" + }, + { + "name": "audio", + "namespace": "conference.example.com/conference123/alice", + "packaging": "loc", + "isLive": true, + "buffers": {"target":2000, "min": 1500, "max": 5000}, + "role": "audio", + "renderGroup": 1, + "codec":"opus", + "samplerate":48000, + "channelConfig":"2", + "bitrate":32000 + } + ] + } + +5.6.7. Time-aligned VOD Audio/Video Tracks + + This example shows a catalog for a media producer offering VOD (video + on-demand) non-live content. The content is LOC packaged, and + includes time-aligned audio and video tracks. + + + + + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 38] + +Internet-Draft MOQT Streaming Format June 2026 + + + { + "version": "1", + "tracks": [ + { + "name": "video", + "namespace": "movies.example.com/assets/boy-meets-girl-season3/episode5", + "packaging": "loc", + "isLive": false, + "trackDuration": 8072340, + "renderGroup": 1, + "codec":"av01.0.08M.10.0.110.09", + "width":1920, + "height":1080, + "framerate":30, + "bitrate":1500000 + }, + { + "name": "audio", + "namespace": "movies.example.com/assets/boy-meets-girl-season3/episode5", + "packaging": "loc", + "isLive": false, + "trackDuration": 8072340, + "renderGroup": 1, + "codec":"opus", + "samplerate":48000, + "channelConfig":"2", + "bitrate":32000 + } + ] + } + +5.6.8. Encrypted Audio/Video Tracks + + This example shows a catalog for encrypted LOC-packaged audio and + video tracks using MoQ Secure Objects with AES-128-GCM. + + + + + + + + + + + + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 39] + +Internet-Draft MOQT Streaming Format June 2026 + + + { + "version": "1", + "generatedAt": 1746104606044, + "tracks": [ + { + "name": "1080p-video", + "namespace": "conference.example.com/conference123/alice", + "packaging": "loc", + "isLive": true, + "targetLatency": 2000, + "role": "video", + "renderGroup": 1, + "codec": "av01.0.08M.10.0.110.09", + "width": 1920, + "height": 1080, + "framerate": 30, + "bitrate": 1500000, + "encryptionScheme": "moq-secure-objects", + "cipherSuite": "aes-128-gcm-sha256", + "keyId": "key-2024-q1-premium", + "trackBaseKey": "dGhpc2lzYXNhbXBsZWJhc2VrZXk=" + }, + { + "name": "audio", + "namespace": "conference.example.com/conference123/alice", + "packaging": "loc", + "isLive": true, + "targetLatency": 2000, + "role": "audio", + "renderGroup": 1, + "codec": "opus", + "samplerate": 48000, + "channelConfig": "2", + "bitrate": 32000, + "encryptionScheme": "moq-secure-objects", + "cipherSuite": "aes-128-gcm-sha256", + "keyId": "key-2024-q1-premium", + "trackBaseKey": "dGhpc2lzYXNhbXBsZWJhc2VrZXk=" + } + ] + } + +5.6.9. Media timeline and Event timeline + + This example shows a catalog for a media producer capable of sending + LOC packaged, time-aligned audio and video tracks, along with a Media + Timeline which describes the history of those tracks and an Event + Timeline providing synchronized data. + + + +Law & Nandakumar Expires 4 December 2026 [Page 40] + +Internet-Draft MOQT Streaming Format June 2026 + + + { + "version": "1", + "generatedAt": 1746104606044, + "tracks": [ + { + "name": "history", + "namespace": "conference.example.com/conference123/alice", + "packaging": "mediatimeline", + "mimetype": "application/json", + "depends": ["1080p-video","audio"] + }, + { + "name": "identified-objects", + "namespace": "another-provider/time-synchronized-data", + "packaging": "eventtimeline", + "eventType": "com.ai-extraction/appID/v3", + "mimetype": "application/json", + "depends": ["1080p-video"] + }, + { + "name": "1080p-video", + "namespace": "conference.example.com/conference123/alice", + "packaging": "loc", + "isLive": true, + "targetLatency": 2000, + "role": "video", + "renderGroup": 1, + "codec":"av01.0.08M.10.0.110.09", + "width":1920, + "height":1080, + "framerate":30, + "bitrate":1500000 + }, + { + "name": "audio", + "namespace": "conference.example.com/conference123/alice", + "packaging": "loc", + "isLive": true, + "targetLatency": 2000, + "role": "audio", + "renderGroup": 1, + "codec":"opus", + "samplerate":48000, + "channelConfig":"2", + "bitrate":32000 + } + ] + } + + + +Law & Nandakumar Expires 4 December 2026 [Page 41] + +Internet-Draft MOQT Streaming Format June 2026 + + +5.6.10. Media timeline template + + This example shows a catalog using inline media timeline templates + instead of an explicit media timeline track. The Section 5.2.15 + attribute on each track defines a regular pattern where each segment + is 2002ms long. Clients can compute any entry using the template + parameters. Note that different tracks MAY have different template + values to accommodate different group durations. + + { + "version": "1", + "generatedAt": 1746104606044, + "tracks": [ + { + "name": "1080p-video", + "namespace": "conference.example.com/conference123/alice", + "packaging": "loc", + "isLive": true, + "targetLatency": 2000, + "role": "video", + "renderGroup": 1, + "template": [0, 2002, [0, 0], [1, 0], 1759924158381, 2002], + "codec":"av01.0.08M.10.0.110.09", + "width":1920, + "height":1080, + "framerate":30, + "bitrate":1500000 + }, + { + "name": "audio", + "namespace": "conference.example.com/conference123/alice", + "packaging": "loc", + "isLive": true, + "targetLatency": 2000, + "role": "audio", + "renderGroup": 1, + "template": [0, 2002, [0, 0], [1, 0], 1759924158381, 2002], + "codec":"opus", + "samplerate":48000, + "channelConfig":"2", + "bitrate":32000 + } + ] + } + + + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 42] + +Internet-Draft MOQT Streaming Format June 2026 + + +5.6.11. Video track with embedded captions and SCTE-35 events + + This example shows a live broadcast with CEA-608 closed captions + embedded in the video track and a separate SCTE-35 event timeline for + ad insertion. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 43] + +Internet-Draft MOQT Streaming Format June 2026 + + + { + "version": "1", + "generatedAt": 1746104606044, + "tracks": [ + { + "name": "video", + "packaging": "loc", + "isLive": true, + "targetLatency": 4000, + "role": "video", + "renderGroup": 1, + "codec": "avc1.4d401f", + "width": 1920, + "height": 1080, + "framerate": 30, + "bitrate": 5000000, + "accessibility": [ + { + "scheme": "urn:scte:dash:cc:cea-608:2015", + "value": "CC1=eng;CC3=spa" + } + ] + }, + { + "name": "audio", + "packaging": "loc", + "isLive": true, + "targetLatency": 4000, + "role": "audio", + "renderGroup": 1, + "codec": "opus", + "samplerate": 48000, + "channelConfig": "2", + "bitrate": 128000 + }, + { + "name": "scte35", + "packaging": "eventtimeline", + "eventType": "urn:scte:scte35:2013:bin", + "mimeType": "application/json", + "isLive": true, + "role": "eventtimeline", + "depends": ["video"] + } + ] + } + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 44] + +Internet-Draft MOQT Streaming Format June 2026 + + +5.6.12. Video track with CEA-708 captions + + This example shows a live broadcast with CEA-708 closed captions + embedded in the video track, demonstrating multiple caption services. + + { + "version": "1", + "generatedAt": 1746104606044, + "tracks": [ + { + "name": "video", + "packaging": "loc", + "isLive": true, + "targetLatency": 4000, + "role": "video", + "renderGroup": 1, + "codec": "hev1.1.6.L93.B0", + "width": 1920, + "height": 1080, + "framerate": 30, + "bitrate": 4000000, + "accessibility": [ + { + "scheme": "urn:scte:dash:cc:cea-708:2015", + "value": "1=lang:eng;2=lang:spa;3=lang:fra" + } + ] + }, + { + "name": "audio", + "packaging": "loc", + "isLive": true, + "targetLatency": 4000, + "role": "audio", + "renderGroup": 1, + "codec": "mp4a.40.2", + "samplerate": 48000, + "channelConfig": "2", + "bitrate": 128000 + } + ] + } + +5.6.13. Terminating a live broadcast + + This example shows a catalog for a media producer terminating a + previously live broadcast containing a video and an audio track. + + + + +Law & Nandakumar Expires 4 December 2026 [Page 45] + +Internet-Draft MOQT Streaming Format June 2026 + + + { + "version": "1", + "generatedAt": 1746104606044, + "isComplete": true, + "tracks": [] + } + +5.6.14. Variable Substitution for personalized delivery + + This example shows a catalog using variable substitution to enable + personalized advertising and reporting while maintaining + cacheability. Given a catalog request URI of: + + moqt://relay.example.com/sports/catalog?a=1#token=1234&id=bob&event=xyz + + The fragment parameters (token, id, event) are available for variable + substitution. The following catalog template: + + { + "version": "1", + "tracks": [ + { + "name": "video", + "packaging": "loc", + "isLive": true, + "role": "video", + "renderGroup": 1 + }, + { + "name": "cmcdv2-%id%", + "namespace": "advertising-decisions/live-sports/%event%", + "packaging": "eventtimeline", + "eventType": "com.example.iab.vast", + "c4m": "%token%" + } + ] + } + + Would be resolved by the subscriber as: + + + + + + + + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 46] + +Internet-Draft MOQT Streaming Format June 2026 + + + { + "version": "1", + "tracks": [ + { + "name": "video", + "packaging": "loc", + "isLive": true, + "role": "video", + "renderGroup": 1 + }, + { + "name": "cmcdv2-bob", + "namespace": "advertising-decisions/live-sports/xyz", + "packaging": "eventtimeline", + "eventType": "com.example.iab.vast", + "c4m": "1234" + } + ] + } + +5.6.15. Time-aligned Audio/Video Tracks with Authorization + + This example shows a catalog for a media producer requiring + authorization for premium content. The premium 4K track uses CAT + authorization with a token resolved via variable substitution from + %cat-token%. The standard 720p track uses Privacy Pass with a token + resolved from %pp-token%. Token presentation timing is determined by + the authorization scheme specification. + + { + "version": "1", + "generatedAt": 1746104606044, + "tracks": [ + { + "name": "premium-4k-video", + "namespace": "streaming.example.com/live/sports", + "packaging": "loc", + "isLive": true, + "targetLatency": 2000, + "role": "video", + "renderGroup": 1, + "codec": "av01.0.12M.10.0.110.09", + "width": 3840, + "height": 2160, + "framerate": 60, + "bitrate": 15000000, + "authInfo": { + "cat": "%cat-token%" + + + +Law & Nandakumar Expires 4 December 2026 [Page 47] + +Internet-Draft MOQT Streaming Format June 2026 + + + } + }, + { + "name": "standard-720p-video", + "namespace": "streaming.example.com/live/sports", + "packaging": "loc", + "isLive": true, + "targetLatency": 2000, + "role": "video", + "renderGroup": 2, + "codec": "av01.0.05M.10.0.110.09", + "width": 1280, + "height": 720, + "framerate": 30, + "bitrate": 2500000, + "authInfo": { + "privacy-pass": "%pp-token%" + } + }, + { + "name": "audio", + "namespace": "streaming.example.com/live/sports", + "packaging": "loc", + "isLive": true, + "targetLatency": 2000, + "role": "audio", + "renderGroup": 1, + "codec": "opus", + "samplerate": 48000, + "channelConfig": "2", + "bitrate": 128000 + } + ] + } + +5.6.16. Publish tracks for logs and metrics + + This example shows a catalog that includes publish tracks for client- + side logging and metrics collection. The subscriber can publish QoE + data and logs back to the delivery system using these track + definitions. The namespace and track name formats follow the + conventions defined in [MOQLOG] and [MOQMETRICS]. + + + + + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 48] + +Internet-Draft MOQT Streaming Format June 2026 + + + { + "version": "1", + "generatedAt": 1746104606044, + "tracks": [ + { + "name": "video", + "namespace": "broadcast.example.com/live/stream1", + "packaging": "loc", + "isLive": true, + "targetLatency": 2000, + "role": "video", + "renderGroup": 1, + "codec": "av01.0.08M.10.0.110.09", + "width": 1920, + "height": 1080, + "framerate": 30, + "bitrate": 1500000 + }, + { + "name": "audio", + "namespace": "broadcast.example.com/live/stream1", + "packaging": "loc", + "isLive": true, + "targetLatency": 2000, + "role": "audio", + "renderGroup": 1, + "codec": "opus", + "samplerate": 48000, + "channelConfig": "2", + "bitrate": 32000 + } + ], + "publishTracks": [ + { + "namespace": "moq://metrics.moq.arpa/v1/%resourceId%", + "name": "4", + "packaging": "moqmetrics", + "role": "metrics", + "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." + }, + { + "namespace": "moq://moq-syslog.arpa/logs-v1/%resourceId%", + "name": "6", + "packaging": "moqlog", + "role": "log", + "connectionUri": "moqt://logs.example.com:4443", + "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." + } + + + +Law & Nandakumar Expires 4 December 2026 [Page 49] + +Internet-Draft MOQT Streaming Format June 2026 + + + ] + } + + In this example: + + * The metrics track uses the namespace format defined in + [MOQMETRICS] with %resourceId% as a placeholder for the + subscriber's unique resource identifier. The track name "4" + indicates Warning level granularity. + + * The log track uses the namespace format defined in [MOQLOG] with + %resourceId% as a placeholder. The track name "6" indicates + Informational level priority. This track establishes a separate + connection to logs.example.com. + + * Both tracks include authentication tokens for publishing + authorization. + + * The subscriber MUST replace %resourceId% with their actual + resource identifier as defined in the respective specifications. + +6. Media transmission + + The MOQT Groups and MOQT Objects need to be mapped to MOQT Streams. + Irrespective of the Section 4 in place, each MOQT Object MUST be + mapped to a new MOQT Stream. + +6.1. Group numbering + + Group IDs for a track MUST be unique and MUST increase monotonically. + Within a continuous publishing session, each subsequent Group ID + SHOULD increase by 1. + + When a publisher restarts (e.g., after connectivity loss or encoder + restart), it MUST ensure the new starting Group ID is greater than + any previously published Group ID for that track. One approach is to + use the current wall clock time in milliseconds since the Unix epoch + as the starting Group ID. + + If a publisher maintains state across a restart and knows the + previous Group ID, it SHOULD signal the gap using the MOQT Prior + Group ID Gap Extension header. + +6.2. Object Numbering + + Object ID MUST be zero for the first Object within a Group and then + MUST increase monotonically by one within that Group. + + + + +Law & Nandakumar Expires 4 December 2026 [Page 50] + +Internet-Draft MOQT Streaming Format June 2026 + + +7. Media Timeline track + + The media timeline track provides data about the previously published + Groups and their relationship to wallclock time and media time. + Media timeline tracks allow players to seek to precise points behind + the live head in a live broadcast, or for random access in a VOD + asset. Media timeline tracks are optional. Multiple media timeline + tracks can exist inside a catalog. + +7.1. Media Timeline track payload + + A media timeline track is a JSON [JSON] document. This document MAY + be compressed using the MSF_COMPRESSION property (Section 12.1). The + document supports two formats: an explicit entry format and a + template format. Publishers MAY combine both formats in a single + document. + +7.1.1. Explicit entry format + + The explicit format contains an array of records. Each record + consists of an array of three required items, whose ordinal position + defines their type: + + * The first item holds the media presentation timestamp, expressed + as a JSON Number. This value MUST match the media presentation + timestamp, expressed as the floor in integral milliseconds, of the + first media sample in the referenced Object. Implementers who + require increased time precision can parse the retrieved media + object itself. + + * The second item holds the MOQT Location of the entry, defined as a + tuple of the MOQT Group ID and MOQT Object ID, and expressed as a + JSON Array of Numbers, where the first number is the Group ID and + the second number is the Object ID. + + * The third item holds the wallclock time at which the media was + encoded, defined as the number of milliseconds that have elapsed + since January 1, 1970 (midnight UTC/GMT) and expressed as a JSON + Number. For VOD assets, or if the wallclock time is not known, + the value SHOULD be 0. + + An example media timeline is shown below: + + + + + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 51] + +Internet-Draft MOQT Streaming Format June 2026 + + + [ + [0, [0,0], 1759924158381], + [2002, [1,0], 1759924160383], + [4004, [2,0], 1759924162385], + [6006, [3,0], 1759924164387], + [8008, [4,0], 1759924166389] + ] + +7.2. Media Timeline Catalog requirements + + A media timeline track MUST carry a 'type' identifier in the Catalog + with a value of "mediatimeline". A media timeline track MUST carry a + 'depends' attribute which contains an array of all track names to + which the media timeline track applies. The mime-type of a media + timeline track MUST be specified as "application/json". + +7.3. Media Timeline track updating + + The publisher MUST publish an independent media timeline in the first + MOQT Object of each MOQT Group of a media timeline track. An + independent media timeline object MUST contain all media timeline + records accumulated and accessible up to that point, allowing a + subscriber joining at any group boundary to receive the accessible + timeline history. The publisher MAY publish incremental updates in + the second and subsequent Objects within each Group. Incremental + updates contain only new media timeline records since the previous + media timeline Object in that Group. + +7.4. Media Timeline Template + + When the relationship between media time, MOQT Location and wallclock + time follows a regular, predictable pattern, a media timeline + template MAY be used instead of an explicit media timeline track. + The template approach is best suited for content with fixed-duration + segments, such as VOD assets or live broadcasts with constant segment + durations. For content with variable segment durations, the explicit + media timeline track (Section 7.1) MUST be used instead. + +7.4.1. Template Format + + A media timeline template is expressed as an inline track attribute + using the Section 5.2.15 field. The template is a JSON Array + containing six mandatory values in the following fixed order: + + 1. startMediaTime - The media presentation timestamp of the first + entry, as defined for media timeline entries in Section 7.1.1. + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 52] + +Internet-Draft MOQT Streaming Format June 2026 + + + 2. deltaMediaTime - The constant interval between media presentation + timestamps, expressed as a JSON Number in milliseconds. + + 3. startLocation - The MOQT Location of the first entry, as defined + for media timeline entries in Section 7.1.1. + + 4. deltaLocation - The constant interval between MOQT Locations, + expressed as a JSON Array of two Numbers where the first number + is the Group ID delta and the second number is the Object ID + delta. + + 5. startWallclock - The wallclock time of the first entry, as + defined for media timeline entries in Section 7.1.1. For VOD + assets, or if the wallclock time is not known, the value SHOULD + be 0. + + 6. deltaWallclock - The constant interval between wallclock times, + expressed as a JSON Number in milliseconds. For VOD assets, or + if the wallclock time is not known, the value SHOULD be 0. + + All six values are mandatory and MUST appear in the specified order. + + Clients compute entry values using the following formulas, where n is + the zero-based entry index: + + mediaTime[n] = startMediaTime + (n * deltaMediaTime) + location[n] = [startLocation[0] + (n * deltaLocation[0]), + startLocation[1] + (n * deltaLocation[1])] + wallclock[n] = startWallclock + (n * deltaWallclock) + + An example template value is shown below: + + [0, 2002, [0, 0], [1, 0], 1759924158381, 2002] + + This template indicates that the first entry has media time 0ms, + location [0,0], and wallclock time 1759924158381. Each subsequent + entry increments media time by 2002ms, location by [1,0] (next group, + same object), and wallclock by 2002ms. + +7.4.2. Template Immutability + + Unlike the explicit media timeline track, the media timeline template + is intended to be immutable once publishing starts. Publishers MUST + NOT change the template values for a track after the first Object has + been published. + + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 53] + +Internet-Draft MOQT Streaming Format June 2026 + + +8. Event Timeline track + + The event timeline track provides a mechanism to associate ad-hoc + event metadata with the broadcast. Use-case examples include live + sports score data, GPS coordinates of race cars, SAP-types for media + segments or active speaker notifications in web conferences. + + To allow the client to bind this event metadata with the broadcast + content described by the media timeline track, each event record MUST + contain a reference to one of Media PTS, wallclock time or MOQT + Location. + + Event timeline tracks are optional. Multiple event timeline tracks + can exist inside a catalog. The type & structure of the data + contained within each event timeline track is declared in the + catalog, to facilitate client selection and parsing. + +8.1. Event Timeline data format + + An event timeline track is a JSON [JSON] document. This document MAY + be compressed using the MSF_COMPRESSION property (Section 12.1). The + document contains an array of records. Each record consists of a + JSON Object containing the following required fields: + + * An index reference, which MUST be either 't' for wallclock time, + 'l' for Location or 'm' for Media PTS. Only one of these index + values may be used within each record. Event timelines SHOULD use + the same index reference type for each record. The definitions + for wallclock time, Location and Media PTS are identical to those + defined for media timeline payload Section 7.1. Wallclock time + and media PTS values are JSON Number, while Location value is an + Array of Numbers, where the first item represents the MOQT GroupID + and the second item the MOQT Object ID. + + * A 'data' Object, whose structure is defined by the Section 5.2.5 + value declared for this track in the Catalog. + +8.2. Event Timeline Catalog requirements + + An event timeline track MUST carry: + + * a Section 5.2.4 attribute with a value of "eventtimeline". + + * a Section 5.2.14 attribute which contains an array of all track + names to which the event timeline track applies. + + * a Section 5.2.19 attribute with a value of "application/json". + + + + +Law & Nandakumar Expires 4 December 2026 [Page 54] + +Internet-Draft MOQT Streaming Format June 2026 + + + * an Section 5.2.5 attribute declaring the type & structure of data + contained in the event timeline track. + +8.3. Event Timeline track updating + + The publisher MUST publish an independent event timeline in the first + MOQT Object of each MOQT Group of an event timeline track. An + independent event timeline object MUST contain all event timeline + records accumulated and accessible up to that point, allowing a + subscriber joining at any group boundary to receive the accessible + event history. The publisher MAY publish incremental updates in the + second and subsequent Objects within each Group. Incremental updates + contain only new event timeline records since the previous event + timeline Object in that Group. + +8.4. Event timeline track examples + +8.4.1. Event timeline track with wallclock time indexing + + This example shows how sports scores and game information might be + defined in a live sports broadcast. + + [ + { + "t": 1756885678361, + "data": { + "status": "in_progress", + "period": 1, + "clock": "12:00", + "homeScore": 0, + "awayScore": 0, + "lastPlay": "Game Start" + } + }, + { + "t": 1756885981542, + "data": { + "status": "in_progress", + "period": 1, + "clock": "09:25", + "homeScore": 2, + "awayScore": 0, + "lastPlay": "Team A: #23 makes 2-pt jump shot" + } + } + ] + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 55] + +Internet-Draft MOQT Streaming Format June 2026 + + +8.4.2. Event timeline track with MOQT Location indexing + + This example shows drone GPS coordinates synched with the start of + each Group. + + [ + { + "l": [0,0], + "data": [47.1812,8.4592] + }, + { + "l": [1,0], + "data": [47.1662,8.5155] + } + ] + +9. Log track + + Log tracks provide a mechanism for subscribers to publish diagnostic + and operational log data back to the delivery system. This enables + QoE monitoring, debugging, and analytics collection. Log tracks are + defined in the catalog's publishTracks array with a packaging value + of "moqlog". + +9.1. Log track payload + + The log track payload format is defined in [MOQLOG]. Each MOQT + Object contains a single JSON-formatted log entry. The log entry + structure includes optional fields such as severity, timestamp, + hostname, application name, process ID, message ID, and the log + message itself. Additional structured data fields support + distributed tracing integration with TraceID, SpanID, and + InstrumentationScope aligned with OpenTelemetry specifications. + Implementations MUST follow the object payload format specified in + Section 4 of [MOQLOG]. + +9.2. Log track namespace and name + + TODO: Finalize on track naming + + Log tracks MUST use the namespace and track name format defined in + Section 3 of [MOQLOG]. The Track Namespace consists of the tuples: + (moq://moq-syslog.arpa/logs-v1/),(resourceID) where resourceID is a + unique identifier for the publishing resource. + + The Track Name is a single byte containing the log priority level in + binary. Priority levels range from 0 (Emergency) to 7 (Debug), + following syslog severity conventions. + + + +Law & Nandakumar Expires 4 December 2026 [Page 56] + +Internet-Draft MOQT Streaming Format June 2026 + + +9.3. Log track Group ID and Object ID + + The Group ID represents the timestamp at which the log entry was + captured, truncated to a 62-bit binary integer representing + microseconds since the Unix epoch. This allows log entries to be + naturally ordered by time within the MOQT object model. + + The Object ID is set to zero for a log entry unless multiple log + messages occur within the same microsecond, in which case the Object + ID increments to distinguish between messages captured at the same + timestamp. + +9.4. Log track catalog requirements + + A log track MUST be declared in the publishTracks array of the + catalog with: + + * a Section 5.2.4 attribute with a value of "moqlog". + + * a Section 5.2.6 attribute with a value of "log". + + A log track MAY include: + + * a Section 5.2.36 attribute if logs should be published to a + different endpoint. + + * a Section 5.2.37 attribute for publish authorization. + +10. Metrics track + + Metrics tracks provide a mechanism for subscribers to publish + quantitative measurements back to the delivery system. This enables + QoE analytics, performance monitoring, and operational dashboards. + Metrics tracks are defined in the catalog's publishTracks array with + a packaging value of "moqmetrics". + +10.1. Metrics track payload + + The metrics track payload format is defined in [MOQMETRICS]. The + data model consists of Resources (systems generating metrics + identified by ResourceID), optional Attributes (dimensional key-value + pairs), and Metrics (named measurements with timeseries values). + + [MOQMETRICS] defines two metric value types - Gauge and Counter. + Both value types support either 64-bit floating point or integer + representation. Implementations MUST follow the object payload + format specified in Section 3 of [MOQMETRICS]. + + + + +Law & Nandakumar Expires 4 December 2026 [Page 57] + +Internet-Draft MOQT Streaming Format June 2026 + + +10.2. Metrics track namespace and name + + TODO: Finalize the track naming. + + Metrics tracks MUST use the namespace and track name format defined + in Section 3 of [MOQMETRICS]. The Track Namespace consists of the + tuples: (moq://metrics.moq.arpa/v1/),(resourceID) where resourceID is + a unique identifier for the publishing resource. + + The Track Name identifies the granularity level for the metrics being + published, specified as a single tuple () where + granularity-level is a value from 0 (Emergency) to 7 (Debug). Higher + priority levels (lower numbers) indicate more critical metrics that + should always be reported. + +10.3. Metrics track Group ID and Object ID + + The Group ID represents the capture time as the number of + milliseconds since January 1, 1970 (Unix epoch). This allows metrics + to be naturally grouped and ordered by their capture timestamp within + the MOQT object model. + + Within each Group, Object IDs are assigned as follows: + + * *Object ID 0*: Contains the capture timestamp as Unix epoch time + in nanoseconds, along with any optional attributes for the metrics + in this group. + + * *Object ID 1 and above*: Each subsequent Object contains an + individual metric as a name-value pair. + + This structure allows a single capture event to include multiple + metrics while maintaining efficient MOQT caching and distribution. + +10.4. Metrics track catalog requirements + + A metrics track MUST be declared in the publishTracks array of the + catalog with: + + * a Section 5.2.4 attribute with a value of "moqmetrics". + + * a Section 5.2.6 attribute with a value of "metrics". + + A metrics track MAY include: + + * a Section 5.2.36 attribute if metrics should be published to a + different endpoint. + + + + +Law & Nandakumar Expires 4 December 2026 [Page 58] + +Internet-Draft MOQT Streaming Format June 2026 + + + * a Section 5.2.37 attribute for publish authorization. + +10.5. Well-known event timeline types + + Event timelines can carry various types of broadcast metadata + synchronized with media content. The "MSF Event Timeline Types" + registry (Section 14.2) maintains a list of well-known event types. + Publishers SHOULD use registered types when applicable to ensure + interoperability. + + Event timelines can carry data types including but not limited to: + + * Ad insertion signaling (e.g., SCTE-35 splice points) - see + [SCTE35-MSF] + + * Out-of-band timed-text cues (WebVTT, IMSC1) - see [WebVTT-MSF] and + [IMSC1-MSF] + + * Sports scores and game state + + * GPS coordinates and telemetry + + * Active speaker notifications + + * Custom application-specific metadata + + The packaging format and data structure for each event type is + defined by the specification referenced in the registry. Custom + event types not in the registry SHOULD use Reverse Domain Name + Notation (e.g., "com.example.myeventtype") to avoid naming + collisions. + +11. Workflow + +11.1. URL construction and interpretation + + An MSF URL identifies a MOQT session and an optional sub-resource + within that session. It inherits the MOQT URI scheme defined in + [MoQTransport] and extends it to add a fragment definition, which + defines the type, the namespace and name of the track along with + optional key-value attributes. + + + + + + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 59] + +Internet-Draft MOQT Streaming Format June 2026 + + + ; MSF URI Definition + ; The following rules are imported from RFC 3986: + ; authority (Section 3.2) + ; path-abempty (Section 3.3) + ; query (Section 3.4) + + msf-uri = "moqt://" authority path-abempty [ "?" query ] "#" msf-fragment + + The MOQT specification carries the normative definition of these + components, along with processing instructions. They are repeated + here for clarity. In the event of any conflict, the definition in + [MoQTransport] is authoritative. + + * Scheme: This case-insensitive scheme defines the underlying + transport. The client may use either a WebTransport or native + QUIC connection. A moqt URI can be converted to an https URI by + replacing the scheme, so the path-abempty and query components use + the same syntax as https URIs. + + * Authority: Required. Contains the host and optional port + (defaulting to 443). This information is used by the client to + establish the transport session. + + * Path: Optional. If present, it provides server-specific + configuration or routing information used during connection + initialization. + + * Query: Optional. Contains key-value parameters separated by &. If + the query is absent, the ? separator MUST be omitted. Query + arguments are intended for the server and SHOULD be ignored by the + client. + + This specification registers a fragment type of "msf" in the "MOQT + URI Fragment Types" registry established by [MoQTransport] (see + Section 14). This type is required for any URL defining an MSF + resource. The value of this type is the msf-fragment-value. + + The msf-fragment is defined by the following ABNF: + + + + + + + + + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 60] + +Internet-Draft MOQT Streaming Format June 2026 + + + ; MSF Fragment Definition + ; The following rules are imported from RFC 3986: + ; pchar (Section 3.3) + ; unreserved (Section 2.3) + ; pct-encoded (Section 2.1) + ; sub-delims (Section 2.2) + + msf-fragment = "msf:" msf-fragment-value + + msf-fragment-value = track-identifier [ "&" parameter-list ] + + track-identifier = 1*( pchar-no-amp / "/" ) + ; MSF namespace-name string + ; MUST NOT contain '&' or '?' + ; '?' MUST be percent-encoded as %3F within this component + + parameter-list = parameter *( "&" parameter ) + + parameter = param-name "=" param-value + + param-name = 1*( pchar-no-amp / "/" ) + + param-value = *( pchar-no-amp / "/" ) + + ; Derived from RFC 3986 pchar (Section 3.3), excluding '&' and '?': + ; pchar = unreserved / pct-encoded / sub-delims / ":" / "@" + ; '&' is excluded as it serves as the MSF fragment component delimiter. + ; '?' is excluded to avoid ambiguity with the URI query component delimiter. + pchar-no-amp = unreserved / pct-encoded / sub-delims-no-amp / ":" / "@" + + ; Derived from RFC 3986 sub-delims (Section 2.2), excluding '&': + ; sub-delims = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "=" + sub-delims-no-amp = "!" / "$" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "=" + + The msf-fragment-value identifies a specific Track. The track- + identifier MUST be formatted as an MSF namespace-name string (see + Section 11.1.2). The client uses this identifier to initiate a + SUBSCRIBE or FETCH command once the transport session is established. + The namespace-name string MAY be followed by a series of key-value + parameters, each separated from the preceding element by &. These + key-value parameters are intended for processing by the client and, + being part of the fragment, are not transferred to the server at + connection time. Certain of the fragment key-value parameters have a + reserved meaning, as defined by Section 11.1.1. + + + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 61] + +Internet-Draft MOQT Streaming Format June 2026 + + +11.1.1. Reserved fragment parameters + + Table 8 defines reserved key names for the parameter portion of the + msf-fragment. Keynames are case-sensitive. + + +=================+=============================================+ + | Name | Description | + +=================+=============================================+ + | wallclock-range | A subclip defined by a wallclock time range | + +-----------------+---------------------------------------------+ + | mediatime-range | A subclip defined by a media time range | + +-----------------+---------------------------------------------+ + | location-range | A subclip defined by a MOQT Location range | + +-----------------+---------------------------------------------+ + | c4m | A base64 encoded C4M token | + +-----------------+---------------------------------------------+ + | connection | Mandates a connection type | + +-----------------+---------------------------------------------+ + + Table 10 + + * wallclock-range - a range defined by start and end wallclock + times, each expressed as milliseconds since Unix Epoch and + separated by a "-" dash. The dash and end time MAY be omitted to + indicate an open range. The range definition is inclusive. + + * mediatime-range - a range defined by start and end media times, + each expressed as milliseconds and separated by a "-" dash. The + dash and end time MAY be omitted to indicate an open range. The + range definition is inclusive. + + * location-range - a range defined by start and end media MOQT + Location separated by a "-" dash. Range definitions are + inclusive. MOQT Location is expressed as Group ID and Object ID + separated by a "." dot. End Location may be omitted to indicate + an open range which continues to the end of the content. End + Object ID may be omitted, indicating the whole end group is + included in the range. The "." dot and "-" dash separators MUST + be omitted when the second value is omitted. + + * c4m - a base64 encoded token, as defined by [C4M]. + + * connection - mandates the client to use a particular connection + type when connecting to the server. There are two allowed values + - "q" or "wt". "q" indicates that a Native QUIC connection MUST be + used. "wt" indicates that a WebTransport connection MUST be used. + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 62] + +Internet-Draft MOQT Streaming Format June 2026 + + + If multiple ranges are specified within the same URL for the same + parameter, the client MUST process the union of those ranges. + + Example fragment parameters: + + * connection=q + + * connection=wt + + * wallclock-range=1761759637565-1761759836189 + + * wallclock-range=1761751753894 + + * mediatime-range=0-13421 + + * mediatime-range=982 + + * location-range=34.0-2145.16 + + * location-range=16.24 (open range starting at Group ID 16 Object ID + 24) + + * location-range=16-24 (range from Group ID 16 through to and + including all Objects in Group ID 24) + + * c4m=gqhkYWxnIGVzaGFyqGR0eXBNhdZ9hdWQAY3VybGZlbWlzcwZleWV2aW5uZWlhdGVwQWNyZW5lY + +11.1.2. MSF Namespace-Name String Encoding + + To represent MoQ Tuples (which are sequences of byte strings) within + the URL fragment, MSF uses a specific encoding convention, which is + normatively defined by MOQT [MoQTransport] and repeated here for + convenience: + + * Hierarchy: Each element of the Namespace tuple is rendered in + order, separated by a single hyphen (-). + + * Delimiter: The Track Name is appended to the end, separated from + the namespace by a double hyphen (--). + + * Character Escaping: + + - Unreserved characters (a-z, A-Z, 0-9, _) are represented + literally. + + + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 63] + +Internet-Draft MOQT Streaming Format June 2026 + + + - All other byte values (including hyphens and periods used as + data) MUST be percent-encoded using a period (.) followed by + two lowercase hexadecimal digits (e.g., a literal hyphen in a + name becomes .2d). + + Note: This encoding ensures that the structural delimiters (- and --) + remain unambiguous. + +11.1.3. Example MSF URLs + + * URL pointing at a catalog track (either WebTransport or native + QUIC may be used): moqt://example.com/server/ + config?a=1&b=2#msf:customer-livestream-123--catalog + + - Session: example.com/server/config?a=1&b=2 + + - Streaming format type: msf + + - Namespace: ('customer', 'livestream', '123') + + - Track Name: 'catalog' + + * URL with a required raw QUIC connection pointing at a catalog: + moqt://example.com/relay-app/relayID#msf:customerID-broadcastID-- + catalog&connection=q + + * URL pointing at a non-catalog track, with a required WebTransport + connection moqt://example.com/relay-app/relayID#msf:customerID- + broadcastID--video&connection=wt + + * URL pointing at a subclip: moqt://example.com/relay-app/ + relayID#msf:customerID-broadcastID--catalog&location-range=34-64 + + * URL pointing at a catalog and supplying a token for the client: + (linebreaks for display only) moqt://example.com/relay-app/ + relayID#msf:customerID-broadcastID-- + catalog&c4m=gqhkYWxnIGVzaGFyqGR0eXBNhdZ9hdWQAY3VybGZlbWlzcwZleWV2 + aW5uZWlhdGVwQWNyZW5lYnJmcmVqMTIzNDU2NzgwMHZpc3VlZF9hdD0xNzMwNDM + + * URL pointing at a catalog and supplying a token for the client + along with a separate token for the server: (linebreaks for + display only) moqt://example.com/relay-app/ + relayID?token=HTRCII74GHFT@JHBCV + SW56HKKneH2Dbyq6NHBI2#msf:customerID-broadcastID--catalog&c4m=gqh + kYWxnIGVzaGFyqGR0eXBNhdZ9hdWQAY3VybGZlbWlzcwZleWV2aW5uZWlhdGVwQWN + yZW5lYnJmcmVqMTIzNDU2NzgwMHZpc3VlZF9hdD0xNzMwNDM + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 64] + +Internet-Draft MOQT Streaming Format June 2026 + + +11.2. Initiating a broadcast + + An MSF publisher MUST publish a catalog track object before + publishing any media track objects. + +11.3. Ending a live broadcast + + After publishing a catalog and defining tracks carrying live content, + an original publisher can deliver a deterministic signal to all + subscribers that the broadcast is complete by taking the following + steps: + + * Send a SUBSCRIBE_DONE (See MOQT Sect 8.1.2) message for all active + tracks using status code 0x2 Track Ended. + + * If the live stream is being converted instantly to a VOD asset, + then publish an independent (non-delta) catalog update which, for + each track, sets isLive Section 5.2.7 to FALSE and adds a track + duration Section 5.2.35 field. + + * If the live stream is being terminated permanently without + conversion to VOD, then publish an independent catalog update + which signals isComplete Section 5.1.3 as TRUE and which contains + an empty Tracks Section 5.1.4 field. + +11.4. Authorization + + MSF supports token-based authorization through pluggable + authentication schemes. Both original publishers and end subscribers + can independently acquire authorization tokens and present them to + relays. Relays use these tokens to authorize whether an end + subscriber is permitted to setup the connection, as well as to + receive content and/or to send content. + +11.4.1. Discovering Authorization Requirements + + End subscribers discover authorization requirements by parsing the + catalog. For each track of interest, examine the authInfo field. If + present, the track requires authorization and the subscriber must + obtain appropriate credentials for one of the schemes listed in the + field. + + Original publishers and end subscribers may obtain authorization + tokens from multiple sources, including out-of-band provisioning or + as a parameter in the connection URI. These tokens can be presented + either in the connection setup message (CLIENT_SETUP) or in control + messages (SUBSCRIBE, FETCH, PUBLISH, PUBLISH_NAMESPACE) as described + in Section 11.4.3. + + + +Law & Nandakumar Expires 4 December 2026 [Page 65] + +Internet-Draft MOQT Streaming Format June 2026 + + +11.4.2. Token Acquisition + + Token acquisition is out of scope for this specification. Both + original publishers and end subscribers independently obtain tokens + through mechanisms such as: + + * Direct authentication with a distribution service + + * OAuth 2.0 or OpenID Connect flows + + * Out-of-band provisioning + + The token acquisition endpoint and flow depend on the authorization + scheme and deployment configuration. Original publishers and end + subscribers MAY use the same or different authorization services + depending on the deployment. + + Tokens MAY also be supplied as parameters in the connection URI. + When a connection URI contains token parameters, the subscriber + extracts the token value and includes it in the appropriate MOQT + message. For example: + +moqt://relay.example.com/moqt#namespace--name&token=eyJhbGciOiJFZERTQSJ9... + + URI parameters provide a convenient mechanism for distributing pre- + authorized playback links. The parameter name and format are + deployment-specific. + +11.4.3. Presenting Authorization + + Once tokens are obtained, both original publishers and end + subscribers present them to relays according to the scheme + specification. Tokens MAY be presented in the SETUP message + (CLIENT_SETUP or SERVER_SETUP) using the AUTHORIZATION TOKEN setup + parameter, or in individual control messages using the AUTHORIZATION + TOKEN message parameter. + + When a token is associated with a track, it MUST be included in ALL + control messages that accept the AUTHORIZATION TOKEN parameter and + are associated with that track. For end subscribers, this includes + SUBSCRIBE, SUBSCRIBE_NAMESPACE, FETCH, and REQUEST_UPDATE messages. + For original publishers, this includes PUBLISH and PUBLISH_NAMESPACE + messages. This requirement applies regardless of whether the token + was also provided in SETUP. + + + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 66] + +Internet-Draft MOQT Streaming Format June 2026 + + +11.4.4. Handling Authorization Failures + + When a relay rejects an authorization token, subscribers SHOULD + handle the failure gracefully: + + * If a SUBSCRIBE or FETCH request is rejected due to invalid or + expired authorization, the subscriber MAY attempt to obtain a + fresh token and retry the request. + + * If a token is rejected due to insufficient scope, the subscriber + SHOULD NOT retry with the same token. + + * For interactive applications, subscribers MAY prompt users to re- + authenticate when authorization fails. + + * Subscribers SHOULD implement exponential backoff when retrying + failed authorization attempts to avoid overwhelming the relay or + token issuer. + + The specific error codes and retry semantics are defined by the + authorization scheme specifications. See [PrivacyPassAuth] for + Privacy Pass error handling and [C4M] for CAT error handling. + +12. MSF Properties + + MSF defines MOQT Track Properties and Object Properties (see + [MoQTransport]) to signal metadata about MSF tracks and objects. + These properties are carried in MOQT control messages and object + headers, allowing endpoints to learn track and object characteristics + before processing payload data. + +12.1. Compression Signaling + + MSF provides two mutually exclusive mechanisms to signal compression + of track payloads, including catalogs (Section 5), media timeline + tracks (Section 7), and event timeline tracks (Section 8). + Publishers MUST use one of the following approaches: + + * *Track Property* (Section 12.1.1): Signals that ALL objects in the + track are compressed using the specified algorithm. + + * *Object Property* (Section 12.1.2): Signals compression on + individual objects, allowing a mixture of compressed and + uncompressed objects within the same track. + + + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 67] + +Internet-Draft MOQT Streaming Format June 2026 + + + A publisher MUST NOT use both mechanisms on the same track. If the + track property is set, then every object in the track is compressed + and the object property MUST NOT be present. If compression varies + between objects, then the track property MUST NOT be set and the + object property MUST be used on each compressed object. + + The compression algorithm values used by both mechanisms are: + + +=======+=======================+===========+ + | Value | Compression Algorithm | Reference | + +=======+=======================+===========+ + | 0 | None (uncompressed) | RFC XXXX | + +-------+-----------------------+-----------+ + | 1 | GZIP | [GZIP] | + +-------+-----------------------+-----------+ + + Table 11 + + Table: MSF Compression Values + + All MSF implementations MUST support both uncompressed payloads + (value 0 or property absent) and GZIP compressed payloads (value 1). + +12.1.1. MSF_COMPRESSION Track Property + + The MSF_COMPRESSION track property signals that ALL objects in the + track are compressed using the specified algorithm. This mechanism + is appropriate when every object published on the track uses the same + compression. + + Publishers MUST include the MSF_COMPRESSION track property in the + PUBLISH message (publisher-initiated flow) or SUBSCRIBE_OK + (subscriber-initiated flow). + + Subscribers MUST check for this property in the corresponding message + before processing the track payload. + + If the property is absent, and no per-object compression is signaled, + the subscriber MUST treat the payload as uncompressed. If the + property is present with a value the subscriber does not support, the + subscriber MUST NOT attempt to process the payload and SHOULD + unsubscribe from the track. + + + + + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 68] + +Internet-Draft MOQT Streaming Format June 2026 + + +12.1.2. MSF_COMPRESSION Object Property + + The MSF_COMPRESSION object property signals that an individual object + is compressed. This mechanism is appropriate when a track contains a + mixture of compressed and uncompressed objects. For example, a + catalog track where the first object in a group (the complete + catalog) is compressed, but subsequent delta update objects within + the same group are uncompressed. + + Publishers MUST include the MSF_COMPRESSION object property on each + compressed object. + + Subscribers MUST check for this property on each received object + before processing its payload. If the property is absent on an + object, the subscriber MUST treat that object's payload as + uncompressed. If the property is present with a value the subscriber + does not support, the subscriber MUST NOT attempt to process that + object. + +13. Security Considerations + + ToDo + +14. IANA Considerations + +14.1. "MOQT URI Fragment Types" registry + + This document creates a new entry in the "MOQT URI Fragment Types" + registry (see [MoQTransport] Sect 14.3). + + +===============+=======================+===============+ + | Fragment Type | Description | Specification | + +===============+=======================+===============+ + | msf | MOQT Streaming Format | this | + +---------------+-----------------------+---------------+ + + Table 12 + +14.2. "MSF Event Timeline Types" registry + + This document establishes the "MSF Event Timeline Types" registry. + This registry lists the event types that can be used with the + eventType field Section 5.2.5 in MSF catalogs. + + New entries in this registry are subject to Expert Review policy as + defined in [RFC8126]. + + The initial contents of this registry are: + + + +Law & Nandakumar Expires 4 December 2026 [Page 69] + +Internet-Draft MOQT Streaming Format June 2026 + + + +==========================+=====================+===============+ + | Event Type | Description | Specification | + +==========================+=====================+===============+ + | urn:scte:scte35:2013:bin | SCTE-35 binary | [SCTE35-MSF] | + | | splice_info_section | | + +--------------------------+---------------------+---------------+ + | urn:scte:scte35:2013:xml | SCTE-35 XML | [SCTE35-MSF] | + | | representation | | + +--------------------------+---------------------+---------------+ + | urn:msf:timedtext:webvtt | WebVTT timed text | [WebVTT-MSF] | + | | cues | | + +--------------------------+---------------------+---------------+ + | urn:msf:timedtext:imsc1 | IMSC1 timed text | [IMSC1-MSF] | + | | cues | | + +--------------------------+---------------------+---------------+ + + Table 13 + +14.3. MSF_COMPRESSION Track Property + + This document requests IANA to register the following entry in the + "Track Properties" registry established by [MoQTransport] + (Section 14.4): + + +=================+=============+============+===========+ + | Property Name | Property ID | Value Type | Reference | + +=================+=============+============+===========+ + | MSF_COMPRESSION | TBD | varint | RFC XXXX | + +-----------------+-------------+------------+-----------+ + + Table 14 + + The MSF_COMPRESSION track property indicates that ALL objects on the + track are compressed using the specified algorithm. See + Section 12.1.1 for the full specification. + +14.4. MSF_COMPRESSION Object Property + + This document requests IANA to create a new "MSF Compression + Algorithms" registry with the following initial values: + + + + + + + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 70] + +Internet-Draft MOQT Streaming Format June 2026 + + + +=======+=======================+===========+ + | Value | Compression Algorithm | Reference | + +=======+=======================+===========+ + | 0 | None (uncompressed) | RFC XXXX | + +-------+-----------------------+-----------+ + | 1 | GZIP | [GZIP] | + +-------+-----------------------+-----------+ + + Table 15 + + Values 2-127 are available for registration via Standards Action. + Values 128 and above are reserved for private use. + +15. References + +15.1. Normative References + + [BASE64] Josefsson, S., "The Base16, Base32, and Base64 Data + Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, + . + + [C4M] Law, W., Lemmons, C., Simon, G., and S. Nandakumar, + "Authentication scheme for MOQT using Common Access + Tokens", Work in Progress, Internet-Draft, draft-ietf-moq- + c4m-00, 19 September 2025, + . + + [GZIP] Deutsch, P., "GZIP file format specification version 4.3", + RFC 1952, DOI 10.17487/RFC1952, May 1996, + . + + [IMSC1] "W3C, TTML Profiles for Internet Media Subtitles and + Captions 1.0 (IMSC1)", April 2016, + . + + [JSON] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data + Interchange Format", STD 90, RFC 8259, + DOI 10.17487/RFC8259, December 2017, + . + + [LANG] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying + Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, + September 2009, . + + + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 71] + +Internet-Draft MOQT Streaming Format June 2026 + + + [LOC] Zanaty, M., Nandakumar, S., and P. Thatcher, "Low Overhead + Media Container", Work in Progress, Internet-Draft, draft- + ietf-moq-loc-02, 15 March 2026, + . + + [MIME] Freed, N., Klensin, J., and T. Hansen, "Media Type + Specifications and Registration Procedures", BCP 13, + RFC 6838, DOI 10.17487/RFC6838, January 2013, + . + + [MOQLOG] Jennings, C. F. and S. Nandakumar, "Logging over Media + over QUIC Transport", Work in Progress, Internet-Draft, + draft-jennings-moq-log-03, 20 October 2025, + . + + [MOQMETRICS] + Jennings, C. F. and S. Nandakumar, "Metrics over MOQT", + Work in Progress, Internet-Draft, draft-jennings-moq- + metrics-02, 20 October 2025, + . + + [MoQTransport] + Nandakumar, S., Vasiliev, V., Swett, I., and A. Frindell, + "Media over QUIC Transport", Work in Progress, Internet- + Draft, draft-ietf-moq-transport-18, 12 May 2026, + . + + [PrivacyPassAuth] + Nandakumar, S., Jennings, C. F., and T. Meunier, "Privacy + Pass Authentication for Media over QUIC (MoQ)", Work in + Progress, Internet-Draft, draft-ietf-moq-privacy-pass- + auth-02, 2 March 2026, + . + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + . + + [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for + Writing an IANA Considerations Section in RFCs", BCP 26, + RFC 8126, DOI 10.17487/RFC8126, June 2017, + . + + + +Law & Nandakumar Expires 4 December 2026 [Page 72] + +Internet-Draft MOQT Streaming Format June 2026 + + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, . + + [RFC9000] Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based + Multiplexed and Secure Transport", RFC 9000, + DOI 10.17487/RFC9000, May 2021, + . + + [SecureObjects] + Jennings, C. F., Nandakumar, S., and R. Barnes, "End-to- + End Secure Objects for Media over QUIC Transport", Work in + Progress, Internet-Draft, draft-jennings-moq-secure- + objects-04, 8 February 2026, + . + + [WEBCODECS-CODEC-REGISTRY] + "WebCodecs Codec Registry", September 2024, + . + + [WEBVTT] "World Wide Web Consortium (W3C), WebVTT: The Web Video + Text Tracks Format", April 2019, + . + +15.2. Informative References + + [E2EE-MLS] Jennings, C. F., Nandakumar, S., and R. Barnes, "End-to- + end Security for Media over QUIC", Work in Progress, + Internet-Draft, draft-jennings-moq-e2ee-mls-03, 30 June + 2025, . + + [IMSC1-MSF] + "IMSC1 Packaging for MOQT Streaming Format", 2026, + . + + [SCTE214-1] + "SCTE 214-1: MPEG DASH for IP-Based Cable Services Part 1 + - MPD Constraints and Extensions", 2022, + . + + [SCTE35-MSF] + "SCTE-35 over MSF Event Timeline", 2026, + . + + + + +Law & Nandakumar Expires 4 December 2026 [Page 73] + +Internet-Draft MOQT Streaming Format June 2026 + + + [WebVTT-MSF] + "WebVTT Packaging for MOQT Streaming Format", 2026, + . + +Acknowledgments + + * the MoQ Workgroup and mailing lists. + +Contributors + + The following persons where the co-authors of the individual draft + (draft-law-moq-warpstreamingformat) this document is based on: + + * Luke Curley + + * Victor Vasiliev + + * Suhas Nandakumar + + * Kirill Pugin + + * Will Law + +Authors' Addresses + + Will Law + Akamai + Email: wilaw@akamai.com + + + Suhas Nandakumar + Cisco + Email: snandaku@cisco.com + + + + + + + + + + + + + + + + + + +Law & Nandakumar Expires 4 December 2026 [Page 74] diff --git a/internal/specs/moq/draft-ietf-moq-transport-20.txt b/internal/specs/moq/draft-ietf-moq-transport-20.txt new file mode 100644 index 0000000000..866fe4947d --- /dev/null +++ b/internal/specs/moq/draft-ietf-moq-transport-20.txt @@ -0,0 +1,8848 @@ + + + + +Media Over QUIC S. Nandakumar +Internet-Draft Cisco +Intended status: Standards Track V. Vasiliev +Expires: 4 March 2027 I. Swett, Ed. + Google + A. Frindell, Ed. + Meta + 31 August 2026 + + + Media over QUIC Transport + draft-ietf-moq-transport-20 + +Abstract + + This document defines Media over QUIC Transport (MOQT), a publish/ + subscribe protocol that runs over QUIC and WebTransport. MOQT + leverages the features of these transports, such as streams, + datagrams, priorities, and partial reliability. MOQT operates both + point-to-point and through intermediate relays, enabling scalable + low-latency delivery. Despite its name, MOQT is media agnostic and + can be used for a wide range of use cases. + +About This Document + + This note is to be removed before publishing as an RFC. + + The latest revision of this draft can be found at https://moq- + wg.github.io/moq-transport/draft-ietf-moq-transport.html. Status + information for this document may be found at + https://datatracker.ietf.org/doc/draft-ietf-moq-transport/. + + Discussion of this document takes place on the Media Over QUIC + Working Group mailing list (mailto:moq@ietf.org), which is archived + at https://mailarchive.ietf.org/arch/browse/moq/. Subscribe at + https://www.ietf.org/mailman/listinfo/moq/. + + Source for this draft and an issue tracker can be found at + https://github.com/moq-wg/moq-transport. + +Status of This Memo + + This Internet-Draft is submitted in full conformance with the + provisions of BCP 78 and BCP 79. + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 1] + +Internet-Draft moq-transport August 2026 + + + Internet-Drafts are working documents of the Internet Engineering + Task Force (IETF). Note that other groups may also distribute + working documents as Internet-Drafts. The list of current Internet- + Drafts is at https://datatracker.ietf.org/drafts/current/. + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as "work in progress." + + This Internet-Draft will expire on 4 March 2027. + +Copyright Notice + + Copyright (c) 2026 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents (https://trustee.ietf.org/ + license-info) in effect on the date of publication of this document. + Please review these documents carefully, as they describe your rights + and restrictions with respect to this document. Code Components + extracted from this document must include Revised BSD License text as + described in Section 4.e of the Trust Legal Provisions and are + provided without warranty as described in the Revised BSD License. + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 7 + 1.1. Motivation . . . . . . . . . . . . . . . . . . . . . . . 7 + 1.1.1. Latency . . . . . . . . . . . . . . . . . . . . . . . 7 + 1.1.2. Leveraging QUIC . . . . . . . . . . . . . . . . . . . 8 + 1.1.3. Convergence . . . . . . . . . . . . . . . . . . . . . 8 + 1.1.4. Relays . . . . . . . . . . . . . . . . . . . . . . . 8 + 1.2. Terms and Definitions . . . . . . . . . . . . . . . . . . 8 + 1.3. Stream Management Terms . . . . . . . . . . . . . . . . . 10 + 1.4. Notational Conventions . . . . . . . . . . . . . . . . . 10 + 1.4.1. Variable-Length Integers . . . . . . . . . . . . . . 10 + 1.4.2. Location Structure . . . . . . . . . . . . . . . . . 12 + 1.4.3. Key-Value-Pair Structure . . . . . . . . . . . . . . 12 + 1.4.4. Reason Phrase Structure . . . . . . . . . . . . . . . 13 + 1.5. Representing Namespace and Track Names . . . . . . . . . 14 + 1.5.1. Parsing Serialized Names . . . . . . . . . . . . . . 14 + 2. Object Data Model . . . . . . . . . . . . . . . . . . . . . . 15 + 2.1. Objects . . . . . . . . . . . . . . . . . . . . . . . . . 15 + 2.2. Subgroups . . . . . . . . . . . . . . . . . . . . . . . . 16 + 2.3. Groups . . . . . . . . . . . . . . . . . . . . . . . . . 18 + 2.3.1. Group IDs . . . . . . . . . . . . . . . . . . . . . . 18 + + + +Nandakumar, et al. Expires 4 March 2027 [Page 2] + +Internet-Draft moq-transport August 2026 + + + 2.4. Track . . . . . . . . . . . . . . . . . . . . . . . . . . 18 + 2.4.1. Track Naming . . . . . . . . . . . . . . . . . . . . 19 + 2.4.2. Malformed Tracks . . . . . . . . . . . . . . . . . . 20 + 2.4.3. Scope . . . . . . . . . . . . . . . . . . . . . . . . 21 + 2.5. Properties . . . . . . . . . . . . . . . . . . . . . . . 22 + 2.5.1. Mandatory Track Properties . . . . . . . . . . . . . 23 + 3. Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . 24 + 3.1. Session establishment . . . . . . . . . . . . . . . . . . 24 + 3.1.1. MOQT URI Scheme . . . . . . . . . . . . . . . . . . . 25 + 3.1.2. Fragment Identifiers . . . . . . . . . . . . . . . . 25 + 3.1.3. Dereferencing a MOQT URI . . . . . . . . . . . . . . 26 + 3.1.4. WebTransport . . . . . . . . . . . . . . . . . . . . 27 + 3.1.5. Native QUIC . . . . . . . . . . . . . . . . . . . . . 27 + 3.1.6. Connection URL . . . . . . . . . . . . . . . . . . . 27 + 3.2. Extension Negotiation . . . . . . . . . . . . . . . . . . 27 + 3.2.1. Reserved Namespaces . . . . . . . . . . . . . . . . . 28 + 3.2.2. Session-Level Tracks and Namespaces . . . . . . . . . 28 + 3.3. Session initialization . . . . . . . . . . . . . . . . . 29 + 3.3.1. 0-RTT . . . . . . . . . . . . . . . . . . . . . . . . 30 + 3.3.2. Graceful Request Stream Closure . . . . . . . . . . . 31 + 3.3.3. Request Cancellation and Rejection . . . . . . . . . 31 + 3.3.4. Stream Reset Error Codes . . . . . . . . . . . . . . 32 + 3.4. Unidirectional Stream Types . . . . . . . . . . . . . . . 32 + 3.5. Termination . . . . . . . . . . . . . . . . . . . . . . . 33 + 3.6. Session Migration . . . . . . . . . . . . . . . . . . . . 35 + 3.7. Congestion Control . . . . . . . . . . . . . . . . . . . 35 + 3.7.1. Bufferbloat . . . . . . . . . . . . . . . . . . . . . 36 + 3.7.2. Application-Limited . . . . . . . . . . . . . . . . . 36 + 3.7.3. Consistent Throughput . . . . . . . . . . . . . . . . 36 + 4. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 37 + 5. Publishing and Retrieving Tracks . . . . . . . . . . . . . . 37 + 5.1. Subscriptions . . . . . . . . . . . . . . . . . . . . . . 37 + 5.1.1. Subscription State Management . . . . . . . . . . . . 39 + 5.1.2. Location Filters . . . . . . . . . . . . . . . . . . 40 + 5.1.3. Fill Semantics . . . . . . . . . . . . . . . . . . . 42 + 5.1.4. Range Filters . . . . . . . . . . . . . . . . . . . . 43 + 5.1.5. Combining Filters . . . . . . . . . . . . . . . . . . 46 + 5.1.6. Joining an Ongoing Track . . . . . . . . . . . . . . 46 + 5.2. Fetch State Management . . . . . . . . . . . . . . . . . 47 + 6. Namespace Discovery . . . . . . . . . . . . . . . . . . . . . 47 + 6.1. Subscribing to Namespaces . . . . . . . . . . . . . . . . 48 + 6.2. Publishing Namespaces . . . . . . . . . . . . . . . . . . 49 + 6.3. Filtering SUBSCRIBE_TRACKS . . . . . . . . . . . . . . . 50 + 6.3.1. Relay Resource Protection in Large Namespaces . . . . 50 + 7. Priorities . . . . . . . . . . . . . . . . . . . . . . . . . 50 + 7.1. Definitions . . . . . . . . . . . . . . . . . . . . . . . 51 + 7.2. Scheduling Algorithm . . . . . . . . . . . . . . . . . . 52 + 7.3. Considerations for Setting Priorities . . . . . . . . . . 53 + + + +Nandakumar, et al. Expires 4 March 2027 [Page 3] + +Internet-Draft moq-transport August 2026 + + + 8. Delivery Timeouts and Data Reliability . . . . . . . . . . . 54 + 9. Relays . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 + 9.1. Caching Relays . . . . . . . . . . . . . . . . . . . . . 56 + 9.2. Forward Handling . . . . . . . . . . . . . . . . . . . . 56 + 9.3. Multiple Publishers . . . . . . . . . . . . . . . . . . . 57 + 9.4. Subscriber Interactions . . . . . . . . . . . . . . . . . 57 + 9.4.1. Graceful Subscriber Relay Switchover . . . . . . . . 58 + 9.5. Publisher Interactions . . . . . . . . . . . . . . . . . 59 + 9.5.1. Graceful Publisher Relay Switchover . . . . . . . . . 61 + 9.6. Relay Track Handling . . . . . . . . . . . . . . . . . . 61 + 9.7. Relay Object Handling . . . . . . . . . . . . . . . . . . 61 + 10. Control Messages . . . . . . . . . . . . . . . . . . . . . . 61 + 10.1. Request ID . . . . . . . . . . . . . . . . . . . . . . . 63 + 10.2. Message Parameters . . . . . . . . . . . . . . . . . . . 63 + 10.2.1. Parameter Scope . . . . . . . . . . . . . . . . . . 65 + 10.2.2. AUTHORIZATION TOKEN Parameter . . . . . . . . . . . 65 + 10.2.3. SUBGROUP_DELIVERY_TIMEOUT Parameter . . . . . . . . 68 + 10.2.4. OBJECT_DELIVERY_TIMEOUT Parameter . . . . . . . . . 68 + 10.2.5. FILL TIMEOUT Parameter . . . . . . . . . . . . . . . 68 + 10.2.6. RENDEZVOUS TIMEOUT Parameter . . . . . . . . . . . . 69 + 10.2.7. SUBSCRIBER PRIORITY Parameter . . . . . . . . . . . 69 + 10.2.8. GROUP ORDER Parameter . . . . . . . . . . . . . . . 70 + 10.2.9. LOCATION FILTER Parameter . . . . . . . . . . . . . 70 + 10.2.10. SUBGROUP FILTER Parameter . . . . . . . . . . . . . 70 + 10.2.11. OBJECTID FILTER Parameter . . . . . . . . . . . . . 70 + 10.2.12. PRIORITY FILTER Parameter . . . . . . . . . . . . . 70 + 10.2.13. OBJECT PROPERTY FILTER Parameter . . . . . . . . . . 71 + 10.2.14. TRACK PROPERTY FILTER Parameter . . . . . . . . . . 71 + 10.2.15. FILL PARAMETERS Parameter . . . . . . . . . . . . . 71 + 10.2.16. EXPIRES Parameter . . . . . . . . . . . . . . . . . 73 + 10.2.17. LARGEST OBJECT Parameter . . . . . . . . . . . . . . 73 + 10.2.18. FORWARD Parameter . . . . . . . . . . . . . . . . . 74 + 10.2.19. NEW GROUP REQUEST Parameter . . . . . . . . . . . . 74 + 10.2.20. TRACK_NAMESPACE_PREFIX Parameter . . . . . . . . . . 75 + 10.2.21. INCLUDE_PROPERTIES Parameter . . . . . . . . . . . . 75 + 10.3. SETUP . . . . . . . . . . . . . . . . . . . . . . . . . 76 + 10.3.1. Setup Options . . . . . . . . . . . . . . . . . . . 76 + 10.4. GOAWAY . . . . . . . . . . . . . . . . . . . . . . . . . 79 + 10.5. REQUEST_OK . . . . . . . . . . . . . . . . . . . . . . . 80 + 10.6. REQUEST_ERROR . . . . . . . . . . . . . . . . . . . . . 81 + 10.6.1. Redirect Structure . . . . . . . . . . . . . . . . . 81 + 10.6.2. REQUEST_ERROR Message Format . . . . . . . . . . . . 82 + 10.7. SUBSCRIBE . . . . . . . . . . . . . . . . . . . . . . . 84 + 10.8. SUBSCRIBE_OK . . . . . . . . . . . . . . . . . . . . . . 85 + 10.9. REQUEST_UPDATE . . . . . . . . . . . . . . . . . . . . . 86 + 10.9.1. Updating Subscriptions . . . . . . . . . . . . . . . 87 + 10.9.2. Updating Namespace Subscriptions . . . . . . . . . . 87 + 10.10. PUBLISH_STATE_NOTIFY . . . . . . . . . . . . . . . . . . 88 + + + +Nandakumar, et al. Expires 4 March 2027 [Page 4] + +Internet-Draft moq-transport August 2026 + + + 10.11. PUBLISH . . . . . . . . . . . . . . . . . . . . . . . . 89 + 10.12. PUBLISH_DONE . . . . . . . . . . . . . . . . . . . . . . 90 + 10.13. FETCH . . . . . . . . . . . . . . . . . . . . . . . . . 92 + 10.14. FETCH_OK . . . . . . . . . . . . . . . . . . . . . . . . 94 + 10.15. TRACK_STATUS . . . . . . . . . . . . . . . . . . . . . . 95 + 10.16. PUBLISH_NAMESPACE . . . . . . . . . . . . . . . . . . . 95 + 10.17. NAMESPACE . . . . . . . . . . . . . . . . . . . . . . . 96 + 10.18. NAMESPACE_DONE . . . . . . . . . . . . . . . . . . . . . 96 + 10.19. SUBSCRIBE_NAMESPACE . . . . . . . . . . . . . . . . . . 96 + 10.20. SUBSCRIBE_TRACKS . . . . . . . . . . . . . . . . . . . . 98 + 10.20.1. Parameters on SUBSCRIBE_TRACKS . . . . . . . . . . 99 + 10.21. PUBLISH_SKIPPED . . . . . . . . . . . . . . . . . . . . 99 + 11. Data Streams and Datagrams . . . . . . . . . . . . . . . . . 100 + 11.1. Track Alias . . . . . . . . . . . . . . . . . . . . . . 100 + 11.2. Objects . . . . . . . . . . . . . . . . . . . . . . . . 101 + 11.2.1. Object Header . . . . . . . . . . . . . . . . . . . 101 + 11.3. Datagrams . . . . . . . . . . . . . . . . . . . . . . . 103 + 11.3.1. Object Datagram . . . . . . . . . . . . . . . . . . 104 + 11.4. Streams . . . . . . . . . . . . . . . . . . . . . . . . 105 + 11.4.1. Stream Cancellation . . . . . . . . . . . . . . . . 106 + 11.4.2. Subgroup Header . . . . . . . . . . . . . . . . . . 106 + 11.4.3. Closing Subgroup Streams . . . . . . . . . . . . . . 108 + 11.4.4. Fetch Header . . . . . . . . . . . . . . . . . . . . 111 + 11.5. Padding . . . . . . . . . . . . . . . . . . . . . . . . 114 + 11.5.1. Padding Streams . . . . . . . . . . . . . . . . . . 115 + 11.5.2. Padding Datagrams . . . . . . . . . . . . . . . . . 115 + 11.6. Examples . . . . . . . . . . . . . . . . . . . . . . . . 115 + 12. MOQT Properties . . . . . . . . . . . . . . . . . . . . . . . 117 + 12.1. SUBGROUP_DELIVERY_TIMEOUT . . . . . . . . . . . . . . . 117 + 12.2. OBJECT_DELIVERY_TIMEOUT . . . . . . . . . . . . . . . . 118 + 12.3. MAX CACHE DURATION . . . . . . . . . . . . . . . . . . . 118 + 12.4. DEFAULT PUBLISHER PRIORITY . . . . . . . . . . . . . . . 118 + 12.5. DEFAULT PUBLISHER GROUP ORDER . . . . . . . . . . . . . 118 + 12.6. DYNAMIC GROUPS . . . . . . . . . . . . . . . . . . . . . 119 + 12.7. Immutable Properties . . . . . . . . . . . . . . . . . . 119 + 12.8. Prior Group ID Gap . . . . . . . . . . . . . . . . . . . 120 + 12.9. Prior Object ID Gap . . . . . . . . . . . . . . . . . . 121 + 13. Security Considerations . . . . . . . . . . . . . . . . . . . 122 + 13.1. Subscription Amplification . . . . . . . . . . . . . . . 122 + 13.2. Communication Security . . . . . . . . . . . . . . . . . 122 + 13.3. Authorization . . . . . . . . . . . . . . . . . . . . . 123 + 13.3.1. Mutual TLS . . . . . . . . . . . . . . . . . . . . . 123 + 13.3.2. Replay Attacks . . . . . . . . . . . . . . . . . . . 123 + 13.3.3. Preventing Impersonation . . . . . . . . . . . . . . 124 + 13.4. Media Security . . . . . . . . . . . . . . . . . . . . . 124 + 13.5. Resource Exhaustion . . . . . . . . . . . . . . . . . . 125 + 13.6. Timeouts . . . . . . . . . . . . . . . . . . . . . . . . 125 + 13.6.1. Idle Connection Handling . . . . . . . . . . . . . . 125 + + + +Nandakumar, et al. Expires 4 March 2027 [Page 5] + +Internet-Draft moq-transport August 2026 + + + 13.7. Relay security considerations . . . . . . . . . . . . . 126 + 13.7.1. State maintenance . . . . . . . . . . . . . . . . . 126 + 13.7.2. SUBSCRIBE_NAMESPACE and SUBSCRIBE_TRACKS with short + prefixes . . . . . . . . . . . . . . . . . . . . . . 126 + 13.8. Implementation Identification Fingerprinting . . . . . . 126 + 13.9. Logging of Untrusted String Fields . . . . . . . . . . . 127 + 14. Grease . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 + 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 128 + 15.1. URI Scheme Registrations . . . . . . . . . . . . . . . . 128 + 15.1.1. "moqt" URI Scheme Registration . . . . . . . . . . . 128 + 15.2. Media Type Registration . . . . . . . . . . . . . . . . 129 + 15.3. MOQT URI Fragment Types . . . . . . . . . . . . . . . . 130 + 15.4. Setup Options . . . . . . . . . . . . . . . . . . . . . 130 + 15.5. Authorization Token Alias Type . . . . . . . . . . . . . 131 + 15.6. MOQT Auth Token Type . . . . . . . . . . . . . . . . . . 131 + 15.7. Message Parameters . . . . . . . . . . . . . . . . . . . 131 + 15.8. Properties . . . . . . . . . . . . . . . . . . . . . . . 132 + 15.9. Object Status . . . . . . . . . . . . . . . . . . . . . 135 + 15.10. Session-Level Track Names . . . . . . . . . . . . . . . 135 + 15.11. Error Codes . . . . . . . . . . . . . . . . . . . . . . 136 + 15.11.1. Session Termination Error Codes . . . . . . . . . . 136 + 15.11.2. REQUEST_ERROR Codes . . . . . . . . . . . . . . . . 137 + 15.11.3. PUBLISH_DONE Codes . . . . . . . . . . . . . . . . 138 + 15.11.4. Stream Reset Error Codes . . . . . . . . . . . . . 139 + Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 139 + Use of Generative AI . . . . . . . . . . . . . . . . . . . . . . 140 + References . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 + Normative References . . . . . . . . . . . . . . . . . . . . . 140 + Informative References . . . . . . . . . . . . . . . . . . . . 142 + Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 144 + A.1. Since draft-ietf-moq-transport-19 . . . . . . . . . . . . 144 + A.2. Since draft-ietf-moq-transport-18 . . . . . . . . . . . . 146 + A.3. Since draft-ietf-moq-transport-17 . . . . . . . . . . . . 147 + A.4. Since draft-ietf-moq-transport-16 . . . . . . . . . . . . 150 + A.5. Since draft-ietf-moq-transport-15 . . . . . . . . . . . . 152 + A.6. Since draft-ietf-moq-transport-14 . . . . . . . . . . . . 153 + A.7. Since draft-ietf-moq-transport-13 . . . . . . . . . . . . 155 + A.8. Since draft-ietf-moq-transport-12 . . . . . . . . . . . . 156 + A.9. Since draft-ietf-moq-transport-11 . . . . . . . . . . . . 156 + A.10. Since draft-ietf-moq-transport-10 . . . . . . . . . . . . 157 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 158 + + + + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 6] + +Internet-Draft moq-transport August 2026 + + +1. Introduction + + Media Over QUIC Transport (MOQT) is a publish/subscribe protocol that + runs over QUIC [QUIC] or WebTransport [WebTransport]. Publishers + produce data that is delivered to subscribers either point-to-point + or through intermediate relays. MOQT leverages transport features + such as streams, datagrams, priorities, and partial reliability to + support a wide range of use cases with different resiliency and + latency needs, from live to interactive, without compromising + scalability. + + Despite its name, MOQT is content agnostic. MoQ Streaming Formats + define how specific content types are encoded, packaged, and mapped + to MOQT objects, along with policies for discovery and subscription. + + * Section 2 describes the data model employed by MOQT. + + * Section 3 covers aspects of setting up an MOQT session. + + * Section 7 covers mechanisms for prioritizing subscriptions. + + * Section 9 covers behavior at the relay entities. + + * Section 10 covers how control messages are encoded on the wire. + + * Section 11 covers how data messages are encoded on the wire. + +1.1. Motivation + + The development of MOQT is driven by goals in a number of areas - + specifically latency, the robust feature set of QUIC and relay + support. + +1.1.1. Latency + + Latency is necessary to correct for variable network throughput. + Ideally live content is consumed at the same bitrate it is produced. + End-to-end latency would be fixed and only subject to encoding and + transmission delays. Unfortunately, networks have variable + throughput, primarily due to congestion. Attempting to deliver + content encoded at a higher bitrate than the network can cause + queuing along the path from producer to consumer. The speed at which + a protocol can detect and respond to congestion determines the + overall latency. TCP-based protocols are simple but are slow to + detect congestion and suffer from head-of-line blocking. Protocols + utilizing UDP directly can avoid queuing, but the application is then + responsible for the complexity of fragmentation, congestion control, + retransmissions, receiver feedback, reassembly, and more. One goal + + + +Nandakumar, et al. Expires 4 March 2027 [Page 7] + +Internet-Draft moq-transport August 2026 + + + of MOQT is to achieve the best of both these worlds: leverage the + features of QUIC to create a simple yet flexible low latency protocol + that can rapidly detect and respond to congestion. + +1.1.2. Leveraging QUIC + + The parallel nature of QUIC streams can provide improvements in the + face of loss. A goal of MOQT is to design a streaming protocol to + leverage the transmission benefits afforded by parallel QUIC streams + as well as exercising options for flexible loss recovery. + +1.1.3. Convergence + + Some live media architectures today have separate protocols for + ingest and distribution, for example RTMP and HTTP based HLS or DASH. + Switching protocols necessitates intermediary origins which re- + package the media content. While specialization can have its + benefits, there are efficiency gains to be had in not having to re- + package content. A goal of MOQT is to develop a single protocol + which can be used for transmission from contribution to distribution. + A related goal is the ability to support existing encoding and + packaging schemas, both for backwards compatibility and for + interoperability with the established content preparation ecosystem. + +1.1.4. Relays + + An integral feature of a protocol being successful is its ability to + deliver media at scale. Greatest scale is achieved when third-party + networks, independent of both the publisher and subscriber, can be + leveraged to relay the content. These relays must cache content for + distribution efficiency while simultaneously routing content and + deterministically responding to congestion in a multi-tenant network. + A goal of MOQT is to treat relays as first-class citizens of the + protocol and ensure that objects are structured such that information + necessary for distribution is available to relays while the media + content itself remains opaque and private. + +1.2. Terms and Definitions + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and + "OPTIONAL" in this document are to be interpreted as described in + BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all + capitals, as shown here. + + The following terms are used with the first letter capitalized. + + Application: The entity using MOQT to transmit and receive data. + + + +Nandakumar, et al. Expires 4 March 2027 [Page 8] + +Internet-Draft moq-transport August 2026 + + + Client: The party initiating a Transport Session. + + Server: The party accepting an incoming Transport Session. + + Endpoint: A Client or Server. + + Peer: The other endpoint than the one being described. + + Publisher: An endpoint that handles subscriptions by sending + requested Objects from the requested track. + + Subscriber: An endpoint that subscribes to and receives tracks. + + Original Publisher: The initial publisher of a given track. + + End Subscriber: A subscriber that initiates a subscription and does + not send the data on to other subscribers. + + Relay: An entity that is both a Publisher and a Subscriber, is not + the Original Publisher or End Subscriber, and conforms to all + requirements in Section 9. + + Upstream: In the direction of the Original Publisher. + + Downstream: In the direction of the End Subscriber(s). + + Transport Session: A raw QUIC connection or a WebTransport session. + + Stream: A bidirectional or unidirectional bytestream provided by the + QUIC transport or WebTransport. + + Congestion: Packet loss and queuing caused by degraded or overloaded + networks. + + Group: A collection of objects within a track. A group represents a + join point in a track. See (Section 2.3). + + Subgroup: A sequence of one or more objects from the same group, + sent on a single transport stream whenever possible. See + (Section 2.2). + + Object: An object is an addressable unit whose payload is a sequence + of bytes. Objects form the base element in the MOQT data model. + See (Section 2.1). + + Track: A track is a collection of groups. See (Section 2.4). + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 9] + +Internet-Draft moq-transport August 2026 + + +1.3. Stream Management Terms + + This document uses stream management terms described in [RFC9000], + Section 1.3 including STOP_SENDING, RESET_STREAM, and FIN. It also + uses RESET_STREAM_AT from + [I-D.draft-ietf-quic-reliable-stream-reset]. RESET_STREAM_AT can be + used by MOQT, but the protocol is also designed to work correctly + when the extension is not supported. + + When this document says an endpoint "resets" a stream, it means the + endpoint sends a RESET_STREAM or RESET_STREAM_AT frame on that stream + (see Section 11.4.3 for considerations on choosing between them). + +1.4. Notational Conventions + + This document uses the conventions detailed in ([RFC9000], + Section 1.3) when describing the binary encoding. + +1.4.1. Variable-Length Integers + + MOQT requires a variable-length integer encoding with the following + properties: + + 1. The encoded length can be determined from the first encoded byte. + + 2. The range of 1 byte values is as large as possible. + + 3. All 64 bit numbers can be encoded. + + The variable-length integer encoding uses the number of leading 1 + bits of the first byte to indicate the length of the encoding in + bytes. The remaining bits after the first 0 and subsequent bytes, if + any, represent the integer value, encoded in network byte order. + + Integers are encoded in 1 to 9 bytes and can encode up to 64 bit + unsigned integers. The following table summarizes the encoding + properties. + + + + + + + + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 10] + +Internet-Draft moq-transport August 2026 + + + +==============+================+========+========================+ + | Leading Bits | Length (bytes) | Usable | Range | + | | | Bits | | + +==============+================+========+========================+ + | 0 | 1 | 7 | 0-127 | + +--------------+----------------+--------+------------------------+ + | 10 | 2 | 14 | 0-16383 | + +--------------+----------------+--------+------------------------+ + | 110 | 3 | 21 | 0-2097151 | + +--------------+----------------+--------+------------------------+ + | 1110 | 4 | 28 | 0-268435455 | + +--------------+----------------+--------+------------------------+ + | 11110 | 5 | 35 | 0-34359738367 | + +--------------+----------------+--------+------------------------+ + | 111110 | 6 | 42 | 0-4398046511103 | + +--------------+----------------+--------+------------------------+ + | 1111110 | 7 | 49 | 0-562949953421311 | + +--------------+----------------+--------+------------------------+ + | 11111110 | 8 | 56 | 0-72057594037927935 | + +--------------+----------------+--------+------------------------+ + | 11111111 | 9 | 64 | 0-18446744073709551615 | + +--------------+----------------+--------+------------------------+ + + Table 1: Summary of Integer Encodings + + The following table contains some example encodings: + + +======================+============================+ + | Byte Sequence | Decimal Value | + +======================+============================+ + | 0x25 | 37 | + +----------------------+----------------------------+ + | 0x8025 | 37 | + +----------------------+----------------------------+ + | 0xbbbd | 15,293 | + +----------------------+----------------------------+ + | 0xed7f3e7d | 226,442,877 | + +----------------------+----------------------------+ + | 0xfaa1a0e403d8 | 2,893,212,287,960 | + +----------------------+----------------------------+ + | 0xfc8998abc66bc0 | 151,288,809,941,952 | + +----------------------+----------------------------+ + | 0xfefa318fa8e3ca11 | 70,423,237,261,249,041 | + +----------------------+----------------------------+ + | 0xffffffffffffffffff | 18,446,744,073,709,551,615 | + +----------------------+----------------------------+ + + Table 2: Example Integer Encodings + + + +Nandakumar, et al. Expires 4 March 2027 [Page 11] + +Internet-Draft moq-transport August 2026 + + + Variable-length integers do not need to be encoded using the minimum + number of bytes; any encoding length that can represent the value is + valid. Note that, as a result, the same numeric value can be + represented by more than one byte sequence. For example, the value 0 + can be encoded as 0x00, 0x8000, 0xc00000, or any longer form. + + x (vi64): Indicates that x holds an integer value using the + variable-length encoding as described above. + +1.4.2. Location Structure + + Location identifies a particular Object in a Group within a Track. + + Location { + Group (vi64), + Object (vi64) + } + + Figure 1: Location structure + + In this document, a Location can be expressed in the form of + {GroupID, ObjectID}, where GroupID and ObjectID indicate the Group ID + and Object ID of the Location, respectively. The constituent parts + of any Location A can be referred to using A.Group or A.Object. + + Location A < Location B if: + + A.Group < B.Group || (A.Group == B.Group && A.Object < B.Object) + +1.4.3. Key-Value-Pair Structure + + Key-Value-Pair is a flexible structure that carries key/value pairs + in which the key is a variable-length integer and the value is either + a variable-length integer or a byte field of arbitrary length. + + Key-Value-Pairs encode a Type value as a delta from the previous Type + value, or from 0 if there is no previous Type value. This is + efficient on the wire and makes it easy to ensure there is only one + instance of a type when needed. The previous Type value plus the + Delta Type MUST NOT be greater than 2^64 - 1. If a Delta Type is + received that would be too large, the Session MUST be closed with a + PROTOCOL_VIOLATION. + + Key-Value-Pair is used in both the data plane and control plane, but + is optimized for use in the data plane. + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 12] + +Internet-Draft moq-transport August 2026 + + + Key-Value-Pair { + Delta Type (vi64), + [Length (vi64),] + Value (..) + } + + Figure 2: MOQT Key-Value-Pair + + * Delta Type: an unsigned variable-length integer identifying the + Type as a delta encoded value from the previous Type, if any. The + Type identifies the type of value and also the subsequent + serialization. + + * Length: Only present when Type is odd. Specifies the length of + the Value field in bytes. The maximum length of a value is 2^16-1 + bytes. If an endpoint receives a length larger than the maximum, + it MUST close the session with a PROTOCOL_VIOLATION. + + * Value: A single variable-length integer when Type is even, + otherwise a sequence of Length bytes. + + If a receiver understands a Type, and the following Value or Length/ + Value does not match the serialization defined by that Type, the + receiver MUST close the session with error code + KEY_VALUE_FORMATTING_ERROR. + + Key-Value-Pairs are always parsed with a known byte length, which + bounds the sequence. The source of this length varies by context. + +1.4.4. Reason Phrase Structure + + Reason Phrase provides a way for the sender to encode additional + diagnostic information about an error condition, where appropriate. + + Reason Phrase { + Reason Phrase Length (vi64), + Reason Phrase Value (..) + } + + * Reason Phrase Length: A variable-length integer specifying the + length of the reason phrase in bytes. The reason phrase length + has a maximum value of 1024 bytes. If an endpoint receives a + length exceeding the maximum, it MUST close the session with a + PROTOCOL_VIOLATION + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 13] + +Internet-Draft moq-transport August 2026 + + + * Reason Phrase Value: Additional diagnostic information about an + error condition. The reason phrase value is encoded as UTF-8 + string and does not carry information, such as language tags, that + would aid comprehension by any entity other than the one that + created the text. + +1.5. Representing Namespace and Track Names + + There is often a need to render namespace tuples and track names for + purposes such as logging, representing track filenames, or use in + certain authorization verification schemes. The namespace and track + name are binary and need to be converted to a safe form. + + The following format is RECOMMENDED: + + * Each of the namespace tuples are rendered in order with a hyphen + (-) between them followed by the track name with a double hyphen + (--) between the last namespace and track name. + + * Bytes in the range a-z, A-Z, 0-9 as well as _ (0x5f) are output + verbatim, while all other bytes are encoded as a period (.) symbol + followed by exactly two lowercase hexadecimal digits. + + This format allows many common names to be rendered in an easily + human readable form while still supporting binary values. Note that + while the character set is chosen to be generally both filename and + URL safe, filename safety is platform specific; for instance, on + case-insensitive filesystems, track names can collide. + +1.5.1. Parsing Serialized Names + + When parsing a serialized namespace or track name back to its binary + form, implementations MUST apply the following rules to ensure a + canonical encoding: + + * A period (.) MUST be followed by exactly two hexadecimal digits. + A trailing period or a period followed by fewer than two + hexadecimal digits is invalid. + + * The hexadecimal digits following a period (.) MUST be lowercase + (a-f). Uppercase hexadecimal digits (A-F) are invalid and MUST + cause parsing to fail. + + * Bytes that can be represented literally (a-z, A-Z, 0-9, _) MUST + NOT appear in their hex-encoded form. For example, .61 is invalid + because a must be represented as the literal character a. A + parser MUST reject such redundant encodings. + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 14] + +Internet-Draft moq-transport August 2026 + + + These rules ensure that the encoding is bijective: every binary value + has exactly one valid serialized representation, and every valid + serialized string maps to exactly one binary value. This property + simplifies comparison of serialized names without requiring full + deserialization. + + Implementations that receive an invalid serialized name SHOULD treat + it as an error. The specific error handling behavior is application- + defined. + + Example: + + example.2enet-team2-project_x--report + Namespace tuples: (example.net, team2, project_x) + Track name: report + +2. Object Data Model + + MOQT has a hierarchical data model, comprised of tracks which contain + groups, and groups that contain objects. Inside of a group, the + objects can be organized into subgroups. + + To give an example of how an application might use this data model, + consider an application sending high and low resolution video using a + codec with temporal scalability. Each resolution is sent as a + separate track to allow the subscriber to pick the appropriate + resolution given the display environment and available bandwidth. + Each independently coded sequence of pictures in a resolution is sent + as a group as the first picture in the sequence can be used as a + random access point. This allows the client to join at the logical + points where decoding of the media can start without needing + information before the join points. The temporal layers are sent as + separate subgroups to allow the priority mechanism to favor lower + temporal layers when there is not enough bandwidth to send all + temporal layers. Each frame of video is sent as a single object. + +2.1. Objects + + The basic data element of MOQT is an object. An object is an + addressable unit whose payload is a sequence of bytes. All objects + belong to a group, indicating ordering and potential dependencies + (see Section 2.3). An object is uniquely identified by its track + namespace, track name, group ID, and object ID, and must be an + identical sequence of bytes regardless of how or where it is + retrieved. An Object can become unavailable, but its contents MUST + NOT change over time. + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 15] + +Internet-Draft moq-transport August 2026 + + + Objects are comprised of two parts: metadata and a payload. The + metadata is never encrypted and is always visible to relays (see + Section 9). The payload portion may be encrypted, in which case it + is only visible to the Original Publisher and End Subscribers. The + Original Publisher is solely responsible for the content of the + object payload. This includes the underlying encoding, compression, + any end-to-end encryption, or authentication. + + From the perspective of a subscriber or a cache, an Object can be in + three possible states: + + 1. The Object is known to not exist. This state is permanent. All + signals that an Object does not exist are authoritative. + + 2. The Object is known to exist. From this state, it can transition + to not existing, but not vice versa. + + 3. The state of the Object is unknown, either because it has not yet + been received, or it has not yet been produced. + + A gap in the observed Object IDs does not by itself convey any + information about the skipped Objects. Skipped Objects remain in the + unknown state until they are received or their non-existence is + signalled, for example in a FETCH stream (see Section 11.4.4) or via + a Prior Object ID Gap (see Section 12.9). + + Since Objects can be delivered out of order, an endpoint can receive + an Object after it has already recorded that the Object does not + exist (e.g., via a FETCH gap from one source and delayed delivery via + a subscription). This is not a protocol error and the Track is not + malformed. + + Whenever the publisher communicates that certain objects do not + exist, this fact is expressed as a contiguous range of non-existent + objects and by including Properties indicating the group/object gaps; + MOQT implementers should take that into account when selecting + appropriate data structures. + +2.2. Subgroups + + A subgroup is a sequence of one or more objects from the same group + (Section 2.3) in ascending order by Object ID. Objects in a subgroup + have a dependency and priority relationship consistent with sharing a + stream and are sent on a single stream whenever possible. A Group is + delivered using at least as many streams as there are Subgroups in + the Group, typically with a one-to-one mapping between Subgroups and + streams. + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 16] + +Internet-Draft moq-transport August 2026 + + + When an Object's forwarding preference (see Section 11.2.1.2) is + "Datagram", it is not sent in Subgroups, does not belong to a + Subgroup in any way, and the description in the remainder of this + section does not apply. + + Streams offer in-order reliable delivery and the ability to cancel + sending and retransmission of data. Furthermore, many QUIC and + WebTransport implementations offer the ability to control the + relative scheduling priority of pending stream data. + + Every Object within a Group belongs to exactly one Subgroup or + Datagram. + + When Objects are sent in a subscription (see Section 5.1), Objects + from two subgroups MUST NOT be sent on the same stream, and Objects + from the same Subgroup MUST NOT be sent on different streams, unless + one of the streams was reset prematurely, or upstream conditions have + forced objects from a Subgroup to be sent out of Object ID order. + + Original publishers assign each Subgroup a Subgroup ID, and do so as + they see fit. The scope of a Subgroup ID is a Group, so Subgroups + from different Groups MAY share a Subgroup ID without implying any + relationship between them. In general, publishers assign objects to + subgroups in order to leverage the features of streams as described + above. + + In general, if Object B is dependent on Object A, then delivery of B + can follow A, i.e. A and B can be usefully delivered over a single + stream. If an Object is dependent on all previous Objects in a + Subgroup, it likely fits best in that Subgroup. If an Object is not + dependent on any of the Objects in a Subgroup, it likely belongs in a + different Subgroup. + + When assigning Objects to different Subgroups, the Original Publisher + makes a reasonable tradeoff between having an optimal mapping of + Object relationships in a Group and minimizing the number of streams + used. + + When the Original Publisher opens a new subgroup, it MUST set the + FIRST_OBJECT bit (Section 11.4.2) to indicate that the first object + in the subgroup stream is the first object ever published in that + subgroup. A relay forwarding a subgroup that begins with the first + object ever published in that subgroup MUST set the FIRST_OBJECT bit. + + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 17] + +Internet-Draft moq-transport August 2026 + + +2.3. Groups + + A group is a collection of Objects and is a sub-unit of a Track + (Section 2.4). Groups SHOULD be independently useful, so Objects + within a Group SHOULD NOT depend on Objects in other Groups. A Group + provides a join point for subscriptions, so a subscriber that does + not want to receive the entire Track can opt to receive only Groups + starting from a given Group ID. Groups can contain any number of + Objects. + +2.3.1. Group IDs + + Within a track, the original publisher SHOULD publish Group IDs which + increase with time (where "time" is defined according to the internal + clock of the media being sent). In some cases, Groups will be + produced in increasing order, but sent to subscribers in a different + order, for example when the subscription's Group Order is Descending. + Due to network reordering and the partial reliability features of + MOQT, Objects from different Groups can always be received out of + order. + + As a result, subscribers cannot infer the existence of a Group until + an object in the Group is received. This can create gaps in a cache + that can be filled by doing a Fetch upstream, if necessary. + + Applications that do not produce Group IDs that increase with time + are limited to the subset of MOQT that does not compare group IDs. + Subscribers to these Tracks SHOULD NOT use Location filters which + span multiple Groups in FETCH or SUBSCRIBE. SUBSCRIBE and FETCH + delivery use Group Order, so they could have an unexpected delivery + order if Group IDs do not increase with time. + + The amount of time elapsed between publishing an Object in Group ID N + and in a Group ID > N, or even which will be published first, is not + defined by this specification and is defined by the applications + using MOQT. + +2.4. Track + + A track is a sequence of groups (Section 2.3). It is the entity + against which a subscriber issues a subscription request. A + subscriber can request to receive individual tracks starting at a + group boundary, including any new objects pushed by the publisher + while the track is active. + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 18] + +Internet-Draft moq-transport August 2026 + + +2.4.1. Track Naming + + In MOQT, every track is identified by a Full Track Name, consisting + of a Track Namespace and a Track Name. + + Track Namespace is an ordered set of between 0 and 32 Track Namespace + Fields, encoded as follows: + + Track Namespace { + Number of Track Namespace Fields (vi64), + Track Namespace Field (..) ... + } + + * Number of Track Namespace Fields: A variable-length integer + specifying the number of Track Namespace Fields in the Track + Namespace. + + Each Track Namespace Field is encoded as follows: + + Track Namespace Field { + Track Namespace Field Length (vi64), + Track Namespace Field Value (..) + } + + * Track Namespace Field Length: A variable-length integer specifying + the length of the Track Namespace Field in bytes. + + * Track Namespace Field Value: A sequence of bytes that forms a + Track Namespace Field. + + Each Track Namespace Field Value MUST contain at least one byte. If + an endpoint receives a Track Namespace Field with a Track Namespace + Field Length of 0, it MUST close the session with a + PROTOCOL_VIOLATION. + + The structured nature of Track Namespace allows relays and + applications to manipulate prefixes of a namespace. If an endpoint + receives a Track Namespace consisting of greater than 32 Track + Namespace Fields, it MUST close the session with a + PROTOCOL_VIOLATION. + + Track Name is a sequence of bytes, possibly empty, that identifies an + individual track within the namespace. + + The maximum total length of a Full Track Name is 4,096 bytes. The + length of a Full Track Name is computed as the sum of the Track + Namespace Field Length fields and the Track Name Length field. The + length of a Track Namespace is the sum of the Track Namespace Field + + + +Nandakumar, et al. Expires 4 March 2027 [Page 19] + +Internet-Draft moq-transport August 2026 + + + Length fields. If an endpoint receives a Track Namespace or a Full + Track Name exceeding 4,096 bytes, it MUST close the session with a + PROTOCOL_VIOLATION. + + In this specification, both the Track Namespace Fields and the Track + Name are not constrained to a specific encoding. They carry a + sequence of bytes and comparison between two Track Namespace Fields + or Track Names is done by exact comparison of the bytes. + Specifications that use MOQT may constrain the information in these + fields, for example by restricting them to UTF-8. Any such + specification needs to specify the canonicalization into the bytes in + the Track Namespace Fields or Track Name such that exact comparison + works. + +2.4.2. Malformed Tracks + + There are multiple ways a publisher can transmit a Track that does + not conform to MOQT constraints. Such a Track is considered + malformed. Some example conditions that constitute a malformed track + when detected by a receiver include: + + 1. An Object with a particular Subgroup ID is received, but its + Publisher Priority is different from that of the previous Object + with the same Subgroup ID. + + 2. An Object is received whose Object ID is larger than the final + Object in the Subgroup. The final Object in a Subgroup is the + last Object received on a Subgroup stream before a FIN. + + 3. A Subgroup is received over multiple transport streams terminated + by FIN with different final Objects. + + 4. An Object is received in a Group whose Object ID is larger than + the final Object in the Group. The final Object in a Group is + the Object with Status END_OF_GROUP, or the last Object before a + FIN in a Subgroup which has the END_OF_GROUP bit set. If the end + of a Group is implicitly determined via a gap in a FETCH + response, the final Object in the Group remains unknown. + + 5. An Object is received whose Group and Object ID are larger than + the final Object in the Track. The final Object in a Track is + the Object with Status END_OF_TRACK or the last Object sent in a + FETCH whose response indicated End of Track. + + 6. The same Object is received more than once with different Payload + or other immutable properties. + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 20] + +Internet-Draft moq-transport August 2026 + + + 7. An Object is received with a different Forwarding Preference than + previously observed. + + The above list of conditions is not considered exhaustive. + + When a subscriber detects a Malformed Track, it MUST cancel any + corresponding subscription or fetches for that Track from that + publisher (see Section 3.3.3), and SHOULD deliver an error to the + application. If a relay detects a Malformed Track, it MUST + immediately terminate downstream subscriptions with PUBLISH_DONE and + reset any fetch streams with Status Code MALFORMED_TRACK. Object(s) + triggering Malformed Track status MUST NOT be cached. + +2.4.3. Scope + + An MOQT scope is a set of servers (as identified by their connection + URIs) for which a Full Track Name is guaranteed to be unique and + identify a specific track. It is up to the application using MOQT to + define how broad or narrow the scope is. An application that deals + with connections between devices on a local network may limit the + scope to a single connection; by contrast, an application that uses + multiple CDNs to serve media may require the scope to include all of + those CDNs. + + A single MOQT transport session is tied to the scope that is + negotiated in the beginning of the session. Unless the application + has additional information, two tracks are assumed to belong to the + same scope if and only if the authority and path-abempty components + (Section 3.1.1) of their connection URIs are equal. These values are + communicated through the SETUP message in case of raw QUIC, and + through HTTP request header fields in case of WebTransport. + + The query component of the connection URI is not part of the scope; + two connection URIs that differ only in their query components + identify the same scope. + + Because each Full Track Name is unique within an MOQT scope, they can + be used as a cache key for the track. If, at a given moment in time, + two tracks within the same scope contain different data, they MUST + have different names and/or namespaces. MOQT provides subscribers + with the ability to alter the specific manner in which tracks are + delivered via Parameters, but the actual content of the tracks does + not depend on those parameters; this is in contrast to protocols like + HTTP, where request headers can alter the server response. + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 21] + +Internet-Draft moq-transport August 2026 + + + A publisher that loses state (e.g. crashes) and intends to resume + publishing on the same Track risks colliding with previously + published Objects and violating the above requirements. A publisher + can handle this in application specific ways, for example: + + 1. Select a unique Track Name or Track Namespace whenever it resumes + publishing. For example, it can base one of the Namespace Fields + on the current time, or select a sufficiently large random value. + + 2. Resume publishing under a previous Track Name and Namespace and + set the initial Group ID to a unique value guaranteed to be + larger than all previously used groups. This can be done by + choosing a Group ID based on the current time. + + 3. Use TRACK_STATUS or similar mechanism to query the previous state + to determine the largest published Group ID. + +2.5. Properties + + Tracks and Objects can have additional relay-visible fields, known as + Properties, which do not require negotiation, and can be used to + alter MOQT Object distribution. + + Properties are defined in Section 12 as well as external + specifications and are registered in an IANA table Section 15. These + specifications define the type and value of the property, along with + any rules concerning processing, modification, caching and + forwarding. + + If a Relay does not support a Property, it MUST NOT be modified, MUST + be forwarded, and MUST be cached with the Track or Object, unless it + is a Mandatory Track Property as described in Section 2.5.1. If a + Track or Object arrives with a different set of unknown properties + than previously cached, the most recent set SHOULD replace any cached + values, removing any unknown values not present in the new set. + Relays MUST NOT attempt to merge sets of unknown properties received + in different messages. + + If a Relay supports a Property, it MUST follow the processing rules + in the Property's definition. Unless those rules permit otherwise, a + Relay MUST NOT modify, add, or remove the Property; it MUST forward + the Property to downstream subscribers and MUST cache it with the + Track or Object if the Track or Object is cached. + + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 22] + +Internet-Draft moq-transport August 2026 + + + Properties are serialized as Key-Value-Pairs (see Figure 2). Track + Properties always appear as the final field in the messages that + carry them; their length is the remaining bytes of the message after + all preceding fields have been consumed. Object Properties + (Section 11.2.1.2) are preceded by an explicit length field. + + Property types are registered in the IANA table 'MOQ Properties'. + See Section 15. + + Certain Property type ranges are reserved for application-specific + use and will never be allocated by IANA in future MOQT + specifications: + + * 0x78 to 0x7F (1-byte encoding): 8 code points for applications + with tight space constraints + + * 0x3800 to 0x3FFF (2-byte encoding): 2048 code points (including + grease Section 14) for applications with moderate space + constraints + + Applications MAY use code points in these ranges without registration + for format-specific metadata or other application-defined purposes. + Relays that do not understand the application format MUST forward + these properties unchanged but MUST NOT attempt to interpret their + semantic meaning. Different applications using the same code point + in these ranges may assign different meanings; the interpretation + depends on the track or application context known to the publisher + and subscriber. + +2.5.1. Mandatory Track Properties + + Property types in the range 0x4000-0x7FFF are designated as Mandatory + Track Properties. These properties MUST have Track scope. Mandatory + Track Properties have special handling rules that prevent tracks with + required properties from being forwarded to or processed by endpoints + that do not understand them. + + An Object received with a Mandatory Track Property as an Object + Property is malformed (see Section 2.4.2). + + When an endpoint receives a Mandatory Track Property in PUBLISH, + SUBSCRIBE_OK, or FETCH_OK that it does not understand, it MUST NOT + process or forward that track: + + * For PUBLISH messages: the subscriber MUST respond with + REQUEST_ERROR with error code UNSUPPORTED_EXTENSION. + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 23] + +Internet-Draft moq-transport August 2026 + + + * For SUBSCRIBE_OK messages: the subscriber MUST cancel the + subscription (see Section 3.3.3). If the subscriber is a relay + with pending downstream subscribers, it MUST send REQUEST_ERROR + with error code UNSUPPORTED_EXTENSION to the downstream + subscribers. + + * For FETCH_OK messages: the subscriber MUST cancel the fetch (see + Section 3.3.3). If the subscriber is a relay and has not yet sent + a FETCH_OK or REQUEST_ERROR downstream, it MUST send REQUEST_ERROR + with error code UNSUPPORTED_EXTENSION to the downstream fetch + requester. If the relay has already forwarded data on a fetch + stream, it MUST reset the stream. + + A publisher that knows a subscriber does not support a Mandatory + Track Property SHOULD take the following action: + + * For SUBSCRIBE: respond with REQUEST_ERROR with error code + UNSUPPORTED_EXTENSION. + + * For FETCH: respond with REQUEST_ERROR with error code + UNSUPPORTED_EXTENSION. + + * For PUBLISH: do not publish the track to that subscriber. + +3. Sessions + +3.1. Session establishment + + This document defines a protocol that can be used interchangeably + both over a QUIC connection directly [QUIC], and over WebTransport + [WebTransport]. Both provide streams and datagrams with similar + semantics (see [I-D.ietf-webtrans-overview], Section 4); thus, the + main difference lies in how the servers are identified and how the + connection is established. The QUIC DATAGRAM extension ([RFC9221]) + MUST be supported and negotiated in the QUIC connection used for + MOQT, which is already a requirement for WebTransport over HTTP/3. + + There is no definition of the protocol over other transports, such as + TCP, and applications using MOQT might need to fallback to another + protocol when QUIC or WebTransport aren't available. + + MOQT uses ALPN in QUIC and "WT-Available-Protocols" in WebTransport + ([WebTransport], Section 3.3) to perform version negotiation. + + The ALPN value [RFC7301] for the final version of this specification + is moqt. + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 24] + +Internet-Draft moq-transport August 2026 + + + [[RFC editor: please remove the remainder of this section before + publication.]] + + ALPNs used to identify IETF drafts are created by appending the draft + number to "moqt-". For example, draft-ietf-moq-transport-13 would be + identified as "moqt-13". + + Note: Draft versions prior to -15 all used moq-00 ALPN, followed by + version negotiation in the SETUP messages. + +3.1.1. MOQT URI Scheme + + An MOQT server is identified using a URI with the "moqt" scheme. The + "moqt" URI scheme is defined as follows, using definitions from + [RFC3986]: + + moqt-URI = "moqt" "://" authority path-abempty [ "?" query ] + + The authority portion MUST NOT contain an empty host portion. The + moqt URI scheme supports the /.well-known/ path prefix defined in + [RFC8615]. + + The moqt URI scheme follows the generic URI syntax of [RFC3986] for + the authority, path-abempty, and query components, including the use + of reserved characters and percent-encoding defined therein. A moqt + URI can be converted to an https URI by replacing the scheme (see + Section 3.1.4), so the path-abempty and query components use the same + syntax as https URIs. + +3.1.2. Fragment Identifiers + + The media type for resources identified by moqt URIs is application/ + moqt (see Section 15.2). + + Fragment identifiers MAY be used with moqt URIs. The fragment is not + transmitted to the server; it is processed locally by the client + after establishing the MOQT session. + + A moqt URI fragment MUST begin with a registered fragment type + identifier, followed by a colon (:), followed by a type-specific + value: + + moqt://example.com/app#: + + Fragment type identifiers MUST consist of ASCII lowercase letters, + digits, and hyphens (a-z, 0-9, -). The semantics of the value after + the colon are defined by the specification that registers the + fragment type. + + + +Nandakumar, et al. Expires 4 March 2027 [Page 25] + +Internet-Draft moq-transport August 2026 + + + Fragment type identifiers are registered in the "MOQT URI Fragment + Types" registry (Section 15.3). + +3.1.3. Dereferencing a MOQT URI + + The default operation for dereferencing a moqt URI is to establish a + MOQT session to the identified server. + + The moqt URI scheme has the following security considerations: + + * The authority component is sent in the TLS SNI extension during + connection establishment, exposing the target server identity to + on-path observers. Encrypted Client Hello (ECH) [RFC9580] can + mitigate this exposure. + + * The path-abempty and query components are visible to the relay + that terminates the client's connection. + + TODO: Add internationalization statement per RFC 7595 Section 3.6. + + The client resolves the host subcomponent of the authority to one or + more network addresses, most commonly using DNS A [RFC1035] and AAAA + [RFC3596] records. + + When SVCB-compatible records [RFC9460] are published for the + authority, a client MAY use them to learn the server's endpoints and + supported ALPN protocols before connecting. A client using + WebTransport resolves the https URI derived in Section 3.1.4 using + HTTPS resource records as for any https origin. TODO: reference moqt + SVCB record draft once available. + + If the port is omitted in the URI, a default port of 443 is used. + + The client MAY use either native QUIC or WebTransport. On a QUIC + connection, the client offers any combination of MOQT ALPNs (e.g. + moqt-1, moqt-2) and h3 that it supports in its TLS ClientHello, in + preference order. If the server selects an MOQT ALPN, the session + proceeds as described in Section 3.1.5. If the server selects h3, + the client establishes a WebTransport session as described in + Section 3.1.4. On a TCP+TLS connection, the client offers h2 in its + TLS ClientHello and establishes a WebTransport session as described + in Section 3.1.4. + + + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 26] + +Internet-Draft moq-transport August 2026 + + +3.1.4. WebTransport + + When the client uses WebTransport, it constructs an https URI from + the moqt URI by replacing the scheme with https. For example, + moqt://example.com/path becomes https://example.com/path. The client + sends an extended CONNECT request to this URI to establish a + WebTransport session, as described in ([WebTransport], Section 3). + The client includes MOQT protocol identifiers in the WT-Available- + Protocols header ([WebTransport], Section 3.3). + +3.1.5. Native QUIC + + The client establishes a QUIC connection to the host and port + identified by the authority section of the URI. When the client uses + native QUIC, the authority, path-abempty and query portions of the + URI are transmitted in Setup Options (see Section 10.3.1). + +3.1.6. Connection URL + + Each track MAY have one or more associated connection URLs specifying + network hosts through which a track may be accessed. The syntax of + the Connection URL and the associated connection setup procedures are + specific to the underlying transport protocol usage (see Section 3). + +3.2. Extension Negotiation + + Endpoints use the exchange of Setup messages to negotiate MOQT + extensions. Extensions can define new Message types, new Parameters, + new Properties, new Parameter values, or new framing for Streams and + Datagrams. + + The client and server MUST include all Setup Options Section 10.3.1 + required for the negotiated MOQT version in SETUP. + + Each endpoint declares the extensions it supports and provides any + initial values required by those extensions as Setup Options in + SETUP. Once an endpoint has both sent and received SETUP messages, + it determines the set of negotiated extensions. + + New versions of MOQT MUST specify which existing extensions can be + used with that version. New extensions MUST specify the existing + versions with which they can be used. + + + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 27] + +Internet-Draft moq-transport August 2026 + + +3.2.1. Reserved Namespaces + + MOQT reserves all Track Namespace values whose first tuple field + begins with a period (0x2e, .). These namespaces MUST NOT be used + unless their meaning is defined through IANA registration. Unless + otherwise specified, an endpoint that receives a request for an + unrecognized reserved namespace MUST pass it to the Application, so + that future extensions can define new reserved namespaces without + breaking older implementations. + + A Track Namespace whose first field is exactly . (a single period, + 0x2e) is reserved and MUST NOT be used for any purpose; endpoints + MUST NOT publish tracks or namespaces under it and MUST reject + requests referencing it with DOES_NOT_EXIST. + +3.2.2. Session-Level Tracks and Namespaces + + MOQT defines the .session namespace (the bytes 0x2e, 0x73, 0x65, + 0x73, 0x73, 0x69, 0x6f, 0x6e) in the first position of the Track + Namespace for session-level tracks and namespaces. Session-level + tracks and namespaces are managed by the MOQT implementation, not the + Application. They provide a mechanism for extending MOQT transport + functionality using existing subscription and object delivery + machinery, without defining new control messages or stream types. + + The Application MUST NOT publish tracks or namespaces whose first + field is .session. Relays MUST NOT forward requests for session- + level tracks and namespaces to other sessions. + + The empty track name in the .session namespace is defined to not + exist. A request with a Track Namespace whose first field is + .session and an empty Track Name MUST be rejected with + DOES_NOT_EXIST. + + An endpoint that receives a request for an unrecognized session-level + track or namespace MUST reject it with REQUEST_ERROR using error code + DOES_NOT_EXIST rather than passing it to the Application. + + The track names and namespaces available under the .session namespace + are defined by extensions to this specification and registered with + IANA (see Section 15.10). + + + + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 28] + +Internet-Draft moq-transport August 2026 + + +3.3. Session initialization + + MOQT uses a pair of unidirectional streams for creating the session + and exchanging control messages. Each peer opens one control stream + beginning with a SETUP message. Using a pair of unidirectional + streams rather than a single bidirectional stream allows either peer + to send data as soon as it is able. Depending on whether 0-RTT is + available on the QUIC connection, either the client or the server + might be able to send stream data first. + + In addition to the control streams, this specification uses + bidirectional streams to carry requests. A request stream begins + with one of these seven message types: TRACK_STATUS, SUBSCRIBE, + PUBLISH, FETCH, PUBLISH_NAMESPACE, SUBSCRIBE_NAMESPACE, and + SUBSCRIBE_TRACKS. Bidirectional streams MUST NOT begin with any + other message type unless negotiated. If they do, the peer MUST + close the Session with a PROTOCOL_VIOLATION. Objects are sent on + unidirectional streams. + + As such, a client can initiate a MOQT session, subscribe, and start + publishing Objects all in parallel. When this is done before the + handshake completes using 0-RTT, the security implications described + in Section 3.3.1 apply. + + Unidirectional streams containing Objects or bidirectional stream(s) + beginning with a request message could arrive prior to the control + streams, in which case the data SHOULD be buffered until both control + streams arrive and setup is complete. If an implementation does not + want to buffer or if the message type is not supported, it MAY reset + such bidirectional streams before the session and control streams are + established. + + A control stream MUST NOT be closed at the underlying transport layer + during the session's lifetime. Doing so results in the session being + closed as a PROTOCOL_VIOLATION. + + Prior to receiving the peer's SETUP message, it's unknown what + extensions a peer will support. Message Parameters requiring + negotiation SHOULD NOT be used prior to receiving the peer's SETUP + message unless the application requires the extension or the endpoint + knows the peer supports the extension. If an unsupported Message + Parameter is used, the peer will be unable to process it and the + session will be terminated. See Section 10.2. + + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 29] + +Internet-Draft moq-transport August 2026 + + +3.3.1. 0-RTT + + QUIC supports 0-RTT (Section 2.3 of [RFC8446]), but WebTransport over + QUIC is not expected to use 0-RTT, because initializing a + WebTransport session uses CONNECT, which is not a safe method. + [RFC8470] describes the use of 0-RTT with HTTP in more detail. If + 0-RTT is used with an existing or future version of WebTransport, the + following would apply to it as well as QUIC. + + MOQT Messages and Objects as defined in this draft are safe to replay + in most circumstances. + + * TRACK_STATUS gets the Largest Object and Track Properties, but + does not change the state of a Track or any Object in the Track. + + * SUBSCRIBE requests Objects be delivered, but does not change the + Objects being requested. + + * PUBLISH initiates a Subscription. Objects can be immediately sent + to the Subscriber. Processing the same Objects multiple times is + idempotent, as the subscriber or relay can identify and discard + duplicates based on the Group ID and Object ID. + + * SUBSCRIBE_NAMESPACE requests a list of namespaces and the + establishment of new subscriptions, but does not change the + available Namespaces, Tracks, or Objects contained within a Track. + + * PUBLISH_NAMESPACE requests that Subscriptions under the namespace + be sent to that Publisher. If a Subscription was sent to the + replaying endpoint, it would fail because the endpoint cannot + complete the handshake. + + Some potential side effects of replay are: + + * Publishing Objects that were previously published could cause + those Objects to be distributed to active Subscriptions if the + relays do not identify them as already having been published. + This re-distribution could also make them available in cache again + after they previously expired. + + Replays could increase load on the MOQT network. For relay to client + traffic, this is no worse than 0-RTT in HTTP/3, since the server is + limited by the amplification factor until address validation. + However, it could cause the relay to initiate new upstream + Subscriptions. For a SUBSCRIBE_TRACKS request, sending that upstream + could cause the Relay to receive a number of new Subscriptions on the + replaying client's behalf. + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 30] + +Internet-Draft moq-transport August 2026 + + + Relays MAY defer initiating upstream subscriptions until the + handshake is complete or reject 0-RTT entirely to mitigate resource + exhaustion from replayed packets. + +3.3.2. Graceful Request Stream Closure + + A request stream is bidirectional and each direction is closed + independently, either gracefully with a FIN or abruptly with + RESET_STREAM. + + A FIN only indicates that an endpoint will send no further messages + in that direction; it is not a request cancellation. An endpoint + MUST NOT send a FIN on a direction of a request stream until it has + sent all required messages on that direction for its request type. + In particular, an endpoint sending a response to a request MUST send + the corresponding response message, and the publisher of an + Established subscription MUST send PUBLISH_DONE, before sending a + FIN. A FIN sent by the responder after its response and any + subsequent messages for the request signals that the request is + complete; if it has not already done so, the requester SHOULD then + send a FIN on its direction, gracefully closing the stream. An + endpoint that receives a FIN before all required messages have + arrived treats the request as failed. + + An endpoint SHOULD send a FIN promptly after a message when it has + nothing further to send on that direction and will not need to + respond to a future REQUEST_UPDATE. A requester, with the exception + of the sender of PUBLISH, MAY FIN immediately after sending a message + if it will not send a REQUEST_UPDATE. + +3.3.3. Request Cancellation and Rejection + + Once a request stream has been opened, the request MAY be cancelled + by either endpoint. Senders cancel requests if the response is no + longer of interest; Receivers cancel requests if they are unable to + or choose not to respond. Implementations cancel a request by + abruptly terminating any directions of the stream that are still + open, using RESET_STREAM for a direction they are sending and + STOP_SENDING for a direction they are receiving. An endpoint that + has already sent a FIN on its sending direction and subsequently + wishes to cancel sends STOP_SENDING on the receiving direction. + + When an endpoint rejects a request without performing any application + processing, it SHOULD send a REQUEST_ERROR and FIN the stream. + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 31] + +Internet-Draft moq-transport August 2026 + + +3.3.4. Stream Reset Error Codes + + The application SHOULD use a relevant error code when resetting or + sending STOP_SENDING on any stream. + + INTERNAL_ERROR (0x0): An implementation specific error. + + CANCELLED (0x1): The stream was cancelled by either endpoint. For + Subscriptions, PUBLISH_DONE (Section 10.12) may have a more + detailed status code. + + DELIVERY_TIMEOUT (0x2): A delivery timeout (Section 8) was exceeded + for this stream. + + SESSION_CLOSED (0x3): The session is being closed. + + GOING_AWAY (0x4): The endpoint is rejecting this request because it + has sent or received a GOAWAY. + + TOO_FAR_BEHIND (0x5): The corresponding subscription has exceeded + the publisher's resource limits and is being terminated (see + Section 8). + + UNKNOWN_OBJECT_STATUS (0x6): In response to a FETCH, the publisher + is unable to determine the status of the next Object in the + requested range. + + EXPIRED_AUTH_TOKEN (0x7): The authorization token for the request + has expired. + + EXCESSIVE_LOAD (0x9): The endpoint is overloaded and is resetting + this stream. + + MALFORMED_TRACK (0x12): A relay publisher detected that the track + was malformed (see Section 2.4.2). + +3.4. Unidirectional Stream Types + + All unidirectional MOQT streams start with a variable-length integer + indicating the type of the stream. + + + + + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 32] + +Internet-Draft moq-transport August 2026 + + + +============+==================================+ + | ID | Type | + +============+==================================+ + | 0x05 | FETCH_HEADER (Section 11.4.4) | + +------------+----------------------------------+ + | 0b0XX1XXXX | SUBGROUP_HEADER (Section 11.4.2) | + +------------+----------------------------------+ + | 0x2F00 | SETUP (Section 10.3) | + +------------+----------------------------------+ + | 0x132B3E28 | PADDING (Section 11.5.1) | + +------------+----------------------------------+ + + Table 3 + + An endpoint that receives an unknown stream type MUST close the + session. + + Control streams (SETUP) are described in Section 3.3. Data streams + (FETCH_HEADER, SUBGROUP_HEADER) are described in Section 11. Padding + streams are described in Section 11.5. + +3.5. Termination + + The Transport Session can be terminated at any point. When native + QUIC is used, the session is closed using the CONNECTION_CLOSE frame + ([QUIC], Section 19.19). When WebTransport is used, the session is + closed using the CLOSE_WEBTRANSPORT_SESSION capsule ([WebTransport], + Section 6). + + When terminating the Session, the application MAY use any error + message and SHOULD use a relevant code, as defined below: + + NO_ERROR (0x0): The session is being terminated without an error. + + INTERNAL_ERROR (0x1): An implementation specific error occurred. + + UNAUTHORIZED (0x2): The client is not authorized to establish a + session. + + PROTOCOL_VIOLATION (0x3): The remote endpoint performed an action + that was disallowed by the specification. + + INVALID_REQUEST_ID (0x4): The endpoint received a Request ID with an + incorrect least significant bit for the sender, or a duplicate + Request ID. See Section 10.1. + + DUPLICATE_TRACK_ALIAS (0x5): The endpoint attempted to use a Track + Alias that was already in use. + + + +Nandakumar, et al. Expires 4 March 2027 [Page 33] + +Internet-Draft moq-transport August 2026 + + + KEY_VALUE_FORMATTING_ERROR (0x6): The key-value pair has a + formatting error. + + INVALID_PATH (0x8): The PATH parameter was used by a server, on a + WebTransport session, or the server does not support the path. + + MALFORMED_PATH (0x9): The PATH parameter does not conform to the + rules in Section 10.3.1.2. + + GOAWAY_TIMEOUT (0x10): The session was closed because the peer took + too long to close the session in response to a GOAWAY + (Section 10.4) message. See session migration (Section 3.6). + + CONTROL_MESSAGE_TIMEOUT (0x11): The session was closed because the + peer took too long to respond to a control message. + + DATA_STREAM_TIMEOUT (0x12): The session was closed because the peer + took too long to send data expected on an open Data Stream (see + Section 11). This includes fields of a stream header or an object + header within a data stream. If an endpoint times out waiting for + a new object header on an open subgroup stream, it MAY send a + STOP_SENDING on that stream or terminate the subscription. + + AUTH_TOKEN_CACHE_OVERFLOW (0x13): The Session limit Section 10.3.1.3 + of the size of all registered Authorization tokens has been + exceeded. + + DUPLICATE_AUTH_TOKEN_ALIAS (0x14): Authorization Token attempted to + register an Alias that was in use (see Section 10.2.2). + + MALFORMED_AUTH_TOKEN (0x16): Invalid Auth Token serialization during + registration (see Section 10.2.2). + + UNKNOWN_AUTH_TOKEN_ALIAS (0x17): No registered token found for the + provided Alias (see Section 10.2.2). + + EXPIRED_AUTH_TOKEN (0x18): Authorization token has expired + (Section 10.2.2). + + INVALID_AUTHORITY (0x19): The specified AUTHORITY does not + correspond to this server or cannot be used in this context. + + MALFORMED_AUTHORITY (0x1A): The AUTHORITY value is syntactically + invalid. + + TOO_MANY_REQUEST_UPDATES (0x1B): The endpoint received a + REQUEST_UPDATE that exceeded the per-stream limit communicated via + the MAX_REQUEST_UPDATES Setup Option (Section 10.3.1.7). + + + +Nandakumar, et al. Expires 4 March 2027 [Page 34] + +Internet-Draft moq-transport August 2026 + + + An endpoint MAY choose to treat a subscription or request specific + error as a session error under certain circumstances, closing the + entire session in response to a condition with a single subscription + or message. Implementations need to consider the impact on other + outstanding subscriptions before making this choice. + +3.6. Session Migration + + MOQT requires a long-lived and stateful session. However, a service + provider needs the ability to shutdown/restart a server without + waiting for all sessions to drain naturally, as that can take days + for long-form media. MOQT enables proactively draining sessions via + the GOAWAY message (Section 10.4). + + A GOAWAY on the control stream migrates the entire session, as + described in this section. A GOAWAY on a single request stream + instead migrates only that request, leaving the rest of the session + in place; see Section 10.4. + + The server sends a GOAWAY message, signaling the client to establish + a new session and migrate any Established subscriptions. The GOAWAY + message optionally contains a new URI for the new session, otherwise + the current URI is reused. The GOAWAY message contains a Timeout + indicating how long, in milliseconds, the sender intends to wait + before closing the session. The sender SHOULD close the session with + GOAWAY_TIMEOUT after the indicated timeout if there are still open + subscriptions or fetches on a connection. + + When the server is a subscriber, it SHOULD send a GOAWAY message to + downstream subscribers prior to unsubscribing from upstream + publishers. + + After the client receives a GOAWAY, it's RECOMMENDED that the client + waits until there are no more Established subscriptions before + closing the session with NO_ERROR. Ideally this is transparent to + the application using MOQT, which involves establishing a new session + in the background and migrating Established subscriptions and + published namespaces. The client can choose to delay closing the + session if it expects more OBJECTs to be delivered. The sender + closes the session with a GOAWAY_TIMEOUT if the peer doesn't close + the session within the indicated Timeout. + +3.7. Congestion Control + + MOQT does not specify a congestion controller, but there are + important attributes to consider when selecting a congestion + controller for use with an application built on top of MOQT. + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 35] + +Internet-Draft moq-transport August 2026 + + +3.7.1. Bufferbloat + + Traditional AIMD congestion controllers (ex. CUBIC [RFC9438] and + Reno [RFC6582]) are prone to Bufferbloat. Bufferbloat occurs when + elements along the path build up a substantial queue of packets, + commonly more than doubling the round trip time. These queued + packets cause head-of-line blocking and latency, even when there is + no packet loss. + +3.7.2. Application-Limited + + The average bitrate for latency sensitive content needs to be less + than the available bandwidth, otherwise data will be queued and/or + dropped. As such, many MOQT applications will typically be limited + by the available data to send, and not the congestion controller. + Many congestion control algorithms only increase the congestion + window or bandwidth estimate if fully utilized. This combination can + lead to underestimating the available network bandwidth. As a + result, applications might need to periodically ensure the congestion + controller is not app-limited for at least a full round trip to + ensure the available bandwidth can be measured. + + Some applications might have APIs to allow sending duplicate data or + forward error correction to probe for more bandwidth while also + limiting the impact of probing in case it causes packet loss. + Subscribers wanting to switch to an alternate representation of a + Track can subscribe to it at a lower priority, or subscribe to + additional Tracks at the lowest (255) priority to fill the congestion + window during probing intervals while minimizing the impact on higher + priority media. Publishers can send padding (Section 11.5) to probe + for additional bandwidth without requiring additional subscriptions. + Network-assisted bandwidth estimation mechanisms such as SCONE + [I-D.ietf-scone-protocol] can provide receivers with sustainable + bandwidth hints, which subscribers can use to inform track selection + decisions and potentially avoid unnecessary probing. + +3.7.3. Consistent Throughput + + Congestion control algorithms are commonly optimized for throughput, + not consistency. For example, BBR's PROBE_RTT state halves the + sending rate for more than a round trip in order to obtain an + accurate minimum RTT. Similarly, Reno halves its congestion window + upon detecting loss. In both cases, the large reduction in sending + rate might cause issues with latency sensitive applications. + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 36] + +Internet-Draft moq-transport August 2026 + + +4. Extensibility + + MOQT defines all messages necessary to implement both simple + publishing or subscribing endpoints as well as fully capable Relays. + Non-Relay endpoints MAY implement only the subset of functionality + required to perform necessary tasks. For example, a limited media + player could operate using only SUBSCRIBE related messages. Limited + endpoints SHOULD respond to any unsupported messages with the + appropriate NOT_SUPPORTED error code, rather than ignoring them. + + Relays MUST implement all MOQT messages defined in this document, as + well as processing rules described in Section 9. + +5. Publishing and Retrieving Tracks + +5.1. Subscriptions + + All subscriptions begin in the Idle state. A subscription can be + initiated and moved to the Pending state by either a publisher or a + subscriber. A publisher initiates a subscription to a track by + sending the PUBLISH message. The subscriber either accepts or + rejects the subscription using PUBLISH_OK (Section 10.5) or + REQUEST_ERROR. A subscriber initiates a subscription to a track by + sending the SUBSCRIBE message. The publisher either accepts or + rejects the subscription using SUBSCRIBE_OK or REQUEST_ERROR. Once + either of these sequences is successful, the subscription moves to + the Established state and can be updated by the subscriber using + REQUEST_UPDATE. Either endpoint can terminate an Established + subscription, moving it to the Terminated state. The subscriber + terminates a subscription in the Pending (Subscriber) or Established + states by sending STOP_SENDING. The publisher terminates a + subscription in the Pending (Publisher) or Established states by + sending PUBLISH_DONE and closing the stream. + + This diagram shows the subscription state machine: + + + + + + + + + + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 37] + +Internet-Draft moq-transport August 2026 + + + +--------+ + | Idle | + +--------+ + | | + SUBSCRIBE | | PUBLISH + (subscriber)| | (publisher) + V V + +--------------+ +--------------+ + | Pending | | Pending | + +----| (Subscriber) | | (Publisher) |----+ + | +--------------+ +--------------+ | + | | | | + REQUEST_ERROR | SUBSCRIBE_OK | | PUBLISH_OK | REQUEST_ERROR + (publisher) | (publisher)| | (subscriber) | (subscriber) + | V V | + | +-------------+ | + | | Established | ------+ + | | | | REQUEST_UPDATE + | +-------------+ <-----+ + | | | | + +--- STOP_SENDING | | PUBLISH_DONE ----+ + | (subscriber)| | (publisher) | + | V V | + | +-------------+ | + +----------->| Terminated | <------------+ + +-------------+ + + A publisher MUST send exactly one SUBSCRIBE_OK or REQUEST_ERROR in + response to a SUBSCRIBE. A subscriber MUST send exactly one + PUBLISH_OK (Section 10.5) or REQUEST_ERROR in response to a PUBLISH. + The peer SHOULD close the session with a protocol error if it + receives more than one. + + All Established subscriptions have a Forward State which is either 0 + or 1. The publisher does not send Objects if the Forward State is 0, + and does send them if the Forward State is 1. The initiator of the + subscription sets the initial Forward State in either PUBLISH or + SUBSCRIBE. The subscriber can send REQUEST_UPDATE to update the + Forward State. Control messages, such as PUBLISH_DONE + (Section 10.12) are sent regardless of the forward state. + + Either endpoint can initiate a subscription to a track without + exchanging any prior messages other than SETUP. Relays MUST NOT send + any PUBLISH messages without knowing the client is interested in and + authorized to receive the content. The communication of intent and + authorization can be accomplished by the client sending + SUBSCRIBE_NAMESPACE, or conveyed in other mechanisms out of band. + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 38] + +Internet-Draft moq-transport August 2026 + + + An endpoint MAY SUBSCRIBE to a Track it is publishing, though only + Relays are required to handle such a SUBSCRIBE. Such self- + subscriptions are identical to subscriptions initiated by other + endpoints, and all published Objects will be forwarded back to the + endpoint, subject to priority and congestion response rules. + + An endpoint MAY have multiple concurrent subscriptions to the same + Track, each identified by a unique Request ID. A publisher MAY + assign the same or different Track Aliases to these subscriptions. + + When an Object matches the filters of multiple subscriptions to the + same Track, the publisher MUST send the Object once for each matching + subscription, even when those subscriptions share the same Track + Alias. Because subscriptions can share a Track Alias, the subscriber + re-applies each subscription's filter to determine which subscription + a received Object belongs to. Subscribers SHOULD avoid overlapping + filters across subscriptions to the same Track, as they are + responsible for deduplicating any resulting duplicate Objects. + + A publisher SHOULD begin sending incomplete objects when available to + avoid incurring additional latency. + + Publishers MAY start sending Objects on PUBLISH-initiated + subscriptions before receiving a PUBLISH_OK response to reduce + latency. Doing so can consume unnecessary resources in cases where + the Subscriber rejects the subscription with REQUEST_ERROR or sets + Forward=0 in REQUEST_UPDATE. It can also result in the Subscriber + dropping Objects if its buffering limits are exceeded (see + Section 11.3 and Section 11.4.2). + +5.1.1. Subscription State Management + + A subscriber keeps subscription state until it cancels the request + (see Section 3.3.3), or until receipt of a PUBLISH_DONE or + REQUEST_ERROR. Note that PUBLISH_DONE does not usually indicate that + state can immediately be removed, see Section 10.12. + + The Publisher can remove subscription state as soon as it has + received STOP_SENDING. It MUST reset any open streams associated + with the SUBSCRIBE. + + The Publisher can also immediately delete subscription state after + sending PUBLISH_DONE, but MUST NOT send it until it has closed all + related streams. + + A REQUEST_ERROR indicates no objects will be delivered, and both + endpoints can immediately remove relevant state. Objects MUST NOT be + sent for requests that end with an error. + + + +Nandakumar, et al. Expires 4 March 2027 [Page 39] + +Internet-Draft moq-transport August 2026 + + +5.1.2. Location Filters + + Subscribers can specify a Location filter on a subscription + indicating to the publisher which Objects to send. Subscriptions + without a filter pass all Objects published or received via upstream + subscriptions. + + Fetch requests can also specify a Location filter. Fetch requests + without a filter include all Locations from {0, 0} up to Largest + Object (defined below). + + A Location filter specifies an inclusive range of Locations. Only + objects with Locations within the inclusive range pass the filter. + + An object published or received in a subgroup or datagram is + *subscription-delivered*. Objects delivered via a fill fetch stream + (see Section 5.1.3) are *fill-delivered*. + + Some Location filters are defined to be relative to the Largest + Object. The Largest Object is the Object with the largest Location + (Section 1.4.2) in the Track from the perspective of the publisher + processing the message. Largest Object updates when the first byte + of an Object with a Location larger than the previous value is + published or received through a subscription. + + A Location filter parameter has the following length-prefixed + structure: + + LOCATION_FILTER Parameter { + Parameter Type (vi64) = 0x21, + Length (vi64), + [StartGroup (vi64),] + [StartObject (vi64),] + [EndGroupDelta (vi64),] + [EndObject (vi64),] + } + + Length (in bytes) determines how many optional vi64 fields are + present. A length of 0 indicates no filter, for example to remove + the filter in REQUEST_UPDATE. * If only one field is present, it is + StartGroup. * If only two fields are present, they are StartGroup + and StartObject. * If only three fields are present, they are + StartGroup, StartObject, and EndGroupDelta. + + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 40] + +Internet-Draft moq-transport August 2026 + + + If only StartGroup is present, it is a relative number of groups + prior to the Next Group, hence the start Location is {Largest + Object.Group + 1 - StartGroup, 0}. For example: * StartGroup=0 will + start at the Next Group * StartGroup=1 will start at the current + group * StartGroup=2 will start at 1 group prior to the current group + * StartGroup=N will start at N-1 groups prior to the current group + + If only StartGroup and StartObject are present and both 0, the start + Location is the Next Object which is {Largest Object.Group, Largest + Object.Object + 1}, or {0, 0} if no content has been delivered yet. + An open-ended filter that starts at absolute Location {0, 0} is + equivalent to unfiltered, so the subscriber need not include a + Location filter. Note that due to network reordering or + prioritization, relays can receive Objects with Locations smaller + than Largest Object after the SUBSCRIBE is processed, but these + Objects do not pass this filter. + + If a relative start group results in a computed absolute group less + than 0, the computed value is set to 0; if greater than 2^64 - 1, it + is set to 2^64 - 1. + + Otherwise, all fields are absolute. EndGroupDelta is delta encoded + from StartGroup, but both the start and end groups are absolute, not + relative to Largest Object. If StartGroup + EndGroupDelta exceeds + 2^64 - 1, the endpoint MUST close the session with a + PROTOCOL_VIOLATION. + + When EndGroupDelta and EndObject are omitted from a subscription + filter, the subscription is open-ended. When they are omitted from a + Fetch, the EndGroup and EndObject are Largest Object. + + When EndObject is omitted, the filter includes all objects in the End + Group. + + A Location Filter on a subscription is always valid, even if it + specifies a range entirely before Largest Object. + + A publisher MUST NOT send subscription-delivered objects from outside + the requested range. Because updating filters is asynchronous, + subscribers can receive objects outside the current filter. + + A publisher does not end a subscription solely because the Largest + Object advances past the end of the current Location Filter. + + Fill-delivered objects are governed by the Location filter in + FILL_PARAMETERS (see Section 5.1.3). + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 41] + +Internet-Draft moq-transport August 2026 + + +5.1.3. Fill Semantics + + A subscription that carries a FILL_PARAMETERS parameter (see + Section 10.2.15) causes the publisher to open a unidirectional stream + beginning with a FETCH_HEADER (see Section 11.4.4) and delivered as a + FETCH response (see Section 10.13). This is called a fill fetch + stream. + + The *fill range* is the range of Locations selected by the Location + filter inside FILL_PARAMETERS, or the subscription's Location filter + if it is omitted. The filter is evaluated using the rules for a + Fetch in Section 5.1.2, so the fill range never extends beyond + Largest Object. When the subscription has no Location filter, or the + LOCATION_FILTER inside FILL_PARAMETERS is zero-length, the fill range + is the entire track up to Largest Object. The subscriber learns the + Largest Object from the LARGEST_OBJECT parameter in SUBSCRIBE_OK or + REQUEST_UPDATE_OK. + + Because the fill range is specified independently of the + subscription's Location filter, a subscriber can retrieve a range of + Groups prior to the live edge while the subscription itself starts at + the Next Group. If the fill range is empty, or starts after Largest + Object, the publisher does not open a fill fetch stream. + + The fill fetch stream inherits the subscription's parameters, + including subscriber priority, range filters and authorization; + parameters carried inside FILL_PARAMETERS override them for the fill + fetch stream. FILL_TIMEOUT (see Section 10.2.5) applies to fill + fetch streams in the same way it applies to a FETCH. + + The FETCH_HEADER on the fill fetch stream carries the Request ID of + the message that initiated it: the SUBSCRIBE Request ID for the + initial fill, or the REQUEST_UPDATE Request ID for a subsequent fill. + As a result of REQUEST_UPDATE, a subscription can have multiple fill + fetch streams open at once, each identified by its Request ID; + opening a new fill fetch stream does not implicitly cancel any + previously opened fill fetch streams. + + An object delivered on the fill fetch stream is *fill-delivered*. + When the fill range overlaps the subscription's Location filter, an + object can be both fill-delivered and subscription-delivered. A + subscriber that wants each Object delivered exactly once uses the + Next Object Subscription Location Filter coupled with an open-ended + fill range, which the publisher will end at Largest Object. + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 42] + +Internet-Draft moq-transport August 2026 + + +5.1.3.1. Opening and Closing Fill Fetch Streams + + A publisher opens a fill fetch stream when it processes a SUBSCRIBE + or REQUEST_UPDATE that carries FILL_PARAMETERS while Forward State is + 1. + + * FILL_PARAMETERS carried while Forward State is 0 opens no fill + fetch stream. Transitioning to Forward State 1 without re-sending + FILL_PARAMETERS does not open one either. + + * A REQUEST_UPDATE that does not carry FILL_PARAMETERS does not open + a new fill fetch stream. + + * When the subscription is cancelled, the publisher MUST reset any + open fill fetch streams. + + The publisher signals that the fill is complete by closing the stream + with a FIN once all objects in the fill range have been delivered. + Because there is no REQUEST_ERROR associated with a fill fetch + stream, the publisher signals a fill failure by resetting the stream; + it MUST open a fill fetch stream and reset it immediately after the + FETCH_HEADER if necessary. A subscriber can cancel a fill fetch + stream independently using STOP_SENDING. Resetting or cancelling a + fill fetch stream, by either endpoint, does not affect the + subscription, which continues to deliver objects using subscribe + subgroups and datagrams. + +5.1.4. Range Filters + + Range Filters are parameters in SUBSCRIBE, FETCH, or SUBSCRIBE_TRACKS + that tell a publisher to filter tracks (via TRACK PROPERTY FILTER) + and objects according to subscriber-provided criteria. Range filters + are specified as ranges of integer values in Track and Object + Properties and other Object header fields (Subgroup ID, Object ID, + and Publisher Priority). There are five Range Filter parameter + types, 0x25-0x29, as shown below. + + + + + + + + + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 43] + +Internet-Draft moq-transport August 2026 + + + SUBGROUP_FILTER { + Type (vi64) = 0x25, + Length (vi64), + [SetID (8)], + [Range (..) ...] + } + + OBJECTID_FILTER { + Type (vi64) = 0x26, + Length (vi64), + [SetID (8)], + [Range (..) ...] + } + + PRIORITY_FILTER { + Type (vi64) = 0x27, + Length (vi64), + [SetID (8)], + [Range (..) ...] + } + + OBJECT_PROPERTY_FILTER { + Type (vi64) = 0x28, + Length (vi64), + [SetID (8)], + [Property Type (vi64)], + [Range (..) ...] + } + + TRACK_PROPERTY_FILTER { + Type (vi64) = 0x29, + Length (vi64), + [SetID (8)], + [Property Type (vi64)], + [Range (..) ...] + } + + Range { + Start (vi64), + [End (vi64)] + } + + Length (vi64) is the byte count of all fields after itself. When + Length is 0, there is no filter and no further fields are present. + This can be used in REQUEST_UPDATE to remove a filter. The Object + Property and Track Property Filters include a Property Type (vi64) + which follows SetID. + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 44] + +Internet-Draft moq-transport August 2026 + + + Each Range is an inclusive Start/End pair. End is optional in the + last pair; if omitted it indicates the last Range is open-ended. An + object matches the filter if its value falls within any Range (i.e., + Ranges are OR'd within a filter parameter). + + Each Start is delta encoded from the prior Range's End (or from 0 for + the first Range), and End is delta encoded from its own Start. If + adding the delta would exceed 2^64-1, the request MUST be rejected + with INVALID_FILTER. For example, ranges 3-5 and 10-15 encode as: + Start=3, End=2, Start=5, End=5. + + Filter parameters with the same SetID are AND'd; distinct SetIDs are + OR'd. The final result is SetID=0 OR SetID=1 OR ... SetID=255, where + each SetID=i is the AND of all filter parameters carrying that SetID. + + The Track Property filter parameter MAY appear multiple times in a + SUBSCRIBE_TRACKS message or REQUEST_UPDATE for it. All other filter + parameters MAY appear multiple times in a FETCH, SUBSCRIBE, + SUBSCRIBE_TRACKS, or REQUEST_UPDATE (on a subscription, from the + subscriber only) message. If the same combination of Parameter Type, + SetID, and Property Type (only in the Track and Object Property + Filters) repeat in any message, an endpoint MUST reject this with + REQUEST_ERROR with error code INVALID_FILTER. + + In REQUEST_UPDATE, Length of 0 removes the filter; non-zero replaces + it entirely. If a filter parameter is omitted from REQUEST_UPDATE, + it is unchanged. If omitted from other messages, the default is no + filter. + + Range Filters are only allowed if the setup option MAX_FILTER_RANGES + is non-zero, which limits the total number of Ranges allowed in all + Range Filter parameters for a given subscription or fetch. If this + limit is exceeded, an endpoint MUST reject this with REQUEST_ERROR + with error code INVALID_FILTER. + + The Track Property Filter can be used in SUBSCRIBE_TRACKS to filter + PUBLISH messages with required Track Property types and values. + PUBLISH messages which pass the filter will be forwarded while those + which do not pass it will not be forwarded nor will any Objects. + + The Object Property Filter can be used to filter Objects with + required Object Property types and values. It only filters Object + Properties in the Object header, and does not evaluate Track + Properties in PUBLISH messages. + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 45] + +Internet-Draft moq-transport August 2026 + + +5.1.5. Combining Filters + + All filter types are combined using logical "AND" operations to + further restrict which tracks and objects pass all filter criteria. + This includes all Range Filters Section 5.1.4 and Location Filters + Section 5.1.2, which can be evaluated in any order. The Forward + parameter is also a type of filter. The publisher MUST forward only + objects that pass all filters. + + Pass = Forward AND Location Filters AND Range Filters + +5.1.6. Joining an Ongoing Track + + The MOQT Object model is designed with the concept that the beginning + of a Group is a join point, so in order for a subscriber to join a + Track, it needs to request an existing Group or wait for a future + Group. Different applications will have different approaches for + when to begin a new Group. + + To join a Track immediately, the subscriber sends a SUBSCRIBE with a + Location Filter Section 5.1.2 that starts at the Next Object. + Delivery begins with the next Object and can begin mid-group. + + To join a Track at the current Group, the subscriber sends a + SUBSCRIBE with a Location Filter that starts at the Next Object and a + FILL_PARAMETERS parameter (see Section 10.2.15) whose Location filter + has StartGroup=1, which fills the current Group from its start. + + To join a Track at a past Group, the subscriber sends a SUBSCRIBE + with a FILL_PARAMETERS parameter whose Location filter selects the + intended Groups, which can be relative. The publisher delivers the + fill range on a fill fetch stream and subscription-delivered Objects + in subgroups or datagrams (see Section 5.1.3). + + To join a Track at the next Group, the subscriber sends a SUBSCRIBE + with a Location Filter Section 5.1.2 that starts at the Next Group. + +5.1.6.1. Dynamically Starting New Groups + + While some publishers will deterministically create new Groups, other + applications might want to only begin a new Group when needed. A + subscriber joining a Track might detect that it is more efficient to + request the Original Publisher create a new group than to fill the + current group. Publishers indicate a Track supports dynamic group + creation using the DYNAMIC_GROUPS Track Property (Section 12.6). + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 46] + +Internet-Draft moq-transport August 2026 + + + One possible subscriber pattern is to SUBSCRIBE to a Track using a + Location Filter that starts at the Next Object and observe the + Largest Object in the response. If the Object ID is below the + application's threshold, the subscriber sends a FETCH for the + beginning of the Group. If the Object ID is above the threshold and + the Track supports dynamic groups, the subscriber sends a + REQUEST_UPDATE message with the NEW_GROUP_REQUEST parameter equal to + the Next Group (see Section 10.2.19). + + Another possible subscriber pattern is to send a SUBSCRIBE with a + Location Filter that starts at the Next Group and NEW_GROUP_REQUEST + equal to 0. The value of DYNAMIC_GROUPS in SUBSCRIBE_OK will + indicate if the publisher supports dynamic groups. A publisher that + does will begin the next group as soon as practical. + +5.2. Fetch State Management + + The publisher MUST send exactly one FETCH_OK or REQUEST_ERROR in + response to a FETCH. + + A subscriber keeps FETCH state until it cancels the request (see + Section 3.3.3), receives REQUEST_ERROR, or the FETCH data stream + receives a FIN or is reset. If the data stream is already open, the + subscriber wishing to cancel the FETCH MAY send STOP_SENDING for the + data stream as well as the bidi request stream. It MUST send + STOP_SENDING for the bidi request stream. + + The Publisher can remove fetch state as soon as it has received a + STOP_SENDING. It MUST reset the bidi request stream and + unidirectional data stream associated with the FETCH. It can also + remove state after closing the FETCH data stream. + + It can remove all FETCH state after closing the data stream with a + FIN. + + A REQUEST_ERROR indicates that both endpoints can immediately remove + state. Since a relay can start delivering FETCH Objects from cache + before determining the result of the request, some Objects could be + received even if the FETCH results in error. + +6. Namespace Discovery + + Discovery of MOQT servers is always done out-of-band. Namespace + discovery can be done in the context of an established MOQT session + using SUBSCRIBE_NAMESPACE (see Section 6.1). + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 47] + +Internet-Draft moq-transport August 2026 + + + Given sufficient out of band information, it is valid for a + subscriber to send a SUBSCRIBE or FETCH message to a publisher + (including a relay) without any previous MOQT messages besides SETUP. + However, SUBSCRIBE_NAMESPACE, SUBSCRIBE_TRACKS, PUBLISH and + PUBLISH_NAMESPACE messages provide an in-band means of discovery of + publishers for a namespace. + + The syntax of these messages is described in Section 10. + +6.1. Subscribing to Namespaces + + If the subscriber is aware of a namespace of interest, it can send + SUBSCRIBE_NAMESPACE or SUBSCRIBE_TRACKS to publishers/relays it has + established a session with. The Track Namespace Prefix carried in + these messages is compared against the namespaces known to the + receiver using Namespace Prefix Matching (Section 9.5, Paragraph 6). + + SUBSCRIBE_NAMESPACE requests namespace discovery: the publisher sends + relevant NAMESPACE and NAMESPACE_DONE messages for namespaces + matching the prefix, including echoing back Track Namespaces under + the prefix that have been published to it. + + SUBSCRIBE_TRACKS requests track subscriptions: the publisher sends + PUBLISH messages for tracks within matching namespaces, excluding + tracks published by the subscriber. + + Either message with zero Track Namespace fields indicates the sender + is interested in all namespaces or all tracks from the receiver, + respectively. + + By sending SUBSCRIBE_NAMESPACE, the subscriber indicates that it + trusts the relay to be authoritative for namespaces matching the + requested prefix. NAMESPACE messages received on the + SUBSCRIBE_NAMESPACE response stream inherit this trust and do not + independently carry authorization. + + The subscriber sends SUBSCRIBE_NAMESPACE or SUBSCRIBE_TRACKS on a new + bidirectional stream and the publisher MUST send a single REQUEST_OK + or REQUEST_ERROR as the first message on the bidirectional stream in + response. + + If a Subscription cannot be created because there are no available + bidirectional streams or any other reason, the Publisher sends a + PUBLISH_SKIPPED message on the SUBSCRIBE_TRACKS response stream to + indicate the Full Track Name of the Subscription that was not + created. The Publisher MUST NOT send a PUBLISH for a Track for a + given SUBSCRIBE_TRACKS after PUBLISH_SKIPPED has been sent, scoped to + a single PUBLISH. If, for example, the publisher disconnects from a + + + +Nandakumar, et al. Expires 4 March 2027 [Page 48] + +Internet-Draft moq-transport August 2026 + + + relay and later reconnects and sends a new PUBLISH, the relay MAY + send the new PUBLISH downstream. If desired, the subscriber can + issue a SUBSCRIBE to establish a subscription to that track. + + The receiver of a REQUEST_OK or REQUEST_ERROR ought to forward the + result to the application, so the application can decide which other + publishers to contact, if any. + + A SUBSCRIBE_NAMESPACE or SUBSCRIBE_TRACKS is cancelled as described + in Section 3.3.3, by resetting or sending STOP_SENDING on the stream. + Cancelling SUBSCRIBE_TRACKS does not prohibit original publishers + from sending further PUBLISH messages, but relays MUST NOT send any + further PUBLISH messages to a client without knowing the client is + interested in and authorized to receive the content. + +6.2. Publishing Namespaces + + A publisher MAY send PUBLISH_NAMESPACE messages to any subscriber. A + PUBLISH_NAMESPACE indicates to the subscriber that the publisher has + tracks available in that namespace. A subscriber MAY send SUBSCRIBE + or FETCH for tracks in a namespace without having received a + PUBLISH_NAMESPACE for it. + + If a publisher is the Original Publisher for one or more tracks in a + given namespace, or is a relay that has received an authorized + PUBLISH_NAMESPACE for that namespace from an upstream publisher, it + MUST send a NAMESPACE message that includes this namespace to any + subscriber that has sent a SUBSCRIBE_NAMESPACE whose prefix matches + this namespace. + + A subscriber can receive a PUBLISH_NAMESPACE on a request stream for + a namespace that falls within an active SUBSCRIBE_NAMESPACE prefix. + This occurs when SUBSCRIBE_NAMESPACE or its response is in flight at + the same time as a PUBLISH_NAMESPACE, or when an original publisher + sends PUBLISH_NAMESPACE to advertise namespaces within the prefix + being discovered. Such a PUBLISH_NAMESPACE is valid and MAY carry an + AUTHORIZATION TOKEN parameter. Its lifetime is independent of the + SUBSCRIBE_NAMESPACE stream. + + An endpoint SHOULD report the reception of a REQUEST_OK or + REQUEST_ERROR to the application to inform the search for additional + subscribers for a namespace, or to abandon the attempt to publish + under this namespace. A subscriber MUST send exactly one REQUEST_OK + or REQUEST_ERROR as the first message on the bidi stream in response + to a PUBLISH_NAMESPACE. The publisher SHOULD close the session with + a protocol error if it receives more than one. + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 49] + +Internet-Draft moq-transport August 2026 + + + A PUBLISH_NAMESPACE is withdrawn by cancelling the request (see + Section 3.3.3), although it is not a protocol error for the + subscriber to send a SUBSCRIBE or FETCH message for a track in a + namespace after the namespace is withdrawn. + + A subscriber can cancel the request (see Section 3.3.3) to revoke + acceptance of a PUBLISH_NAMESPACE. If the reason for cancellation is + expiration of authorization credentials, the publisher can send + PUBLISH_NAMESPACE again on a new bidi stream with refreshed + authorization, or close the stream and discard associated state. + + While PUBLISH_NAMESPACE indicates to relays how to connect publishers + and subscribers, it is not a full-fledged routing protocol and does + not protect against loops and other phenomena. In particular, + PUBLISH_NAMESPACE SHOULD NOT be used to find paths through richly + connected networks of relays. + + A subscriber MAY send a SUBSCRIBE or FETCH for a track to any + publisher. If it has accepted a PUBLISH_NAMESPACE with a namespace + that exactly matches the namespace for that track, it SHOULD only + request it from the senders of those PUBLISH_NAMESPACE messages. + +6.3. Filtering SUBSCRIBE_TRACKS + + Range Filters Section 5.1.4 can be used in SUBSCRIBE_TRACKS to filter + Tracks in a namespace using the Track Property Filter. Objects + published in the resulting Subscriptions can be filtered by any Range + Filter. + +6.3.1. Relay Resource Protection in Large Namespaces + + Relays SHOULD aggregate and propagate filters upstream on + subscriptions, especially namespace subscriptions, to conserve and + protect their resources from excessive load. They MAY also impose + limits on the number of publishers in a namespace, by rejecting or + closing namespace subscriptions with the error NAMESPACE_TOO_LARGE, + or CONFLICTING_FILTERS if too many disjoint filters are requested on + downstream subscriptions across a large number of subscribers, or + PREFIX_OVERLAP if different subscribers force an aggregated upstream + subscription to overlap. + +7. Priorities + + MOQT priorities allow a subscriber and original publisher to + influence the transmission order of Objects within a session in the + presence of congestion. + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 50] + +Internet-Draft moq-transport August 2026 + + +7.1. Definitions + + MOQT maintains priorities between different schedulable objects. A + schedulable object in MOQT is either: + + 1. The first or next Object in a Subgroup that is in response to a + subscription. + + 2. An Object with forwarding preference Datagram. + + 3. An Object in response to a FETCH where that Object is the next + Object in the response. + + An Object is not schedulable if it is known that no part of it can be + written due to underlying transport flow control limits. + + A single subgroup or datagram has a single publisher priority. + Within a subscription, it can be useful to conceptualize this process + as scheduling subgroups or datagrams instead of individual objects on + them. FETCH responses however can contain objects with different + publisher priorities. + + A priority numberis an unsigned integer with a value between 0 and + 255. A lower priority number indicates higher priority; the highest + priority is 0. + + Subscriber Priority is a priority number associated with an + individual request. It is carried in the SUBSCRIBER_PRIORITY + parameter (Section 10.2.7), and can be updated. The subscriber + priority of an individual schedulable object is the subscriber + priority of the request that caused that object to be sent. When + subscriber priority is changed, a best effort SHOULD be made to apply + the change to all objects that have not been scheduled, but it is + implementation dependent what happens to objects that have already + been scheduled. + + Publisher Priority is a priority number associated with an individual + schedulable object. A default for the subscription is specified in + the DEFAULT_PUBLISHER_PRIORITY Track Property (Section 12.4). + Publisher priority can also be set per subgroup or datagram in the + subgroup header or datagram (see Section 11), which overrides the + default. + + Group Order is a property of an individual subscription. It can be + either 'Ascending' (groups with lower group ID are sent first), or + 'Descending' (groups with higher group ID are sent first). The + subscriber optionally communicates its group order preference in the + SUBSCRIBE or SUBSCRIBE_TRACKS message; the publisher's preference, + + + +Nandakumar, et al. Expires 4 March 2027 [Page 51] + +Internet-Draft moq-transport August 2026 + + + carried in the DEFAULT_PUBLISHER_GROUP_ORDER Track Property + (Section 12.5), is used if the subscriber did not express one (by + omitting the Group Order parameter). The group order of an existing + subscription cannot be changed. + +7.2. Scheduling Algorithm + + When an MOQT publisher has multiple schedulable objects it can choose + between, the objects SHOULD be selected as follows: + + 1. If two objects have different subscriber priorities associated + with them, the one with *the highest subscriber priority* is + scheduled to be sent first. + + 2. If two objects have the same subscriber priority, but different + publisher priorities, the one with *the highest publisher + priority* is scheduled to be sent first. + + 3. If two objects in the same subscription have the same subscriber + and publisher priority, but belong to two different groups of the + same track, *the group order* of the subscription is used to + decide the one that is scheduled to be sent first. When a + subscription fill's Group Order differs from the subscription's + Group Order, the subscription-delivered object is scheduled + first. + + 4. If two objects in the same subscription have the same subscriber + and publisher priority and belong to the same group of the same + track, and one is delivered by the fill fetch stream while the + other is subscription-delivered, the fill-delivered object is + scheduled first. Otherwise, the one with *the lowest Subgroup + ID* (for objects with forwarding preference Subgroup), or *the + lowest Object ID* (for objects with forwarding preference + Datagram) is scheduled to be sent first. If the two objects have + different Forwarding Preferences the datagram is sent first. + + Within the same group, fill-delivered objects win the tie-break over + subscription-delivered objects (rule 4) because objects with smaller + Locations are assumed to be needed before those with larger + Locations. + + The definition of "scheduled to be sent first" in the algorithm is + implementation dependent and is constrained by the prioritization + interface of the underlying transport. For some implementations, it + could mean that the object is serialized and passed to the underlying + transport first. Other implementations can control the order packets + are initially transmitted. + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 52] + +Internet-Draft moq-transport August 2026 + + + This algorithm does not provide a well-defined ordering for objects + that belong to different subscriptions or FETCH responses, but have + the same subscriber and publisher priority. The ordering in those + cases is implementation-defined, though the expectation is that all + subscriptions will be able to send some data. + + A publisher might not utilize the entire available congestion window, + session flow control, or all available streams for lower priority + Objects if it expects higher priority Objects will be available to + send in the near future or it wants to reserve some bandwidth for + control messages. + + Given the critical nature of control messages and their relatively + small size, the control streams SHOULD be prioritized highest, + followed by the bidi request streams and then all Objects. Bidi + request streams MAY be prioritized within themselves by Subscriber + Priority if specified. + +7.3. Considerations for Setting Priorities + + For downstream subscriptions, relays SHOULD respect the subscriber + and original publisher's priorities. Relays can receive + subscriptions with conflicting subscriber priorities or Group Order + preferences. Relays SHOULD NOT directly use Subscriber Priority or + Group Order from incoming subscriptions for upstream subscriptions. + A Relay's use of these fields for upstream subscriptions can be based + on factors specific to it, such as the popularity of the content or + policy, or relays can specify the same value for all upstream + subscriptions. + + MOQT Sessions can span multiple namespaces, and priorities might not + be coordinated across namespaces. The subscriber's priority is + considered first, so there is a mechanism for a subscriber to fix + incompatibilities between different namespaces prioritization + schemes. Additionally, it is anticipated that when multiple + namespaces are present within a session, the namespaces could be + coordinating, possibly part of the same application. In cases when + pooling among namespaces is expected to cause issues, multiple MOQT + sessions, either within a single connection or on multiple + connections can be used. + + Implementations that have a default priority SHOULD set it to a value + in the middle of the range (eg: 128) to allow non-default priorities + to be set either higher or lower. + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 53] + +Internet-Draft moq-transport August 2026 + + +8. Delivery Timeouts and Data Reliability + + Each MOQT subscription has two timeout values associated with it: a + SUBGROUP_DELIVERY_TIMEOUT and an OBJECT_DELIVERY_TIMEOUT. Both of + those values are expressed in milliseconds and both are optional; a + value of 0 means that there is no timeout set. + + The publisher communicates both timeout values as a Track Property; + the subscriber communicates them as Message Parameters. Either + timeout value can also be set as an Object Property on the first + object in a subgroup, overriding the Track-level value for that + subgroup. If either timeout is set as an Object Property on any + object other than the first in a subgroup, it is ignored. For each + type of timeout, the publisher's value is the Object Property when + present on the first object of the subgroup, and the Track Property + otherwise. If both the publisher's value and the subscriber's value + are non-zero, the smaller of the two is used. + + If the OBJECT_DELIVERY_TIMEOUT is not zero, the MOQT implementation + MUST retain the time at which the last header byte of every object + has been either received from the upstream subscription, or provided + by the original publisher application. The actual mechanism by which + the timeout works depends on the Object Forwarding Preference: + + * For subgroups, the implementation MUST check the time elapsed + before attempting to pass it to the underlying transport for + transmission; if the time elapsed exceeds OBJECT_DELIVERY_TIMEOUT, + it MUST reset the underlying transport stream with the reset + stream code DELIVERY_TIMEOUT (see Section 11.4.3) and SHOULD NOT + attempt to open a new stream to deliver additional Objects in that + Subgroup. The implementation SHOULD check object delivery + timeouts before retransmitting object data if the underlying + transport implementation allows. The implementations SHOULD + minimize the amount of data buffered at the underlying transport + layer, as any data buffered at this layer can no longer be timed + out, potentially leading to transmission of expired data. + + * For datagrams, the implementation MUST drop the datagrams if the + time elapsed exceeds OBJECT_DELIVERY_TIMEOUT. Similar to + subgroups, implementations SHOULD either minimize datagram + queueing, or use datagram queueing mechanisms that support time + bounds (such as the outgoingMaxAge parameter in the W3C + WebTransport API). + + If the Object Forwarding Preference is Subgroup and the value of + SUBGROUP_DELIVERY_TIMEOUT is not zero, the MOQT implementation MUST + start a timer of SUBGROUP_DELIVERY_TIMEOUT duration once it becomes + aware that all of the objects on the subgroup have been published + + + +Nandakumar, et al. Expires 4 March 2027 [Page 54] + +Internet-Draft moq-transport August 2026 + + + (either by receiving a FIN from the upstream subscription, or, in + case of the original publisher, through being notified of this fact + by the application). If the timer expires before the underlying + transport stream reaches "all data committed" state + ([I-D.ietf-webtrans-overview], Section 4.3), the implementation MUST + reset the stream. This ensures that MOQT can time out subgroups + where all of the data has been sent but not yet fully delivered due + to packet loss. + + For objects whose Object Forwarding Preference is Datagram, the + SUBGROUP_DELIVERY_TIMEOUT acts the same way as + OBJECT_DELIVERY_TIMEOUT; if both are non-zero, the smaller of the two + is used. + + +=========+===========================+===========================+ + | | SUBGROUP_DELIVERY_TIMEOUT | OBJECT_DELIVERY_TIMEOUT | + +=========+===========================+===========================+ + | Timeout | When the FIN for the | When the last byte of the | + | starts | subgroup is received | object header is received | + +---------+---------------------------+---------------------------+ + | Timeout | Via a timer until all | When the object is sent | + | checked | data is acknowledged | to the underlying | + | at | | transport | + +---------+---------------------------+---------------------------+ + | Action | Reset for subgroups, drop | Reset for subgroups, drop | + | upon | for datagrams | for datagrams | + | timeout | | | + +---------+---------------------------+---------------------------+ + + Table 4: Comparison of the delivery timeout mechanisms + + Publishers can, at their discretion, discontinue forwarding Objects + before either timeout occurs, subject to stream closure and ordering + constraints described in Section 11.4.3. However, if neither timeout + is set to a non-zero value, all Objects in the track matching the + subscription filter are delivered as indicated by their Group Order + and Priority. If a subscriber fails to consume Objects at a + sufficient rate, causing the publisher to exceed its resource limits, + the publisher MAY terminate the subscription using PUBLISH_DONE with + error TOO_FAR_BEHIND. + +9. Relays + + Relays are leveraged to enable distribution scale in the MOQT + architecture. Relays can be used to form an overlay delivery + network, similar in functionality to Content Delivery Networks + (CDNs). Additionally, relays serve as policy enforcement points by + validating subscribe and publish requests at the edge of a network. + + + +Nandakumar, et al. Expires 4 March 2027 [Page 55] + +Internet-Draft moq-transport August 2026 + + + Relays are endpoints, which means they terminate Transport Sessions + in order to have visibility of MOQT Object metadata. + +9.1. Caching Relays + + Relays MAY cache Objects, but are not required to. + + A caching relay saves Objects to its cache identified by the Object's + Full Track Name, Group ID and Object ID. If multiple objects are + received with the same Full Track Name, Group ID and Object ID, + Relays MAY ignore subsequently received Objects or MAY use them to + update certain cached fields. Implementations that update the cache + need to protect against cache poisoning. The only Object fields that + can be updated are the following: + + 1. Object can transition from existing to not existing in cases + where the object is no longer available. + + 2. Object Properties can be added, removed or updated, subject to + the constraints of the specific property. + + An endpoint that receives a duplicate Object with a different + Forwarding Preference, Subgroup ID, Priority or Payload MUST treat + the track as Malformed. + + For ranges of objects that do not exist, relays MAY change the + representation of a missing range to a semantically equivalent one. + For instance, a relay may change an End-of-Group="Y" Subgroup Header + to an equivalent object with an End of Group status, or a Prior Group + ID Gap property could be removed in FETCH, where it's redundant. + + As described in Section 2.1, an endpoint can receive an Object after + it has already recorded that the Object does not exist. A caching + relay SHOULD NOT cache or forward the Object in this case. + + A cache MUST store all fields of an Object defined in Section 11.2.1, + with the exception of any Object Properties (Section 11.2.1.2) that + specify otherwise. + +9.2. Forward Handling + + If one or more downstream subscribers to a track have Forward=1, the + relay MUST set Forward=1 upstream in order to receive and forward the + requested Objects. When no downstream subscriber has Forward=1, the + relay chooses the upstream Forward value at its discretion, + considering the following tradeoffs and deployment considerations: + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 56] + +Internet-Draft moq-transport August 2026 + + + * Setting Forward=1 upstream starts object delivery and pre-warms + the relay's cache, so objects are available when a downstream + subscriber sets Forward=1. This reduces latency but consumes + upstream and publisher resources for content no downstream + subscriber is currently receiving. + + * Setting Forward=0 upstream avoids that work, at the cost of higher + latency when forwarding is later enabled. + +9.3. Multiple Publishers + + A Relay can receive PUBLISH_NAMESPACE for the same Track Namespace or + PUBLISH messages for the same Track from multiple publishers. The + following sections explain how Relays maintain subscriptions to all + available publishers for a given Track. + + There is no specified limit to the number of publishers of a Track + Namespace or Track. An implementation can use mechanisms such as + REQUEST_ERROR or unsubscribing (see Section 3.3.3) if it cannot + accept an additional publisher due to implementation constraints. + Implementations can consider the establishment or idle time of the + session or subscription to determine which publisher to reject or + disconnect. + + Relays MUST handle Objects for the same Track from multiple + publishers and forward them to matching Established subscriptions. + The Relay SHOULD attempt to deduplicate Objects before forwarding, + subject to implementation constraints. + +9.4. Subscriber Interactions + + Subscribers request Tracks by sending a SUBSCRIBE (see Section 10.7) + or FETCH (see Section 10.13) control message for each Track of + interest. Relays MUST ensure subscribers are authorized to access + the content associated with the Track. The authorization information + can be part of request itself or part of the encompassing session. + The specifics of how a relay authorizes a user are outside the scope + of this specification. + + The relay MUST have an Established upstream subscription before + sending SUBSCRIBE_OK in response to a downstream SUBSCRIBE. If a + relay does not have sufficient information to send a FETCH_OK + immediately in response to a FETCH, it MUST withhold sending FETCH_OK + until it does. Relays MUST follow the constraints on LARGEST_OBJECT + defined in Section 10.2.17. + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 57] + +Internet-Draft moq-transport August 2026 + + + Publishers maintain a list of Established downstream subscriptions + for each Track. Relays use the Track Alias (Section 11.1) of an + incoming Object to identify its Track and find the current + subscribers. Each new Object belonging to the Track is forwarded to + each subscriber, as allowed by the subscription's filter (see + Section 10.7), and delivered according to the priority (see + Section 7) and delivery timeout (see Section 8). + + A relay MUST NOT reorder or drop objects received on a multi-object + stream when forwarding to subscribers. + + Relays MAY aggregate authorized subscriptions for a given Track when + multiple subscribers request the same Track. Subscription + aggregation allows relays to make only a single upstream subscription + for the Track. The published content received from the upstream + subscription request is cached and shared among the pending + subscribers. Relays that aggregate subscriptions MAY combine filters + from downstream subscribers on the upstream subscription, up to the + peer's MAX_FILTER_RANGES. If adding filters to an upstream + subscription is not possible, the relay can either remove some or all + filters, or make additional subscriptions to the same Track. + Multiple subscriptions to the same Track with non-disjoint filter + sets will result in duplicate objects arriving at the relay. Using + wider upstream filters can protect the relay from churn as + subscribers with disparate filters subscribe and unsubscribe from a + Track, at the cost of receiving more objects. + + A subscriber remains subscribed to a Track at a Relay until it + unsubscribes, the upstream publisher terminates the subscription, or + the subscription expires (see Section 10.8). A subscription with a + filter can reach a state where all possible Objects matching the + filter have been delivered to the subscriber. Since tracking this + can be prohibitively expensive, Relays are not required or expected + to do so. + +9.4.1. Graceful Subscriber Relay Switchover + + This section describes a behavior that a Subscriber MAY implement to + improve user experience when a relay sends a GOAWAY or the Subscriber + switches between networks, such as WiFi to Cellular, and QUIC + Connection Migration is not possible. + + When a subscriber receives the GOAWAY message, it starts the process + of connecting to a new relay and sending the SUBSCRIBE requests for + all Established subscriptions to the new relay. The new relay will + send a response to the subscribes and if they are successful, the + subscriptions to the old relay can be cancelled (see Section 3.3.3). + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 58] + +Internet-Draft moq-transport August 2026 + + +9.5. Publisher Interactions + + There are two ways to publish through a relay: + + 1. Send a PUBLISH message for a specific Track to the relay. The + relay MAY pause the Subscription with REQUEST_UPDATE in Forward + State=0 until there are known subscribers for new Tracks. + + 2. Send a PUBLISH_NAMESPACE message for a Track Namespace to the + relay. This enables the relay to send SUBSCRIBE or FETCH + messages to publishers for Tracks in this Namespace in response + to requests received from subscribers. + + Relays MUST verify that publishers are authorized to publish the set + of Tracks whose Track Namespace matches the namespace in a + PUBLISH_NAMESPACE, or the Full Track Name in PUBLISH. Relays MUST + NOT assume that an authorized publisher of a single Track is + implicitly authorized to publish any other Tracks or Track + Namespaces. If a Publisher would like Subscriptions in a Namespace + routed to it, it MUST send an explicit PUBLISH_NAMESPACE. The + authorization and identification of the publisher depends on the way + the relay is managed and is application specific. + + When a publisher wants to stop new subscriptions for a published + namespace, it cancels the request (see Section 3.3.3) to withdraw the + PUBLISH_NAMESPACE. A subscriber indicates it will no longer + subscribe to Tracks in a namespace it previously responded + PUBLISH_NAMESPACE_OK to by cancelling the PUBLISH_NAMESPACE request. + + A Relay connects publishers and subscribers by managing sessions + based on the Track Namespace or Full Track Name. When a SUBSCRIBE + message is sent, its Full Track Name is matched exactly against + existing upstream subscriptions. + + Namespace Prefix Matching is further used to decide which publishers + receive a SUBSCRIBE and which subscribers receive a PUBLISH. In this + process, the fields in the Track Namespace are matched sequentially, + requiring an exact match for each field. If the published or + subscribed Track Namespace has the same or fewer fields than the + Track Namespace in the message, it qualifies as a match. + + For example: A SUBSCRIBE message with namespace=(foo, bar) and name=x + will match sessions that sent PUBLISH_NAMESPACE messages with + namespace=(foo) or namespace=(foo, bar). It will not match a session + with namespace=(foobar). + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 59] + +Internet-Draft moq-transport August 2026 + + + Relays MUST send SUBSCRIBE messages to all matching publishers. This + includes matching both Established subscriptions on the Full Track + Name and Namespace Prefix Matching against published Namespaces. + Relays MUST forward PUBLISH_NAMESPACE or PUBLISH messages to all + matching subscribers. + + When a Relay needs to make an upstream FETCH request, it determines + the available publishers using the same matching rules as SUBSCRIBE. + When more than one publisher is available, the Relay MUST send the + FETCH to at least one of them. + + When a Relay receives a SUBSCRIBE with FILL_PARAMETERS, it serves the + fill range from its cache and retrieves any missing objects upstream + using a SUBSCRIBE with FILL_PARAMETERS or FETCHes (see + Section 5.1.3). + + When a Relay receives an authorized SUBSCRIBE for a Track with one or + more Established upstream subscriptions, it MUST reply with + SUBSCRIBE_OK. If the SUBSCRIBE has Forward State=1 and the upstream + subscriptions are in Forward State=0, the Relay MUST send + REQUEST_UPDATE with Forward=1 to all publishers. If there are no + Established upstream subscriptions for the requested Track, the Relay + MUST send a SUBSCRIBE request to each publisher that has published + the subscription's namespace or prefix thereof. If the SUBSCRIBE has + Forward=1, then the Relay MUST use Forward=1 when subscribing + upstream. + + When a relay receives an incoming PUBLISH message, it MUST send a + PUBLISH request to each subscriber that has sent SUBSCRIBE_TRACKS for + the Track's namespace or a prefix thereof. However, if the relay is + holding a downstream SUBSCRIBE awaiting a publisher for this Track + (see Section 10.2.6), it MUST proceed with the SUBSCRIBE and MUST NOT + also forward the PUBLISH to that subscriber. + + When a relay receives an authorized PUBLISH_NAMESPACE for a namespace + that matches one or more existing subscriptions to other upstream + sessions, it MUST send a SUBSCRIBE to the publisher that sent the + PUBLISH_NAMESPACE for each matching subscription. When it receives + an authorized PUBLISH message for a Track that has Established + downstream subscriptions, it MUST respond with PUBLISH_OK. If at + least one downstream subscriber for the Track has Forward State=1, + the Relay MUST change the Forward State to 1 with REQUEST_UPDATE. + + If a Session is closed due to an unknown or invalid control message + or Object, the Relay MUST NOT propagate that message or Object to + another Session, because it would enable a single Session error to + force an unrelated Session, which might be handling other + subscriptions, to be closed. + + + +Nandakumar, et al. Expires 4 March 2027 [Page 60] + +Internet-Draft moq-transport August 2026 + + +9.5.1. Graceful Publisher Relay Switchover + + This section describes a behavior that a publisher MAY implement to + improve user experience when a relay sends a GOAWAY or the publisher + switches between networks, such as WiFi to Cellular, and QUIC + Connection Migration is not possible. + + A new Session is established, to a new URI if specified in a GOAWAY. + The publisher sends PUBLISH_NAMESPACE and/or PUBLISH messages to + begin publishing on the new Session, but it does not immediately stop + publishing Objects on the old Session. + + Once the subscriptions have migrated over to the new session, the + publisher can stop publishing Objects on the old session. The relay + will attempt to deduplicate Objects received on both subscriptions. + Ideally, the subscriptions downstream from the relay do not observe + this change, and keep receiving the Objects on the same subscription. + +9.6. Relay Track Handling + + A relay MUST include all Properties associated with a Track when + sending any PUBLISH, SUBSCRIBE_OK, TRACK_STATUS_OK, or FETCH_OK, + unless allowed by the property's specification (see Section 2.5). + +9.7. Relay Object Handling + + MOQT encodes the delivery information in the Object header + (Section 11.2.1). A relay MUST NOT modify Object fields when + forwarding, except for Object Properties as specified in Section 2.5. + + A relay MUST treat the object payload as opaque. A relay MUST NOT + combine, split, or otherwise modify object payloads. + + Relays prioritize forwarded Objects as described in Section 7. + +10. Control Messages + + MOQT uses a pair of unidirectional streams to exchange control + messages, as defined in Section 3.3. Every message on a control or + request stream is formatted as follows: + + MOQT Control Message { + Message Type (vi64), + Message Length (16), + Message Body (..), + } + + Figure 3: MOQT Control Message + + + +Nandakumar, et al. Expires 4 March 2027 [Page 61] + +Internet-Draft moq-transport August 2026 + + + The following Message Types are defined. The Stream column indicates + which stream type each message is sent on: Control indicates the + control stream (Section 3.3), and Request indicates a bidirectional + request stream. Messages marked "First" MUST be the first message on + a new request stream. + + +========+======================================+==================+ + | ID | Messages | Stream | + +========+======================================+==================+ + | 0x01 | RESERVED (SETUP for version 00) | | + +--------+--------------------------------------+------------------+ + | 0x40 | RESERVED (CLIENT_SETUP for <= 10) | | + +--------+--------------------------------------+------------------+ + | 0x41 | RESERVED (SERVER_SETUP for <= 10) | | + +--------+--------------------------------------+------------------+ + | 0x20 | RESERVED (CLIENT_SETUP in <= 16) | | + +--------+--------------------------------------+------------------+ + | 0x21 | RESERVED (SERVER_SETUP in <= 16) | | + +--------+--------------------------------------+------------------+ + | 0x2F00 | SETUP (Section 10.3) | Control | + +--------+--------------------------------------+------------------+ + | 0x10 | GOAWAY (Section 10.4) | Control, Request | + +--------+--------------------------------------+------------------+ + | 0x3 | SUBSCRIBE (Section 10.7) | Request, First | + +--------+--------------------------------------+------------------+ + | 0x4 | SUBSCRIBE_OK (Section 10.8) | Request | + +--------+--------------------------------------+------------------+ + | 0x22 | PUBLISH_STATE_NOTIFY (Section 10.10) | Request | + +--------+--------------------------------------+------------------+ + | 0x1D | PUBLISH (Section 10.11) | Request, First | + +--------+--------------------------------------+------------------+ + | 0x1E | RESERVED (PUBLISH_OK in <= 17) | Request | + +--------+--------------------------------------+------------------+ + | 0xB | PUBLISH_DONE (Section 10.12) | Request | + +--------+--------------------------------------+------------------+ + | 0x16 | FETCH (Section 10.13) | Request, First | + +--------+--------------------------------------+------------------+ + | 0x18 | FETCH_OK (Section 10.14) | Request | + +--------+--------------------------------------+------------------+ + | 0xD | TRACK_STATUS (Section 10.15) | Request, First | + +--------+--------------------------------------+------------------+ + | 0x6 | PUBLISH_NAMESPACE (Section 10.16) | Request, First | + +--------+--------------------------------------+------------------+ + | 0x50 | SUBSCRIBE_NAMESPACE (Section 10.19) | Request, First | + +--------+--------------------------------------+------------------+ + | 0x51 | SUBSCRIBE_TRACKS (Section 10.20) | Request, First | + +--------+--------------------------------------+------------------+ + | 0x8 | NAMESPACE (Section 10.17) | Request | + + + +Nandakumar, et al. Expires 4 March 2027 [Page 62] + +Internet-Draft moq-transport August 2026 + + + +--------+--------------------------------------+------------------+ + | 0xE | NAMESPACE_DONE (Section 10.18) | Request | + +--------+--------------------------------------+------------------+ + | 0xF | PUBLISH_SKIPPED (Section 10.21) | Request | + +--------+--------------------------------------+------------------+ + | 0x2 | REQUEST_UPDATE (Section 10.9) | Request | + +--------+--------------------------------------+------------------+ + | 0x7 | REQUEST_OK (Section 10.5) | Request | + +--------+--------------------------------------+------------------+ + | 0x5 | REQUEST_ERROR (Section 10.6) | Request | + +--------+--------------------------------------+------------------+ + + Table 5 + + An endpoint that receives an unknown message type MUST close the + session. Control messages have a length to simplify parsing, but no + control messages are intended to be ignored. The length is set to + the number of bytes in the Message Body, which is defined by each + message type. If the length does not match the length of the Message + Body, the receiver MUST close the session with a PROTOCOL_VIOLATION. + +10.1. Request ID + + Request ID is included in request messages and is used to identify + requests across messages. For example, fetch streams reference the + Request ID of a SUBSCRIBE, PUBLISH, FETCH, or REQUEST_UPDATE. + + The client generates even numbered Request IDs, starting at 0, and + the server generates odd numbered Request IDs, starting at 1. Each + endpoint increments its Request ID by 2 for each new request. + + Each SUBSCRIBE, PUBLISH, FETCH, SUBSCRIBE_NAMESPACE, + SUBSCRIBE_TRACKS, PUBLISH_NAMESPACE, REQUEST_UPDATE, and TRACK_STATUS + message consumes a Request ID. Only request messages include a + Request ID; response messages do not, since they are sent on the same + bidirectional stream as the request. + + If an endpoint receives a Request ID where the least significant bit + is incorrect for the sender, or a duplicate Request ID, it MUST close + the session with INVALID_REQUEST_ID. + +10.2. Message Parameters + + Some control messages include a field that encodes optional Message + Parameters. Message Parameters are serialized as follows: + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 63] + +Internet-Draft moq-transport August 2026 + + + Message Parameter { + Type Delta (vi64), + Value (..) + } + + Figure 4: Message Parameter + + Type Delta: The difference between this Parameter Type and the + previous Parameter Type in the message, or the Parameter Type itself + for the first parameter. Parameters MUST be serialized in ascending + order by Type. If the resulting Type would be greater than 2^64 - 1, + the endpoint MUST close the session with a PROTOCOL_VIOLATION. + + * Value: The encoding is specified by each parameter definition. + The encodings defined in this draft are: + + - uint8: A single-byte unsigned integer (0-255) + + - varint: A variable-length integer + + - Location: Two consecutive varints (Group, Object) + + - Length-prefixed: A varint length followed by that many bytes + + Message Parameters are intended for the peer only and are not + forwarded by Relays, though relays can consider received parameter + values when making a request. + + All Message Parameters MUST be defined in the negotiated version of + MOQT or negotiated via Setup Options. An endpoint that receives an + unknown Message Parameter MUST close the session with + PROTOCOL_VIOLATION. Because the receiver has to understand every + Message Parameter, there is no need for a mechanism to skip unknown + parameters. Because unknown parameters cannot be skipped, the block + is bounded by a parameter count rather than a length. + + The Message Parameter types defined in this version of MOQT are + defined in the following subsections. + + Senders MUST NOT repeat the same Parameter Type in a message unless + the parameter definition explicitly allows multiple instances of that + type to be sent in a single message. Receivers SHOULD check that + there are no unexpected duplicate parameters and close the session + with PROTOCOL_VIOLATION if found. + + The number of Message Parameters is not specifically limited, but the + total length of a control message is limited to 2^16-1 bytes. + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 64] + +Internet-Draft moq-transport August 2026 + + + Message Parameters in SUBSCRIBE and FETCH MUST NOT cause the + publisher to alter the payload of the objects it sends, as that would + violate the track uniqueness guarantee described in Section 2.4.3. + +10.2.1. Parameter Scope + + Message Parameters are always intended for the peer endpoint only and + are not forwarded by Relays, though relays can consider received + parameter values when making a request. Track information not + specific to the Message or Session is encoded in Track Properties. + See Section 2.5. + + Each Message Parameter definition indicates the message types in + which it can appear. If it appears in some other type of message, + the receiving endpoint MUST close the connection with a + PROTOCOL_VIOLATION. Note that since Setup Options use a separate + namespace, it is impossible for Message Parameters to appear in Setup + messages. + +10.2.2. AUTHORIZATION TOKEN Parameter + + The AUTHORIZATION TOKEN parameter (Parameter Type 0x03) uses Length- + prefixed encoding. It MAY appear in a PUBLISH, SUBSCRIBE, + REQUEST_UPDATE, SUBSCRIBE_NAMESPACE, SUBSCRIBE_TRACKS, + PUBLISH_NAMESPACE, TRACK_STATUS or FETCH message. This parameter + conveys information to authorize the sender to perform the operation + carrying the parameter. This Parameter MUST NOT be copied from a + SUBSCRIBE_TRACKS to the resulting PUBLISH message Parameters. + + The parameter value is a Token structure containing an optional + Session-specific Alias. The Alias allows the sender to reference a + previously transmitted Token Type and Token Value in future messages. + The Token structure is serialized as follows: + + Token { + Alias Type (vi64), + [Token Alias (vi64),] + [Token Type (vi64),] + [Token Value (..)] + } + + Figure 5: Token structure + + * Alias Type - an integer defining both the serialization and the + processing behavior of the receiver. This Alias type has the + following code points: + + DELETE (0x0): There is an Alias but no Type or Value. This Alias + + + +Nandakumar, et al. Expires 4 March 2027 [Page 65] + +Internet-Draft moq-transport August 2026 + + + and the Token Value it was previously associated with MUST be + retired. Retiring removes them from the pool of actively + registered tokens. + + REGISTER (0x1): There is an Alias, a Type and a Value. This Alias + MUST be associated with the Token Value for the duration of the + Session or it is deleted. This action is termed "registering" the + Token. + + USE_ALIAS (0x2): There is an Alias but no Type or Value. Use the + Token Type and Value previously registered with this Alias. + + USE_VALUE (0x3): There is no Alias and there is a Type and Value. + Use the Token Value as provided. The Token Value MAY be discarded + after processing. + + If a server receives Alias Type DELETE (0x0) or USE_ALIAS (0x2) in a + SETUP message, it MUST close the session with a PROTOCOL_VIOLATION. + + * Token Alias - a Session-specific integer identifier that + references a Token Type and Token Value. There are separate Alias + spaces for the client and server (e.g.: they can each register + Alias=1). Once a Token Alias has been registered, it cannot be + re-registered by the same endpoint in the Session without first + being deleted. Use of the Token Alias is optional. + + * Token Type - a numeric identifier for the type of Token payload + being transmitted. This type is defined by the IANA table "MOQT + Auth Token Type" (see Section 15). Type 0 is reserved to indicate + that the type is not defined in the table and is negotiated out- + of-band between client and receiver. + + * Token Value - the payload of the Token. The contents and + serialization of this payload are defined by the Token Type. + + If the Token structure cannot be decoded, the receiver MUST close the + Session with KEY_VALUE_FORMATTING_ERROR. The receiver of a message + attempting to register an Alias which is already registered MUST + close the Session with DUPLICATE_AUTH_TOKEN_ALIAS. The receiver of a + message referencing an Alias that is not currently registered MUST + reject the message with UNKNOWN_AUTH_TOKEN_ALIAS. + + The receiver of a message containing a well-formed Token structure + but otherwise invalid AUTHORIZATION TOKEN parameter MUST reject that + message with an MALFORMED_AUTH_TOKEN error. + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 66] + +Internet-Draft moq-transport August 2026 + + + The receiver of a message carrying an AUTHORIZATION TOKEN with Alias + Type REGISTER that does not result in a Session error MUST register + the Token Alias in the token cache, even if the message fails for + other reasons, including Unauthorized. This allows senders to + pipeline messages that refer to previously registered tokens without + potentially terminating the entire Session. A receiver MAY store an + error code (eg: UNAUTHORIZED or MALFORMED_AUTH_TOKEN) in place of the + Token Type and Token Alias if any future message referencing the + Token Alias will result in that error. However, it is important to + not store an error code for a token that might be valid in the future + or due to some other property becoming fulfilled which currently + isn't. The size of a registered cache entry includes the length of + the Token Value, regardless of whether it is stored. + + If a receiver detects that an authorization token has expired, it + MUST retain the registered Alias until it is deleted by the sender, + though it MAY discard other state associated with the token that is + no longer needed. Expiration does not affect the size occupied by a + token in the token cache. Any message that references an expired + token with Alias Type USE_ALIAS fails with EXPIRED_AUTH_TOKEN. + + Using an Alias to refer to a previously registered Token Type and + Value is for efficiency only and has the same effect as if the Token + Type and Value was included directly. Retiring an Alias that was + previously used to authorize a message has no retroactive effect on + the original authorization, nor does it prevent that same Token Type + and Value from being re-registered. + + Senders of tokens SHOULD only register tokens which they intend to + re-use during the Session and SHOULD retire previously registered + tokens once their utility has passed. + + By registering a Token, the sender is requiring the receiver to store + the Token Alias and Token Value until they are deleted, or the + Session ends. The receiver can protect its resources by sending a + Setup Option defining the MAX_AUTH_TOKEN_CACHE_SIZE limit (see + Section 10.3.1.3) it is willing to accept. If a registration is + attempted which would cause this limit to be exceeded, the receiver + MUST terminate the Session with a AUTH_TOKEN_CACHE_OVERFLOW error. + + The AUTHORIZATION TOKEN parameter MAY be repeated within a message as + long as the combination of Token Type and Token Value are unique + after resolving any aliases. + + Messages carrying the AUTHORIZATION TOKEN parameter can appear on + different control streams. Because stream processing order can be + different than send order, the receiver and sender can have + inconsistent views of the token cache state. + + + +Nandakumar, et al. Expires 4 March 2027 [Page 67] + +Internet-Draft moq-transport August 2026 + + + Senders MUST NOT send USE_ALIAS on one control stream for an alias + registered on a different stream until the sender has received a + response to the message containing the REGISTER. Senders MAY use + USE_ALIAS on the same control stream as the REGISTER without waiting + for a response. + + Senders MUST NOT send DELETE for an alias while any message using + USE_ALIAS with that alias has not received a response. + +10.2.3. SUBGROUP_DELIVERY_TIMEOUT Parameter + + The SUBGROUP_DELIVERY_TIMEOUT parameter (Parameter Type 0x06) is a + varint. It MAY appear in a SUBSCRIBE, PUBLISH, or REQUEST_UPDATE + message. Its semantics are defined in Section 8. + + This parameter is intended to be specific to a subscription, so it + SHOULD NOT be forwarded upstream by a relay that intends to serve + multiple subscriptions for the same track. + +10.2.4. OBJECT_DELIVERY_TIMEOUT Parameter + + The OBJECT_DELIVERY_TIMEOUT parameter (Parameter Type 0x02) is a + varint. It MAY appear in a SUBSCRIBE, PUBLISH, or REQUEST_UPDATE + message. Its semantics are defined in Section 8. + + This parameter is intended to be specific to a subscription, so it + SHOULD NOT be forwarded upstream by a relay that intends to serve + multiple subscriptions for the same track. + +10.2.5. FILL TIMEOUT Parameter + + The FILL_TIMEOUT parameter (Parameter Type 0x0A) MAY appear in a + FETCH message, or inside a FILL_PARAMETERS parameter (see + Section 10.2.15) in a SUBSCRIBE or REQUEST_UPDATE (for a + subscription), where it applies to the fill fetch stream. + + It is the maximum total duration in milliseconds a relay SHOULD spend + waiting for upstream sources to provide Objects that are not + immediately available before reporting them as Timed-Out gaps in the + FETCH response. When a relay encounters Objects within the requested + range that are not immediately available and have unknown status, it + issues upstream FETCHes to retrieve them. The Fill Timeout + represents a total budget for all such upstream FETCHes generated by + this request. If the budget is exhausted, the relay reports any + remaining unavailable Objects as Timed-Out gaps (End of Timed-Out + Range, see Section 11.4.4.2) and continues delivering available + Objects in the range. + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 68] + +Internet-Draft moq-transport August 2026 + + + A value of 0 indicates the subscriber only wants Objects that are + immediately available; the relay MUST NOT wait for upstream delivery + and MUST report any unavailable Objects as Timed-Out gaps. + + If the Fill Timeout parameter is absent, the relay waits for an + implementation specific duration before reporting Timed-Out gaps. If + the subscriber specifies a Fill Timeout larger than the relay is + willing to wait, the relay MAY use a shorter timeout without + informing the subscriber. + +10.2.6. RENDEZVOUS TIMEOUT Parameter + + The RENDEZVOUS_TIMEOUT parameter (Parameter Type 0x04) MAY appear in + a SUBSCRIBE message. + + It is the duration in milliseconds the subscriber is willing to wait + for a publisher to become available. This applies when a relay + receives a SUBSCRIBE for a Track that has no current publisher. + + If the RENDEZVOUS_TIMEOUT is present, the relay SHOULD hold the + subscription and wait for a publisher to appear, up to the specified + duration. The relay does not send SUBSCRIBE_OK until a publisher + becomes available. If a publisher becomes available within this + time, the relay proceeds with the subscription normally. If the + timeout expires without a publisher, the relay SHOULD respond with + REQUEST_ERROR with error code TIMEOUT. + + The relay MAY use a shorter timeout than requested by the subscriber. + For example, a relay might limit the maximum rendezvous timeout to + protect its resources. + + A value of 0 indicates the subscriber does not want to wait and + expects an immediate response. The relay MUST immediately return + REQUEST_ERROR with error code DOES_NOT_EXIST if no publisher is + available + + If RENDEZVOUS_TIMEOUT is absent, the default is 0. + +10.2.7. SUBSCRIBER PRIORITY Parameter + + The SUBSCRIBER_PRIORITY parameter (Parameter Type 0x20) is a uint8. + It MAY appear in a SUBSCRIBE, PUBLISH, FETCH, or REQUEST_UPDATE (for + a subscription or FETCH). It is an integer expressing the priority + of a subscription relative to other subscriptions and fetch responses + in the same session. Lower numbers get higher priority. See + Section 7. + + If omitted from SUBSCRIBE or FETCH, the publisher uses the value 128. + + + +Nandakumar, et al. Expires 4 March 2027 [Page 69] + +Internet-Draft moq-transport August 2026 + + +10.2.8. GROUP ORDER Parameter + + The GROUP_ORDER parameter (Parameter Type 0x22) is a uint8. It MAY + appear in a SUBSCRIBE, PUBLISH, SUBSCRIBE_TRACKS, or FETCH, or inside + a FILL_PARAMETERS parameter (see Section 10.2.15). + + Its value indicates how to prioritize Objects from different groups + within the same subscription (see Section 7), or how to order Groups + in a Fetch response (see Section 10.13). When it appears inside + FILL_PARAMETERS, it governs the fill fetch stream and its ordering + relative to subscription-delivered Objects (see Section 7). The + allowed values are Ascending (0x1) or Descending (0x2). If an + endpoint receives a value outside this range, it MUST close the + session with PROTOCOL_VIOLATION. + + If omitted from SUBSCRIBE or SUBSCRIBE_TRACKS, the publisher's + preference from the Track is used. If omitted from FETCH, the + receiver uses Ascending (0x1). + +10.2.9. LOCATION FILTER Parameter + + The LOCATION_FILTER parameter (Parameter Type 0x21) uses length- + prefixed encoding. It MAY appear in a FETCH, SUBSCRIBE, PUBLISH, + REQUEST_UPDATE (for a subscription) or PUBLISH_STATE_NOTIFY message. + It is a Location Filter (see Section 5.1.2). + + If omitted from FETCH or SUBSCRIBE, the fetch or subscription is + unfiltered. If omitted from REQUEST_UPDATE or PUBLISH_STATE_NOTIFY, + the value is unchanged. When sent in PUBLISH_STATE_NOTIFY, it + reports the Location Filter now in effect at the publisher. + +10.2.10. SUBGROUP FILTER Parameter + + The SUBGROUP_FILTER parameter (Type 0x25) selects objects with + specified Ranges of Subgroup ID. See Section 5.1.4. + +10.2.11. OBJECTID FILTER Parameter + + The OBJECTID_FILTER parameter (Type 0x26) selects objects with + specified Ranges of Object ID. See Section 5.1.4. + +10.2.12. PRIORITY FILTER Parameter + + The PRIORITY_FILTER parameter (Type 0x27) selects objects with + specified Ranges of Publisher Priority. See Section 5.1.4. If a + decoded value exceeds 255, the endpoint MUST reject this with + REQUEST_ERROR with error code INVALID_FILTER since Publisher Priority + is an 8-bit field. + + + +Nandakumar, et al. Expires 4 March 2027 [Page 70] + +Internet-Draft moq-transport August 2026 + + +10.2.13. OBJECT PROPERTY FILTER Parameter + + The OBJECT_PROPERTY_FILTER parameter (Type 0x28) selects objects with + required Ranges of Property Value for a required Object Property Type + which MUST be even, i.e. a single integer value (see Figure 2), + otherwise the endpoint MUST reject this with REQUEST_ERROR with error + code INVALID_FILTER. See Section 5.1.4. + +10.2.14. TRACK PROPERTY FILTER Parameter + + The TRACK_PROPERTY_FILTER parameter (Type 0x29) selects tracks with + required Ranges of Property Value for a required Track Property Type + which MUST be even, i.e. a single integer value (see Figure 2), + otherwise the endpoint MUST reject this with REQUEST_ERROR with error + code INVALID_FILTER. See Section 5.1.4. + +10.2.15. FILL PARAMETERS Parameter + + The FILL_PARAMETERS parameter (Parameter Type 0x23) uses length- + prefixed encoding. It MAY appear in a SUBSCRIBE or REQUEST_UPDATE + (for a subscription) message. Its value is a sequence of Parameters + that apply to the fill fetch stream (see Section 5.1.3), encoded as + if they were Parameters for a separate message (see Section 15.7). + Its presence is what requests a fill fetch stream; a subscription + with no FILL_PARAMETERS opens none. + + The following parameters MAY appear inside FILL_PARAMETERS: + + + + + + + + + + + + + + + + + + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 71] + +Internet-Draft moq-transport August 2026 + + + +================+========================+================+ + | Parameter Type | Parameter Name | Specification | + +================+========================+================+ + | 0x0A | FILL_TIMEOUT | Section 10.2.5 | + +----------------+------------------------+----------------+ + | 0x20 | SUBSCRIBER_PRIORITY | Section 10.2.7 | + +----------------+------------------------+----------------+ + | 0x21 | LOCATION_FILTER | Section 10.2.9 | + +----------------+------------------------+----------------+ + | 0x22 | GROUP_ORDER | Section 10.2.8 | + +----------------+------------------------+----------------+ + | 0x25 | SUBGROUP_FILTER | Section 5.1.4 | + +----------------+------------------------+----------------+ + | 0x26 | OBJECTID_FILTER | Section 5.1.4 | + +----------------+------------------------+----------------+ + | 0x27 | PRIORITY_FILTER | Section 5.1.4 | + +----------------+------------------------+----------------+ + | 0x28 | OBJECT_PROPERTY_FILTER | Section 5.1.4 | + +----------------+------------------------+----------------+ + + Table 6 + + The LOCATION_FILTER inside FILL_PARAMETERS selects the fill range and + is evaluated using the rules for a Fetch (see Section 5.1.2); it is + independent of the subscription's own Location filter. + + A parameter that is omitted from FILL_PARAMETERS takes the value it + has for the subscription; FILL_PARAMETERS therefore carries only the + settings that differ. An endpoint that receives a parameter inside + FILL_PARAMETERS that is not listed above MUST close the session with + PROTOCOL_VIOLATION. + + The value of FILL_PARAMETERS is a separate parameter scope. + Parameters inside it are not considered to appear in the enclosing + message for the purposes of Section 10.2, so a Parameter Type MAY + appear both in the message and inside FILL_PARAMETERS. + + FILL_PARAMETERS is not retained as subscription state. It applies + only to the message that carries it, so the sticky-parameter rules in + Section 10.9 do not apply to it. + + + + + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 72] + +Internet-Draft moq-transport August 2026 + + +10.2.16. EXPIRES Parameter + + The EXPIRES parameter (Parameter Type 0x8) is a varint. It MAY + appear in SUBSCRIBE_OK, PUBLISH, PUBLISH_OK, SUBSCRIBE_NAMESPACE_OK, + SUBSCRIBE_TRACKS_OK, PUBLISH_NAMESPACE_OK, or REQUEST_UPDATE_OK. It + encodes the time in milliseconds after which the sender of the + parameter will terminate the subscription. The sender will terminate + the subscription using PUBLISH_DONE or by cancelling the request (see + Section 3.3.3). This value is advisory and the sender can terminate + the subscription prior to or after the expiry time. + + The receiver of the parameter can attempt to extend the subscription + by sending a REQUEST_UPDATE with 0 or more updated parameters. If + the receiver has one or more updated AUTHORIZATION_TOKENs, it SHOULD + include those in the REQUEST_UPDATE. If the extension is granted, + the sender includes a new EXPIRES value in REQUEST_UPDATE_OK. Relays + that send this parameter and applications that receive it MAY + introduce jitter to prevent many endpoints from updating + simultaneously. + + If the EXPIRES parameter is 0 or is not present in a message, the + subscription does not expire or expires at an unknown time. + +10.2.17. LARGEST OBJECT Parameter + + The LARGEST_OBJECT parameter (Parameter Type 0x9) is a Location. It + MAY appear in SUBSCRIBE_OK, PUBLISH, REQUEST_UPDATE_OK, + TRACK_STATUS_OK, or PUBLISH_STATE_NOTIFY. It contains the largest + Location (see Section 1.4.2) in the Track observed by the sending + endpoint (see Section 5.1.2). If Objects have been published on this + Track the Publisher MUST include this parameter. + + If omitted from a message, the sending endpoint has not published or + received any Objects in the Track. + + A relay MUST set LARGEST_OBJECT to the largest of the following: + + 1. Any LARGEST_OBJECT value received from the upstream publisher in + SUBSCRIBE_OK, PUBLISH, or REQUEST_UPDATE_OK + + 2. The largest Location of an Object received on an upstream + subscription + + + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 73] + +Internet-Draft moq-transport August 2026 + + +10.2.18. FORWARD Parameter + + The FORWARD parameter (Parameter Type 0x10) is a uint8. It MAY + appear in SUBSCRIBE, REQUEST_UPDATE (for a subscription or a + SUBSCRIBE_TRACKS request), PUBLISH, SUBSCRIBE_TRACKS and + PUBLISH_STATE_NOTIFY. It specifies the Forwarding State on affected + subscriptions (see Section 5.1). The allowed values are 0 (don't + forward) or 1 (forward). If an endpoint receives a value outside + this range, it MUST close the session with PROTOCOL_VIOLATION. + + In the case of a REQUEST_UPDATE for SUBSCRIBE_TRACKS, it specifies + the Forwarding State on future subscriptions that match the prefix. + Existing subscriptions are unaffected. + + If the parameter is omitted from REQUEST_UPDATE or + PUBLISH_STATE_NOTIFY, the value for the subscription remains + unchanged. If the parameter is omitted from any other message, the + default value is 1. When sent in PUBLISH_STATE_NOTIFY, it reports + the Forwarding State now in effect at the publisher. + +10.2.19. NEW GROUP REQUEST Parameter + + The NEW_GROUP_REQUEST parameter (Parameter Type 0x32) is a varint. + It MAY appear in SUBSCRIBE or REQUEST_UPDATE for a subscription. It + represents the largest Group ID in the Track known by the subscriber, + plus 1. A value of 0 indicates that the subscriber has no Group + information for the Track. A subscriber MUST NOT send this parameter + in REQUEST_UPDATE if the Track did not include the DYNAMIC_GROUPS + Property with value 1. A subscriber MAY include this parameter in + SUBSCRIBE without foreknowledge of support. If the original + publisher does not support dynamic Groups, it ignores the parameter + in that case. + + When an Original Publisher that supports dynamic Groups receives a + NEW_GROUP_REQUEST with a value of 0 or a value larger than the + current Group, it SHOULD end the current Group and begin a new Group + as soon as practical. The Original Publisher MAY delay the + NEW_GROUP_REQUEST subject to implementation specific concerns, for + example, achieving a minimum duration for each Group. The Original + Publisher chooses the next Group ID; there are no requirements that + it be equal to the NEW_GROUP_REQUEST parameter value. + + Relay Handling: + + A relay that receives a NEW_GROUP_REQUEST for a Track without an + Established subscription MUST include the NEW_GROUP_REQUEST when + subscribing upstream. + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 74] + +Internet-Draft moq-transport August 2026 + + + A relay that receives a NEW_GROUP_REQUEST for an Established + subscription with a value of 0 or a value larger than the Largest + Group MUST send a REQUEST_UPDATE including the NEW_GROUP_REQUEST to + the publisher unless: + + 1. The Track does not support dynamic Groups + + 2. There is already an outstanding NEW_GROUP_REQUEST from this Relay + with a greater or equal value + + If a relay receives a NEW_GROUP_REQUEST with a non-zero value less + than or equal to the Largest Group, it does not send a + NEW_GROUP_REQUEST upstream. + + After sending a NEW_GROUP_REQUEST upstream, the request is considered + outstanding until the Largest Group increases. + +10.2.20. TRACK_NAMESPACE_PREFIX Parameter + + The TRACK_NAMESPACE_PREFIX parameter (Parameter Type 0x34) uses the + Track Namespace encoding described in Section 2.4.1. It MAY appear + in REQUEST_UPDATE for a SUBSCRIBE_NAMESPACE or SUBSCRIBE_TRACKS + request. It updates the Track Namespace Prefix for that + subscription. If the new prefix would share a common prefix with + another active subscription of the same type in the same session, the + receiver MUST respond with REQUEST_ERROR with error code + PREFIX_OVERLAP. + +10.2.21. INCLUDE_PROPERTIES Parameter + + The INCLUDE_PROPERTIES parameter (Parameter Type 0x35) is a uint8. + It MAY appear in SUBSCRIBE, TRACK_STATUS, FETCH or SUBSCRIBE_TRACKS. + It specifies whether the OK message sent in response includes Track + Properties or whether the resulting PUBLISH messages include Track + Properties in the case of SUBSCRIBE_TRACKS. If INCLUDE_PROPERTIES is + 0, the Track Properties are still present in the message, but they + SHOULD be empty. The allowed values are 0 (do not send Properties) + or 1 (send Properties), and the default is 1. If an endpoint + receives a value outside this range, it MUST close the session with + PROTOCOL_VIOLATION. + + + + + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 75] + +Internet-Draft moq-transport August 2026 + + +10.3. SETUP + + The SETUP message is the first message each endpoint sends on its + control stream (see Section 3.3); it allows the endpoints to agree on + the initial configuration before any other control messages are + exchanged. An endpoint that is not offering extensions which modify + control message semantics MAY pipeline other control messages after + SETUP without waiting for the peer's SETUP. + + The messages contain a sequence of key-value pairs called Setup + Options; the semantics and format of which can vary based on whether + the client or server is sending. To ensure future extensibility of + MOQT, endpoints MUST ignore unknown Setup Options. + + The wire format of the Setup message is as follows: + + SETUP Message { + Type (vi64) = 0x2F00, + Length (16), + Setup Options (..) ..., + } + + Figure 6: MOQT SETUP Message + + Setup Options are serialized as Key-Value-Pairs Figure 2, spanning + the entire message payload, bounded by the message Length field. + Setup Options use a namespace that is constant across all MOQT + versions, separate from Message Parameters. Receivers MUST ignore + unrecognized Setup Options. Senders MUST NOT repeat the same Option + Type in a message unless the option definition explicitly allows + multiple instances. Receivers MUST allow duplicates of unknown Setup + Options. + + The available Setup Options are detailed in the next sections. + +10.3.1. Setup Options + +10.3.1.1. AUTHORITY + + The AUTHORITY option (Option Type 0x05) allows the client to specify + the authority component of the MoQ URI when using native QUIC + (Section 3.1.5). It MUST NOT be used by the server, or when + WebTransport is used. When an AUTHORITY option is received from a + server, or when an AUTHORITY option is received while WebTransport is + used, or when an AUTHORITY option is received by a server but the + server does not support the specified authority, the session MUST be + closed with INVALID_AUTHORITY. + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 76] + +Internet-Draft moq-transport August 2026 + + + The AUTHORITY option follows the URI formatting rules [RFC3986]. + When connecting to a server using a URI with the "moqt" scheme, the + client MUST set the AUTHORITY option to the authority portion of the + URI. If an AUTHORITY option does not conform to these rules, the + session MUST be closed with MALFORMED_AUTHORITY. + +10.3.1.2. PATH + + The PATH option (Option Type 0x01) allows the client to specify the + path of the MoQ URI when using native QUIC (Section 3.1.5). It MUST + NOT be used by the server, or when WebTransport is used. When a PATH + setup option is received from a server, or when a PATH parameter is + received while WebTransport is used, or when a PATH parameter is + received by a server but the server does not support the specified + path, the session MUST be closed with INVALID_PATH. + + The PATH option follows the URI formatting rules [RFC3986]. When + connecting to a server using a URI with the "moqt" scheme, the client + MUST set the PATH option to the path-abempty portion of the URI; if + query is present, the client MUST concatenate ?, followed by the + query portion of the URI to the option. If a PATH does not conform + to these rules, the session MUST be closed with MALFORMED_PATH. + +10.3.1.3. MAX_AUTH_TOKEN_CACHE_SIZE + + The MAX_AUTH_TOKEN_CACHE_SIZE option (Option Type 0x04) communicates + the maximum size in bytes of all actively registered Authorization + tokens that the endpoint is willing to store per Session. This + option is optional. The default value is 0 which prohibits the use + of token Aliases. + + The token size is calculated as 16 bytes + the size of the Token + Value field (see Figure 5). The total size as restricted by the + MAX_AUTH_TOKEN_CACHE_SIZE option is calculated as the sum of the + token sizes for all registered tokens (Alias Type value of 0x01) + minus the sum of the token sizes for all deregistered tokens (Alias + Type value of 0x00), since Session initiation. + +10.3.1.4. AUTHORIZATION TOKEN + + The AUTHORIZATION TOKEN Setup Option (Option Type 0x03) is + functionally equivalent to the AUTHORIZATION TOKEN message parameter, + see Section 10.2.2. The endpoint can specify one or more tokens in + SETUP that the peer can use to authorize MOQT session establishment. + + If an endpoint receives an AUTHORIZATION TOKEN option in SETUP with + Alias Type REGISTER that exceeds its MAX_AUTH_TOKEN_CACHE_SIZE, it + MUST NOT fail the session with AUTH_TOKEN_CACHE_OVERFLOW. Instead, + + + +Nandakumar, et al. Expires 4 March 2027 [Page 77] + +Internet-Draft moq-transport August 2026 + + + it MUST treat the option as Alias Type USE_VALUE. Since each + endpoint's SETUP may be sent before the peer's SETUP is received, the + sender MUST handle registration failures of this kind by purging any + Token Aliases that failed to register based on the peer's + MAX_AUTH_TOKEN_CACHE_SIZE option in SETUP (or the default value of + 0). + +10.3.1.5. MOQT IMPLEMENTATION + + The MOQT_IMPLEMENTATION option (Option Type 0x07) identifies the name + and version of the sender's MOQT implementation. This SHOULD be a + UTF-8 encoded string [RFC3629], though the message does not carry + information, such as language tags, that would aid comprehension by + any entity other than the one that created the text. + + An endpoint SHOULD send a MOQT_IMPLEMENTATION option unless + specifically configured not to do so. This option helps identify the + scope of interoperability problems and work around implementation- + specific limitations. + + Senders SHOULD limit the value to the implementation name and + version, avoiding advertising or other nonessential information. + Implementations SHOULD NOT use the identifiers of other + implementations to declare compatibility, as this undermines the + usefulness of implementation identification for debugging. + +10.3.1.6. MAX FILTER RANGES + + The MAX_FILTER_RANGES option (Type 0x06) limits the peer's total + number of Ranges (Start/End pairs) allowed concurrently in all Range + filter Section 5.1.4 parameters for a given subscription or fetch. + The default value is 0, so if not specified, the peer MUST NOT send + any such filter parameters. If this limit is exceeded, an endpoint + MUST reject this with REQUEST_ERROR with error code INVALID_FILTER. + +10.3.1.7. MAX_REQUEST_UPDATES + + The MAX_REQUEST_UPDATES option (Option Type 0x08) communicates the + maximum number of unacknowledged REQUEST_UPDATE messages per request + stream that the endpoint is willing to receive. + + A REQUEST_UPDATE is considered outstanding from when it is sent until + the sender receives the corresponding REQUEST_OK or REQUEST_ERROR + response. The sender MUST NOT have more than MAX_REQUEST_UPDATES + outstanding REQUEST_UPDATEs on any single request stream at a time. + Each REQUEST_OK or REQUEST_ERROR response restores one credit on that + stream. An implementation that processes and responds to a + REQUEST_UPDATE immediately might not detect when a peer has pipelined + + + +Nandakumar, et al. Expires 4 March 2027 [Page 78] + +Internet-Draft moq-transport August 2026 + + + messages exceeding its limit; coalescing REQUEST_UPDATE processing + (see Section 10.9) can be more effective at enforcing + MAX_REQUEST_UPDATES. + + The value is encoded as a variable-length integer. A value of 0 + means the endpoint does not limit REQUEST_UPDATE concurrency. If not + present, the default value is 0. + + If an endpoint receives a REQUEST_UPDATE on a stream that already has + MAX_REQUEST_UPDATES outstanding REQUEST_UPDATEs, it MUST close the + session with TOO_MANY_REQUEST_UPDATES. + +10.4. GOAWAY + + An endpoint sends a GOAWAY message on its control stream to inform + the peer it intends to close the session soon. When sent by a + server, it can initiate session migration (Section 3.6) with an + optional URI. A client MUST send a zero-length New Session URI in + any GOAWAY, as clients cannot instruct servers to initiate + connections. + + A GOAWAY MAY also be sent on a request stream to initiate migration + of that individual request. Upon receiving a GOAWAY on a request + stream, the endpoint SHOULD re-issue that specific request on a + session at the specified URI (or the current session if no URI is + provided), and close the old request stream using the appropriate + mechanism (e.g. FIN, stream reset, or PUBLISH_DONE). This allows, + for example, moving the publishers and subscribers of a common set of + tracks to a common relay without draining their entire session. + + The GOAWAY message does not impact subscription state. A subscriber + SHOULD individually unsubscribe from each existing subscription, + while a publisher MAY reject new requests after sending a GOAWAY. + + Upon receiving a GOAWAY on the control stream, an endpoint SHOULD NOT + initiate new requests to the peer including SUBSCRIBE, PUBLISH, + FETCH, PUBLISH_NAMESPACE, SUBSCRIBE_NAMESPACE, SUBSCRIBE_TRACKS and + TRACK_STATUS. + + Sending a GOAWAY does not prevent the sender from initiating new + requests, though the sender SHOULD avoid initiating requests unless + required by migration (see (Section 9.4.1 and Section 9.5.1). An + endpoint that receives a GOAWAY MAY reject new requests with an + appropriate error code (e.g., REQUEST_ERROR with error code + GOING_AWAY). + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 79] + +Internet-Draft moq-transport August 2026 + + + The endpoint MUST close the session with a PROTOCOL_VIOLATION + (Section 3.5) if it receives more than one GOAWAY on the control + stream or on a single request stream. + + GOAWAY Message { + Type (vi64) = 0x10, + Length (16), + New Session URI Length (vi64), + New Session URI (..), + Timeout (vi64), + } + + Figure 7: MOQT GOAWAY Message + + * New Session URI: When received by a client, indicates where the + client can connect to continue this session or re-issue this + request. The client MUST use this URI for the new session if + provided. If the URI is zero bytes long, the current URI is + reused instead. The new session URI SHOULD use the same scheme as + the current URI to ensure compatibility. The maximum length of + the New Session URI is 8,192 bytes. If an endpoint receives a + length exceeding the maximum, it MUST close the session with a + PROTOCOL_VIOLATION. + + If a server receives a GOAWAY with a non-zero New Session URI + Length it MUST close the session with a PROTOCOL_VIOLATION. + + * Timeout: The time in milliseconds the sender will wait for + graceful closure. When sent on the control stream, the sender + closes the session with GOAWAY_TIMEOUT after the indicated timeout + if there are still open requests. When sent on a request stream, + the sender SHOULD reset the stream with GOING_AWAY after the + indicated timeout. A value of 0 indicates the sender has no + specific timeout, but the recipient SHOULD migrate as quickly as + possible. This is a hint; the sender of the GOAWAY MAY close the + session or reset the request stream before the indicated timeout + has elapsed. + +10.5. REQUEST_OK + + The REQUEST_OK message is sent in response to PUBLISH, + REQUEST_UPDATE, TRACK_STATUS, SUBSCRIBE_NAMESPACE, SUBSCRIBE_TRACKS + and PUBLISH_NAMESPACE requests. + + This document uses the shorthand PUBLISH_OK, REQUEST_UPDATE_OK, + TRACK_STATUS_OK, SUBSCRIBE_NAMESPACE_OK, SUBSCRIBE_TRACKS_OK and + PUBLISH_NAMESPACE_OK to refer to a REQUEST_OK sent in response to the + corresponding request type. + + + +Nandakumar, et al. Expires 4 March 2027 [Page 80] + +Internet-Draft moq-transport August 2026 + + + REQUEST_OK Message { + Type (vi64) = 0x7, + Length (16), + Number of Parameters (vi64), + Parameters (..) ..., + Track Properties (..), + } + + Figure 8: MOQT REQUEST_OK Message + + * Parameters: The parameters are defined in Section 10.2. + + * Track Properties : A sequence of Properties. See Section 2.5. + The length of Track Properties is the remaining length of the + message after parsing all previous fields. Track Properties are + populated in TRACK_STATUS_OK; they are empty in PUBLISH_OK, + REQUEST_UPDATE_OK, SUBSCRIBE_NAMESPACE_OK and + PUBLISH_NAMESPACE_OK. If an endpoint receives Track Properties in + one of these messages it MUST close the session with a + PROTOCOL_VIOLATION. + +10.6. REQUEST_ERROR + + The REQUEST_ERROR message is sent in response to any request + (SUBSCRIBE, FETCH, PUBLISH, SUBSCRIBE_NAMESPACE, SUBSCRIBE_TRACKS, + PUBLISH_NAMESPACE, TRACK_STATUS, REQUEST_UPDATE). + +10.6.1. Redirect Structure + + A Redirect provides a way for an endpoint to direct the peer to retry + a request at a different URI and/or for a different Full Track Name. + + Redirect { + Connect URI Length (vi64), + Connect URI (..), + Track Namespace (..), + Track Name Length (vi64), + Track Name (..), + } + + * Connect URI: The URI to connect to for the redirected request. If + the length is zero, the requester SHOULD use the current session's + URI. If a server receives a Redirect with a non-zero Connect URI + Length it MUST close the session with a PROTOCOL_VIOLATION. + + * Track Namespace and Track Name: The Track Namespace and Track Name + to use for the redirected request, together referred to as the + Redirect target. + + + +Nandakumar, et al. Expires 4 March 2027 [Page 81] + +Internet-Draft moq-transport August 2026 + + + Track Name is not meaningful for namespace-scoped requests + (SUBSCRIBE_NAMESPACE, PUBLISH_NAMESPACE, SUBSCRIBE_TRACKS) and + MUST be empty; an endpoint that receives a non-empty Track Name in + a Redirect for a namespace-scoped request MUST close the session + with a PROTOCOL_VIOLATION. + +10.6.2. REQUEST_ERROR Message Format + + REQUEST_ERROR Message { + Type (vi64) = 0x5, + Length (16), + Error Code (vi64), + Retry Interval (vi64), + Error Reason (Reason Phrase), + [Redirect (Redirect),] + } + + Figure 9: MOQT REQUEST_ERROR Message + + * Error Code: Identifies an integer error code for request failure. + + * Retry Interval: The minimum time (in milliseconds) before the + request SHOULD be sent again, plus one. If the value is 0, the + request SHOULD NOT be retried. + + * Error Reason: Provides a text description of the request error. + See Section 1.4.4. + + * Redirect: Present only when Error Code is REDIRECT. See + Section 10.6.1. + + The application SHOULD use a relevant error code in REQUEST_ERROR, as + defined below and assigned in Section 15.11.2. Most codepoints have + identical meanings for various request types, but some have request- + specific meanings. + + If a request is retryable with the same parameters at a later time, + the sender of REQUEST_ERROR includes a non-zero Retry Interval in the + message. To minimize the risk of synchronized retry storms, the + sender can apply randomization to each retry interval so that retries + are spread out over time. A Retry Interval value of 1 indicates the + request can be retried immediately. + + INTERNAL_ERROR: An implementation specific or generic error + occurred. + + UNAUTHORIZED: The subscriber is not authorized to perform the + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 82] + +Internet-Draft moq-transport August 2026 + + + requested action on the given track. This might be retryable if + the authorization token is not yet valid. + + TIMEOUT: The subscription could not be completed before an + implementation specific timeout. For example, a relay could not + establish an upstream subscription within the timeout. + + NOT_SUPPORTED: The endpoint does not support the type of request. + + MALFORMED_AUTH_TOKEN: Invalid Auth Token serialization during + registration (see Section 10.2.2). + + EXPIRED_AUTH_TOKEN: Authorization token has expired + (Section 10.2.2). + + GOING_AWAY: The endpoint has received a GOAWAY and MAY reject new + requests. + + EXCESSIVE_LOAD: The responder is overloaded and cannot process the + request at this time. The sender SHOULD use the Retry Interval to + indicate when the request can be retried. + + UNSUPPORTED_EXTENSION: The track contains a Mandatory Track Property + (see Section 2.5.1) that the endpoint does not understand. + + REDIRECT: The request cannot be fulfilled by this endpoint, but + could succeed at the location specified in the Redirect structure. + The requester SHOULD establish a new session to the provided URI + (if present) and retry the request using the Redirect target. A + Retry Interval of 0 indicates the original request SHOULD NOT be + retried as sent; it does not prevent the requester from following + a Redirect to a different URI or Redirect target. This error code + can appear in response to SUBSCRIBE, FETCH, TRACK_STATUS, PUBLISH, + PUBLISH_NAMESPACE, SUBSCRIBE_NAMESPACE, and SUBSCRIBE_TRACKS. + Relays are not required to follow redirects from upstream and MAY + forward a REDIRECT response to matching downstream requests. A + relay MAY cache a REDIRECT response for up to Retry Interval + milliseconds and use it to respond to subsequent matching requests + without forwarding them upstream. + + Below are errors for use by the publisher. They can appear in + response to SUBSCRIBE, FETCH, TRACK_STATUS, SUBSCRIBE_NAMESPACE, and + SUBSCRIBE_TRACKS, unless otherwise noted. + + DOES_NOT_EXIST: The track or namespace is not available at the + publisher. + + INVALID_RANGE: In response to SUBSCRIBE or FETCH, specified Filter + + + +Nandakumar, et al. Expires 4 March 2027 [Page 83] + +Internet-Draft moq-transport August 2026 + + + or range of Locations cannot be satisfied. + + INVALID_FILTER: A filter parameter is invalid. + + MALFORMED_TRACK: In response to a FETCH, a relay publisher detected + the track was malformed (see Section 2.4.2). + + The following are errors for use by the subscriber. They can appear + in response to PUBLISH or PUBLISH_NAMESPACE, unless otherwise noted. + + UNINTERESTED: The subscriber is not interested in the track or + namespace. + + Errors below can only be used in response to one message type. + + PREFIX_OVERLAP: In response to SUBSCRIBE_NAMESPACE or + SUBSCRIBE_TRACKS, the namespace prefix shares a common prefix with + another subscription of the same type in the same session. + SUBSCRIBE_NAMESPACE and SUBSCRIBE_TRACKS have independent overlap + spaces, so a SUBSCRIBE_NAMESPACE and a SUBSCRIBE_TRACKS may share + the same prefix. + + NAMESPACE_TOO_LARGE: In response to SUBSCRIBE_NAMESPACE or + SUBSCRIBE_TRACKS, the namespace prefix matches more publishers + than the relay is willing to enumerate. + + CONFLICTING_FILTERS: In response to SUBSCRIBE_TRACKS, the filter + parameters conflict among too many subscribers to aggregate the + subscription upstream or otherwise efficiently service it. + +10.7. SUBSCRIBE + + SUBSCRIBE initiates a subscription to a track. The associated + parameters determine the range and mechanism of object delivery; the + Location Filter (see Section 5.1.2) selects which Objects are sent, + and a FILL_PARAMETERS parameter (see Section 10.2.15) additionally + retrieves the fill range on a fill fetch stream (see Section 5.1.3). + + The format of SUBSCRIBE is as follows: + + + + + + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 84] + +Internet-Draft moq-transport August 2026 + + + SUBSCRIBE Message { + Type (vi64) = 0x3, + Length (16), + Request ID (vi64), + Track Namespace (..), + Track Name Length (vi64), + Track Name (..), + Number of Parameters (vi64), + Parameters (..) ... + } + + Figure 10: MOQT SUBSCRIBE Message + + * Request ID: See Section 10.1. + + * Track Namespace: Identifies the namespace of the track as defined + in (Section 2.4.1). + + * Track Name: Identifies the track name as defined in + (Section 2.4.1). + + * Parameters: The parameters are defined in Section 10.2. + + On successful subscription, the publisher MUST reply with a + SUBSCRIBE_OK, allowing the subscriber to determine the start group/ + object when not explicitly specified, and start sending objects. + +10.8. SUBSCRIBE_OK + + A publisher sends a SUBSCRIBE_OK as the first response message on the + bidi stream for successful subscriptions. + + SUBSCRIBE_OK Message { + Type (vi64) = 0x4, + Length (16), + Track Alias (vi64), + Number of Parameters (vi64), + Parameters (..) ..., + Track Properties (..), + } + + Figure 11: MOQT SUBSCRIBE_OK Message + + * Track Alias: The identifer used for this track in Subgroups or + Datagrams (see Section 11.1). + + * Parameters: The parameters are defined in Section 10.2. + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 85] + +Internet-Draft moq-transport August 2026 + + + * Track Properties : A sequence of Properties. See Section 2.5. + +10.9. REQUEST_UPDATE + + The sender of a request (SUBSCRIBE, PUBLISH, FETCH, + PUBLISH_NAMESPACE, SUBSCRIBE_NAMESPACE, SUBSCRIBE_TRACKS) can later + send a REQUEST_UPDATE on the same bidi stream as the request to + modify it. A subscriber can also send REQUEST_UPDATE to modify + parameters of a subscription established with PUBLISH. + + An endpoint that receives a REQUEST_UPDATE other than in the two + cases above MUST close the session with a PROTOCOL_VIOLATION. + + The receiver of a REQUEST_UPDATE MUST respond with exactly one + REQUEST_OK or REQUEST_ERROR message indicating if the update was + successful, unless it is coalescing failed updates to produce just + one REQUEST_ERROR for multiple REQUEST_UPDATE messages. + + The number of outstanding REQUEST_UPDATEs on a single request stream + is limited by the MAX_REQUEST_UPDATES Setup Option + (Section 10.3.1.7). + + If a parameter previously set on the request is not present in + REQUEST_UPDATE, its value remains unchanged. + + There is no mechanism to remove a parameter from a request. + + The format of REQUEST_UPDATE is as follows: + + REQUEST_UPDATE Message { + Type (vi64) = 0x2, + Length (16), + Request ID (vi64), + Number of Parameters (vi64), + Parameters (..) ... + } + + Figure 12: MOQT REQUEST_UPDATE Message + + * Request ID: See Section 10.1. + + * Parameters: The parameters are defined in Section 10.2. + + + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 86] + +Internet-Draft moq-transport August 2026 + + +10.9.1. Updating Subscriptions + + When a subscriber decreases the Start Location of the Location Filter + (see Section 5.1.2), the Start Location can be smaller than the + Track's Largest Location, similar to a new Subscription. Including + FILL_PARAMETERS (see Section 10.2.15) in the REQUEST_UPDATE causes + the publisher to deliver the new fill range by opening a new fill + fetch stream (see Section 5.1.3). FETCH can also be used to retrieve + any necessary Objects smaller than the current Largest Location. + + When a subscriber increases the End Location, the Largest Object at + the publisher might already be larger than the previous End Location. + This will create a gap in the subscription. The REQUEST_UPDATE_OK + will include the LARGEST_OBJECT parameter, and the subscriber can + issue a FETCH to retrieve the omitted Objects, if any. + + When a subscriber narrows their subscription (increase the Start + Location and/or decrease the End Group), it might still receive + Objects outside the new range if the publisher sent them before the + update was processed. + + When a REQUEST_UPDATE is unsuccessful, the publisher MUST also + terminate the subscription by sending a PUBLISH_DONE with error code + UPDATE_FAILED. When a REQUEST_UPDATE fails for a FETCH, the + publisher MUST reset the FETCH data stream. When a REQUEST_UPDATE + fails for a SUBSCRIBE_NAMESPACE, SUBSCRIBE_TRACKS or + PUBLISH_NAMESPACE, the responder MUST close the bidi stream (see + Section 3.3.2). + + A receiver of multiple REQUEST_UPDATE messages on the same stream MAY + coalesce their processing by applying only the cumulative result. + Parameter values from later REQUEST_UPDATE messages override values + from earlier ones. The receiver MUST still send a REQUEST_OK for + each successful update, but it is not required to process + intermediate states individually. If the coalesced REQUEST_UPDATE + results in REQUEST_ERROR, only a single REQUEST_ERROR will be sent + and the sender of the REQUEST_UPDATEs will not always be able to + determine which caused an error. + +10.9.2. Updating Namespace Subscriptions + + A subscriber can update the Track Namespace Prefix of an established + SUBSCRIBE_NAMESPACE or SUBSCRIBE_TRACKS by including the + TRACK_NAMESPACE_PREFIX parameter (Section 10.2.20) in a + REQUEST_UPDATE. The overlap restriction applies independently per + type: the new prefix MUST NOT share a common prefix with any other + active SUBSCRIBE_NAMESPACE (for a SUBSCRIBE_NAMESPACE update) or + SUBSCRIBE_TRACKS (for a SUBSCRIBE_TRACKS update) in the same session. + + + +Nandakumar, et al. Expires 4 March 2027 [Page 87] + +Internet-Draft moq-transport August 2026 + + + If the update is accepted, NAMESPACE and NAMESPACE_DONE messages + following the REQUEST_OK will contain Track Namespace suffixes + relative to the updated prefix. Updating the prefix of a + SUBSCRIBE_TRACKS has no effect on existing subscriptions. If the + subscriber is no longer interested it can cancel the corresponding + bidirectional stream. + +10.10. PUBLISH_STATE_NOTIFY + + A publisher sends PUBLISH_STATE_NOTIFY on a subscription's + bidirectional stream to notify the subscriber that the state of the + subscription has changed for a reason other than a subscriber sent + REQUEST_UPDATE. Unlike REQUEST_UPDATE (Section 10.9), it is a + unilateral notification: the receiver does not respond with + REQUEST_OK or REQUEST_ERROR, and the message is not subject to the + MAX_REQUEST_UPDATES limit (Section 10.3.1.7). + + PUBLISH_STATE_NOTIFY applies only to subscriptions, and is sent only + by the publisher. An endpoint that receives a PUBLISH_STATE_NOTIFY + for any other request type, or from the subscriber, MUST close the + session with a PROTOCOL_VIOLATION. + + A PUBLISH_STATE_NOTIFY carries the parameters whose values have + changed. If a parameter is not present, its value is unchanged. The + semantics of each parameter, including whether it may appear in + PUBLISH_STATE_NOTIFY, are defined by the parameter. + + A publisher MUST NOT use PUBLISH_STATE_NOTIFY to change the value of + a subscriber controlled subscription parameter unless the subscriber + requested the change. + + The publisher MUST include the LARGEST_OBJECT parameter + (Section 10.2.17), if known, in PUBLISH_STATE_NOTIFY so the + subscriber can determine the point in the Track at which the change + took effect. + + This message is informative and no action is required by the + recipient. + + The format of PUBLISH_STATE_NOTIFY is as follows: + + PUBLISH_STATE_NOTIFY Message { + Type (vi64) = 0x22, + Length (16), + Number of Parameters (vi64), + Parameters (..) ... + } + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 88] + +Internet-Draft moq-transport August 2026 + + + Figure 13: MOQT PUBLISH_STATE_NOTIFY Message + + * Parameters: The parameters are defined in Section 10.2. + +10.11. PUBLISH + + The publisher sends PUBLISH as the first message on a new + bidirectional stream to initiate a subscription for a Track. The + receiver verifies the publisher is authorized to publish this track. + + PUBLISH Message { + Type (vi64) = 0x1D, + Length (16), + Request ID (vi64), + Track Namespace (..), + Track Name Length (vi64), + Track Name (..), + Track Alias (vi64), + Number of Parameters (vi64), + Parameters (..) ..., + Track Properties (..), + } + + Figure 14: MOQT PUBLISH Message + + * Request ID: See Section 10.1. + + * Track Namespace: Identifies a track's namespace as defined in + (Section 2.4.1) + + * Track Name: Identifies the track name as defined in + (Section 2.4.1). + + * Track Alias: The identifer used for this track in Subgroups or + Datagrams (see Section 11.1). + + * Parameters: The parameters are defined in Section 10.2. + Parameters such as FORWARD, GROUP_ORDER, SUBSCRIBER_PRIORITY, + SUBGROUP_DELIVERY_TIMEOUT, OBJECT_DELIVERY_TIMEOUT, and LOCATION + FILTER can appear in the Parameters of a PUBLISH to inform the + Subscriber of the initial Subscription parameters. If the PUBLISH + is the result of a SUBSCRIBE_TRACKS, the parameters are handled as + described in Section 10.20.1, otherwise, they represent the + publisher's initial settings for the subscription, which the + subscriber can change. + + * Track Properties : A sequence of Properties. See Section 2.5. + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 89] + +Internet-Draft moq-transport August 2026 + + + A subscriber receiving a PUBLISH for a Track it does not wish to + receive SHOULD send REQUEST_ERROR with error code UNINTERESTED, and + abandon reading any publisher initiated streams associated with that + subscription using a STOP_SENDING frame. + + A publisher that sends the FORWARD parameter (Section 10.2.18) equal + to 0 indicates that it will not transmit any objects until the + subscriber sets the Forward State to 1. If the FORWARD parameter is + omitted or equal to 1, the publisher will start transmitting objects + immediately, possibly before PUBLISH_OK. Delivery starts at the Next + Object relative to the Largest Object at the time the publisher + begins sending. + +10.12. PUBLISH_DONE + + A publisher sends a PUBLISH_DONE message as the final message before + closing the subscription's bidi stream to indicate it is done + publishing Objects for that subscription. The Status Code indicates + why the subscription ended, and whether it was an error. Because + PUBLISH_DONE is sent on a request stream, it is likely to arrive at + the receiver before late-arriving objects, and often even late- + opening streams. However, the receiver uses it as an indication that + it should receive any late-opening streams in a relatively short + time. + + Note that some objects in the subscribed track might never be + delivered, because a stream was reset, or never opened in the first + place, due to the delivery timeouts (see Section 8). + + A sender MUST NOT send PUBLISH_DONE until it has closed all streams + it will ever open, and has no further datagrams to send, for a + subscription. After sending PUBLISH_DONE, the sender can immediately + destroy subscription state, although stream state can persist until + delivery completes. The sender might persist subscription state to + enforce the subgroup delivery timeout. + + A sender MUST NOT destroy subscription state until it sends + PUBLISH_DONE, though it can choose to stop sending objects (and thus + send PUBLISH_DONE) for any reason. + + A subscriber that receives PUBLISH_DONE SHOULD set a timer of at + least the larger of SUBGROUP_DELIVERY_TIMEOUT or + OBJECT_DELIVERY_TIMEOUT in case some objects are still inbound due to + prioritization or packet loss. The subscriber MAY dispense with a + timer if it unsubscribed or is otherwise no longer interested in + objects from the track. Once the timer has expired, the receiver + destroys subscription state once all open streams for the + subscription have closed. A subscriber MAY discard subscription + + + +Nandakumar, et al. Expires 4 March 2027 [Page 90] + +Internet-Draft moq-transport August 2026 + + + state earlier, at the cost of potentially not delivering some late + objects to the application. The subscriber SHOULD send STOP_SENDING + on all streams related to the subscription when it deletes + subscription state. + + The format of PUBLISH_DONE is as follows: + + PUBLISH_DONE Message { + Type (vi64) = 0xB, + Length (16), + Status Code (vi64), + Stream Count (vi64), + Error Reason (Reason Phrase) + } + + Figure 15: MOQT PUBLISH_DONE Message + + * Status Code: An integer status code indicating why the + subscription ended. + + * Stream Count: An integer indicating the number of data streams the + publisher opened for this subscription, including streams that + contained no Objects (e.g., an empty Subgroup) and including any + fill fetch streams (see Section 5.1.3). This helps the subscriber + know if it has received all of the data published in this + subscription by comparing the number of streams received. The + subscriber can immediately remove all subscription state once the + same number of streams have been processed. If the publisher did + not open any streams for this subscription, the publisher MUST set + Stream Count to 0. If the publisher is unable to set Stream Count + to the exact number of streams opened for the subscription, it + MUST set Stream Count to 2^64 - 1. Subscribers SHOULD use a + timeout or other mechanism to remove subscription state in case + the publisher set an incorrect value, reset a stream before the + SUBGROUP_HEADER, or set the maximum value. If a subscriber + receives more streams for a subscription than specified in Stream + Count, it MAY close the session with a PROTOCOL_VIOLATION. + + * Error Reason: Provides the reason for subscription error. See + Section 1.4.4. + + The application SHOULD use a relevant status code in PUBLISH_DONE, as + defined below: + + INTERNAL_ERROR (0x0): An implementation specific or generic error + occurred. + + UNAUTHORIZED (0x1): The subscriber is no longer authorized to + + + +Nandakumar, et al. Expires 4 March 2027 [Page 91] + +Internet-Draft moq-transport August 2026 + + + subscribe to the given track. + + TRACK_ENDED (0x2): The track is no longer being published. + + GOING_AWAY (0x4): The subscriber or publisher issued a GOAWAY + message. + + TOO_FAR_BEHIND (0x5): The publisher's queue of objects to be sent to + the given subscriber exceeds its implementation defined limit. + + EXPIRED (0x6): The publisher reached the timeout specified in + SUBSCRIBE_OK. + + MALFORMED_TRACK (0x12): A relay publisher detected that the track + was malformed (see Section 2.4.2). + + UPDATE_FAILED (0x8): REQUEST_UPDATE failed on this subscription (see + Section 10.9). + + EXCESSIVE_LOAD (0x9): The publisher is overloaded and is terminating + the subscription. + +10.13. FETCH + + A subscriber sends FETCH as the first message on a new bidi stream to + a publisher to request a range of already published objects within a + track. + + The format of FETCH is as follows: + + FETCH Message { + Type (vi64) = 0x16, + Length (16), + Request ID (vi64), + Track Namespace (..), + Track Name Length (vi64), + Track Name (..), + Number of Parameters (vi64), + Parameters (..) ... + } + + Figure 16: MOQT FETCH Message + + * Request ID: See Section 10.1. + + * Track Namespace: Identifies the namespace of the track as defined + in (Section 2.4.1). + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 92] + +Internet-Draft moq-transport August 2026 + + + * Track Name: Identifies the track name as defined in + (Section 2.4.1). + + * Parameters: The parameters are defined in Section 10.2. + + A publisher responds to a FETCH request with either a FETCH_OK or a + REQUEST_ERROR message. The publisher creates a new unidirectional + stream that is used to send the Objects. The FETCH_OK or + REQUEST_ERROR can come at any time relative to object delivery. + + The publisher responding to a FETCH is responsible for delivering all + available Objects in the requested range in the requested order (see + Section 10.2.8). The Objects in the response are delivered on a + single unidirectional stream. Any gaps in the Group and Object IDs + in the response stream indicate objects that do not exist unless + filters were requested. For Ascending Group Order this includes + ranges between the first requested object and the first object in the + stream; between objects in the stream; and between the last object in + the stream and the Largest Group/Object indicated in FETCH_OK, so + long as the fetch stream is terminated by a FIN. If no Objects exist + in the requested range, the publisher opens the unidirectional + stream, sends the FETCH_HEADER (see Section 11.4.4) and closes the + stream with a FIN. + + A relay that has cached objects from the beginning of the range MAY + start sending objects immediately in response to a FETCH. If it + encounters an object in the requested range that is not cached and + has unknown status, the relay MUST pause subsequent delivery until it + has confirmed the object's status upstream. If the upstream FETCH + fails, the relay sends a REQUEST_ERROR and can reset the + unidirectional stream. It can choose to do so immediately or wait + until the cached objects have been delivered before resetting the + stream. + + The Object Forwarding Preference does not apply to fetches. + + Fetch can include a Location Filter parameter (see Section 5.1.2) + which specifies an inclusive range of Objects starting at Start + Location and ending at End Location. + + Objects with Locations larger than the Largest Object at the time the + request is processed will not be retrieved by a FETCH. If the + requested End Location exceeds the Largest Object, the actual end of + the FETCH response is indicated in the FETCH_OK End Location. + + If no Objects have been published for the track or Start Location is + greater than the Largest Object (Section 10.7) the publisher MUST + return REQUEST_ERROR with error code INVALID_RANGE. + + + +Nandakumar, et al. Expires 4 March 2027 [Page 93] + +Internet-Draft moq-transport August 2026 + + + A publisher MUST send fetched groups in the requested group order, + either ascending or descending. Within each group, objects are sent + in Object ID order; subgroup ID is not used for ordering. + + If a Publisher receives a FETCH with a range that includes one or + more Objects with unknown status (e.g. a Relay has temporarily lost + contact with the Original Publisher and does not have the Object in + cache), it can choose to reset the FETCH data stream with + UNKNOWN_OBJECT_STATUS (Section 3.3.4), or indicate the range of + unknown Objects and continue serving other known Objects. + +10.14. FETCH_OK + + A publisher sends a FETCH_OK as the first message on the bidi stream + in response to a successful fetch. A publisher MAY send Objects in + response to a FETCH before the FETCH_OK message is sent, but the + FETCH_OK MUST NOT be sent until the End Location is known. + + FETCH_OK Message { + Type (vi64) = 0x18, + Length (16), + End Of Track (8), + End Location (Location), + Number of Parameters (vi64), + Parameters (..) ... + Track Properties (..), + } + + Figure 17: MOQT FETCH_OK Message + + * End Of Track: 1 if all Objects have been published on this Track, + and the End Location is the final Object in the Track, 0 if not. + + * End Location: The end of the range covered by the FETCH response. + This is the End Location from the FETCH request Location Filter + parameter unless the requested range extends beyond Largest Object + at the time the request was processed, or the last Object in the + Track. If End Location is smaller than the Start Location in the + corresponding FETCH the receiver MUST close the session with a + PROTOCOL_VIOLATION. + + * Parameters: The parameters are defined in Section 10.2. + + * Track Properties : A sequence of Properties. See Section 2.5. + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 94] + +Internet-Draft moq-transport August 2026 + + +10.15. TRACK_STATUS + + A potential subscriber sends TRACK_STATUS as the first and only + message on a new bidi stream to obtain information about the current + status of a given track. + + The TRACK_STATUS message format is identical to the SUBSCRIBE message + (Section 10.7), but subscriber parameters related to Track delivery + (e.g. SUBSCRIBER_PRIORITY) are not included. + + The receiver of a TRACK_STATUS message treats it identically as if it + had received a SUBSCRIBE message, except it does not create + downstream subscription state or send any Objects. If successful, + the publisher responds with a TRACK_STATUS_OK with the same + parameters and Track Properties it would have set in a SUBSCRIBE_OK. + Track Alias is not used. A publisher responds to a failed + TRACK_STATUS with an appropriate REQUEST_ERROR message. The bidi + stream is closed with a FIN after TRACK_STATUS_OK or REQUEST_ERROR + are sent. + + Relays without an Established subscription MAY forward TRACK_STATUS + to one or more publishers, or MAY initiate a subscription (subject to + authorization) as described in Section 9.5 to determine the response. + The publisher does not send PUBLISH_DONE for this request, and the + subscriber cannot send REQUEST_UPDATE. + +10.16. PUBLISH_NAMESPACE + + The publisher sends the PUBLISH_NAMESPACE message as the first + message on a new bidi stream to advertise that it has tracks + available within a Track Namespace. The receiver verifies the + publisher is authorized to publish tracks under this namespace. + + PUBLISH_NAMESPACE Message { + Type (vi64) = 0x6, + Length (16), + Request ID (vi64), + Track Namespace (..), + Number of Parameters (vi64), + Parameters (..) ... + } + + Figure 18: MOQT PUBLISH_NAMESPACE Message + + * Request ID: See Section 10.1. + + * Track Namespace: Identifies a track's namespace as defined in + Section 2.4.1. + + + +Nandakumar, et al. Expires 4 March 2027 [Page 95] + +Internet-Draft moq-transport August 2026 + + + * Parameters: The parameters are defined in Section 10.2. + +10.17. NAMESPACE + + The NAMESPACE message is similar to the PUBLISH_NAMESPACE message, + except it is sent on the response stream of a SUBSCRIBE_NAMESPACE + request. All NAMESPACE messages are in response to a + SUBSCRIBE_NAMESPACE, so only the namespace tuples after the 'Track + Namespace Prefix' are included in the 'Track Namespace Suffix'. + + NAMESPACE Message { + Type (vi64) = 0x8, + Length (16), + Track Namespace Suffix (..), + } + + Figure 19: MOQT NAMESPACE Message + + * Track Namespace Suffix: Specifies the final portion of a track's + namespace as defined in Section 2.4.1 after removing namespace + tuples included in 'Track Namespace Prefix' Section 10.19. + +10.18. NAMESPACE_DONE + + The publisher sends the NAMESPACE_DONE control message to indicate + its intent to stop serving new subscriptions for tracks within the + provided Track Namespace. All NAMESPACE_DONE messages are in + response to a SUBSCRIBE_NAMESPACE, so only the namespace tuples after + the 'Track Namespace Prefix' are included in the 'Track Namespace + Suffix'. + + NAMESPACE_DONE Message { + Type (vi64) = 0xE, + Length (16), + Track Namespace Suffix (..) + } + + Figure 20: MOQT NAMESPACE_DONE Message + + * Track Namespace Suffix: Specifies the final portion of a track's + namespace as defined in Section 2.4.1. The namespace begins with + the 'Track Namespace Prefix' specified in Section 10.19. + +10.19. SUBSCRIBE_NAMESPACE + + The subscriber sends a SUBSCRIBE_NAMESPACE control message on a new + bidirectional stream to a publisher to request the current set of + matching published namespaces, as well as future updates to the set. + + + +Nandakumar, et al. Expires 4 March 2027 [Page 96] + +Internet-Draft moq-transport August 2026 + + + SUBSCRIBE_NAMESPACE Message { + Type (vi64) = 0x50, + Length (16), + Request ID (vi64), + Track Namespace Prefix (..), + Number of Parameters (vi64), + Parameters (..) ... + } + + Figure 21: MOQT SUBSCRIBE_NAMESPACE Message + + * Request ID: See Section 10.1. + + * Track Namespace Prefix: A Track Namespace structure as described + in Section 2.4.1 with between 0 and 32 Track Namespace Fields. + This prefix is matched against track namespaces known to the + publisher. For example, using the serialized format from + Section 1.5, if the publisher is a relay that has received + PUBLISH_NAMESPACE messages for namespaces example.2ecom-123-100 + and example.2ecom-123-200, a SUBSCRIBE_NAMESPACE for + example.2ecom-123 would match both. If an endpoint receives a + Track Namespace Prefix consisting of greater than 32 Track + Namespace Fields, it MUST close the session with a + PROTOCOL_VIOLATION. + + * Parameters: The parameters are defined in Section 10.2. + + The publisher will respond with REQUEST_OK or REQUEST_ERROR on the + response half of the stream. If the subscriber receives any message + other than a REQUEST_OK or a REQUEST_ERROR as the first message on + the response half of the stream, then it MUST close the session with + a PROTOCOL_VIOLATION. If the SUBSCRIBE_NAMESPACE is successful, the + publisher will send matching NAMESPACE messages on the response + stream. If it is an error, the stream will be immediately closed via + FIN. When there are changes to the namespaces being published and + the subscriber is subscribed to them, the publisher sends the + corresponding NAMESPACE or NAMESPACE_DONE messages. + + Within a session, if a publisher receives a SUBSCRIBE_NAMESPACE with + a Track Namespace Prefix that shares a common prefix with an + established SUBSCRIBE_NAMESPACE, it MUST respond with REQUEST_ERROR + with error code PREFIX_OVERLAP. SUBSCRIBE_NAMESPACE and + SUBSCRIBE_TRACKS have independent overlap spaces (see Section 10.20). + + The publisher MUST ensure the subscriber is authorized to perform + this namespace subscription. + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 97] + +Internet-Draft moq-transport August 2026 + + + The publisher MUST NOT send NAMESPACE_DONE for a namespace suffix + before the corresponding NAMESPACE. If a subscriber receives a + NAMESPACE_DONE before the corresponding NAMESPACE, it MUST close the + session with a 'PROTOCOL_VIOLATION'. + + If the publisher is unable to send NAMESPACE or NAMESPACE_DONE + messages in a timely manner because the SUBSCRIBE_NAMESPACE response + stream is blocked by flow control, the publisher MAY reset the + SUBSCRIBE_NAMESPACE response stream. When a subscriber receives a + stream reset or FIN on a SUBSCRIBE_NAMESPACE response stream, it + SHOULD treat this as though each active namespace received a + NAMESPACE_DONE. Subscriptions established via PUBLISH on separate + bidi streams are not affected by closure of the SUBSCRIBE_NAMESPACE + stream. + +10.20. SUBSCRIBE_TRACKS + + The subscriber sends a SUBSCRIBE_TRACKS control message on a new + bidirectional stream to a publisher to request PUBLISH messages for + all tracks within matching namespaces, as well as future track + publications within those namespaces. + + SUBSCRIBE_TRACKS Message { + Type (vi64) = 0x51, + Length (16), + Request ID (vi64), + Track Namespace Prefix (..), + Number of Parameters (vi64), + Parameters (..) ... + } + + Figure 22: MOQT SUBSCRIBE_TRACKS Message + + * Request ID: See Section 10.1. + + * Track Namespace Prefix: A Track Namespace structure as described + in Section 2.4.1 with between 0 and 32 Track Namespace Fields. + This prefix is matched against track namespaces known to the + publisher. If an endpoint receives a Track Namespace Prefix + consisting of greater than 32 Track Namespace Fields, it MUST + close the session with a PROTOCOL_VIOLATION. + + * Parameters: The parameters are defined in Section 10.2, though + they are handled differently from the same Parameters on + Subscriptions, as outlined below. + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 98] + +Internet-Draft moq-transport August 2026 + + + The publisher will respond with REQUEST_OK or REQUEST_ERROR on the + response half of the stream. If the subscriber receives any message + other than a REQUEST_OK or a REQUEST_ERROR as the first message on + the response half of the stream, then it MUST close the session with + a PROTOCOL_VIOLATION. If the SUBSCRIBE_TRACKS is successful, the + publisher will send PUBLISH messages on new bidirectional streams for + tracks within matching namespaces. If it is an error, the stream + will be closed via FIN after REQUEST_ERROR is sent. + + Within a session, if a publisher receives a SUBSCRIBE_TRACKS with a + Track Namespace Prefix that shares a common prefix with an + established SUBSCRIBE_TRACKS, it MUST respond with REQUEST_ERROR with + error code PREFIX_OVERLAP. SUBSCRIBE_TRACKS and SUBSCRIBE_NAMESPACE + have independent overlap spaces (see Section 10.19). + + The publisher MUST ensure the subscriber is authorized to perform + this namespace subscription. + + SUBSCRIBE_TRACKS is not required for a publisher to send PUBLISH + messages to a subscriber. It is useful for subscribers that are only + interested in or authorized to access a subset of available tracks. + +10.20.1. Parameters on SUBSCRIBE_TRACKS + + Any Parameter that can be specified on a Subscription (ie: in + SUBSCRIBE) is valid in SUBSCRIBE_TRACKS, unless otherwise specified. + These parameters are used by the publisher as the initial + Subscription parameters when a PUBLISH is sent as a result of + SUBSCRIBE_TRACKS. These Parameters are explicitly communicated in + PUBLISH. When omitted by the publisher in PUBLISH, the subscriber + uses the default value for each. + + To join Tracks initiated via the resulting PUBLISHes, the subscriber + can specify a Location Filter and optionally include FILL_PARAMETERS, + as described in Section 5.1.6. + +10.21. PUBLISH_SKIPPED + + The publisher sends the PUBLISH_SKIPPED control message to indicate + it will not send a PUBLISH message to initiate a new Subscription for + a Track in the SUBSCRIBE_TRACKS's Track Namespace. All + PUBLISH_SKIPPED messages are in response to a SUBSCRIBE_TRACKS, so + only the namespace tuples after the 'Track Namespace Prefix' are + included in the 'Track Namespace Suffix'. + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 99] + +Internet-Draft moq-transport August 2026 + + + PUBLISH_SKIPPED Message { + Type (vi64) = 0xF, + Length (16), + Track Namespace Suffix (..), + Track Name Length (vi64), + Track Name (..), + } + + Figure 23: MOQT PUBLISH_SKIPPED Message + + * Track Namespace Suffix: Specifies the final portion of a track's + namespace as defined in Section 2.4.1. The namespace begins with + the 'Track Namespace Prefix' specified in Section 10.20. + + * Track Name: Identifies the track name as defined in + (Section 2.4.1). + +11. Data Streams and Datagrams + + A publisher sends Objects matching a subscription on Data Streams or + Datagrams and sends Objects matching a FETCH request on one Data + Stream. + + Unidirectional stream types are defined in Section 3.4. Data streams + use SUBGROUP_HEADER or FETCH_HEADER types. + + All MOQT datagrams start with a variable-length integer indicating + the type of the datagram. See Section 11.3.1. + + An endpoint that receives an unknown datagram type MUST close the + session. + + Every Object has a 'Object Forwarding Preference' and the Original + Publisher MAY use both Subgroups and Datagrams within a Group or + Track. + +11.1. Track Alias + + To optimize wire efficiency, Subgroups and Datagrams refer to a track + by a numeric identifier, rather than the Full Track Name. Track + Alias is chosen by the publisher and included in SUBSCRIBE_OK + (Section 10.8) or PUBLISH (Section 10.11). + + The same Track Alias MUST NOT be used by a publisher to refer to two + different Tracks simultaneously in the same session. If a subscriber + receives a PUBLISH or SUBSCRIBE_OK that uses the same Track Alias as + a different Track with an Established subscription, it MUST close the + session with error DUPLICATE_TRACK_ALIAS. + + + +Nandakumar, et al. Expires 4 March 2027 [Page 100] + +Internet-Draft moq-transport August 2026 + + + Objects can be sent before the Subscriber knows the Track Alias, + requiring buffering Objects with an unknown Track Alias. If a Track + Alias is used for two concurrent subscriptions to the same Track, an + Object that arrives with the Track Alias could be for either + Subscription. Reusing the same Track Alias for concurrent + subscriptions to the same Track can lead to missed delivery if + objects for the new subscription arrive before the control message + establishing the shared Alias. The Subscriber can assume the Track + Alias is reused until told otherwise, in order to avoid missing + Objects. + + To avoid a protocol violation and to ensure the Subscriber knows + which Track Objects are from, Publishers SHOULD NOT reuse a Track + Alias for different Tracks within a session, unless it is certain the + prior Subscription has been completely closed and no Objects are + scheduled to be sent or in flight. + + Objects can arrive after a subscription has been cancelled. + Subscribers SHOULD retain sufficient state to quickly discard these + unwanted Objects, rather than treating them as belonging to an + unknown Track Alias. + +11.2. Objects + + An Object contains a range of contiguous bytes from the specified + track, as well as associated metadata required to deliver, cache, and + forward it. Objects are sent by publishers. + +11.2.1. Object Header + + A canonical MOQT Object has the following fields: + + * Track Namespace and Track Name: The track this object belongs to. + + * Group ID: The identifier of the Object's Group (see Section 2.3) + within the Track. + + * Object ID: The order of the object within the group. + + * Publisher Priority: An 8 bit integer indicating the publisher's + priority for the Object (Section 7). + + * Object Forwarding Preference: An enumeration indicating how a + publisher sends an object. The preferences are Subgroup and + Datagram. Object Forwarding Preference is a property of an + individual Object and can vary among Objects in the same Track. + In a subscription, an Object MUST be sent according to its Object + Forwarding Preference. + + + +Nandakumar, et al. Expires 4 March 2027 [Page 101] + +Internet-Draft moq-transport August 2026 + + + * Subgroup ID: The identifier of the Object's Subgroup (see + Section 2.2) within the Group. This field is omitted if the + Object Forwarding Preference is Datagram. + + * Object Status: An enumeration used to indicate whether the Object + is a normal Object or mark the end of a group or track. See + Section 11.2.1.1 below. + + * Object Properties : A sequence of Properties associated with the + object. See Section 11.2.1.2. + + * Object Payload: An opaque payload intended for an End Subscriber + and SHOULD NOT be processed by a relay. Only present when 'Object + Status' is Normal (0x0). + +11.2.1.1. Object Status + + The Object Status is a field that is only present in objects that are + delivered via a SUBSCRIPTION, and is absent in Objects delivered via + a FETCH. It allows the publisher to explicitly communicate that a + specific range of objects does not exist. + + Status can have following values: + + * 0x0 := Normal object. This status is implicit for any non-zero + length object. Zero-length objects explicitly encode the Normal + status. + + * 0x3 := Indicates End of Group. Indicates that no objects with the + specified Group ID and the Object ID that is greater than or equal + to the one specified exist in the group identified by the Group + ID. + + * 0x4 := Indicates End of Track. Indicates that no objects with the + location that is equal to or greater than the one specified exist. + + All of those SHOULD be cached. + + There is no Object Status value indicating the end of a Subgroup. + The end of a Subgroup is signaled by closing its stream with a FIN + (see Section 11.4.3). + + Any other value SHOULD be treated as a protocol error and the session + SHOULD be closed with a PROTOCOL_VIOLATION (Section 3.5). An Object + MUST have an empty payload unless its Object Status value is + registered as permitting a payload in the Object Status registry + (Section 15.9). Of the values defined in this document, only Normal + (0x0) permits a payload. + + + +Nandakumar, et al. Expires 4 March 2027 [Page 102] + +Internet-Draft moq-transport August 2026 + + +11.2.1.2. Object Properties + + Any Object with status Normal can have properties (Section 2.5). If + an endpoint receives properties on an Object with status that is not + Normal, it MUST close the session with a PROTOCOL_VIOLATION. + + Object Properties are visible to relays and are intended to be + relevant to MOQT Object distribution. Any Object metadata never + intended to be accessed by the transport or Relays SHOULD be + serialized as part of the Object payload and not as an Object + Property. + + Object Properties set by the Original Publisher that are intended to + be visible to relays, but not modified by them, SHOULD be placed in + Immutable Properties (Section 12.7), which enables end-to-end + authentication schemes. + + Object Properties are serialized as a length in bytes followed by + Key-Value-Pairs (see Figure 2). + + Object Properties { + Properties Length (vi64), + Properties (..), + } + + Object Property types are registered in the IANA table 'MOQ + Properties'. See Section 15. + +11.3. Datagrams + + A single object can be conveyed in a datagram. The Track Alias field + (Section 11.1) indicates the track this Datagram belongs to. If an + endpoint receives a datagram with an unknown Track Alias, it MAY drop + the datagram or choose to buffer it for a brief period to handle + reordering with the control message that establishes the Track Alias. + + An Object received in an OBJECT_DATAGRAM message has an Object + Forwarding Preference = Datagram. + + To send an Object with Object Forwarding Preference = Datagram, + determine the length of the header and payload and send the Object as + datagram. When the total size is larger than the maximum datagram + size for the session, the Object will be dropped without any explicit + notification. + + Each session along the path between the Original Publisher and End + Subscriber might have different maximum datagram sizes. + Additionally, Object Properties (Section 11.2.1.2) can be added to + + + +Nandakumar, et al. Expires 4 March 2027 [Page 103] + +Internet-Draft moq-transport August 2026 + + + Objects as they pass through the MOQT network, increasing the size of + the Object and the chances it will exceed the maximum datagram size + of a downstream session and be dropped. + +11.3.1. Object Datagram + + An OBJECT_DATAGRAM carries a single object in a datagram. + + OBJECT_DATAGRAM { + Type Flags (vi64), + Track Alias (vi64), + Group ID (vi64), + [Object ID (vi64),] + [Publisher Priority (8),] + [Properties (..),] + [Object Status (vi64),] + [Object Payload (..),] + } + + Figure 24: MOQT OBJECT_DATAGRAM + + The Type Flags field in the OBJECT_DATAGRAM is a variable-length + integer that encodes a set of flags. All values defined in this + specification fit in a single-byte encoding (values less than 128). + If a received value has bit 4 set, or has a bit set whose meaning is + not specified, the endpoint MUST close the session with a + PROTOCOL_VIOLATION. + + The four low-order bits and bit 5 of the Type Flags field determine + which fields are present in the datagram: + + * The *PROPERTIES* bit (0x01) indicates when the Properties field is + present. When set to 1, the Object Properties structure defined + in Section 11.2.1.2 is present. When set to 0, the field is + absent. If an endpoint receives a datagram with the PROPERTIES + bit set and an Properties Length of 0, it MUST close the session + with a PROTOCOL_VIOLATION. + + * The *END_OF_GROUP* bit (0x02) indicates End of Group. When set to + 1, this indicates that no Object with the same Group ID and an + Object ID greater than the Object ID in this datagram exists. + + * The *ZERO_OBJECT_ID* bit (0x04) indicates when the Object ID field + is present. When set to 1, the Object ID field is omitted and the + Object ID is 0. When set to 0, the Object ID field is present. + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 104] + +Internet-Draft moq-transport August 2026 + + + * The *DEFAULT_PRIORITY* bit (0x08) indicates when the Priority + field is present. When set to 1, the Priority field is omitted + and this Object inherits the Publisher Priority specified in the + control message that established the subscription. When set to 0, + the Priority field is present. + + * The *STATUS* bit (0x20) indicates whether the datagram contains an + Object Status or Object Payload. When set to 1, the Object Status + field is present and there is no Object Payload. When set to 0, + the Object Payload is present and the Object Status field is + omitted. There is no explicit length field for the Object + Payload; the entirety of the transport datagram following the + Object header contains the payload. + + The following Type Flags values are invalid. If an endpoint receives + a datagram with any of these values, it MUST close the session with a + PROTOCOL_VIOLATION: + + * Values with both the STATUS bit (0x20) and END_OF_GROUP bit (0x02) + set. + + * Values with bit 4 (0x10) set. This bit is reserved and MUST be + zero. + + * Values with a bit set whose meaning is not specified. + + If an Object Datagram includes both the STATUS bit and PROPERTIES + bit, and the Object Status is not Normal (0x0), the endpoint MUST + close the session with a PROTOCOL_VIOLATION, because only Normal + Objects can have Properties. + +11.4. Streams + + When Objects are sent on streams, the stream begins with a Subgroup + or Fetch Header and is followed by one or more sets of serialized + Object fields. If a stream ends gracefully (i.e., the stream + terminates with a FIN) in the middle of a serialized Object, the + session SHOULD be closed with a PROTOCOL_VIOLATION. + + A publisher SHOULD NOT open more than one stream at a time with the + same Subgroup Header field values. + + + + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 105] + +Internet-Draft moq-transport August 2026 + + +11.4.1. Stream Cancellation + + Streams aside from the control streams MAY be canceled due to + congestion or other reasons by either the publisher or subscriber. + Early termination of a unidirectional stream does not affect the MOQT + application state, and therefore has no effect on outstanding + subscriptions. Closing a bidirectional request stream is governed by + Section 3.3.3. + +11.4.2. Subgroup Header + + All Objects on a Subgroup stream belong to the track identified by + Track Alias (see Section 11.1) and the Subgroup indicated by 'Group + ID' and Subgroup ID indicated by the SUBGROUP_HEADER. + + If an endpoint receives a subgroup with an unknown Track Alias, it + MAY abandon the stream, or choose to buffer it for a brief period to + handle reordering with the control message that establishes the Track + Alias. The endpoint MAY withhold stream flow control beyond the + SUBGROUP_HEADER until the Track Alias has been established. To + prevent deadlocks, endpoints MUST allocate connection flow control to + the control streams before allocating it to any data streams. + Otherwise, a receiver might wait for a control message containing a + Track Alias to release flow control, while the sender waits for flow + control to send the message. + + SUBGROUP_HEADER { + Type Flags (vi64), + Track Alias (vi64), + Group ID (vi64), + [Subgroup ID (vi64),] + [Publisher Priority (8),] + } + + Figure 25: MOQT SUBGROUP_HEADER + + All Objects received on a stream opened with SUBGROUP_HEADER have an + Object Forwarding Preference = Subgroup. + + The Type Flags field in the SUBGROUP_HEADER is a variable-length + integer that encodes a set of flags. All values defined in this + specification fit in a single-byte encoding (values less than 128). + + Bit 4 is always set to 1. The four low-order bits and bits 5-6 + determine which fields are present in the header: + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 106] + +Internet-Draft moq-transport August 2026 + + + * The *PROPERTIES* bit (0x01) indicates when the Properties field is + present in all Objects in this Subgroup. When set to 1, the + Object Properties structure defined in Section 11.2.1.2 is present + in all Objects; Objects with no properties set Properties Length + to 0. When set to 0, the field is never present. + + * The *SUBGROUP_ID_MODE* field (bits 1-2, mask 0x06) is a two-bit + field that determines the encoding of the Subgroup ID. To extract + this value, perform a bitwise AND with mask 0x06 and right-shift + by 1 bit: + + - 0b00: The Subgroup ID field is absent and the Subgroup ID is 0. + + - 0b01: The Subgroup ID field is absent and the Subgroup ID is + the Object ID of the first Object transmitted in this Subgroup. + + - 0b10: The Subgroup ID field is present in the header. + + - 0b11: Reserved for future use. + + * The *END_OF_GROUP* bit (0x08) indicates that this subgroup + contains the largest Object in the Group. When set to 1, the + subscriber can infer the final Object in the Group when the data + stream is terminated by a FIN. In this case, Objects that have + the same Group ID and an Object ID larger than the last Object + received on the stream do not exist. This does not apply when the + data stream is reset. + + * The *DEFAULT_PRIORITY* bit (0x20) indicates when the Priority + field is present. When set to 1, the Priority field is omitted + and this Subgroup inherits the Publisher Priority specified in the + control message that established the subscription. When set to 0, + the Priority field is present in the Subgroup header. + + * The *FIRST_OBJECT* bit (0x40) indicates that the first object in + this subgroup stream is the first object published in the subgroup + by the original publisher. + + The following Type Flags values are invalid. If an endpoint receives + a stream header with any of these values, it MUST close the session + with a PROTOCOL_VIOLATION: + + * Values with SUBGROUP_ID_MODE set to 0b11. This mode is reserved + for future use. + + * Values where bit 4 is not set. Bit 4 MUST be 1 for + SUBGROUP_HEADER. + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 107] + +Internet-Draft moq-transport August 2026 + + + * Values of 128 or greater (i.e., any value that requires more than + a one-byte variable-length integer encoding). + + To send an Object with Object Forwarding Preference = Subgroup, find + the open stream that is associated with the subscription, Group ID + and Subgroup ID, or open a new one and send the SUBGROUP_HEADER. + Then serialize the following fields. + + The Object Status field is only sent if the Object Payload Length is + zero. + + The Object ID Delta + 1 is added to the previous Object ID in the + Subgroup stream if there was one. The Object ID is the Object ID + Delta if it's the first Object in the Subgroup stream. If the + resulting Object ID would be greater than 2^64 - 1, the endpoint MUST + close the session with a PROTOCOL_VIOLATION. For example, a Subgroup + of sequential Object IDs starting at 0 will have 0 for all Object ID + Delta values. A consumer cannot infer information about the + existence of Objects between the current and previous Object ID in + the Subgroup (e.g. when Object ID Delta is non-zero) unless there is + a Prior Object ID Gap property (see Section 12.9). + + { + Object ID Delta (vi64), + [Properties (..),] + Object Payload Length (vi64), + [Object Status (vi64),] + [Object Payload (..),] + } + + Figure 26: MOQT Subgroup Object Fields + +11.4.3. Closing Subgroup Streams + + Subscribers will often need to know if they have received all objects + in a Subgroup, particularly if they serve as a relay or cache. QUIC + and Webtransport streams provide signals that can be used for this + purpose. Closing Subgroups promptly frees system resources and often + unlocks flow control credit to open more streams. + + If a sender has delivered all objects in a Subgroup to the QUIC + stream, except any Objects with Locations smaller than the + subscription's Start Location, it MUST close the stream with a FIN. + + If a sender closes the stream before delivering all such objects to + the QUIC stream, it MUST reset the stream. This includes, but is not + limited to: + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 108] + +Internet-Draft moq-transport August 2026 + + + * Either of the delivery timeouts defined in Section 8 + + * Early termination of subscription due to request cancellation + + * A publisher's decision to end the subscription early + + * A REQUEST_UPDATE moving the subscription's End Group to a smaller + Group or the Start Location to a larger Location + + * Omitting a Subgroup Object due to the subscriber's Forward State + + When RESET_STREAM_AT is used, the reliable_size SHOULD include the + stream header so the receiver can identify the corresponding + subscription and accurately account for reset data streams when + handling PUBLISH_DONE (see Section 10.12). Publishers that reset + data streams without using RESET_STREAM_AT with an appropriate + reliable_size can cause subscribers to hold on to subscription state + until a timeout expires. + + A sender might send all objects in a Subgroup and the FIN on a QUIC + stream, and then reset the stream. In this case, the receiving + application would receive the FIN if and only if all objects were + received. If the application receives all data on the stream and the + FIN, it can ignore any subsequent reset. + + If a sender will not deliver any objects from a Subgroup, it MAY send + a SUBGROUP_HEADER on a new stream, with no objects, and then send + RESET_STREAM_AT with a reliable_size equal to the length of the + stream header. This explicitly tells the receiver there is an unsent + Subgroup. + + A relay MUST NOT forward an Object on an existing Subgroup stream + unless it is the next Object in that Subgroup. A relay determines + that an Object is the next Object in the Subgroup if at least one of + the following is true: + + * The Object ID is one greater than the previous Object sent on this + Subgroup stream. + + * The Object was received on the same upstream Subgroup stream as + the previously sent Object on the downstream Subgroup stream, with + no other Objects in between, unless the intervening Objects did + not pass the subscriber's filters. + + * It determined all Object IDs between the current and previous + Object IDs on the Subgroup stream belong to different Subgroups or + do not exist, or do not pass the subscriber's filters. + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 109] + +Internet-Draft moq-transport August 2026 + + + If the relay does not know if an Object is the next Object, it MUST + reset the Subgroup stream and open a new one to forward it. + + Since SUBSCRIBEs always end on a group boundary, an ending + subscription can always cleanly close all its subgroups. A sender + that terminates a stream early for any other reason (e.g., to handoff + to a different sender) MUST reset the stream. Senders SHOULD + terminate a stream on Group boundaries to avoid doing so. + + An MOQT implementation that processes a stream FIN is assured it has + received all objects in a subgroup from the start of the + subscription. If a relay, it can forward stream FINs to its own + subscribers once those objects have been sent. A relay MAY treat + receipt of EndOfGroup or EndOfTrack objects as a signal to close + corresponding streams even if the FIN has not arrived, as further + objects on the stream would be a protocol violation. + + Similarly, an EndOfGroup message indicates the maximum Object ID in + the Group, so if all Objects in the Group have been received, a FIN + can be sent on any stream where the entire subgroup has been sent. + This might be complex to implement. + + Processing a reset means that there might be other objects in the + Subgroup beyond the last one received. A relay might immediately + reset the corresponding downstream stream, or it might attempt to + recover the missing Objects in an effort to send all the Objects in + the subgroups and the FIN. It also might send RESET_STREAM_AT with + reliable_size set to the last Object it has, so as to reliably + deliver the Objects it has while signaling that other Objects might + exist. + + A subscriber MAY send a QUIC STOP_SENDING frame for a subgroup stream + if the Group or Subgroup is no longer of interest to it. The + publisher SHOULD respond with a reset. If RESET_STREAM_AT is sent, + note that the receiver has indicated no interest in the objects, so + setting a reliable_size beyond the stream header is of questionable + utility. + + Resets and STOP_SENDING on SUBSCRIBE data streams have no impact on + other Subgroups in the Group or the subscription, although + applications might cancel all Subgroups in a Group at once. + + A publisher that receives a STOP_SENDING on a Subgroup stream SHOULD + NOT attempt to open a new stream to deliver additional Objects in + that Subgroup. However, if the publisher subsequently receives a + REQUEST_UPDATE that changes the Forward State from 0 to 1, it MAY + open a new stream to deliver Objects in that Subgroup, as the update + indicates the subscriber has renewed interest in forwarded Objects. + + + +Nandakumar, et al. Expires 4 March 2027 [Page 110] + +Internet-Draft moq-transport August 2026 + + + The application SHOULD use a relevant error code when resetting a + stream, as defined in Section 3.3.4. + +11.4.4. Fetch Header + + When a stream begins with FETCH_HEADER, all objects on the stream + belong to the track requested in the message identified by Request + ID. + + FETCH_HEADER { + Type (vi64) = 0x5, + Request ID (vi64), + } + + Figure 27: MOQT FETCH_HEADER + + Each Object sent on a FETCH stream after the FETCH_HEADER has the + following format: + + { + Serialization Flags (vi64), + [Group ID Delta (vi64),] + [Subgroup ID (vi64),] + [Object ID Delta (vi64),] + [Publisher Priority (8),] + [Properties (..),] + Object Payload Length (vi64), + [Object Payload (..),] + } + + Figure 28: MOQT Fetch Object Fields + + The Serialization Flags field defines the serialization of the + Object. It is a variable-length integer. When less than 128, the + bits represent flags described below. The following additional + values are defined: + + +=======+===========================+ + | Value | Meaning | + +=======+===========================+ + | 0x8C | End of Non-Existent Range | + +-------+---------------------------+ + | 0x10C | End of Unknown Range | + +-------+---------------------------+ + | 0x20C | End of Timed-Out Range | + +-------+---------------------------+ + + Table 7 + + + +Nandakumar, et al. Expires 4 March 2027 [Page 111] + +Internet-Draft moq-transport August 2026 + + + Any other value is a PROTOCOL_VIOLATION. + +11.4.4.1. Flags + + The two least significant bits (LSBs) of the Serialization Flags form + a two-bit field that defines the encoding of the Subgroup. To + extract this value, the Subscriber performs a bitwise AND operation + with the mask 0x03. + + +==============================+===============================+ + | Bitmask Result | Meaning | + | (Serialization Flags & 0x03) | | + +==============================+===============================+ + | 0x00 | Subgroup ID is zero | + +------------------------------+-------------------------------+ + | 0x01 | Subgroup ID is the prior | + | | Object's Subgroup ID | + +------------------------------+-------------------------------+ + | 0x02 | Subgroup ID is the prior | + | | Object's Subgroup ID plus one | + +------------------------------+-------------------------------+ + | 0x03 | The Subgroup ID field is | + | | present | + +------------------------------+-------------------------------+ + + Table 8 + + The following table defines additional flags within the Serialization + Flags field. Each flag is an independent boolean value, where a set + bit (1) indicates the corresponding condition is true. + + + + + + + + + + + + + + + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 112] + +Internet-Draft moq-transport August 2026 + + + +=========+==========================+=========================+ + | Bitmask | Condition if set | Condition if not set | + | | | (0) | + +=========+==========================+=========================+ + | 0x04 | Object ID Delta is | Object ID is the prior | + | | present | Object's ID plus one | + +---------+--------------------------+-------------------------+ + | 0x08 | Group ID Delta is | Group ID is the prior | + | | present | Object's Group ID | + +---------+--------------------------+-------------------------+ + | 0x10 | Priority field is | Priority is the prior | + | | present | Object's Priority | + +---------+--------------------------+-------------------------+ + | 0x20 | Properties field is | Properties field is not | + | | present | present | + +---------+--------------------------+-------------------------+ + | 0x40 | Datagram: ignore the two | Decode the Subgroup ID | + | | least significant bits | as indicated by the two | + | | | least significant bits | + +---------+--------------------------+-------------------------+ + + Table 9 + + The first Object MUST include a Group ID Delta and Object ID Delta, + and these values are the absolute Group ID and Object ID. If the + first Object in the FETCH response uses a flag that references fields + in the prior Object, the Subscriber MUST close the session with a + PROTOCOL_VIOLATION. + + If the Group ID Delta field is present on an Object other than the + first, the Group ID is computed from the Group ID Delta and the prior + Object's Group ID. If the Group Order is Ascending, the Group ID is + the prior Object's Group ID plus the Group ID Delta + 1. If the + Group Order is Descending, the Group ID is the prior Object's Group + ID minus the (Group ID Delta + 1). If the computed Group ID would be + less than 0 or greater than 2^64-1, the Subscriber MUST close the + Session with error 'PROTOCOL_VIOLATION'. + + When the Group ID Delta field is present, the Object ID is the value + of Object ID Delta if present. When the Group ID Delta field is not + present, the Object ID is the prior Object's ID plus the Object ID + Delta if present. If Object ID Delta is not present, the Object ID + is the prior Object's ID plus one, regardless of which group it + belongs to. If the computed Object ID would be greater than 2^64-1, + the Subscriber MUST close the Session with error + 'PROTOCOL_VIOLATION'. + + The Object Properties structure is defined in Section 11.2.1.2. + + + +Nandakumar, et al. Expires 4 March 2027 [Page 113] + +Internet-Draft moq-transport August 2026 + + + When encoding an Object with a Forwarding Preference of "Datagram" + (see Section 11.2.1.2), the object has no Subgroup ID. The publisher + MUST SET bit 0x40 to '1'. When 0x40 is set, it SHOULD set the two + least significant bits to zero and the subscriber MUST ignore the + bits. + +11.4.4.2. End of Range + + When Serialization Flags indicates an End of Range (e.g. values 0x8C, + 0x10C, or 0x20C), the Group ID and Object ID fields are present. + Subgroup ID, Priority and Properties are not present. All Objects + with Locations between the last serialized Object, if any, and this + Location, inclusive, either do not exist (when Serialization Flags is + 0x8C), are unknown (0x10C), or timed out (0x20C). A publisher SHOULD + NOT use End of Non-Existent Range in a FETCH response except to split + a range of Objects that will not be serialized into those that are + known not to exist and those with unknown or timed out status. + + When an Object follows an End of Range indicator and uses flags that + reference the "prior Object", the prior Object fields are determined + as follows: + + * Prior Group ID and prior Object ID: The values from the End of + Range indicator. + + * Prior Subgroup ID: The Subgroup ID from the last actual Object + before the End of Range indicator. If there was no prior Object, + using a flag that references the prior Subgroup ID is a + PROTOCOL_VIOLATION. + + * Prior Priority: The Priority from the last actual Object before + the End of Range indicator. If there was no prior Object, using a + flag that references the prior Priority is a PROTOCOL_VIOLATION. + +11.5. Padding + + An endpoint MAY send padding on unidirectional streams or datagrams. + Padding does not carry Objects or any other application data. An + endpoint can use padding to probe for additional bandwidth while + minimizing the impact on the delivery of application data. + + To avoid interfering with the delivery of Objects, senders SHOULD + send padding streams at a lower priority than any control stream or + Object data. + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 114] + +Internet-Draft moq-transport August 2026 + + +11.5.1. Padding Streams + + An endpoint MAY open a unidirectional stream with a stream type of + 0x132B3E28 to send padding data. The stream begins with the stream + type, followed by zero or more bytes that MUST all be set to zero. + + PADDING STREAM { + Type (vi64) = 0x132B3E28, + Padding Data (..) = 0x00.. + } + + Figure 29: MOQT Padding Stream + + The receiver MUST discard all data received on a padding stream to + prevent exhausting flow control. + + Either the sender or the receiver MAY cancel a padding stream at any + time without affecting any MOQT application state. + +11.5.2. Padding Datagrams + + An endpoint MAY send a datagram with a type of 0x132B3E29 to send + padding data. The datagram contains the type followed by zero or + more bytes that MUST all be set to zero. + + PADDING DATAGRAM { + Type (vi64) = 0x132B3E29, + Padding Data (..) = 0x00.. + } + + Figure 30: MOQT Padding Datagram + + The receiver MUST discard all data received in a padding datagram. + +11.6. Examples + + Sending a subgroup on one stream: + + + + + + + + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 115] + +Internet-Draft moq-transport August 2026 + + + Stream = 2 + + SUBGROUP_HEADER { + Type Flags = 0x14 + Track Alias = 2 + Group ID = 0 + Subgroup ID = 0 + Priority = 0 + } + { + Object ID = 0 + Object Payload Length = 4 + Payload = "abcd" + } + { + Object ID = 1 + Object Payload Length = 4 + Payload = "efgh" + } + + Sending a group on one stream, with the first object containing two + Properties. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 116] + +Internet-Draft moq-transport August 2026 + + + Stream = 2 + + SUBGROUP_HEADER { + Type Flags = 0x35 + Track Alias = 2 + Group ID = 0 + Subgroup ID = 0 + } + { + Object ID Delta = 0 (Object ID is 0) + Properties Length = 33 + { + Type = 4 + Value = 2186796243 + }, + { + Type = 77 + Length = 21 + Value = "traceID:123456" + } + Object Payload Length = 4 + Payload = "abcd" + } + { + Object ID Delta = 0 (Object ID is 1) + Properties Length = 0 + Object Payload Length = 4 + Payload = "efgh" + } + +12. MOQT Properties + + The following Properties are defined in MOQT. Each Property + specifies whether it can be used with Tracks, Objects, or both. + + Property types in ranges reserved for application-specific use + (0x78-0x7F, 0x3800-0x3FFF) are not defined by MOQT. See Section 2.5 + for usage guidance. + +12.1. SUBGROUP_DELIVERY_TIMEOUT + + SUBGROUP_DELIVERY_TIMEOUT (Property Type 0x06) is a Track and Object + Property. It is a variable-length integer. Its semantics are + defined in Section 8. As an Object Property on the first object in a + subgroup, it overrides the Track-level value for that subgroup; it is + ignored on any other object in the subgroup. + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 117] + +Internet-Draft moq-transport August 2026 + + +12.2. OBJECT_DELIVERY_TIMEOUT + + OBJECT_DELIVERY_TIMEOUT (Property Type 0x02) is a Track and Object + Property. It is a variable-length integer. Its semantics are + defined in Section 8. As an Object Property on the first object in a + subgroup, it overrides the Track-level value for that subgroup; it is + ignored on any other object in the subgroup. + +12.3. MAX CACHE DURATION + + MAX_CACHE_DURATION (Property Type 0x04) is a Track Property. + + It is an integer expressing the number of milliseconds an Object can + be served from a cache. If present, the relay MUST NOT start + forwarding any individual Object received through this subscription + or fetch after the specified number of milliseconds has elapsed since + the beginning of the Object was received. This means Objects earlier + in a multi-object stream will expire earlier than Objects later in + the stream. Once Objects have expired from cache, their state + becomes unknown (see Section 2.1). + + If MAX_CACHE_DURATION is not sent by the publisher, the Objects can + be cached until implementation constraints cause them to be evicted. + +12.4. DEFAULT PUBLISHER PRIORITY + + DEFAULT PUBLISHER PRIORITY (Property Type 0x0E) is a Track Property + that specifies the priority of a subscription relative to other + subscriptions in the same session. The value is from 0 to 255 and + lower numbers get higher priority. See Section 7. Priorities above + 255 are invalid. Subgroups and Datagrams for this subscription + inherit this priority, unless they specifically override it. + + If omitted, the Default Publisher Priority is 128. + +12.5. DEFAULT PUBLISHER GROUP ORDER + + DEFAULT_PUBLISHER_GROUP_ORDER (Property Type 0x22) is a Track + Property. + + It is an enum indicating the publisher's preference for prioritizing + Objects from different groups within the same subscription (see + Section 7). The allowed values are Ascending (0x1) or Descending + (0x2). If an endpoint receives a value outside this range, it MUST + close the session with PROTOCOL_VIOLATION. + + If omitted, the publisher's preference is Ascending (0x1). + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 118] + +Internet-Draft moq-transport August 2026 + + +12.6. DYNAMIC GROUPS + + DYNAMIC_GROUPS (Property Type 0x30) is a Track Property. The allowed + values are 0 or 1. When the value is 1, it indicates that the + subscriber can request the Original Publisher to start a new Group by + including the NEW_GROUP_REQUEST parameter in REQUEST_UPDATE for this + Track. If an endpoint receives a value larger than 1, it MUST close + the session with PROTOCOL_VIOLATION. + + If omitted, the value is 0. + +12.7. Immutable Properties + + Immutable Properties (Property Type 0xB) is a Track or Object + Property that contains a sequence of Key-Value-Pairs (see Figure 2) + that are themselves Track or Object Properties, respectively. + + Immutable Properties { + Type (0xB), + Length (vi64), + Key-Value-Pair (..) ... + } + + This Property can be added by the Original Publisher, but MUST NOT be + added by Relays. This Property MUST NOT be modified or removed and + the serialization (e.g. variable-length integer encodings) of the + Key-Value-Pairs MUST NOT change). Like other Properties, Relays MUST + cache Immutable Properties if the Object or Track are cached and MUST + forward it. Relays MAY decode and view the Properties in the Key- + Value-Pairs. + + Unless specified by a particular Property specification, Properties + MAY appear either in the mutable property list or inside Immutable + Properties. When looking for the value of a property, processors + MUST search both the mutable properties and the contents of Immutable + Properties. + + If a Property allows multiple values, the same Property Type MAY + appear in both the mutable list and inside Immutable Properties, + unless prohibited by the Property specification. + + A Track is considered malformed (see Section 2.4.2) if any of the + following conditions are detected: + + * An Object contains an Immutable Properties property that contains + another Immutable Properties key. + + * A Key-Value-Pair cannot be parsed. + + + +Nandakumar, et al. Expires 4 March 2027 [Page 119] + +Internet-Draft moq-transport August 2026 + + + The following figure shows an example Object structure with a + combination of mutable and immutable properties and end to end + encrypted metadata in the Object payload. + + Object Header Object Payload +<------------------------------------------------> <-------------------> ++--------+-------+------------+-------+-----------+--------------------+ +| Object | Ext 1 | Immutable | Ext N | [Payload] | Private Properties | +| Fields | | Properties | | [Length] | App Payload | ++--------+-------+------------+-------+-----------+--------------------+ + xxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxx + yyyyyyyyyyyyyyyyyyyy +x = e2e Authenticated Data +y = e2e Encrypted Data +EXT 1 and EXT N can be modified or removed by Relays + + An Object MUST NOT contain more than one instance of this property. + +12.8. Prior Group ID Gap + + Prior Group ID Gap only applies to Objects, not Tracks. + + Prior Group ID Gap (Property Type 0x3C) is a variable-length integer + containing the number of Groups prior to the current Group that do + not, and will never, exist. For example, if the Original Publisher + is publishing an Object in Group 7 and knows it will never publish + any Objects in Group 8 or Group 9, it can include Prior Group ID Gap + = 2 in any number of Objects in Group 10, as it sees fit. A Track is + considered malformed (see Section 2.4.2) if any of the following + conditions are detected: + + * An Object contains more than one instance of Prior Group ID Gap. + + * A Group contains more than one Object with different values for + Prior Group ID Gap. + + * An Object has a Prior Group ID Gap larger than the Group ID. + + * An endpoint receives an Object with a Prior Group ID Gap covering + an Object it previously received. + + * An endpoint receives an Object with a Group ID within a previously + communicated gap. + + Use of this property is optional, as publishers might not know the + prior gap size, or there may not be a gap. If Prior Group ID Gap is + not present, the receiver cannot infer any information about the + existence of prior groups (see Section 2.3.1). + + + +Nandakumar, et al. Expires 4 March 2027 [Page 120] + +Internet-Draft moq-transport August 2026 + + + This property can be added by the Original Publisher, but MUST NOT be + added by relays. This property MAY be removed by a relay when the + object in question is served via FETCH, and the gap that the property + communicates is already communicated implicitly in the FETCH + response; it MUST NOT be modified or removed otherwise. + + An Object MUST NOT contain more than one instance of this property. + +12.9. Prior Object ID Gap + + Prior Object ID Gap only applies to Objects, not Tracks. + + Prior Object ID Gap (Property Type 0x3E) is a variable-length integer + containing the number of Objects prior to the current Object that do + not, and will never, exist. For example, if the Original Publisher + is publishing Object 10 in Group 3 and knows it will never publish + Objects 8 or 9 in this Group, it can include Prior Object ID Gap = 2. + A Track is considered malformed (see Section 2.4.2) if any of the + following conditions are detected: + + * An Object contains more than one instance of Prior Object ID Gap. + + * An Object has a Prior Object ID Gap larger than the Object ID. + + * An endpoint receives an Object with a Prior Object ID Gap covering + an Object it previously received. + + * An endpoint receives an Object with an Object ID within a + previously communicated gap. + + Use of this property is optional, as publishers might not know the + prior gap size, or there might not be a gap. If Prior Object ID Gap + is not present, the receiver cannot infer any information about the + existence of prior objects (see Section 2.1). + + This property can be added by the Original Publisher, but MUST NOT be + added by relays. This property MAY be removed by a relay when the + object in question is served via FETCH, and the gap that the property + communicates is already communicated implicitly in the FETCH + response; it MUST NOT be modified or removed otherwise. + + An Object MUST NOT contain more than one instance of this property. + + + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 121] + +Internet-Draft moq-transport August 2026 + + +13. Security Considerations + + MOQT is a protocol used hop-by-hop between original publishers to + relay, (possibly) relay to relay, and relay to end subscribers. + Thus, the security considerations need to consider first what happens + between two Endpoints, but also consider the impacts end to end over + several hops of MOQT. + + MOQT uses a trust model where on each hop the Endpoints need to be + securely identified, authorized to use resources of the peer, provide + confidentiality and integrity to prevent third party attacks and + limit monitoring and leakage of privacy sensitive information. The + relays within the chain from original publisher to end subscribers + will have access to Track names, Track Properties, Object Properties, + as well as the object's content unless it is end-to-end encrypted + Section 13.4. + + Publishers, including Relays, require authorization to prevent + unauthorized subscriptions to content. Subscription requests can + carry authorization tokens (see Section 13.3) to prove the + subscriber's right to access specific tracks or namespaces. Relays + that aggregate subscriptions from multiple downstream subscribers + MUST ensure each subscriber is independently authorized. + +13.1. Subscription Amplification + + A malicious subscriber could attempt to overwhelm a publisher or + relay by requesting subscriptions to many tracks simultaneously. + Relays SHOULD implement rate limiting on subscription requests and + MAY reject excessive subscriptions with REQUEST_ERROR using the + EXCESSIVE_LOAD error code. Publishers SHOULD monitor the number of + active subscriptions and enforce limits to prevent resource + exhaustion from a single subscriber or session. + + TODO: Describe Cache Poisoning attacks + +13.2. Communication Security + + MOQT depends on a secure transport to provide confidentiality, + integrity and endpoint authentication between subscriber and + publisher. Implementations use QUIC or WebTransport to fulfill the + basic communication security requirements and these implementations + SHOULD follow best practices for TLS 1.3 and QUIC. Relays MUST use + authentication to prevent impersonation (Section 13.3.3). + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 122] + +Internet-Draft moq-transport August 2026 + + + Note that the basic security protection offered by QUIC or TCP/TLS + does not prevent traffic pattern analysis. Object sizes, sizes of + request messages, etc can make it possible for a third party observer + to identify media content, user patterns and media stream origin. + +13.3. Authorization + + MOQT supports authorization via mutual TLS (mTLS) for endpoint + identification and via token-based schemes for fine-grained, + application-defined access control. The two mechanisms can be used + together. + +13.3.1. Mutual TLS + + In mutual TLS, both peers present an X.509 certificate during the TLS + 1.3 handshake ([RFC8446]), carried in the underlying transport. An + endpoint that verifies a server certificate does so following + [RFC9525]. An application that authenticates clients via mTLS + defines how a client certificate maps to identity. + + Once a peer is authenticated, an application MAY use attributes in + the peer's certificate as an input to authorization decisions; the + granularity and policy of such authorization is out of scope for this + document. ### Authorization Tokens {#sec-tokens} + + MOQT has functionality to carry Authorization tokens as message + parameters. These tokens can vary based on the application + requirements. Two variants of authorization tokens have already been + defined for MOQT, and more are expected in the future. The current + tokens are Privacy Pass Authentication for Media over QUIC [PPA] and + Authentication scheme for MOQT using Common Access Tokens [CAT]. + + Tokens are expected to contain information about which actions and + which resources the endpoint providing the token is authorized to + perform and access. Relays will verify the token to ensure that the + request is authorized. + +13.3.2. Replay Attacks + + Replay protection for authorization tokens is the responsibility of + the specific token scheme used. Token schemes such as [CAT] and + [PPA] include requirements for relays when processing tokens and + requests. + + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 123] + +Internet-Draft moq-transport August 2026 + + +13.3.3. Preventing Impersonation + + A relay MUST ensure that a client cannot publish to namespaces or + tracks belonging to another identity. Impersonation occurs when a + client publishes objects that appear to originate from a different + publisher — for example, by targeting a namespace containing another + user's identifier. + + To prevent impersonation, a relay MUST verify that the authenticated + identity or token scope permits publishing to the specific namespace. + The mapping from authenticated identity to permitted namespaces is + determined by the authorization framework in use. + + When using bearer token-based authentication (e.g., [CAT]), a token + that is bound to a client-held key via a confirmation claim prevents + a stolen token from being replayed by a different party. + + When unlinkable access is used (e.g., [PPA]), the token's scope + extensions determine which namespaces the bearer can publish to. + Impersonation is still prevented because the token does not grant + access beyond its defined scope. + + A relay that does not enforce these checks allows any connected + client to inject content into arbitrary namespaces, breaking the + integrity of content delivery. + +13.4. Media Security + + MOQT uses secure transports that provide confidentiality and + integrity protection. However, media objects are accessible to + relays, and are subject to both intentional and accidental + modification, unless they are additionally end-to-end protected. + + The media objects transported by MOQT in various tracks from various + original publishers are subject to several considerations. The first + is source authenticity, i.e. to know that the received media objects + are what the original publisher actually published. In addition to + the media objects, it can also be important to authenticate some + Track and Object Properties. For example, timestamps are crucial to + understand where on the timeline this media fragment belongs. + + The second aspect is content confidentiality. Beyond direct relay + access to media objects, object sizes and traffic patterns enable + analysis of content. Track namespace and track name can also be + analyzed and correlated between end subscribers by relays. + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 124] + +Internet-Draft moq-transport August 2026 + + + Consistent with the principle of confidential operation by default, + publishers can apply end-to-end object encryption, for example using + Secure Objects ([I-D.ietf-moq-secure-objects]), so that relays retain + access only to the metadata required for forwarding. Such end-to-end + security mechanisms are external to this specification and + additionally provide source authenticity. MOQT's object model + enables both the object data and Object Properties to be + confidentiality and integrity protected, or integrity protected only. + + Secure key distribution for end-to-end encryption is specific to the + encryption system and deployment, and outside the scope of this + document. + +13.5. Resource Exhaustion + + Live content requires significant bandwidth and resources. Failure + to set limits will quickly cause resource exhaustion. + + MOQT uses stream limits and flow control to impose resource limits at + the network layer. Endpoints SHOULD set flow control limits based on + the anticipated bitrate. + + Endpoints MAY impose a MAX STREAM count limit which would restrict + the number of concurrent streams which an application could have in + flight. + + The publisher prioritizes and transmits streams out of order. + Streams might be starved indefinitely during congestion. The + publisher and subscriber MUST cancel a stream, preferably the one + with the lowest priority, after reaching a resource limit. + +13.6. Timeouts + + Implementations are advised to use timeouts to prevent resource + exhaustion attacks by a peer that does not send expected data within + an expected time. Each implementation is expected to set its own + timeouts. + +13.6.1. Idle Connection Handling + + The transport connection (e.g., QUIC) underlying a MOQT session can + close due to idle timeout if no data is exchanged, either because + there are no established subscriptions or the established + subscriptions are not publishing Objects frequently. This includes + publisher sessions that have issued a PUBLISH_NAMESPACE and are + waiting for subscribers. + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 125] + +Internet-Draft moq-transport August 2026 + + + Implementations that want to keep idle sessions open have several + options: + + * Use transport-layer keep-alive mechanisms, such as QUIC PING + frames, to prevent idle timeout closure. + + * Send periodic control messages, for example REQUEST_UPDATE with no + modified Message Parameters. + + * Accept that idle connections can close and implement reconnection + logic when needed. + + The choice of mechanism is implementation-specific. + +13.7. Relay security considerations + +13.7.1. State maintenance + + A Relay SHOULD have mechanisms to prevent malicious endpoints from + flooding it with PUBLISH_NAMESPACE, SUBSCRIBE_NAMESPACE, or + SUBSCRIBE_TRACKS requests that could bloat data structures. It could + use QUIC stream limits to limit the number of such requests, or could + have application-specific policies that can reject incoming requests + that cause the state maintenance for the session to be excessive. + +13.7.2. SUBSCRIBE_NAMESPACE and SUBSCRIBE_TRACKS with short prefixes + + A Relay can use authorization rules in order to prevent subscriptions + closer to the root of a large prefix tree. Otherwise, if an entity + sends a relay a SUBSCRIBE_NAMESPACE or SUBSCRIBE_TRACKS message with + a short prefix, it can cause the relay to send a large volume of + NAMESPACE or PUBLISH messages. As changes occur in the tree of + namespaces, the relay would have to send matching NAMESPACE/ + NAMESPACE_DONE messages or initiate new PUBLISH streams. + +13.8. Implementation Identification Fingerprinting + + The MOQT_IMPLEMENTATION option (Section 10.3.1.5) can reveal + information that contributes to fingerprinting, a set of techniques + for identifying a specific endpoint over time through its unique set + of characteristics. + + Detailed implementation information, including specific version + numbers, build identifiers, or platform details, can create a unique + fingerprint that enables tracking endpoints across sessions without + their awareness. When combined with other session characteristics, + even minimal implementation identification can contribute to + distinguishing one endpoint from another. + + + +Nandakumar, et al. Expires 4 March 2027 [Page 126] + +Internet-Draft moq-transport August 2026 + + + To mitigate fingerprinting risks: + + * Implementations SHOULD send only the minimum information necessary + for interoperability debugging. A short implementation name and + major version number are typically sufficient. + + * Implementations SHOULD NOT include detailed system information, + build numbers, or other attributes that could uniquely identify a + specific instance or user. + + * Privacy-conscious deployments MAY omit the MOQT_IMPLEMENTATION + option entirely or send a generic value. + + * Implementations MAY provide users with the ability to configure or + disable the MOQT_IMPLEMENTATION option. + + Operators are advised that detailed implementation identification + facilitates the same privacy concerns as persistent identifiers, + since it enables correlation of sessions across time. + +13.9. Logging of Untrusted String Fields + + The Reason Phrase (Section 1.4.4) and MOQT_IMPLEMENTATION option + (Section 10.3.1.5) carry sender-controlled text that is commonly + written to logs. Even though these fields are UTF-8 encoded, an + endpoint that logs or renders them SHOULD sanitize them first (for + example, by escaping bytes outside the printable ASCII range), since + unsanitized values can enable log injection or terminal escape + sequence injection. + +14. Grease + + To ensure that implementations correctly handle unknown values and do + not fail when encountering protocol extensions they do not + understand, this document reserves a range of values for the purpose + of greasing; see Section 3.3 of [RFC9170]. + + Grease values follow the pattern 0x7f * N + 0x9D for non-negative + integer values of N (that is, 0x9D, 0x11C, ..., 0x3fffffffffffffde). + + The following registries include GREASE reservations: + + * Setup Options (Section 15.4) + + * Properties (Section 15.8) + + * Session Termination Error Codes (Section 15.11.1) + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 127] + +Internet-Draft moq-transport August 2026 + + + * REQUEST_ERROR Codes (Section 15.11.2) + + * PUBLISH_DONE Codes (Section 15.11.3) + + * Stream Reset Error Codes (Section 15.11.4) + + * MOQT Auth Token Type + + Because new values in these registries can be defined without + negotiation, implementations MUST handle unknown values gracefully. + Endpoints MUST NOT close the session solely because they received an + unknown value. The following rules apply: + + Setup Options with reserved identifiers have no semantics and can + carry arbitrary values. Endpoints MUST ignore unknown Setup Options + as specified in Section 10.3. + + Unknown Properties MUST be handled as specified in Section 2.5. + + Receipt of an unknown error code in any error context (Session + Termination, REQUEST_ERROR, PUBLISH_DONE, or Data Stream Reset) MUST + be treated as equivalent to INTERNAL_ERROR for that context. An + endpoint MUST NOT close the session because it received an unknown + error code in a REQUEST_ERROR or PUBLISH_DONE. + +15. IANA Considerations + + TODO: fill out currently missing registries: + + * MOQT ALPN values + + * Message types + + * Session-Level Track Names + +15.1. URI Scheme Registrations + + This document requests the registration of the following URI schemes + in the "Uniform Resource Identifier (URI) Schemes" registry, per + [RFC7595]: + +15.1.1. "moqt" URI Scheme Registration + + Scheme name: moqt + + Status: Permanent + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 128] + +Internet-Draft moq-transport August 2026 + + + Applications/protocols that use this scheme name: Media over QUIC + Transport (MOQT) over native QUIC or WebTransport, as defined in this + document. + + Contact: IETF MoQ Working Group (moq@ietf.org) + + Change controller: IETF + + References: This document + +15.2. Media Type Registration + + This document registers the following media type in the "Media Types" + registry [RFC6838]: + + Type name: application + + Subtype name: moqt + + Required parameters: N/A + + Optional parameters: N/A + + Encoding considerations: This media type is used to identify + resources accessed via the moqt URI scheme. It is not used to label + the content of MOQT objects, which are defined by separate media + types in application-specific specifications. + + Security considerations: See the Security Considerations section of + this document. + + Interoperability considerations: N/A + + Published specification: This document + + Applications that use this media type: Implementations of the Media + over QUIC Transport (MOQT) protocol. + + Fragment identifier considerations: Fragment identifiers for + application/moqt follow the syntax defined in Section 3.1.2. + + Additional information: N/A + + Contact: IETF MoQ Working Group (moq@ietf.org) + + Change controller: IETF + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 129] + +Internet-Draft moq-transport August 2026 + + +15.3. MOQT URI Fragment Types + + This document establishes the "MOQT URI Fragment Types" registry. + This registry governs fragment type identifiers used in moqt URI + fragments as defined in Section 3.1.2. + + New fragment type identifiers are registered using the Specification + Required policy ([RFC8126], Section 4.6). + + Each entry in the registry contains the following fields: + + | Fragment Type | Description | + Specification | |:--------------|:------------|:--------------| + + This registry is initially empty. + +15.4. Setup Options + + +=================+===========================+==================+ + | Type | Name | Specification | + +=================+===========================+==================+ + | 0x01 | PATH | Section 10.3.1.2 | + +-----------------+---------------------------+------------------+ + | 0x03 | AUTHORIZATION_TOKEN | Section 10.3.1.4 | + +-----------------+---------------------------+------------------+ + | 0x04 | MAX_AUTH_TOKEN_CACHE_SIZE | Section 10.3.1.3 | + +-----------------+---------------------------+------------------+ + | 0x05 | AUTHORITY | Section 10.3.1.1 | + +-----------------+---------------------------+------------------+ + | 0x06 | MAX_FILTER_RANGES | Section 10.3.1.6 | + +-----------------+---------------------------+------------------+ + | 0x07 | MOQT_IMPLEMENTATION | Section 10.3.1.5 | + +-----------------+---------------------------+------------------+ + | 0x08 | MAX_REQUEST_UPDATES | Section 10.3.1.7 | + +-----------------+---------------------------+------------------+ + | 0x7f * N + 0x9D | Reserved for greasing | Section 14 | + +-----------------+---------------------------+------------------+ + + Table 10 + + Endpoints MUST ignore unknown Setup Options as specified in + Section 10.3. + + + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 130] + +Internet-Draft moq-transport August 2026 + + + New Setup Option types are registered using the Specification + Required policy ([RFC8126], Section 4.6). Provisional registrations + are permitted to allow experimentation and avoid codepoint collisions + between independent implementations. There is no reserved range for + private or application-specific use; implementations that need custom + Setup Options SHOULD request a provisional registration. + +15.5. Authorization Token Alias Type + + +======+===========+================+ + | Code | Name | Specification | + +======+===========+================+ + | 0x0 | DELETE | Section 10.2.2 | + +------+-----------+----------------+ + | 0x1 | REGISTER | Section 10.2.2 | + +------+-----------+----------------+ + | 0x2 | USE_ALIAS | Section 10.2.2 | + +------+-----------+----------------+ + | 0x3 | USE_VALUE | Section 10.2.2 | + +------+-----------+----------------+ + + Table 11 + +15.6. MOQT Auth Token Type + + +=================+=======================+================+ + | Code | Name | Specification | + +=================+=======================+================+ + | 0x0 | Reserved | Section 10.2.2 | + +-----------------+-----------------------+----------------+ + | 0x7f * N + 0x9D | Reserved for greasing | Section 14 | + +-----------------+-----------------------+----------------+ + + Table 12 + +15.7. Message Parameters + + +================+===========================+=================+ + | Parameter Type | Parameter Name | Specification | + +================+===========================+=================+ + | 0x02 | OBJECT_DELIVERY_TIMEOUT | Section 10.2.4 | + +----------------+---------------------------+-----------------+ + | 0x03 | AUTHORIZATION_TOKEN | Section 10.2.2 | + +----------------+---------------------------+-----------------+ + | 0x04 | RENDEZVOUS_TIMEOUT | Section 10.2.6 | + +----------------+---------------------------+-----------------+ + | 0x06 | SUBGROUP_DELIVERY_TIMEOUT | Section 10.2.3 | + +----------------+---------------------------+-----------------+ + + + +Nandakumar, et al. Expires 4 March 2027 [Page 131] + +Internet-Draft moq-transport August 2026 + + + | 0x08 | EXPIRES | Section 10.2.16 | + +----------------+---------------------------+-----------------+ + | 0x09 | LARGEST_OBJECT | Section 10.2.17 | + +----------------+---------------------------+-----------------+ + | 0x0A | FILL_TIMEOUT | Section 10.2.5 | + +----------------+---------------------------+-----------------+ + | 0x10 | FORWARD | Section 10.2.18 | + +----------------+---------------------------+-----------------+ + | 0x20 | SUBSCRIBER_PRIORITY | Section 10.2.7 | + +----------------+---------------------------+-----------------+ + | 0x21 | LOCATION_FILTER | Section 10.2.9 | + +----------------+---------------------------+-----------------+ + | 0x22 | GROUP_ORDER | Section 10.2.8 | + +----------------+---------------------------+-----------------+ + | 0x23 | FILL_PARAMETERS | Section 10.2.15 | + +----------------+---------------------------+-----------------+ + | 0x25 | SUBGROUP_FILTER | Section 10.2.10 | + +----------------+---------------------------+-----------------+ + | 0x26 | OBJECTID_FILTER | Section 10.2.11 | + +----------------+---------------------------+-----------------+ + | 0x27 | PRIORITY_FILTER | Section 10.2.12 | + +----------------+---------------------------+-----------------+ + | 0x28 | OBJECT_PROPERTY_FILTER | Section 10.2.13 | + +----------------+---------------------------+-----------------+ + | 0x29 | TRACK_PROPERTY_FILTER | Section 10.2.14 | + +----------------+---------------------------+-----------------+ + | 0x32 | NEW_GROUP_REQUEST | Section 10.2.19 | + +----------------+---------------------------+-----------------+ + | 0x34 | TRACK_NAMESPACE_PREFIX | Section 10.2.20 | + +----------------+---------------------------+-----------------+ + | 0x35 | INCLUDE_PROPERTIES | Section 10.2.21 | + +----------------+---------------------------+-----------------+ + + Table 13 + + * Message Parameters - List which params can be repeated in the + table. + +15.8. Properties + + +==========+===============================+========+===============+ + | Type | Name | Scope | Specification | + +==========+===============================+========+===============+ + | 0x02 | OBJECT_DELIVERY_TIMEOUT | Track, | Section 12.2 | + | | | Object | | + +----------+-------------------------------+--------+---------------+ + | 0x04 | MAX_CACHE_DURATION | Track | Section 12.3 | + +----------+-------------------------------+--------+---------------+ + + + +Nandakumar, et al. Expires 4 March 2027 [Page 132] + +Internet-Draft moq-transport August 2026 + + + | 0x06 | SUBGROUP_DELIVERY_TIMEOUT | Track, | Section 12.1 | + | | | Object | | + +----------+-------------------------------+--------+---------------+ + | 0x0B | IMMUTABLE_PROPERTIES | Track, | Section 12.7 | + | | | Object | | + +----------+-------------------------------+--------+---------------+ + | 0x0E | DEFAULT_PUBLISHER_PRIORITY | Track | Section 12.4 | + +----------+-------------------------------+--------+---------------+ + | 0x22 | DEFAULT_PUBLISHER_GROUP_ORDER | Track | Section 12.5 | + +----------+-------------------------------+--------+---------------+ + | 0x30 | DYNAMIC_GROUPS | Track | Section 12.6 | + +----------+-------------------------------+--------+---------------+ + | 0x3C | PRIOR_GROUP_ID_GAP | Object | Section 12.8 | + +----------+-------------------------------+--------+---------------+ + | 0x3E | PRIOR_OBJECT_ID_GAP | Object | Section 12.9 | + +----------+-------------------------------+--------+---------------+ + | 0x7f | Reserved for greasing | Any | Section 14 | + | * N + | | | | + | 0x9D | | | | + +----------+-------------------------------+--------+---------------+ + + Table 14 + + The following table contains provisional registrations for other + active drafts in the moq wg. These entries share the same Property + Type space as the table above. + + + + + + + + + + + + + + + + + + + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 133] + +Internet-Draft moq-transport August 2026 + + + +====+=====================+======+===============================+ + |Type| Name |Scope | Specification | + +====+=====================+======+===============================+ + |0x10| TIMESTAMP |Object| draft-ietf-moq-loc | + +----+---------------------+------+-------------------------------+ + |0x08| TIMESCALE |Track,| draft-ietf-moq-loc | + | | |Object| | + +----+---------------------+------+-------------------------------+ + |0x09| VIDEO_FRAME_MARKING |Object| draft-ietf-moq-loc | + +----+---------------------+------+-------------------------------+ + |0x0C| AUDIO_LEVEL |Object| draft-ietf-moq-loc | + +----+---------------------+------+-------------------------------+ + |0x0D| VIDEO_CONFIG |Track,| draft-ietf-moq-loc | + | | |Object| | + +----+---------------------+------+-------------------------------+ + |0x0F| AUDIO_CONFIG |Track,| draft-ietf-moq-loc | + | | |Object| | + +----+---------------------+------+-------------------------------+ + |0x0A| ENCRYPTED_LIST |Object| draft-ietf-moq-secure-objects | + +----+---------------------+------+-------------------------------+ + |0x32| PADDING |Object| draft-ietf-moq-secure-objects | + +----+---------------------+------+-------------------------------+ + + Table 15 + + Endpoints MUST ignore unknown Property types, skipping them according + to the Key-Value-Pair encoding; odd types use their length field, + even types are skipped by parsing a variable-length integer value. + + * MOQ Properties - we wish to define the following registration + policies: + + - 0x00 to 0x77: Standards Action or IESG Approval (1-byte + encoding) + + - 0x78 to 0x7F: Reserved for application-specific use (1-byte + encoding, no registration permitted) + + - 0x80 to 0x37FF: Specification Required (2-byte encoding) + + - 0x3800 to 0x3FFF: Reserved for application-specific use (2-byte + encoding, no registration permitted) + + - 0x4000 to 0x7FFF: Reserved for Mandatory Track Properties (see + Section 2.5.1). Properties registered in this range MUST have + Track scope; Object scope properties MUST NOT be registered in + this range. + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 134] + +Internet-Draft moq-transport August 2026 + + + - 0x8000 and above: First Come First Served + + Code points reserved for application-specific use will never be + allocated by IANA. Applications using these values do not need to + coordinate with IANA. Note that applications consuming tracks + from uncoordinated sources may encounter different semantics for + the same code points, creating potential collision risks. + +15.9. Object Status + + This document establishes a registry for Object Status values (see + Section 11.2.1.1). The "Payload" column indicates whether an Object + with that status is permitted to carry a non-empty payload. + + +======+==============+=========+==================+ + | Code | Name | Payload | Specification | + +======+==============+=========+==================+ + | 0x0 | Normal | Yes | Section 11.2.1.1 | + +------+--------------+---------+------------------+ + | 0x3 | End of Group | No | Section 11.2.1.1 | + +------+--------------+---------+------------------+ + | 0x4 | End of Track | No | Section 11.2.1.1 | + +------+--------------+---------+------------------+ + + Table 16 + + New Object Status values are registered using the Specification + Required policy ([RFC8126], Section 4.6). Each registration MUST + indicate whether the status permits a payload. + +15.10. Session-Level Track Names + + This document establishes a registry for session-level track names + under the .session namespace (see Section 3.2.2). The registration + policy is Specification Required (per [RFC8126], Section 4.6). + + Each registration must include: + + + + + + + + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 135] + +Internet-Draft moq-transport August 2026 + + + +=================+==================================+ + | Field | Description | + +=================+==================================+ + | Track Namespace | The track namespace under the | + | | .session namespace, can be empty | + +-----------------+----------------------------------+ + | Track Name | The track name (bytes) within | + | | the full namespace | + +-----------------+----------------------------------+ + | Description | Brief description of the track's | + | | purpose | + +-----------------+----------------------------------+ + | Change | Who may update the registration | + | Controller | | + +-----------------+----------------------------------+ + | Specification | Reference to the defining | + | | specification | + +-----------------+----------------------------------+ + + Table 17 + + This document does not define any initial entries. + +15.11. Error Codes + +15.11.1. Session Termination Error Codes + + +============================+=================+===============+ + | Name | Code | Specification | + +============================+=================+===============+ + | NO_ERROR | 0x0 | Section 3.5 | + +----------------------------+-----------------+---------------+ + | INTERNAL_ERROR | 0x1 | Section 3.5 | + +----------------------------+-----------------+---------------+ + | UNAUTHORIZED | 0x2 | Section 3.5 | + +----------------------------+-----------------+---------------+ + | PROTOCOL_VIOLATION | 0x3 | Section 3.5 | + +----------------------------+-----------------+---------------+ + | INVALID_REQUEST_ID | 0x4 | Section 3.5 | + +----------------------------+-----------------+---------------+ + | DUPLICATE_TRACK_ALIAS | 0x5 | Section 3.5 | + +----------------------------+-----------------+---------------+ + | KEY_VALUE_FORMATTING_ERROR | 0x6 | Section 3.5 | + +----------------------------+-----------------+---------------+ + | INVALID_PATH | 0x8 | Section 3.5 | + +----------------------------+-----------------+---------------+ + | MALFORMED_PATH | 0x9 | Section 3.5 | + +----------------------------+-----------------+---------------+ + + + +Nandakumar, et al. Expires 4 March 2027 [Page 136] + +Internet-Draft moq-transport August 2026 + + + | GOAWAY_TIMEOUT | 0x10 | Section 3.5 | + +----------------------------+-----------------+---------------+ + | CONTROL_MESSAGE_TIMEOUT | 0x11 | Section 3.5 | + +----------------------------+-----------------+---------------+ + | DATA_STREAM_TIMEOUT | 0x12 | Section 3.5 | + +----------------------------+-----------------+---------------+ + | AUTH_TOKEN_CACHE_OVERFLOW | 0x13 | Section 3.5 | + +----------------------------+-----------------+---------------+ + | DUPLICATE_AUTH_TOKEN_ALIAS | 0x14 | Section 3.5 | + +----------------------------+-----------------+---------------+ + | MALFORMED_AUTH_TOKEN | 0x16 | Section 3.5 | + +----------------------------+-----------------+---------------+ + | UNKNOWN_AUTH_TOKEN_ALIAS | 0x17 | Section 3.5 | + +----------------------------+-----------------+---------------+ + | EXPIRED_AUTH_TOKEN | 0x18 | Section 3.5 | + +----------------------------+-----------------+---------------+ + | INVALID_AUTHORITY | 0x19 | Section 3.5 | + +----------------------------+-----------------+---------------+ + | MALFORMED_AUTHORITY | 0x1A | Section 3.5 | + +----------------------------+-----------------+---------------+ + | TOO_MANY_REQUEST_UPDATES | 0x1B | Section 3.5 | + +----------------------------+-----------------+---------------+ + | Reserved for greasing | 0x7f * N + 0x9D | Section 14 | + +----------------------------+-----------------+---------------+ + + Table 18 + +15.11.2. REQUEST_ERROR Codes + + +=======================+=================+===============+ + | Name | Code | Specification | + +=======================+=================+===============+ + | INTERNAL_ERROR | 0x0 | Section 10.6 | + +-----------------------+-----------------+---------------+ + | UNAUTHORIZED | 0x1 | Section 10.6 | + +-----------------------+-----------------+---------------+ + | TIMEOUT | 0x2 | Section 10.6 | + +-----------------------+-----------------+---------------+ + | NOT_SUPPORTED | 0x3 | Section 10.6 | + +-----------------------+-----------------+---------------+ + | MALFORMED_AUTH_TOKEN | 0x4 | Section 10.6 | + +-----------------------+-----------------+---------------+ + | EXPIRED_AUTH_TOKEN | 0x5 | Section 10.6 | + +-----------------------+-----------------+---------------+ + | GOING_AWAY | 0x6 | Section 10.6 | + +-----------------------+-----------------+---------------+ + | EXCESSIVE_LOAD | 0x9 | Section 10.6 | + +-----------------------+-----------------+---------------+ + + + +Nandakumar, et al. Expires 4 March 2027 [Page 137] + +Internet-Draft moq-transport August 2026 + + + | DOES_NOT_EXIST | 0x10 | Section 10.6 | + +-----------------------+-----------------+---------------+ + | INVALID_RANGE | 0x11 | Section 10.6 | + +-----------------------+-----------------+---------------+ + | MALFORMED_TRACK | 0x12 | Section 10.6 | + +-----------------------+-----------------+---------------+ + | UNINTERESTED | 0x20 | Section 10.6 | + +-----------------------+-----------------+---------------+ + | PREFIX_OVERLAP | 0x30 | Section 10.6 | + +-----------------------+-----------------+---------------+ + | NAMESPACE_TOO_LARGE | 0x31 | Section 10.6 | + +-----------------------+-----------------+---------------+ + | UNSUPPORTED_EXTENSION | 0x33 | Section 10.6 | + +-----------------------+-----------------+---------------+ + | REDIRECT | 0x34 | Section 10.6 | + +-----------------------+-----------------+---------------+ + | CONFLICTING_FILTERS | 0x35 | Section 10.6 | + +-----------------------+-----------------+---------------+ + | INVALID_FILTER | 0x36 | Section 10.6 | + +-----------------------+-----------------+---------------+ + | Reserved for greasing | 0x7f * N + 0x9D | Section 14 | + +-----------------------+-----------------+---------------+ + + Table 19 + +15.11.3. PUBLISH_DONE Codes + + +=======================+=================+===============+ + | Name | Code | Specification | + +=======================+=================+===============+ + | INTERNAL_ERROR | 0x0 | Section 10.12 | + +-----------------------+-----------------+---------------+ + | UNAUTHORIZED | 0x1 | Section 10.12 | + +-----------------------+-----------------+---------------+ + | TRACK_ENDED | 0x2 | Section 10.12 | + +-----------------------+-----------------+---------------+ + | GOING_AWAY | 0x4 | Section 10.12 | + +-----------------------+-----------------+---------------+ + | TOO_FAR_BEHIND | 0x5 | Section 10.12 | + +-----------------------+-----------------+---------------+ + | EXPIRED | 0x6 | Section 10.12 | + +-----------------------+-----------------+---------------+ + | UPDATE_FAILED | 0x8 | Section 10.12 | + +-----------------------+-----------------+---------------+ + | EXCESSIVE_LOAD | 0x9 | Section 10.12 | + +-----------------------+-----------------+---------------+ + | MALFORMED_TRACK | 0x12 | Section 10.12 | + +-----------------------+-----------------+---------------+ + + + +Nandakumar, et al. Expires 4 March 2027 [Page 138] + +Internet-Draft moq-transport August 2026 + + + | Reserved for greasing | 0x7f * N + 0x9D | Section 14 | + +-----------------------+-----------------+---------------+ + + Table 20 + +15.11.4. Stream Reset Error Codes + + +=======================+=================+===============+ + | Name | Code | Specification | + +=======================+=================+===============+ + | INTERNAL_ERROR | 0x0 | Section 3.3.4 | + +-----------------------+-----------------+---------------+ + | CANCELLED | 0x1 | Section 3.3.4 | + +-----------------------+-----------------+---------------+ + | DELIVERY_TIMEOUT | 0x2 | Section 3.3.4 | + +-----------------------+-----------------+---------------+ + | SESSION_CLOSED | 0x3 | Section 3.3.4 | + +-----------------------+-----------------+---------------+ + | GOING_AWAY | 0x4 | Section 3.3.4 | + +-----------------------+-----------------+---------------+ + | TOO_FAR_BEHIND | 0x5 | Section 3.3.4 | + +-----------------------+-----------------+---------------+ + | UNKNOWN_OBJECT_STATUS | 0x6 | Section 3.3.4 | + +-----------------------+-----------------+---------------+ + | EXPIRED_AUTH_TOKEN | 0x7 | Section 3.3.4 | + +-----------------------+-----------------+---------------+ + | EXCESSIVE_LOAD | 0x9 | Section 3.3.4 | + +-----------------------+-----------------+---------------+ + | MALFORMED_TRACK | 0x12 | Section 3.3.4 | + +-----------------------+-----------------+---------------+ + | Reserved for greasing | 0x7f * N + 0x9D | Section 14 | + +-----------------------+-----------------+---------------+ + + Table 21 + +Contributors + + The original design behind this protocol was inspired by three + independent proposals: WARP [I-D.draft-lcurley-warp] by Luke Curley, + RUSH [I-D.draft-kpugin-rush] by Kirill Pugin, Nitin Garg, Alan + Frindell, Jordi Cenzano and Jake Weissman, and QUICR + [I-D.draft-jennings-moq-quicr-proto] by Cullen Jennings, Suhas + Nandakumar and Christian Huitema. The authors of those documents + merged their proposals to create the first draft of moq-transport. + The IETF MoQ Working Group received an enormous amount of support + from many people. The following people provided substantive + contributions to this document: + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 139] + +Internet-Draft moq-transport August 2026 + + + * Ali Begen + + * Charles Krasic + + * Christian Huitema + + * Cullen Jennings + + * James Hurley + + * Jordi Cenzano + + * Kirill Pugin + + * Luke Curley + + * Martin Duke + + * Mike English + + * Mo Zanaty + + * Will Law + +Use of Generative AI + + Generative AI tools were used to assist with drafting and editing + text for this document. All AI-generated content was reviewed and + approved by the editors. + +References + +Normative References + + [I-D.draft-ietf-quic-reliable-stream-reset] + Seemann, M. and K. Oku, "QUIC Stream Resets with Partial + Delivery", Work in Progress, Internet-Draft, draft-ietf- + quic-reliable-stream-reset-10, 9 August 2026, + . + + [I-D.ietf-webtrans-overview] + Kinnear, E. and V. Vasiliev, "The WebTransport Protocol + Framework", Work in Progress, Internet-Draft, draft-ietf- + webtrans-overview-13, 6 July 2026, + . + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 140] + +Internet-Draft moq-transport August 2026 + + + [QUIC] Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based + Multiplexed and Secure Transport", RFC 9000, + DOI 10.17487/RFC9000, May 2021, + . + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + . + + [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO + 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November + 2003, . + + [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform + Resource Identifier (URI): Generic Syntax", STD 66, + RFC 3986, DOI 10.17487/RFC3986, January 2005, + . + + [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type + Specifications and Registration Procedures", BCP 13, + RFC 6838, DOI 10.17487/RFC6838, January 2013, + . + + [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, + "Transport Layer Security (TLS) Application-Layer Protocol + Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, + July 2014, . + + [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines + and Registration Procedures for URI Schemes", BCP 35, + RFC 7595, DOI 10.17487/RFC7595, June 2015, + . + + [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for + Writing an IANA Considerations Section in RFCs", BCP 26, + RFC 8126, DOI 10.17487/RFC8126, June 2017, + . + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, . + + [RFC8615] Nottingham, M., "Well-Known Uniform Resource Identifiers + (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019, + . + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 141] + +Internet-Draft moq-transport August 2026 + + + [RFC9221] Pauly, T., Kinnear, E., and D. Schinazi, "An Unreliable + Datagram Extension to QUIC", RFC 9221, + DOI 10.17487/RFC9221, March 2022, + . + + [WebTransport] + Frindell, A., Kinnear, E., and V. Vasiliev, "WebTransport + over HTTP/3", Work in Progress, Internet-Draft, draft- + ietf-webtrans-http3-16, 6 July 2026, + . + +Informative References + + [CAT] Law, W., Lemmons, C., Simon, G., and S. Nandakumar, + "Authorization scheme for MOQT using Common Access + Tokens", Work in Progress, Internet-Draft, draft-ietf-moq- + c4m-01, 18 June 2026, + . + + [I-D.draft-jennings-moq-quicr-proto] + Jennings, C. F., Nandakumar, S., and C. Huitema, "QuicR - + Media Delivery Protocol over QUIC", Work in Progress, + Internet-Draft, draft-jennings-moq-quicr-proto-01, 11 July + 2022, . + + [I-D.draft-kpugin-rush] + Pugin, K., Garg, N., Frindell, A., Ferret, J. C., and J. + Weissman, "RUSH - Reliable (unreliable) streaming + protocol", Work in Progress, Internet-Draft, draft-kpugin- + rush-03, 21 April 2025, + . + + [I-D.draft-lcurley-warp] + Curley, L., Pugin, K., Nandakumar, S., and V. Vasiliev, + "Warp - Live Media Transport over QUIC", Work in Progress, + Internet-Draft, draft-lcurley-warp-04, 13 March 2023, + . + + + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 142] + +Internet-Draft moq-transport August 2026 + + + [I-D.ietf-moq-secure-objects] + Jennings, C. F., Nandakumar, S., and R. Barnes, "End-to- + End Secure Objects for Media over QUIC Transport", Work in + Progress, Internet-Draft, draft-ietf-moq-secure-objects- + 01, 6 July 2026, . + + [I-D.ietf-scone-protocol] + Thomson, M., Huitema, C., Oku, K., Joras, M., and L. M. + Ihlar, "Standard Communication with Network Elements + (SCONE) Protocol", Work in Progress, Internet-Draft, + draft-ietf-scone-protocol-07, 20 August 2026, + . + + [PPA] Nandakumar, S., Jennings, C. F., and T. Meunier, "Privacy + Pass Authentication for Media over QUIC (MoQ)", Work in + Progress, Internet-Draft, draft-ietf-moq-privacy-pass- + auth-03, 6 July 2026, + . + + [RFC1035] Mockapetris, P., "Domain names - implementation and + specification", STD 13, RFC 1035, DOI 10.17487/RFC1035, + November 1987, . + + [RFC3596] Thomson, S., Huitema, C., Ksinant, V., and M. Souissi, + "DNS Extensions to Support IP Version 6", STD 88, + RFC 3596, DOI 10.17487/RFC3596, October 2003, + . + + [RFC6582] Henderson, T., Floyd, S., Gurtov, A., and Y. Nishida, "The + NewReno Modification to TCP's Fast Recovery Algorithm", + RFC 6582, DOI 10.17487/RFC6582, April 2012, + . + + [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol + Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, + . + + [RFC8470] Thomson, M., Nottingham, M., and W. Tarreau, "Using Early + Data in HTTP", RFC 8470, DOI 10.17487/RFC8470, September + 2018, . + + [RFC9000] Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based + Multiplexed and Secure Transport", RFC 9000, + DOI 10.17487/RFC9000, May 2021, + . + + + +Nandakumar, et al. Expires 4 March 2027 [Page 143] + +Internet-Draft moq-transport August 2026 + + + [RFC9170] Thomson, M. and T. Pauly, "Long-Term Viability of Protocol + Extension Mechanisms", RFC 9170, DOI 10.17487/RFC9170, + December 2021, . + + [RFC9438] Xu, L., Ha, S., Rhee, I., Goel, V., and L. Eggert, Ed., + "CUBIC for Fast and Long-Distance Networks", RFC 9438, + DOI 10.17487/RFC9438, August 2023, + . + + [RFC9460] Schwartz, B., Bishop, M., and E. Nygren, "Service Binding + and Parameter Specification via the DNS (SVCB and HTTPS + Resource Records)", RFC 9460, DOI 10.17487/RFC9460, + November 2023, . + + [RFC9525] Saint-Andre, P. and R. Salz, "Service Identity in TLS", + RFC 9525, DOI 10.17487/RFC9525, November 2023, + . + + [RFC9580] Wouters, P., Ed., Huigens, D., Winter, J., and Y. Niibe, + "OpenPGP", RFC 9580, DOI 10.17487/RFC9580, July 2024, + . + +Appendix A. Change Log + + RFC Editor's Note: Please remove this section prior to publication of + a final version of this document. + + Issue and pull request numbers are listed with a leading octothorp. + +A.1. Since draft-ietf-moq-transport-19 + + *Session and Control Plane* + + * Replace Joining FETCH with fill fetch streams (#1673) + + - Add the FILL_PARAMETERS parameter, whose presence on a + subscription requests a fill; it carries a sequence of + Parameters (#1868) + + - Remove the Joining variant of FETCH and the "standalone" + moniker + + * Restructure the Location Filter to match the other filter + parameters, and carry the FETCH range in LOCATION_FILTER instead + of message fields (#1809) + + * Add PUBLISH_STATE_NOTIFY message (#1820) + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 144] + +Internet-Draft moq-transport August 2026 + + + * Add INCLUDE_PROPERTIES parameter (#1813, #1847) + + * PUBLISH can carry Subscription Parameters, and AUTHORIZATION TOKEN + is never copied from SUBSCRIBE_TRACKS (#1834) + + * Subscription parameters appear in REQUEST_UPDATE, not PUBLISH_OK + (#1790) + + * Allow FORWARD on a REQUEST_UPDATE for SUBSCRIBE_TRACKS (#1812) + + * Remove PUBLISH_DONE status code SUBSCRIPTION_ENDED; a subscription + does not end because Largest Object passes the end of the Location + Filter (#1833) + + * Change the maximum Stream Count in PUBLISH_DONE to 2^64 - 1 + (#1831) + + * Remove the requirement for a publisher to retain Largest Location + (#1872) + + * Remove the VERSION_NEGOTIATION_FAILED session error (#1867) + + * A relay MUST send an upstream FETCH to at least one publisher + (#1804) + + * Discuss the tradeoffs of aggregating downstream filters onto an + upstream subscription (#1735) + + * Resolve REDIRECT ambiguity with empty Track Namespace and Track + Name (#1824) + + * Clarify Retry Interval of 0 with REDIRECT (#1785) + + * Define host resolution for moqt URIs (#1817) + + * Exclude the URI query component from the MOQT scope (#1855) + + * SUBSCRIBE_TRACKS Parameters are the publisher's initial + Subscription parameters and are explicitly communicated in the + resulting PUBLISH (#1815, #1869) + + *Data Plane Wire Format and Handling* + + * Describe OBJECT_DATAGRAM and SUBGROUP_HEADER types as Type Flags + bitfields; a set bit with no specified meaning is a + PROTOCOL_VIOLATION (#1774) + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 145] + +Internet-Draft moq-transport August 2026 + + + * Add End of Timed-Out Range for Objects abandoned when Fill Timeout + expires (#1822) + + * OBJECT_DELIVERY_TIMEOUT starts at the last header byte instead of + the first payload byte (#1844) + + * Define scheduling between fill-delivered and subscription- + delivered Objects (#1673) + + * Beware re-using a Track Alias for concurrent subscriptions (#1856) + + *Security Considerations* + + * Add a Preventing Impersonation section (#1737, #1789) + + * Expand mutual TLS and authorization guidance (#1786) + + * Add moqt URI scheme security considerations (#1772) + + * Add a security consideration for logging untrusted string fields + (#1823) + + * Recommend end-to-end object encryption for confidentiality from + relays (#1755) + + *Notable Editorial Changes* + + * Clarify the Range Filters section for readability (#1851) + + * Note that the recommended name encoding is not guaranteed + filename-safe (#1863) + + * Fix LOC and Secure Objects entries in the provisional Property + registry (#1807, #1818, #1848) + +A.2. Since draft-ietf-moq-transport-18 + + *Session and Control Plane* + + * Add Range Filters that can filter Objects from Subscriptions and + SUBSCRIBE_TRACKS (#1765) + + * Add MAX_REQUEST_UPDATES Setup Option and TOO_MANY_REQUEST_UPDATES + error (#1613) + + * Allow multiple concurrent subscriptions per Track (#1775) + + * Move GROUP_ORDER from PUBLISH_OK to SUBSCRIBE_TRACKS (#1777) + + + +Nandakumar, et al. Expires 4 March 2027 [Page 146] + +Internet-Draft moq-transport August 2026 + + + * Rename PUBLISH_BLOCKED to PUBLISH_SKIPPED (#1779) + + * Remove Request ID from GOAWAY (#1623) + + * Clarify session vs. per-request GOAWAY migration (#1787) + + * Define FIN vs. RST/STOP_SENDING semantics on request streams + (#1698) + + * Unexpected REQUEST_UPDATE is a session error (#1784) + + * Update Forward State handling for relays (#1782) + + * Clarify authorization trust model for namespace subscriptions + (#1656) + + * Clarify namespace discovery and NAMESPACE sending (#1710) + + *Data Plane Wire Format and Handling* + + * Delivery timeouts are both Track and Object Properties (#1476) + + * Make the Object Status payload rule extensible via IANA registry + (#1760) + + * Datagrams take precedence in cross-forwarding-preference + scheduling ties (#1780) + + * Remove relay exception for reordering or dropping objects (#1762) + + * Specify relay processing rules for known Track Properties (#1771) + + * Recommend Immutable Properties for relay-visible, unmodifiable + data (#1759) + + *Notable Editorial Changes* + + * Rename control Message Payload field to Message Body (#1756) + + * Clarify Group and Subgroup terminology and object model (#1708) + +A.3. Since draft-ietf-moq-transport-17 + + *Session and Control Plane* + + * Unified moqt:// URI scheme for QUIC and WebTransport (#1486) + + * Add fragment identifier support for moqt URIs (#1571) + + + +Nandakumar, et al. Expires 4 March 2027 [Page 147] + +Internet-Draft moq-transport August 2026 + + + * Split SUBSCRIBE_NAMESPACE into SUBSCRIBE_NAMESPACE and + SUBSCRIBE_TRACKS (#1542) + + * Remove Required Request ID (#1615) + + * Add REDIRECT for request errors and established subscriptions + (#1534) + + * Allow GOAWAY on request streams to migrate individual requests + (#1617) + + * Add Request ID to GOAWAY (#1559) + + * Remove PUBLISH_OK message type, make it a REQUEST_OK alias (#1611) + + * Generalize stream reset codes to all request streams, add new + codes, align with PUBLISH_DONE (#1606) + + * Add Track Properties to REQUEST_OK (#1576) + + * Add support for mandatory-to-understand track extensions (#1509) + + * Exclude your own tracks from SUBSCRIBE_NAMESPACE (#1596) + + * Add Session-Level Tracks reserved namespace (#1562) + + * Allow coalescing REQUEST_UPDATE processing (#1540) + + * SUBSCRIBE takes precedence over SUBSCRIBE_NAMESPACE at relay + (#1533) + + * Don't close the Session for unknown errors (#1561) + + * Clarify REQUEST_UPDATE failure behavior for all request types + (#1539) + + * Clarify SUBSCRIBE_NAMESPACE stream closure semantics (#1541) + + * FETCH to a track with no objects returns INVALID_RANGE (#1537) + + * Clarify FETCH_OK End Location semantics (#1536) + + * Clarify definition of scope (#1629) + + * Clarify Joining Fetch behavior: + + - Joining FETCH is unaffected by forward changing to 0 (#1620) + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 148] + +Internet-Draft moq-transport August 2026 + + + - Joining Fetch forward state mismatch is a request error (#1609) + + - Clarify Joining Fetch ordering with Forward State transitions + (#1577) + + *Data Plane Wire Format and Handling* + + * Make Object ID and Group ID delta encoded in Fetch responses + (#1586) + + * Add FIRST_OBJECT bit to SUBGROUP_HEADER type (#1618) + + * Split DELIVERY_TIMEOUT into two types of timeout (#1605) + + * FILL_TIMEOUT parameter (#1490) + + * Forbid relays from lying about LARGEST_OBJECT (#1621) + + * Allow publisher to reopen subgroup after REQUEST_UPDATE forward + 0->1 (#1583) + + * Allow 7-byte varint and non-minimal encodings (#1595) + + * Padding streams and datagrams (#1475) + + * Close session when delta encoding wraps (#1560) + + *Notable Editorial Changes* + + * Clarify Object existence and cross-source contradictions (#1566) + + * Clarify immutable track properties (#1535) + + * Improve Startup Latency and 0-RTT guidance (#1544) + + * Improve Security Considerations section (#1625) + + * Rewrite abstract and introduction (#1556) + + * Define textual aliases for REQUEST_OK by request type (#1610) + + * Add IANA registry for Setup Options (#1564) + + * Add provisional registry for LOC properties (#1624) + + * Update MOQ Properties registration policies (#1525) + + * Add stream type column to message type table (#1555) + + + +Nandakumar, et al. Expires 4 March 2027 [Page 149] + +Internet-Draft moq-transport August 2026 + + + * Fix grease examples to match 0x7f multiplier (#1569) + +A.4. Since draft-ietf-moq-transport-16 + + *Session and Control Plane* + + * Change control stream from bidi to a pair of uni streams (#1510) + + * Collapse CLIENT_SETUP and SERVER_SETUP into a single SETUP message + (#1510) + + * Move requests to bidirectional streams; remove cancel messages + (#1389) + + * Remove MAX_REQUEST_ID/REQUESTS_BLOCKED (#1471) + + * New variable-length integer encoding (#1016) + + * Encode Message Parameters as Type-Value pairs (#1462) + + * Add GREASE for Setup Options, Properties, and error code + registries (#1460) + + * Add RENDEZVOUS_TIMEOUT parameter for SUBSCRIBE (#1447) + + * Add PUBLISH_BLOCKED message for SUBSCRIBE_NAMESPACE flow control + (#1452) + + * Add Timeout field to GOAWAY message (#1497) + + * Add GOING_AWAY to REQUEST_ERROR codes (#1434) + + * Add EXCESSIVE_LOAD error code (#1479) + + * Add NAMESPACE_TOO_LARGE error and stream reset for large + namespaces (#1496) + + * Add TOO_FAR_BEHIND stream reset code (#1445) + + * Add REQUEST_UPDATE to list of REQUEST_ERROR causes (#1466) + + * Enforce REQUEST_OK/ERROR as first message on the response stream + (#1499) + + * Allow joining FETCH for PUBLISH and REQUEST_UPDATE with forward=1 + (#1335) + + * Allow DELIVERY_TIMEOUT value of 0 to mean no timeout (#1450) + + + +Nandakumar, et al. Expires 4 March 2027 [Page 150] + +Internet-Draft moq-transport August 2026 + + + * Allow zero-element namespaces (#1472) + + * Clarify EXPIRES parameter update mechanism (#1448) + + * Remove TRACK_STATUS from REQUEST_UPDATE (#1436) + + * Define how to use auth token cache safely with multiple streams + (#1430) + + * Constrain encoding/parsing of track namespace and names (#1512) + + * Reserve Property type ranges for application-specific use (#1473) + + * Make EndGroup in Subscription Filters a delta (#1470) + + * Copy DELIVERY_TIMEOUT min requirement from parameter to property + (#1427) + + *Data Plane Wire Format and Handling* + + * Clarify prior Object semantics after End of Range indicators in + FETCH (#1513) + + * Clarify datagram status and properties cases (#1444) + + * Clarify Stream Count includes empty subgroups (#1449) + + * Clarify language for malformed tracks in a subgroup with + END_OF_GROUP (#1464) + + * Properties can appear in mutable list or inside Immutable + Properties (#1442) + + * Clarify immutable property preservation requirements (#1441) + + * Clarification for Track Alias uniqueness (#1418) + + *Notable Editorial Changes* + + * Rename Setup Parameters to Setup Options (#1461) + + * Rename Extension Headers to Properties (#1504) + + * Add security/privacy considerations for MOQT_IMPLEMENTATION + (#1511) + + * Add editorial text on bandwidth probing techniques (#1477) + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 151] + +Internet-Draft moq-transport August 2026 + + + * Explain idle connection handling (#1443) + + * Fix "SUBSCRIBE_NAMESPACE with short prefixes" (#1502) + + * Add generative AI disclosure per IRTF guidelines + +A.5. Since draft-ietf-moq-transport-15 + + *Setup and Control Plane* + + * Delta encode Key-Value-Pairs for Parameters and Headers (#1315) + + * Use Request ID in PUBLISH_NAMESPACE_{DONE/CANCEL} (#1329) + + * Remove delivery related params from TRACK_STATUS for Subscribers + (#1325) + + * PUBLISH does not imply PUBLISH_NAMESPACE (#1364) + + * Allow Start Location to decrease in SUBSCRIBE_UPDATE (#1323) + + * Change SUBSCRIBE_UPDATE to REQUEST_UPDATE and expand ability to + update (#1332) + + * Put SUBSCRIBE_NAMESPACE on a stream, make Namespaces and PUBLISH + independent (#1344) + + * Require NAMESPACE before NAMESPACE_DONE (#1392) + + * Allow the '*' or the empty namespace in SUBSCRIBE_NAMESPACE + (#1393) + + * Relays match SUBSCRIBE to both Tracks and Namespaces (#1397) + + * Clarify sending requests after sending GOAWAY (#1398) + + * Add Retry Interval to REQUEST_ERROR (#1339) + + * Add Extension Headers to PUBLISH, SUBSCRIBE_OK, and FETCH_OK + (#1374) + + * Move track properties to extensions, scope parameters (#1390) + + * Add LARGEST_OBJECT parameter to TRACK_STATUS (#1367) + + * Duplicate subscription processing (#1341) + + * Address Track Name/Namespace edge cases (#1399) + + + +Nandakumar, et al. Expires 4 March 2027 [Page 152] + +Internet-Draft moq-transport August 2026 + + + *Data Plane Wire Format and Handling* + + * Enable mixing datagrams with streams in one track (#1350) + + * Clarify datagrams and subgroups (#1382) + + * Redo the way we deal with missing Objects and Object Status + (#1342) + + * Allow unknown ranges in a FETCH response (#1331) + + * Do not reopen subgroups after delivery timeout or STOP_SENDING + (#1396) + + * Clarify handling of unknown extensions (#1395) + + * Clarify Delivery Timeout for datagrams (#1406) + + * Disallow DELIVERY_TIMEOUT=0 (#1330) + + * Malformed track due to multiple priorities for one subgroup + (#1317) + + *Notable Editorial Changes* + + * Subscribers can migrate networks too (#1410) + + * Rename Version Specific Parameters to Message Parameters (#1411) + + * Clarify valid joining fetch subscription states (#1363) + + * Formatting names for logs (#1355) + + * A Publisher might not use the congestion window (#1408) + +A.6. Since draft-ietf-moq-transport-14 + + *Setup and Control Plane* + + * Always use ALPN for version negotiation (#499) + + * Consolidate all the Error Message types (#1159) + + * Change MOQT IMPLEMENTATION code point to 0x7 (#1191) + + * Add Forward to SUBSCRIBE_NAMESPACE (#1220) + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 153] + +Internet-Draft moq-transport August 2026 + + + * Parameters for Group Order, Subscribe Priority and Subscription + Filter (redo) (#1273) + + * REQUEST_OK message (#1274) + + * Subscribe Update Acknowledgements (#1275) + + * Disallow DELETE and USE_ALIAS in CLIENT_SETUP (#1277) + + * Remove Expires field from SUBSCRIBE_OK (#1282) + + * Make Forward a Parameter (#1283) + + * Allow SUBSCRIBE_UPDATE to increase the end location (#1288) + + * Add default port for raw QUIC (#1289) + + * Unsubscribe Namespace should be linked to Subscribe Namespace + (#1292) + + *Data Plane Wire Format and Handling* + + * Fetch Object serialization optimization (#949) + + * Make default PUBLISHER PRIORITY a parameter, optional in Subgroup/ + Datagram (#1056) + + * Allow datagram status with object ID=0 (#1197) + + * Disallow object extension headers in all non-Normal status objects + (#1266) + + * Objects for malformed track must not be cached (#1290) + + * Remove NO_OBJECTS fetch error code (#1303) + + * Clarify what happens when max_cache_duration parameter is omitted + (#1287) + + *Notable Editorial Changes* + + * Rename Request ID field in MAX_REQUEST_ID (#1250) + + * Define and draw subscription state machine (#1296) + + * Omitting a subgroup object necessitates reset (#1295) + + * Define duplication rules for header extensions (#1293) + + + +Nandakumar, et al. Expires 4 March 2027 [Page 154] + +Internet-Draft moq-transport August 2026 + + + * Clarify joining fetch end location (#1286) + +A.7. Since draft-ietf-moq-transport-13 + + *Setup and Control Plane* + + * Add an AUTHORITY parameter (#1058) + + * Add a free-form SETUP parameter identifying the implementation + (#1114) + + * Add a Request ID to SUBSCRIBE_UDPATE (#1106) + + * Indicate which params can appear PUBLISH* messages (#1071) + + * Add TRACK_STATUS to the list of request types affected by GOAWAY + (#1105) + + *Data Plane Wire Format and Handling* + + * Delta encode Object IDs within Subgroups (#1042) + + * Use a bit in Datagram Type to convey Object ID = 0 (#1055) + + * Corrected missed code point updates to Object Datagram Status + (#1082) + + * Merge OBJECT_DATAGRAM and OBJECT_DATAGRAM_STATUS description + (#1179) + + * Objects are not schedulable if flow-control blocked (#1054) + + * Clarify DELIVERY_TIMEOUT reordering computation (#1120) + + * Receiving unrequested Objects (#1112) + + * Clarify End of Track (#1111) + + * Malformed tracks apply to FETCH (#1083) + + * Remove early FIN from the definition of malformed tracks (#1096) + + * Prior Object ID Gap Extension header (#939) + + * Add Extension containing immutable extensions (#1025) + + *Relay Handling* + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 155] + +Internet-Draft moq-transport August 2026 + + + * Explain FETCH routing for relays (#1165) + + * MUST for multi-publisher relay handling (#1115) + + * Filters don't (usually) determine the end of subscription (#1113) + + * Allow self-subscriptions (#1110) + + * Explain Namespace Prefix Matching in more detail (#1116) + + *Explanatory* + + * Explain Modularity of MOQT (#1107) + + * Explain how to resume publishing after losing state (#1087) + + *Major Editorial Changes* + + * Rename ANNOUNCE to PUBLISH_NAMESPACE (#1104) + + * Rename SUBSCRIBE_DONE to PUBLISH_DONE (#1108) + + * Major FETCH Reorganization (#1173) + + * Reformat Error Codes (#1091) + +A.8. Since draft-ietf-moq-transport-12 + + * TRACK_STATUS_REQUEST and TRACK_STATUS have changed to directly + mirror SUBSCRIBE/OK/ERROR (#1015) + + * SUBSCRIBE_ANNOUNCES was renamed back to SUBSCRIBE_NAMESPACE + (#1049) + +A.9. Since draft-ietf-moq-transport-11 + + * Move Track Alias from SUBSCRIBE to SUBSCRIBE_OK (#977) + + * Expand cases FETCH_OK returns Invalid Range (#946) and clarify + fields (#936) + + * Add an error code to FETCH_ERROR when an Object status is unknown + (#825) + + * Rename Latest Object to Largest Object (#1024) and clarify what to + do when it's incomplete (#937) + + * Explain Malformed Tracks and what to do with them (#938) + + + +Nandakumar, et al. Expires 4 March 2027 [Page 156] + +Internet-Draft moq-transport August 2026 + + + * Allow End of Group to be indicated in a normal Object (#1011) + + * Relays MUST have an upstream subscription to send SUBSCRIBE_OK + (#1017) + + * Allow AUTHORIZATION TOKEN in CLIENT_SETUP, SERVER_SETUP and other + fixes (#1013) + + * Add PUBLISH for publisher initiated subscriptions (#995) and fix + the PUBLISH codepoints (#1048, #1051) + +A.10. Since draft-ietf-moq-transport-10 + + * Added Common Structure definitions - Location, Key-Value-Pair and + Reason Phrase + + * Limit lengths of all variable length fields, including Track + Namespace and Name + + * Control Message length is now 16 bits instead of variable length + + * Subscribe ID became Request ID, and was added to most control + messages. Request ID is used to correlate OK/ERROR responses for + ANNOUNCE, SUBSCRIBE_NAMESPACE, and TRACK_STATUS. Like Subscribe + ID, Request IDs are flow controlled. + + * Explain rules for caching in more detail + + * Changed the SETUP parameter format for even number parameters to + match the Object Header Extension format + + * Rotated SETUP code points + + * Added Parameters to TRACK_STATUS and TRACK_STATUS_REQUEST + + * Clarified how subscribe filters work + + * Added Next Group Filter to SUBSCRIBE + + * Added Forward flag to SUBSCRIBE + + * Renamed FETCH_OK field to End and clarified how to set it + + * Added Absolute Joining Fetch + + * Clarified No Error vs Invalid Range FETCH_ERROR cases + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 157] + +Internet-Draft moq-transport August 2026 + + + * Use bits in SUBGROUP_HEADER and DATAGRAM* types to compress + subgroup ID and extensions + + * Coalesced END_OF_GROUP and END_OF_TRACK_AND_GROUP status + + * Objects that Do Not Exist cannot have extensions when sent on the + wire + + * Specified error codes for resetting data streams + + * Defined an Object Header Extension for communicating a known Group + ID gap + + * Replaced AUTHORIZATION_INFO with AUTHORIZATION_TOKEN, which has + more structure, compression, and additional Auth related error + codes (#760) + +Authors' Addresses + + Suhas Nandakumar + Cisco + Email: snandaku@cisco.com + + + Victor Vasiliev + Google + Email: vasilvv@google.com + + + Ian Swett (editor) + Google + Email: ianswett@google.com + + + Alan Frindell (editor) + Meta + Email: afrind@meta.com + + + + + + + + + + + + + + +Nandakumar, et al. Expires 4 March 2027 [Page 158] From 960a80fadc002603abafb4ef0622215bec7ea11a Mon Sep 17 00:00:00 2001 From: Matt McClure Date: Wed, 2 Sep 2026 23:43:29 +0000 Subject: [PATCH 2/6] feat(spf): speak moq-transport draft-20 (moqt-20) Cut the MoQ stack over from draft-19 to draft-20, matching moq-relay 0.14.14: - ALPN moqt-20; decode PUBLISH_STATE_NOTIFY (0x22), FILL_PARAMETERS (0x23) and INCLUDE_PROPERTIES (0x35); read End of Timed-Out Range (0x20C); drop SUBSCRIPTION_ENDED, INVALID_JOINING_REQUEST_ID and VERSION_NEGOTIATION_FAILED. - LOCATION_FILTER is the length-counted field list (none / relative-group / next-object / absolute); FETCH takes the SUBSCRIBE body with its range in LOCATION_FILTER. - LARGEST_OBJECT and INCLUDE_PROPERTIES are framed length-prefixed, as moq-relay does (moq-dev/moq#3255 records the spec conflict). - The catalog joins with a relative-group 1 subscription and no FETCH: draft-20 relays no longer replay the current group for Next Object, and the joining FETCH never carried catalog data. - REQUEST_UPDATE consumes its own Request ID (section 10.1); PUBLISH_DONE's 2^64-1 Stream Count sentinel decodes as undefined instead of failing the session. --- .../templates/moq-relay-interop/main.ts | 2 +- .../templates/spf-moq-player/index.html | 2 +- .../spf-moq-player/loopback-relay.ts | 13 +- apps/sandbox/templates/spf-moq-player/main.ts | 2 +- packages/spf/src/media/moq/timeline.ts | 4 +- packages/spf/src/network/moqt/bytes.ts | 17 + .../spf/src/network/moqt/control-messages.ts | 421 +++++++++++------- packages/spf/src/network/moqt/errors.ts | 3 +- .../spf/src/network/moqt/object-stream.ts | 36 +- .../spf/src/network/moqt/request-stream.ts | 4 +- packages/spf/src/network/moqt/session.ts | 66 ++- .../moqt/tests/control-messages.test.ts | 224 ++++++++-- .../network/moqt/tests/object-stream.test.ts | 14 +- .../src/network/moqt/tests/session.test.ts | 119 ++++- packages/spf/src/network/moqt/varint.ts | 2 +- .../src/playback/actors/dom/audio-renderer.ts | 2 +- .../actors/dom/tests/audio-renderer.test.ts | 2 +- .../spf/src/playback/actors/moq-session.ts | 28 +- .../playback/actors/tests/moq-session.test.ts | 4 +- .../actors/tests/track-subscriber.test.ts | 2 +- .../src/playback/actors/track-subscriber.ts | 4 +- .../behaviors/adapt-latency-target.ts | 2 +- .../src/playback/behaviors/resolve-catalog.ts | 183 +++----- .../behaviors/subscribe-selected-tracks.ts | 8 +- .../behaviors/tests/resolve-catalog.test.ts | 249 ++++------- .../tests/subscribe-selected-tracks.test.ts | 24 +- .../playback/engines/moq/tests/engine.test.ts | 18 +- 27 files changed, 852 insertions(+), 603 deletions(-) diff --git a/apps/sandbox/templates/moq-relay-interop/main.ts b/apps/sandbox/templates/moq-relay-interop/main.ts index ff23d140ea..ad0019094e 100644 --- a/apps/sandbox/templates/moq-relay-interop/main.ts +++ b/apps/sandbox/templates/moq-relay-interop/main.ts @@ -1,4 +1,4 @@ -// MoQ (draft-ietf-moq-transport-19 / MSF) relay interop smoke test. +// MoQ (draft-ietf-moq-transport-20 / MSF) relay interop smoke test. // http://localhost:5173/moq-relay-interop/ // // Query params: diff --git a/apps/sandbox/templates/spf-moq-player/index.html b/apps/sandbox/templates/spf-moq-player/index.html index f54a353658..b89c399bbb 100644 --- a/apps/sandbox/templates/spf-moq-player/index.html +++ b/apps/sandbox/templates/spf-moq-player/index.html @@ -251,7 +251,7 @@

MoQ Player

<simple-moq-video> inside the real <live-video-player> shell and skin — the MoQ engine driving actual Video.js controls. Defaults to a loopback relay: an in-page MSF - publisher speaking draft-19 bytes over an in-memory transport, so playback works with no server. Point at a real + publisher speaking draft-20 bytes over an in-memory transport, so playback works with no server. Point at a real relay with a full MSF URL (?relay=moqt://…%23msf:… — percent-encode the #, or the browser reads it as this page's fragment), or compose one from parts: relay host, broadcast path (what your token was issued for, e.g. mattypoo/room/42), and an optional JWT — the same diff --git a/apps/sandbox/templates/spf-moq-player/loopback-relay.ts b/apps/sandbox/templates/spf-moq-player/loopback-relay.ts index b465950e7d..72d209ceb6 100644 --- a/apps/sandbox/templates/spf-moq-player/loopback-relay.ts +++ b/apps/sandbox/templates/spf-moq-player/loopback-relay.ts @@ -2,7 +2,7 @@ * Loopback MoQ relay — a synthetic MSF publisher for the sandbox. * * There is no public relay that serves draft-ietf-moq-msf-01 catalogs yet (Phase 0 interop is still owed), so this - * stands in for one: it speaks real draft-19 bytes over an in-memory `MoqtTransport` and publishes real + * stands in for one: it speaks real draft-20 bytes over an in-memory `MoqtTransport` and publishes real * WebCodecs-encoded media, which is enough to drive the whole engine — catalog → selection → subscribe → decode → * canvas + AudioContext. * @@ -19,7 +19,7 @@ import type { CreateMoqTransport } from '@videojs/spf/moq'; // ============================================================================ -// Wire primitives (draft-ietf-moq-transport-19) +// Wire primitives (draft-ietf-moq-transport-20) // ============================================================================ /** Control/request message types (§10, Table 5). */ @@ -40,8 +40,8 @@ const ERROR_INVALID_RANGE = 0x11; */ const SUBGROUP_HEADER_TYPE = 0x31; -/** LOC property IDs (draft-ietf-moq-loc-02 §2.3). */ -const LOC_TIMESTAMP = 0x06; +/** LOC property IDs (draft-ietf-moq-loc-04 §2.3). */ +const LOC_TIMESTAMP = 0x10; /** * The vi64 varint of draft-15+ (§1.4.1) — leading ones on the first byte give the encoded length minus one, so an @@ -672,8 +672,9 @@ export function createLoopbackRelay({ onLog }: LoopbackRelayOptions = {}): Loopb if (message.type === MESSAGE_TYPE.SUBSCRIBE) { onSubscribe(message.body); } else if (message.type === MESSAGE_TYPE.FETCH) { - // No history is retained: the engine falls back to joining the - // live catalog track, which is what a fresh live stream does. + // The engine never fetches — a draft-20 join is a subscription + // filter, and every subscription replays the newest group anyway. + // Anything else asking for history is refused: none is retained. await writer.write(encodeRequestError(ERROR_INVALID_RANGE, 'nothing published')); await writer.close(); return; diff --git a/apps/sandbox/templates/spf-moq-player/main.ts b/apps/sandbox/templates/spf-moq-player/main.ts index 097dd0dff4..3afc8cb04c 100644 --- a/apps/sandbox/templates/spf-moq-player/main.ts +++ b/apps/sandbox/templates/spf-moq-player/main.ts @@ -166,7 +166,7 @@ const DEFAULT_RELAY_ORIGIN = 'moqt://relay.mux.dev'; * (the same shape as the publisher sandbox's `?ns=`), and an optional JWT. Delegates to the engine's own * `composeMoqSource` so the page cannot drift from the encoding `parseMoqSource` accepts. The token rides the `c4m` * fragment parameter, which the engine composes onto the connect URL as `?jwt=` — the only auth carriage the relay - * fleet accepts (draft-19 AUTHORIZATION_TOKEN structures hard-close the session). + * fleet accepts (AUTHORIZATION_TOKEN request parameters hard-close the session). */ function composeMsfSource(origin: string, path: string, token: string): string { return composeMoqSource(origin.trim() || DEFAULT_RELAY_ORIGIN, path, token ? { token } : {}); diff --git a/packages/spf/src/media/moq/timeline.ts b/packages/spf/src/media/moq/timeline.ts index 59d2f63246..8a3f18bcac 100644 --- a/packages/spf/src/media/moq/timeline.ts +++ b/packages/spf/src/media/moq/timeline.ts @@ -191,8 +191,8 @@ export function preferredTargetLatencySeconds( /** * Media timestamp playout should join a jitter buffer at: `targetLatencySeconds` behind the newest buffered frame. A - * relay replays several recent groups to every joining subscriber, so anchoring at the oldest buffered frame instead - * parks playout that whole replay behind the live edge. + * current-group join (`relative-group 1`) is served from the relay's cache, so the first frames can be a whole group + * old; anchoring at the oldest buffered frame instead would park playout that whole replay behind the live edge. */ export function joinAnchorUs(newestTimestampUs: number, targetLatencySeconds: number): number { return newestTimestampUs - targetLatencySeconds * MICROSECONDS_PER_SECOND; diff --git a/packages/spf/src/network/moqt/bytes.ts b/packages/spf/src/network/moqt/bytes.ts index 8ba08d17e0..cfb7e66d9f 100644 --- a/packages/spf/src/network/moqt/bytes.ts +++ b/packages/spf/src/network/moqt/bytes.ts @@ -5,6 +5,7 @@ * fully buffered — the 16-bit message length bounds them). `StreamReader` is the asynchronous counterpart for * unidirectional data streams, where headers and objects arrive incrementally over a WebTransport `ReadableStream`. */ +import { isMoqtProtocolError } from './errors'; import { decodeVarint, encodeVarintInto, varintByteLength, varintLengthFromFirstByte } from './varint'; const textEncoder = new TextEncoder(); @@ -43,6 +44,22 @@ export class ByteReader { return value; } + /** + * Read a varint whose legal range exceeds this codec's 2^53−1 ceiling — PUBLISH_DONE's Stream Count uses 2^64−1 as + * its "could not count" sentinel (§10.12). A value above the ceiling reads as `undefined` and is skipped, instead of + * failing the session the way `readVarint` does. + */ + readUnboundedVarint(): number | undefined { + try { + return this.readVarint(); + } catch (error) { + if (!isMoqtProtocolError(error)) throw error; + + this.#offset += varintLengthFromFirstByte(this.#bytes[this.#offset]!); + return undefined; + } + } + readUint8(): number { if (this.remaining < 1) throw new RangeError('read past end of buffer'); diff --git a/packages/spf/src/network/moqt/control-messages.ts b/packages/spf/src/network/moqt/control-messages.ts index 6762153918..b6b7264c55 100644 --- a/packages/spf/src/network/moqt/control-messages.ts +++ b/packages/spf/src/network/moqt/control-messages.ts @@ -1,5 +1,5 @@ /** - * MOQT control-message wire codecs (moq-transport draft-19 §10). + * MOQT control-message wire codecs (moq-transport draft-20 §10). * * Every control or request-stream message is framed as: * @@ -14,24 +14,28 @@ * PUBLISH); the decoders cover what it receives. All draft-version specifics live in this directory — this is the * churn-absorption layer for pre-WGLC drafts. * + * Where the draft text and the deployed relay (moq-relay, moq-dev/moq) disagree on a wire detail, the codec follows the + * relay and says so at the site — interop is with the relay, not the prose. + * * Namespace fields and track names are byte strings on the wire; this codec surfaces them as UTF-8 `string`s, which is * what MSF (the streaming format this engine speaks) constrains them to. */ import { ByteReader, ByteWriter, utf8Decode, utf8Encode } from './bytes'; import { MoqtProtocolError } from './errors'; -import { decodeVarint } from './varint'; +import { decodeVarint, MAX_VARINT_VALUE } from './varint'; // ============================================================================ // Wire constants // ============================================================================ /** - * ALPN / WebTransport protocol identifier for the implemented draft. Version negotiation happens at connection time - * (`WT-Available-Protocols` in WebTransport, ALPN in native QUIC) — not in SETUP. + * ALPN / WebTransport protocol identifier for the implemented draft (§3.1: `moqt-` plus the draft number). Version + * negotiation happens at connection time (`WT-Available-Protocols` in WebTransport, ALPN in native QUIC) — not in + * SETUP. */ -export const MOQT_PROTOCOL_ID = 'moqt-19'; +export const MOQT_PROTOCOL_ID = 'moqt-20'; -/** Control/request message type codes (draft-19 §10, Table 5). */ +/** Control/request message type codes (§10, Table 5). */ export const MESSAGE_TYPE = { SETUP: 0x2f00, GOAWAY: 0x10, @@ -48,12 +52,13 @@ export const MESSAGE_TYPE = { FETCH: 0x16, FETCH_OK: 0x18, PUBLISH: 0x1d, + PUBLISH_STATE_NOTIFY: 0x22, REQUEST_UPDATE: 0x2, SUBSCRIBE_NAMESPACE: 0x50, SUBSCRIBE_TRACKS: 0x51, } as const; -/** Setup Option types (draft-19 §10.3.1). A namespace separate from message parameters. */ +/** Setup Option types (§10.3.1). A namespace separate from message parameters. */ export const SETUP_OPTION = { PATH: 0x01, AUTHORIZATION_TOKEN: 0x03, @@ -64,7 +69,7 @@ export const SETUP_OPTION = { MAX_REQUEST_UPDATES: 0x08, } as const; -/** Message parameter types (draft-19 §10.2). */ +/** Message parameter types (§10.2, §15.7). */ export const PARAMETER_TYPE = { OBJECT_DELIVERY_TIMEOUT: 0x02, AUTHORIZATION_TOKEN: 0x03, @@ -77,6 +82,7 @@ export const PARAMETER_TYPE = { SUBSCRIBER_PRIORITY: 0x20, LOCATION_FILTER: 0x21, GROUP_ORDER: 0x22, + FILL_PARAMETERS: 0x23, SUBGROUP_FILTER: 0x25, OBJECTID_FILTER: 0x26, PRIORITY_FILTER: 0x27, @@ -84,9 +90,10 @@ export const PARAMETER_TYPE = { TRACK_PROPERTY_FILTER: 0x29, NEW_GROUP_REQUEST: 0x32, TRACK_NAMESPACE_PREFIX: 0x34, + INCLUDE_PROPERTIES: 0x35, } as const; -/** REQUEST_ERROR codes (draft-19 §15.11.2). */ +/** REQUEST_ERROR codes (§15.11.2). */ export const REQUEST_ERROR_CODE = { INTERNAL_ERROR: 0x0, UNAUTHORIZED: 0x1, @@ -102,19 +109,17 @@ export const REQUEST_ERROR_CODE = { UNINTERESTED: 0x20, PREFIX_OVERLAP: 0x30, NAMESPACE_TOO_LARGE: 0x31, - INVALID_JOINING_REQUEST_ID: 0x32, UNSUPPORTED_EXTENSION: 0x33, REDIRECT: 0x34, CONFLICTING_FILTERS: 0x35, INVALID_FILTER: 0x36, } as const; -/** PUBLISH_DONE status codes (draft-19 §10.11). */ +/** PUBLISH_DONE status codes (§10.12). */ export const PUBLISH_DONE_STATUS = { INTERNAL_ERROR: 0x0, UNAUTHORIZED: 0x1, TRACK_ENDED: 0x2, - SUBSCRIPTION_ENDED: 0x3, GOING_AWAY: 0x4, TOO_FAR_BEHIND: 0x5, EXPIRED: 0x6, @@ -141,7 +146,6 @@ const PERMANENT_REQUEST_ERROR_CODES: ReadonlySet = new Set([ REQUEST_ERROR_CODE.UNINTERESTED, REQUEST_ERROR_CODE.PREFIX_OVERLAP, REQUEST_ERROR_CODE.NAMESPACE_TOO_LARGE, - REQUEST_ERROR_CODE.INVALID_JOINING_REQUEST_ID, REQUEST_ERROR_CODE.UNSUPPORTED_EXTENSION, // Until session migration exists, the redirect target is unreachable and // re-asking the same relay just re-earns the redirect. @@ -177,7 +181,7 @@ export function isRetryablePublishDoneStatus(statusCode: number): boolean { return !PERMANENT_PUBLISH_DONE_STATUSES.has(statusCode); } -/** Stream reset / STOP_SENDING error codes (draft-19 §3.3.4). */ +/** Stream reset / STOP_SENDING error codes (§3.3.4). */ export const STREAM_RESET_CODE = { INTERNAL_ERROR: 0x0, CANCELLED: 0x1, @@ -199,12 +203,13 @@ const MAX_FULL_TRACK_NAME_LENGTH = 4096; const MAX_REASON_PHRASE_LENGTH = 1024; const MAX_NEW_SESSION_URI_LENGTH = 8192; const MAX_KVP_VALUE_LENGTH = 0xffff; +const MAX_LOCATION_FILTER_FIELDS = 4; // ============================================================================ // Shared structures // ============================================================================ -/** A particular Object in a Group within a Track (draft-19 §1.4.2). */ +/** A particular Object in a Group within a Track (§1.4.2). */ export interface Location { group: number; object: number; @@ -287,8 +292,30 @@ function readLocation(reader: ByteReader): Location { return { group: reader.readVarint(), object: reader.readVarint() }; } +/** + * LARGEST_OBJECT rides inside a length prefix. §10.2 defines a Location parameter as two bare varints, but moq-relay — + * the peer this engine is deployed against — applies the Key-Value-Pair parity rule to the odd type 0x09 and frames it + * with a Length on every draft (moq-dev/moq#3255 records it as a spec conflict). The two forms are indistinguishable on + * the wire, so the codec follows the relay. + */ +function writeLocationParameter(writer: ByteWriter, location: Location): void { + const value = new ByteWriter(16); + + writeLocation(value, location); + writer.writeLengthPrefixed(value.toBytes()); +} + +function readLocationParameter(reader: ByteReader): Location { + const value = new ByteReader(reader.readBytes(reader.readVarint())); + const location = readLocation(value); + + if (value.remaining !== 0) throw new MoqtProtocolError('Location parameter has trailing bytes'); + + return location; +} + // ============================================================================ -// Key-Value-Pairs (draft-19 §1.4.3) — Setup Options and Track Properties +// Key-Value-Pairs (§1.4.3) — Setup Options and Track Properties // ============================================================================ /** @@ -349,33 +376,60 @@ export function decodeKeyValuePairs(reader: ByteReader, endOffset: number): KeyV } // ============================================================================ -// Location Filters (draft-19 §5.1.2) — carried in the LOCATION_FILTER parameter +// Location Filters (§5.1.2) — carried in the LOCATION_FILTER parameter // ============================================================================ +/** + * Which Objects a subscription or fetch covers. On the wire the LOCATION_FILTER value is up to four varints — + * StartGroup, StartObject, EndGroupDelta, EndObject — and how many are present selects the meaning: + * + * - `none` — zero fields. Unfiltered: the whole track for a subscription, `{0,0}` up to Largest Object for a fetch; in + * REQUEST_UPDATE it clears the filter. + * - `relative-group` — one field. Start at `{Largest.Group + 1 − groupsBeforeNext, 0}`, open-ended: `0` is the next + * group, `1` the start of the current group (a decodable join), `N` N−1 groups before it. + * - `next-object` — the two-field spelling `{0,0}`: `{Largest.Group, Largest.Object + 1}`, the live edge, which can begin + * mid-group. + * - `absolute` — two to four fields: an explicit start, optionally bounded by an end group (delta from the start group, + * whole group included unless `endObject` narrows it). An open-ended absolute `{0,0}` is unfiltered by definition and + * encodes as `none` — its two-field spelling would read as `next-object`. + */ export type LocationFilter = - | { type: 'largest-object' } - | { type: 'next-group-start' } - | { type: 'absolute-start'; start: Location } - | { type: 'absolute-range'; start: Location; endGroupDelta: number }; - -const LOCATION_FILTER_TYPE = { - 'next-group-start': 0x1, - 'largest-object': 0x2, - 'absolute-start': 0x3, - 'absolute-range': 0x4, -} as const; + | { type: 'none' } + | { type: 'next-object' } + | { type: 'relative-group'; groupsBeforeNext: number } + | { type: 'absolute'; start: Location; endGroupDelta?: number; endObject?: number }; +/** Serialize a filter as the LOCATION_FILTER parameter's value (without its length prefix). */ export function encodeLocationFilter(filter: LocationFilter): Uint8Array { const writer = new ByteWriter(32); - writer.writeVarint(LOCATION_FILTER_TYPE[filter.type]); + switch (filter.type) { + case 'none': + break; + case 'next-object': + writer.writeVarint(0); + writer.writeVarint(0); + break; + case 'relative-group': + writer.writeVarint(filter.groupsBeforeNext); + break; + case 'absolute': { + const { start, endGroupDelta, endObject } = filter; + + if (endObject !== undefined && endGroupDelta === undefined) { + throw new MoqtProtocolError('location filter end object requires an end group'); + } + + if (start.group === 0 && start.object === 0 && endGroupDelta === undefined) break; - if (filter.type === 'absolute-start' || filter.type === 'absolute-range') { - writeLocation(writer, filter.start); - } + writeLocation(writer, start); + + if (endGroupDelta !== undefined) writer.writeVarint(endGroupDelta); + + if (endObject !== undefined) writer.writeVarint(endObject); - if (filter.type === 'absolute-range') { - writer.writeVarint(filter.endGroupDelta); + break; + } } return writer.toBytes(); @@ -383,39 +437,48 @@ export function encodeLocationFilter(filter: LocationFilter): Uint8Array { export function decodeLocationFilter(bytes: Uint8Array): LocationFilter { const reader = new ByteReader(bytes); - const type = reader.readVarint(); - const filter = ((): LocationFilter => { - switch (type) { - case LOCATION_FILTER_TYPE['next-group-start']: - return { type: 'next-group-start' }; - case LOCATION_FILTER_TYPE['largest-object']: - return { type: 'largest-object' }; - case LOCATION_FILTER_TYPE['absolute-start']: - return { type: 'absolute-start', start: readLocation(reader) }; - case LOCATION_FILTER_TYPE['absolute-range']: - return { type: 'absolute-range', start: readLocation(reader), endGroupDelta: reader.readVarint() }; - default: - throw new MoqtProtocolError(`unknown location filter type ${type}`); + const fields: number[] = []; + + while (reader.remaining > 0) { + if (fields.length === MAX_LOCATION_FILTER_FIELDS) { + throw new MoqtProtocolError('location filter has more than four fields'); + } + + fields.push(reader.readVarint()); + } + + if (fields.length === 0) return { type: 'none' }; + + if (fields.length === 1) return { type: 'relative-group', groupsBeforeNext: fields[0]! }; + + const [group, object, endGroupDelta, endObject] = fields as [number, number, number?, number?]; + if (fields.length === 2 && group === 0 && object === 0) return { type: 'next-object' }; + + const filter: LocationFilter = { type: 'absolute', start: { group, object } }; + + if (endGroupDelta !== undefined) { + if (group + endGroupDelta > MAX_VARINT_VALUE) { + throw new MoqtProtocolError('location filter end group exceeds supported range'); } - })(); - if (reader.remaining !== 0) { - throw new MoqtProtocolError('location filter has trailing bytes'); + filter.endGroupDelta = endGroupDelta; } + if (endObject !== undefined) filter.endObject = endObject; + return filter; } // ============================================================================ -// Message Parameters (draft-19 §10.2) +// Message Parameters (§10.2) // ============================================================================ export type GroupOrder = 'ascending' | 'descending'; /** * Decoded message parameters. Unlike Setup Options, message parameters use per-type encodings (uint8 / varint / - * Location / length-prefixed), so the codec is registry-driven. Per §10.2 an unknown parameter type is a - * PROTOCOL_VIOLATION (parameters cannot be skipped — the block is bounded by count, not length). + * length-prefixed), so the codec is registry-driven. Per §10.2 an unknown parameter type is a PROTOCOL_VIOLATION + * (parameters cannot be skipped — the block is bounded by count, not length). */ export interface MessageParameters { objectDeliveryTimeout?: number; @@ -430,12 +493,39 @@ export interface MessageParameters { subscriberPriority?: number; locationFilter?: LocationFilter; groupOrder?: GroupOrder; + /** + * FILL_PARAMETERS (§10.2.15): asks the publisher to deliver a fill range on a fetch stream alongside the subscription + * — its presence alone requests the fill. A nested parameter scope: only the fill-scoped subset is legal inside, and + * omitted entries inherit the subscription's own values. + */ + fillParameters?: FillParameters; newGroupRequest?: number; - /** Range-filter parameters (§5.1.3), kept opaque — the engine never sends or interprets them. */ + /** Range-filter parameters (§5.1.4), kept opaque — the engine never sends or interprets them. */ rangeFilters?: { type: number; value: Uint8Array }[]; trackNamespacePrefix?: TrackNamespace; + /** INCLUDE_PROPERTIES (§10.2.21): `0` asks the responder to send empty Track Properties. Default `1`. */ + includeProperties?: 0 | 1; } +/** The parameters FILL_PARAMETERS may carry (§10.2.15, Table 6). */ +export type FillParameters = Pick< + MessageParameters, + 'fillTimeout' | 'subscriberPriority' | 'locationFilter' | 'groupOrder' | 'rangeFilters' +>; + +type ParameterScope = 'message' | 'fill'; + +const FILL_SCOPE_TYPES: ReadonlySet = new Set([ + PARAMETER_TYPE.FILL_TIMEOUT, + PARAMETER_TYPE.SUBSCRIBER_PRIORITY, + PARAMETER_TYPE.LOCATION_FILTER, + PARAMETER_TYPE.GROUP_ORDER, + PARAMETER_TYPE.SUBGROUP_FILTER, + PARAMETER_TYPE.OBJECTID_FILTER, + PARAMETER_TYPE.PRIORITY_FILTER, + PARAMETER_TYPE.OBJECT_PROPERTY_FILTER, +]); + const GROUP_ORDER_WIRE: Record = { ascending: 0x1, descending: 0x2 }; interface ParameterEntry { @@ -472,7 +562,7 @@ function collectParameterEntries(parameters: MessageParameters): ParameterEntry[ } if (parameters.largestObject !== undefined) { - push(PARAMETER_TYPE.LARGEST_OBJECT, (w) => writeLocation(w, parameters.largestObject!)); + push(PARAMETER_TYPE.LARGEST_OBJECT, (w) => writeLocationParameter(w, parameters.largestObject!)); } if (parameters.forward !== undefined) { @@ -493,6 +583,12 @@ function collectParameterEntries(parameters: MessageParameters): ParameterEntry[ push(PARAMETER_TYPE.GROUP_ORDER, (w) => w.writeUint8(GROUP_ORDER_WIRE[parameters.groupOrder!])); } + if (parameters.fillParameters !== undefined) { + push(PARAMETER_TYPE.FILL_PARAMETERS, (w) => + w.writeLengthPrefixed(encodeFillParameters(parameters.fillParameters!)) + ); + } + if (parameters.newGroupRequest !== undefined) { push(PARAMETER_TYPE.NEW_GROUP_REQUEST, (w) => w.writeVarint(parameters.newGroupRequest!)); } @@ -505,13 +601,32 @@ function collectParameterEntries(parameters: MessageParameters): ParameterEntry[ push(PARAMETER_TYPE.TRACK_NAMESPACE_PREFIX, (w) => writeTrackNamespace(w, parameters.trackNamespacePrefix!)); } + if (parameters.includeProperties !== undefined) { + push(PARAMETER_TYPE.INCLUDE_PROPERTIES, (w) => w.writeLengthPrefixed(Uint8Array.of(parameters.includeProperties!))); + } + return entries; } -/** Serialize as `Number of Parameters (vi64)` + delta-typed parameter list. */ -export function encodeMessageParameters(writer: ByteWriter, parameters: MessageParameters = {}): void { +/** + * Serialize as `Number of Parameters (vi64)` + delta-typed parameter list. The `'fill'` scope is the nested list inside + * FILL_PARAMETERS, where only Table 6's types are legal. + */ +export function encodeMessageParameters( + writer: ByteWriter, + parameters: MessageParameters = {}, + scope: ParameterScope = 'message' +): void { const entries = collectParameterEntries(parameters).sort((a, b) => a.type - b.type); + if (scope === 'fill') { + const disallowed = entries.find((entry) => !FILL_SCOPE_TYPES.has(entry.type)); + + if (disallowed) { + throw new MoqtProtocolError(`parameter type ${disallowed.type} is not allowed inside FILL_PARAMETERS`); + } + } + writer.writeVarint(entries.length); let previousType = 0; @@ -522,6 +637,14 @@ export function encodeMessageParameters(writer: ByteWriter, parameters: MessageP } } +/** FILL_PARAMETERS' value: a parameter list encoded as if for a separate message (§10.2.15). */ +function encodeFillParameters(fill: FillParameters): Uint8Array { + const writer = new ByteWriter(64); + + encodeMessageParameters(writer, fill, 'fill'); + return writer.toBytes(); +} + const RANGE_FILTER_TYPES: readonly number[] = [ PARAMETER_TYPE.SUBGROUP_FILTER, PARAMETER_TYPE.OBJECTID_FILTER, @@ -530,7 +653,7 @@ const RANGE_FILTER_TYPES: readonly number[] = [ PARAMETER_TYPE.TRACK_PROPERTY_FILTER, ]; -export function decodeMessageParameters(reader: ByteReader): MessageParameters { +export function decodeMessageParameters(reader: ByteReader, scope: ParameterScope = 'message'): MessageParameters { const count = reader.readVarint(); const parameters: MessageParameters = {}; let previousType = 0; @@ -540,6 +663,12 @@ export function decodeMessageParameters(reader: ByteReader): MessageParameters { previousType = type; + // §10.2.15: a type outside Table 6 inside FILL_PARAMETERS is a + // PROTOCOL_VIOLATION, the nested scope included. + if (scope === 'fill' && !FILL_SCOPE_TYPES.has(type)) { + throw new MoqtProtocolError(`parameter type ${type} is not allowed inside FILL_PARAMETERS`); + } + switch (type) { case PARAMETER_TYPE.OBJECT_DELIVERY_TIMEOUT: parameters.objectDeliveryTimeout = reader.readVarint(); @@ -563,7 +692,7 @@ export function decodeMessageParameters(reader: ByteReader): MessageParameters { parameters.expires = reader.readVarint(); break; case PARAMETER_TYPE.LARGEST_OBJECT: - parameters.largestObject = readLocation(reader); + parameters.largestObject = readLocationParameter(reader); break; case PARAMETER_TYPE.FORWARD: { const forward = reader.readUint8(); @@ -585,12 +714,34 @@ export function decodeMessageParameters(reader: ByteReader): MessageParameters { parameters.groupOrder = order === 0x1 ? 'ascending' : 'descending'; break; } + case PARAMETER_TYPE.FILL_PARAMETERS: { + const value = new ByteReader(reader.readBytes(reader.readVarint())); + + parameters.fillParameters = decodeMessageParameters(value, 'fill'); + + if (value.remaining !== 0) throw new MoqtProtocolError('FILL_PARAMETERS has trailing bytes'); + + break; + } case PARAMETER_TYPE.NEW_GROUP_REQUEST: parameters.newGroupRequest = reader.readVarint(); break; case PARAMETER_TYPE.TRACK_NAMESPACE_PREFIX: parameters.trackNamespacePrefix = readTrackNamespace(reader); break; + case PARAMETER_TYPE.INCLUDE_PROPERTIES: { + // §10.2.21 calls the value a uint8; moq-relay frames it + // length-prefixed by the odd-type parity rule (moq-dev/moq#3255), + // and the codec follows the relay — see `writeLocationParameter`. + const value = reader.readBytes(reader.readVarint()); + + if (value.length !== 1 || value[0]! > 1) { + throw new MoqtProtocolError(`invalid INCLUDE_PROPERTIES value ${Array.from(value).join(',')}`); + } + + parameters.includeProperties = value[0] as 0 | 1; + break; + } default: { if (RANGE_FILTER_TYPES.includes(type)) { const value = reader.readBytes(reader.readVarint()); @@ -610,7 +761,7 @@ export function decodeMessageParameters(reader: ByteReader): MessageParameters { } // ============================================================================ -// Authorization tokens (draft-19 §10.2.2) +// Authorization tokens (§10.2.2) // ============================================================================ /** @@ -740,70 +891,37 @@ export interface SubscribeRequest { parameters?: MessageParameters; } -/** SUBSCRIBE (§10.7) — first message on a new request stream. */ -export function encodeSubscribe(request: SubscribeRequest): Uint8Array { - const body = new ByteWriter(); - - body.writeVarint(request.requestId); - writeTrackNamespace(body, request.trackNamespace); - body.writeLengthPrefixed(utf8Encode(request.trackName)); - encodeMessageParameters(body, request.parameters); - return frameMessage(MESSAGE_TYPE.SUBSCRIBE, body); -} +/** + * FETCH (§10.13) has the SUBSCRIBE body: the range is `parameters.locationFilter`, evaluated with the fetch rules of + * §5.1.2 — relative starts count back from Largest Object, an omitted end stops there, and no filter means the whole + * track. Nothing selects "standalone" or "joining" any more; a join is a subscription with FILL_PARAMETERS. + */ +export type FetchRequest = SubscribeRequest; -/** TRACK_STATUS (§10.14) — identical wire format to SUBSCRIBE. */ -export function encodeTrackStatus(request: SubscribeRequest): Uint8Array { +/** SUBSCRIBE, TRACK_STATUS, and FETCH share one body: Request ID, Full Track Name, Parameters. */ +function encodeTrackRequest(type: number, request: SubscribeRequest): Uint8Array { const body = new ByteWriter(); body.writeVarint(request.requestId); writeTrackNamespace(body, request.trackNamespace); body.writeLengthPrefixed(utf8Encode(request.trackName)); encodeMessageParameters(body, request.parameters); - return frameMessage(MESSAGE_TYPE.TRACK_STATUS, body); + return frameMessage(type, body); } -export type FetchRequest = - | { - requestId: number; - type: 'standalone'; - trackNamespace: TrackNamespace; - trackName: string; - startLocation: Location; - /** The end Location, plus 1; `object: 0` requests the entire group. */ - endLocation: Location; - parameters?: MessageParameters; - } - | { - requestId: number; - type: 'relative-joining' | 'absolute-joining'; - /** Request ID of the subscription this fetch joins. */ - joiningRequestId: number; - /** Relative: groups before the Joining Location. Absolute: the start Group ID. */ - joiningStart: number; - parameters?: MessageParameters; - }; +/** SUBSCRIBE (§10.7) — first message on a new request stream. */ +export function encodeSubscribe(request: SubscribeRequest): Uint8Array { + return encodeTrackRequest(MESSAGE_TYPE.SUBSCRIBE, request); +} -const FETCH_TYPE_WIRE = { standalone: 0x1, 'relative-joining': 0x2, 'absolute-joining': 0x3 } as const; +/** TRACK_STATUS (§10.15) — identical wire format to SUBSCRIBE. */ +export function encodeTrackStatus(request: SubscribeRequest): Uint8Array { + return encodeTrackRequest(MESSAGE_TYPE.TRACK_STATUS, request); +} -/** FETCH (§10.12) — first message on a new request stream. */ +/** FETCH (§10.13) — first message on a new request stream. */ export function encodeFetch(request: FetchRequest): Uint8Array { - const body = new ByteWriter(); - - body.writeVarint(request.requestId); - body.writeVarint(FETCH_TYPE_WIRE[request.type]); - - if (request.type === 'standalone') { - writeTrackNamespace(body, request.trackNamespace); - body.writeLengthPrefixed(utf8Encode(request.trackName)); - writeLocation(body, request.startLocation); - writeLocation(body, request.endLocation); - } else { - body.writeVarint(request.joiningRequestId); - body.writeVarint(request.joiningStart); - } - - encodeMessageParameters(body, request.parameters); - return frameMessage(MESSAGE_TYPE.FETCH, body); + return encodeTrackRequest(MESSAGE_TYPE.FETCH, request); } export interface SubscribeNamespaceRequest { @@ -812,7 +930,7 @@ export interface SubscribeNamespaceRequest { parameters?: MessageParameters; } -/** SUBSCRIBE_NAMESPACE (§10.18) — first message on a new request stream. */ +/** SUBSCRIBE_NAMESPACE (§10.19) — first message on a new request stream. */ export function encodeSubscribeNamespace(request: SubscribeNamespaceRequest): Uint8Array { const body = new ByteWriter(); @@ -822,7 +940,11 @@ export function encodeSubscribeNamespace(request: SubscribeNamespaceRequest): Ui return frameMessage(MESSAGE_TYPE.SUBSCRIBE_NAMESPACE, body); } -/** REQUEST_UPDATE (§10.9) — sent on an existing request stream. */ +/** + * REQUEST_UPDATE (§10.9) — sent on an existing request stream. `requestId` is the update's own, freshly allocated + * Request ID (§10.1 counts REQUEST_UPDATE among the messages that consume one); the stream identifies the request being + * updated. + */ export function encodeRequestUpdate(requestId: number, parameters: MessageParameters = {}): Uint8Array { const body = new ByteWriter(); @@ -845,7 +967,8 @@ export function encodeGoaway(timeout = 0): Uint8Array { /** * REQUEST_OK (§10.5). The subscriber sends this to accept an incoming PUBLISH (PUBLISH_OK). Track Properties are always - * empty in that role. + * empty in that role, and since draft-20 so are the parameters — a subscriber changes subscription parameters with + * REQUEST_UPDATE, not in PUBLISH_OK (§10.11). */ export function encodeRequestOk(parameters: MessageParameters = {}): Uint8Array { const body = new ByteWriter(); @@ -886,7 +1009,7 @@ export function encodeSubscribeOk( return frameMessage(MESSAGE_TYPE.SUBSCRIBE_OK, body); } -/** PUBLISH_DONE (§10.11). */ +/** PUBLISH_DONE (§10.12). */ export function encodePublishDone(statusCode: number, streamCount: number, reason = ''): Uint8Array { const body = new ByteWriter(); @@ -896,7 +1019,15 @@ export function encodePublishDone(statusCode: number, streamCount: number, reaso return frameMessage(MESSAGE_TYPE.PUBLISH_DONE, body); } -/** FETCH_OK (§10.13). */ +/** PUBLISH_STATE_NOTIFY (§10.10) — the publisher's unilateral "these subscription parameters changed". */ +export function encodePublishStateNotify(parameters: MessageParameters = {}): Uint8Array { + const body = new ByteWriter(); + + encodeMessageParameters(body, parameters); + return frameMessage(MESSAGE_TYPE.PUBLISH_STATE_NOTIFY, body); +} + +/** FETCH_OK (§10.14). */ export function encodeFetchOk( endOfTrack: boolean, endLocation: Location, @@ -912,7 +1043,7 @@ export function encodeFetchOk( return frameMessage(MESSAGE_TYPE.FETCH_OK, body); } -/** PUBLISH (§10.10). */ +/** PUBLISH (§10.11). */ export function encodePublish( request: SubscribeRequest & { trackAlias: number }, trackProperties: readonly KeyValuePair[] = [] @@ -934,7 +1065,7 @@ export interface PublishNamespaceRequest { parameters?: MessageParameters; } -/** PUBLISH_NAMESPACE (§10.15) — a publisher announcing a namespace. */ +/** PUBLISH_NAMESPACE (§10.16) — a publisher announcing a namespace. */ export function encodePublishNamespace(request: PublishNamespaceRequest): Uint8Array { const body = new ByteWriter(); @@ -971,7 +1102,7 @@ export type ControlMessage = trackName: string; parameters: MessageParameters; } - | { kind: 'fetch'; request: FetchRequest } + | { kind: 'fetch'; request: FetchRequest & { parameters: MessageParameters } } | { kind: 'subscribe-namespace'; requestId: number; @@ -982,7 +1113,14 @@ export type ControlMessage = | { kind: 'request-ok'; parameters: MessageParameters; trackProperties: KeyValuePair[] } | { kind: 'request-error'; errorCode: number; retryInterval: number; reason: string; redirect?: Redirect } | { kind: 'request-update'; requestId: number; parameters: MessageParameters } - | { kind: 'publish-done'; statusCode: number; streamCount: number; reason: string } + | { kind: 'publish-state-notify'; parameters: MessageParameters } + | { + kind: 'publish-done'; + statusCode: number; + /** `undefined` when the publisher could not count its streams (the 2^64−1 sentinel, §10.12). */ + streamCount: number | undefined; + reason: string; + } | { kind: 'publish'; requestId: number; @@ -1086,9 +1224,14 @@ function decodeControlMessageBody(type: number, reader: ByteReader, end: number) return { kind: 'request-update', requestId, parameters: decodeMessageParameters(reader) }; } + case MESSAGE_TYPE.PUBLISH_STATE_NOTIFY: + return { kind: 'publish-state-notify', parameters: decodeMessageParameters(reader) }; case MESSAGE_TYPE.PUBLISH_DONE: { const statusCode = reader.readVarint(); - const streamCount = reader.readVarint(); + // A publisher that cannot count its streams MUST send 2^64−1 (§10.12), + // which is above this codec's varint ceiling — read it as "unknown" + // rather than failing the session over a legitimate PUBLISH_DONE. + const streamCount = reader.readUnboundedVarint(); return { kind: 'publish-done', statusCode, streamCount, reason: readReasonPhrase(reader) }; } @@ -1132,42 +1275,20 @@ function decodeControlMessageBody(type: number, reader: ByteReader, end: number) }; } case MESSAGE_TYPE.SUBSCRIBE: - case MESSAGE_TYPE.TRACK_STATUS: { + case MESSAGE_TYPE.TRACK_STATUS: + case MESSAGE_TYPE.FETCH: { const requestId = reader.readVarint(); const trackNamespace = readTrackNamespace(reader); const trackName = utf8Decode(reader.readBytes(reader.readVarint())); const parameters = decodeMessageParameters(reader); - const kind = type === MESSAGE_TYPE.SUBSCRIBE ? 'subscribe' : 'track-status'; - - return { kind, requestId, trackNamespace, trackName, parameters }; - } - case MESSAGE_TYPE.FETCH: { - const requestId = reader.readVarint(); - const fetchType = reader.readVarint(); - - if (fetchType === FETCH_TYPE_WIRE.standalone) { - const trackNamespace = readTrackNamespace(reader); - const trackName = utf8Decode(reader.readBytes(reader.readVarint())); - const startLocation = readLocation(reader); - const endLocation = readLocation(reader); - const parameters = decodeMessageParameters(reader); - - return { - kind: 'fetch', - request: { requestId, type: 'standalone', trackNamespace, trackName, startLocation, endLocation, parameters }, - }; - } - if (fetchType !== FETCH_TYPE_WIRE['relative-joining'] && fetchType !== FETCH_TYPE_WIRE['absolute-joining']) { - throw new MoqtProtocolError(`unknown fetch type ${fetchType}`); + if (type === MESSAGE_TYPE.FETCH) { + return { kind: 'fetch', request: { requestId, trackNamespace, trackName, parameters } }; } - const joiningRequestId = reader.readVarint(); - const joiningStart = reader.readVarint(); - const parameters = decodeMessageParameters(reader); - const joiningType = fetchType === FETCH_TYPE_WIRE['relative-joining'] ? 'relative-joining' : 'absolute-joining'; + const kind = type === MESSAGE_TYPE.SUBSCRIBE ? 'subscribe' : 'track-status'; - return { kind: 'fetch', request: { requestId, type: joiningType, joiningRequestId, joiningStart, parameters } }; + return { kind, requestId, trackNamespace, trackName, parameters }; } case MESSAGE_TYPE.SUBSCRIBE_NAMESPACE: { const requestId = reader.readVarint(); diff --git a/packages/spf/src/network/moqt/errors.ts b/packages/spf/src/network/moqt/errors.ts index 206dec2a3d..ee16c972aa 100644 --- a/packages/spf/src/network/moqt/errors.ts +++ b/packages/spf/src/network/moqt/errors.ts @@ -1,5 +1,5 @@ /** - * MOQT session-termination error codes (moq-transport draft-19 §3.5). Used as the close code when terminating the + * MOQT session-termination error codes (moq-transport draft-20 §3.5). Used as the close code when terminating the * transport session and as the `code` carried by `MoqtProtocolError`. */ export const SESSION_ERROR = { @@ -17,7 +17,6 @@ export const SESSION_ERROR = { DATA_STREAM_TIMEOUT: 0x12, AUTH_TOKEN_CACHE_OVERFLOW: 0x13, DUPLICATE_AUTH_TOKEN_ALIAS: 0x14, - VERSION_NEGOTIATION_FAILED: 0x15, MALFORMED_AUTH_TOKEN: 0x16, UNKNOWN_AUTH_TOKEN_ALIAS: 0x17, EXPIRED_AUTH_TOKEN: 0x18, diff --git a/packages/spf/src/network/moqt/object-stream.ts b/packages/spf/src/network/moqt/object-stream.ts index 6de7853129..424c80dda2 100644 --- a/packages/spf/src/network/moqt/object-stream.ts +++ b/packages/spf/src/network/moqt/object-stream.ts @@ -1,11 +1,12 @@ /** - * MOQT unidirectional data-stream parsing (moq-transport draft-19 §3.4, §11). + * MOQT unidirectional data-stream parsing (moq-transport draft-20 §3.4, §11). * * Every unidirectional stream begins with a varint stream type: * - * - `SUBGROUP_HEADER` (0b0XX1XXXX) — objects for one subgroup of one group of a subscribed track, identified by Track - * Alias. - * - `FETCH_HEADER` (0x05) — objects for a FETCH response, identified by Request ID. + * - `SUBGROUP_HEADER` (a Type Flags bitfield with bit 4 set, §11.4.2) — objects for one subgroup of one group of a + * subscribed track, identified by Track Alias. + * - `FETCH_HEADER` (0x05) — objects for a FETCH response, identified by Request ID. A fill fetch stream (§5.1.3) has the + * same shape and names the SUBSCRIBE or REQUEST_UPDATE that asked for it. * - `SETUP` (0x2F00) — the peer's control stream (handled by the session). * - `PADDING` (0x132B3E28) — bandwidth probing; drained and ignored. * @@ -28,8 +29,9 @@ export const STREAM_TYPE = { } as const; /** - * Whether a stream-type varint is a SUBGROUP_HEADER. Valid values have the form 0b0XX1XXXX (bit 4 set, bit 7 clear) - * with SUBGROUP_ID_MODE ≠ 0b11 (reserved). + * Whether a stream-type varint is a SUBGROUP_HEADER. §11.4.2 describes the type as Type Flags: bit 4 is always set, + * SUBGROUP_ID_MODE 0b11 is reserved, and a value of 128 or more — or any set bit without a specified meaning — is a + * PROTOCOL_VIOLATION. Every bit below 0x80 is assigned, so "bit 7 clear" is that last rule in full. */ export function isSubgroupHeaderType(type: number): boolean { if (type > 0x7f || (type & 0x10) === 0) return false; @@ -218,8 +220,18 @@ const FETCH_FLAG = { DATAGRAM: 0x40, } as const; -const FETCH_END_OF_NON_EXISTENT_RANGE = 0x8c; -const FETCH_END_OF_UNKNOWN_RANGE = 0x10c; +/** End of Range serialization flags (§11.4.4, Table 7). */ +const FETCH_END_OF_RANGE_STATUS: Record = { + 0x8c: 'non-existent', + 0x10c: 'unknown', + 0x20c: 'timed-out', +}; + +/** + * Why a run of Locations was not serialized: they do not exist, their status is unknown to the relay, or the relay's + * Fill Timeout expired before upstream supplied them (§10.2.5). + */ +export type FetchEndOfRangeStatus = 'non-existent' | 'unknown' | 'timed-out'; export type FetchStreamEntry = | { @@ -234,7 +246,7 @@ export type FetchStreamEntry = } | { kind: 'end-of-range'; - status: 'non-existent' | 'unknown'; + status: FetchEndOfRangeStatus; groupId: number; objectId: number; }; @@ -256,16 +268,16 @@ export async function* readFetchEntries( while (!(await reader.atEnd())) { const flags = await reader.readVarint(); + const endOfRange = FETCH_END_OF_RANGE_STATUS[flags]; - if (flags === FETCH_END_OF_NON_EXISTENT_RANGE || flags === FETCH_END_OF_UNKNOWN_RANGE) { + if (endOfRange !== undefined) { const groupId = await reader.readVarint(); const objectId = await reader.readVarint(); - const status = flags === FETCH_END_OF_NON_EXISTENT_RANGE ? 'non-existent' : 'unknown'; // The indicator becomes the prior Location; subgroup/priority carry // over from the last actual object (§11.4.4.2). prior = { groupId, objectId, subgroupId: prior?.subgroupId, priority: prior?.priority }; - yield { kind: 'end-of-range', status, groupId, objectId }; + yield { kind: 'end-of-range', status: endOfRange, groupId, objectId }; continue; } diff --git a/packages/spf/src/network/moqt/request-stream.ts b/packages/spf/src/network/moqt/request-stream.ts index 72bd8e67d0..38c20e3637 100644 --- a/packages/spf/src/network/moqt/request-stream.ts +++ b/packages/spf/src/network/moqt/request-stream.ts @@ -1,7 +1,7 @@ /** - * Per-request bidirectional-stream lifecycle (moq-transport draft-19 §3.3). + * Per-request bidirectional-stream lifecycle (moq-transport draft-20 §3.3). * - * Draft-19's control model is request-stream based: each request (SUBSCRIBE, FETCH, TRACK_STATUS, …) opens its own + * The control model is request-stream based: each request (SUBSCRIBE, FETCH, TRACK_STATUS, …) opens its own * bidirectional stream, the first message on it is the request, and responses (SUBSCRIBE_OK / REQUEST_OK / * REQUEST_ERROR / PUBLISH_DONE / GOAWAY) arrive as control messages on the same stream. There is no UNSUBSCRIBE message * — cancellation IS the stream lifecycle: abort our sending direction (RESET_STREAM) and cancel the receiving direction diff --git a/packages/spf/src/network/moqt/session.ts b/packages/spf/src/network/moqt/session.ts index 6a4918e6c1..e4a3be06ee 100644 --- a/packages/spf/src/network/moqt/session.ts +++ b/packages/spf/src/network/moqt/session.ts @@ -1,5 +1,5 @@ /** - * Pure MOQT session protocol driver (moq-transport draft-19), subscribe side only. + * Pure MOQT session protocol driver (moq-transport draft-20), subscribe side only. * * Owns the protocol mechanics over an established transport: the SETUP exchange on paired unidirectional control * streams (§3.3), request-stream bookkeeping keyed by Request ID (§10.1 — client IDs are even, starting at 0), routing @@ -88,7 +88,8 @@ export interface SubscribeOk { export interface PublishDone { statusCode: number; - streamCount: number; + /** Data streams the publisher opened; `undefined` when it could not count them (§10.12). */ + streamCount: number | undefined; reason: string; } @@ -103,6 +104,11 @@ export interface SubscriptionHandlers { onDone?(done: PublishDone): void; /** Response to a REQUEST_UPDATE sent on this subscription. */ onUpdateOk?(): void; + /** + * PUBLISH_STATE_NOTIFY (§10.10): the publisher changed subscription state on its own — `parameters` carries only what + * changed, with LARGEST_OBJECT marking where. Informational; the session sends no reply. + */ + onStateNotify?(parameters: MessageParameters): void; /** GOAWAY on this request stream: re-issue the request (possibly elsewhere). */ onGoaway?(goaway: Goaway): void; } @@ -111,10 +117,7 @@ export interface Subscription { readonly requestId: number; /** Modify the subscription (REQUEST_UPDATE, §10.9). */ update(parameters: MessageParameters): void; - /** - * Tear the subscription down. Draft-19 has no UNSUBSCRIBE message — teardown is the request stream's lifecycle - * (§3.3.3). - */ + /** Tear the subscription down. MOQT has no UNSUBSCRIBE message — teardown is the request stream's lifecycle (§3.3.3). */ cancel(reason?: unknown): void; } @@ -188,7 +191,7 @@ export interface MoqtSessionConfig { unknownAliasTimeoutMs?: number; /** * How long to wait for a request's first response (SUBSCRIBE_OK / FETCH_OK / REQUEST_OK / REQUEST_ERROR) before - * failing it. Draft-19 expects implementations to bound control exchanges (§3.5's CONTROL_MESSAGE_TIMEOUT); without + * failing it. The draft expects implementations to bound control exchanges (§3.5's CONTROL_MESSAGE_TIMEOUT); without * this a relay that accepts the stream and then goes quiet leaves the request pending forever. Default 10000ms. */ requestTimeoutMs?: number; @@ -201,22 +204,11 @@ export interface MoqtSubscribeOptions { parameters?: MessageParameters; } -/** A joining fetch omits namespace/name — they come from the joined subscription. */ -export type MoqtFetchOptions = - | { - type: 'standalone'; - trackNamespace: TrackNamespace; - trackName: string; - startLocation: { group: number; object: number }; - endLocation: { group: number; object: number }; - parameters?: MessageParameters; - } - | { - type: 'relative-joining' | 'absolute-joining'; - joiningRequestId: number; - joiningStart: number; - parameters?: MessageParameters; - }; +/** + * FETCH (§10.13) takes the SUBSCRIBE shape; the range is `parameters.locationFilter`, read with fetch rules (§5.1.2): a + * relative start counts back from Largest Object, an omitted end stops there, no filter means the whole track. + */ +export type MoqtFetchOptions = MoqtSubscribeOptions; export interface MoqtSession { /** Resolves when the server's SETUP has been received. */ @@ -476,7 +468,10 @@ class MoqtSessionImpl implements MoqtSession { return { requestId, update: (parameters) => { - record.stream?.send(encodeRequestUpdate(requestId, parameters)).catch(() => {}); + // REQUEST_UPDATE consumes a Request ID of its own (§10.1); the stream + // it travels on is what names the subscription. Reusing the + // subscription's id would be a duplicate the peer MUST close on. + record.stream?.send(encodeRequestUpdate(this.#allocateRequestId(), parameters)).catch(() => {}); }, cancel: (reason) => this.#cancelSubscription(record, reason), }; @@ -494,16 +489,7 @@ class MoqtSessionImpl implements MoqtSession { this.#fetches.set(requestId, record); - const request: FetchRequest = - options.type === 'standalone' - ? { requestId, ...options } - : { - requestId, - type: options.type, - joiningRequestId: options.joiningRequestId, - joiningStart: options.joiningStart, - parameters: options.parameters, - }; + const request: FetchRequest = { requestId, ...options }; void this.#openRequest( encodeFetch(request), @@ -684,9 +670,14 @@ class MoqtSessionImpl implements MoqtSession { case 'publish-done': // Data streams may still be inbound; the alias route stays until // the subscription is cancelled or the session ends, so late - // subgroups still deliver (§10.11 leaves the timing policy to us). + // subgroups still deliver (§10.12 leaves the timing policy to us). record.handlers.onDone?.(message); break; + case 'publish-state-notify': + // Unilateral (§10.10): no REQUEST_OK back, and it does not count + // against MAX_REQUEST_UPDATES. + record.handlers.onStateNotify?.(message.parameters); + break; case 'goaway': record.handlers.onGoaway?.(message); break; @@ -707,7 +698,7 @@ class MoqtSessionImpl implements MoqtSession { }); break; // Some deployed relays accept a FETCH with the generic REQUEST_OK - // instead of the FETCH_OK moq-transport-19 §10.12.3 mandates. It + // instead of the FETCH_OK §10.13 mandates. It // carries no End Location/End Of Track, so `onOk` can't fire — the // fetch's actual completion still surfaces via onEntry/onEnd on the // data stream, which this response has no bearing on. It is still @@ -918,6 +909,9 @@ class MoqtSessionImpl implements MoqtSession { async #runFetchStream(reader: StreamReader, requestId: number): Promise { const record = this.#fetches.get(requestId); + // A FETCH_HEADER naming no fetch of ours is dropped, not fatal. That + // includes a fill fetch stream (§5.1.3), keyed by a SUBSCRIBE's Request + // ID — this subscriber never asks for one, so none is expected. if (!record || record.cancelled) { await reader.cancel(); return; diff --git a/packages/spf/src/network/moqt/tests/control-messages.test.ts b/packages/spf/src/network/moqt/tests/control-messages.test.ts index 1e0a370061..2b2976da4a 100644 --- a/packages/spf/src/network/moqt/tests/control-messages.test.ts +++ b/packages/spf/src/network/moqt/tests/control-messages.test.ts @@ -15,14 +15,17 @@ import { encodeMessageParameters, encodePublishDone, encodePublishNamespace, + encodePublishStateNotify, encodeRequestError, encodeSetup, encodeSubscribe, encodeSubscribeOk, isRetryablePublishDoneStatus, isRetryableRequestErrorCode, + type LocationFilter, MESSAGE_TYPE, type MessageParameters, + PARAMETER_TYPE, PUBLISH_DONE_STATUS, REQUEST_ERROR_CODE, SETUP_OPTION, @@ -47,6 +50,13 @@ function decodeAll(bytes: Uint8Array) { return deframer.push(bytes).map(decodeControlMessage); } +function encodeParameters(parameters: MessageParameters): Uint8Array { + const writer = new ByteWriter(); + + encodeMessageParameters(writer, parameters); + return writer.toBytes(); +} + describe('ControlMessageDeframer', () => { it('reassembles messages split across arbitrary chunk boundaries', () => { const encoded = frames( @@ -81,7 +91,7 @@ describe('encodeSubscribe', () => { const parameters: MessageParameters = { subscriberPriority: 16, groupOrder: 'ascending', - locationFilter: { type: 'largest-object' }, + locationFilter: { type: 'next-object' }, forward: 1, }; const [message] = decodeAll( @@ -96,49 +106,57 @@ describe('encodeSubscribe', () => { parameters: { subscriberPriority: 16, groupOrder: 'ascending', - locationFilter: { type: 'largest-object' }, + locationFilter: { type: 'next-object' }, forward: 1, }, }); }); + it('round-trips the canonical current-group join: Next Object plus a StartGroup=1 fill', () => { + const parameters: MessageParameters = { + locationFilter: { type: 'next-object' }, + fillParameters: { locationFilter: { type: 'relative-group', groupsBeforeNext: 1 } }, + }; + const [message] = decodeAll( + encodeSubscribe({ requestId: 0, trackNamespace: ['live'], trackName: 'video', parameters }) + ); + + expect(message).toMatchObject({ kind: 'subscribe', parameters }); + }); + it('rejects empty namespace fields', () => { expect(() => encodeSubscribe({ requestId: 0, trackNamespace: [''], trackName: 't' })).toThrow(MoqtProtocolError); }); }); describe('encodeFetch', () => { - it('round-trips a standalone fetch', () => { + it('round-trips a fetch whose range rides in LOCATION_FILTER', () => { const [message] = decodeAll( encodeFetch({ requestId: 2, - type: 'standalone', trackNamespace: ['live'], trackName: 'video', - startLocation: { group: 10, object: 0 }, - endLocation: { group: 12, object: 0 }, + parameters: { locationFilter: { type: 'absolute', start: { group: 10, object: 0 }, endGroupDelta: 2 } }, }) ); - expect(message).toMatchObject({ + expect(message).toEqual({ kind: 'fetch', request: { - type: 'standalone', requestId: 2, - startLocation: { group: 10, object: 0 }, - endLocation: { group: 12, object: 0 }, + trackNamespace: ['live'], + trackName: 'video', + parameters: { locationFilter: { type: 'absolute', start: { group: 10, object: 0 }, endGroupDelta: 2 } }, }, }); }); - it('round-trips a relative joining fetch (the MSF catalog join shape)', () => { - const [message] = decodeAll( - encodeFetch({ requestId: 6, type: 'relative-joining', joiningRequestId: 4, joiningStart: 0 }) - ); + it('round-trips an unfiltered fetch (the whole track up to Largest Object)', () => { + const [message] = decodeAll(encodeFetch({ requestId: 6, trackNamespace: ['live'], trackName: 'catalog' })); - expect(message).toMatchObject({ + expect(message).toEqual({ kind: 'fetch', - request: { type: 'relative-joining', requestId: 6, joiningRequestId: 4, joiningStart: 0 }, + request: { requestId: 6, trackNamespace: ['live'], trackName: 'catalog', parameters: {} }, }); }); }); @@ -158,6 +176,44 @@ describe('encodeSubscribeOk', () => { }); }); +describe('encodePublishDone', () => { + it('round-trips a counted stream total', () => { + const [message] = decodeAll(encodePublishDone(PUBLISH_DONE_STATUS.TRACK_ENDED, 5, 'ended')); + + expect(message).toEqual({ + kind: 'publish-done', + statusCode: PUBLISH_DONE_STATUS.TRACK_ENDED, + streamCount: 5, + reason: 'ended', + }); + }); + + it('reads the 2^64-1 "could not count" sentinel as an undefined stream count', () => { + // Status, then the 9-byte varint 0xFF..FF (2^64-1), then an empty reason. + const body = Uint8Array.of(PUBLISH_DONE_STATUS.GOING_AWAY, ...new Array(9).fill(0xff), 0x00); + const message = decodeControlMessage({ type: MESSAGE_TYPE.PUBLISH_DONE, body }); + + expect(message).toEqual({ + kind: 'publish-done', + statusCode: PUBLISH_DONE_STATUS.GOING_AWAY, + streamCount: undefined, + reason: '', + }); + }); +}); + +describe('encodePublishStateNotify', () => { + it('round-trips the changed parameters', () => { + const parameters: MessageParameters = { + largestObject: { group: 9, object: 4 }, + locationFilter: { type: 'relative-group', groupsBeforeNext: 0 }, + }; + const [message] = decodeAll(encodePublishStateNotify(parameters)); + + expect(message).toEqual({ kind: 'publish-state-notify', parameters }); + }); +}); + describe('encodeRequestError', () => { it('round-trips code, retry interval, and reason', () => { const [message] = decodeAll(encodeRequestError(REQUEST_ERROR_CODE.DOES_NOT_EXIST, 'no such track', 1500)); @@ -259,14 +315,18 @@ describe('encodeMessageParameters', () => { largestObject: { group: 100, object: 3 }, forward: 0, subscriberPriority: 200, - locationFilter: { type: 'absolute-range', start: { group: 5, object: 1 }, endGroupDelta: 4 }, + locationFilter: { type: 'absolute', start: { group: 5, object: 1 }, endGroupDelta: 4 }, groupOrder: 'descending', + fillParameters: { + fillTimeout: 500, + subscriberPriority: 8, + locationFilter: { type: 'relative-group', groupsBeforeNext: 1 }, + groupOrder: 'ascending', + }, newGroupRequest: 42, + includeProperties: 0, }; - const writer = new ByteWriter(); - - encodeMessageParameters(writer, parameters); - const decoded = decodeMessageParameters(new ByteReader(writer.toBytes())); + const decoded = decodeMessageParameters(new ByteReader(encodeParameters(parameters))); expect(decoded).toEqual(parameters); }); @@ -279,28 +339,126 @@ describe('encodeMessageParameters', () => { writer.writeVarint(0x99); expect(() => decodeMessageParameters(new ByteReader(writer.toBytes()))).toThrow(MoqtProtocolError); }); + + // §10.2 calls LARGEST_OBJECT a bare Location; moq-relay frames it with a + // length by the odd-type parity rule, and the codec follows the relay. + // Vector from moq-dev/moq `test_param_location_wire_vectors`. + it('frames LARGEST_OBJECT length-prefixed, byte-for-byte with moq-relay', () => { + const bytes = encodeParameters({ largestObject: { group: 255, object: 128 } }); + + expect(Array.from(bytes)).toEqual([0x01, 0x09, 0x04, 0x80, 0xff, 0x80, 0x80]); + expect(decodeMessageParameters(new ByteReader(bytes))).toEqual({ largestObject: { group: 255, object: 128 } }); + }); + + it('rejects a LARGEST_OBJECT value with trailing bytes', () => { + const writer = new ByteWriter(); + + writer.writeVarint(1); + writer.writeVarint(PARAMETER_TYPE.LARGEST_OBJECT); + writer.writeVarint(3); // length: two varints plus a stray byte + writer.writeVarint(1); + writer.writeVarint(2); + writer.writeUint8(0); + expect(() => decodeMessageParameters(new ByteReader(writer.toBytes()))).toThrow(/trailing bytes/); + }); + + it('frames INCLUDE_PROPERTIES as a length-prefixed byte and rejects values other than 0 and 1', () => { + expect(Array.from(encodeParameters({ includeProperties: 1 }))).toEqual([0x01, 0x35, 0x01, 0x01]); + + const writer = new ByteWriter(); + + writer.writeVarint(1); + writer.writeVarint(PARAMETER_TYPE.INCLUDE_PROPERTIES); + writer.writeVarint(1); + writer.writeUint8(2); + expect(() => decodeMessageParameters(new ByteReader(writer.toBytes()))).toThrow(/INCLUDE_PROPERTIES/); + }); + + it('encodes FILL_PARAMETERS as a nested parameter list', () => { + const bytes = encodeParameters({ + fillParameters: { locationFilter: { type: 'relative-group', groupsBeforeNext: 1 } }, + }); + + // count 1, type 0x23, length 4, then the nested list: count 1, type 0x21, length 1, StartGroup 1. + expect(Array.from(bytes)).toEqual([0x01, 0x23, 0x04, 0x01, 0x21, 0x01, 0x01]); + }); + + it('rejects parameters outside Table 6 inside FILL_PARAMETERS, on both sides', () => { + // Decode: FILL_PARAMETERS whose nested list carries FORWARD (0x10). + const writer = new ByteWriter(); + + writer.writeVarint(1); + writer.writeVarint(PARAMETER_TYPE.FILL_PARAMETERS); + writer.writeVarint(3); + writer.writeVarint(1); // nested count + writer.writeVarint(PARAMETER_TYPE.FORWARD); + writer.writeUint8(1); + expect(() => decodeMessageParameters(new ByteReader(writer.toBytes()))).toThrow(/FILL_PARAMETERS/); + + // Encode: a range filter type the fill scope excludes (TRACK_PROPERTY_FILTER). + expect(() => + encodeParameters({ + fillParameters: { rangeFilters: [{ type: PARAMETER_TYPE.TRACK_PROPERTY_FILTER, value: new Uint8Array(0) }] }, + }) + ).toThrow(/FILL_PARAMETERS/); + }); }); describe('encodeLocationFilter', () => { - it('round-trips all filter shapes', () => { - const filters = [ - { type: 'largest-object' }, - { type: 'next-group-start' }, - { type: 'absolute-start', start: { group: 3, object: 9 } }, - { type: 'absolute-range', start: { group: 3, object: 9 }, endGroupDelta: 0 }, - ] as const; + it('round-trips every filter shape', () => { + const filters: LocationFilter[] = [ + { type: 'none' }, + { type: 'next-object' }, + { type: 'relative-group', groupsBeforeNext: 0 }, + { type: 'relative-group', groupsBeforeNext: 1 }, + { type: 'relative-group', groupsBeforeNext: 5 }, + { type: 'absolute', start: { group: 3, object: 9 } }, + { type: 'absolute', start: { group: 3, object: 9 }, endGroupDelta: 0 }, + { type: 'absolute', start: { group: 3, object: 9 }, endGroupDelta: 2, endObject: 7 }, + ]; for (const filter of filters) { expect(decodeLocationFilter(encodeLocationFilter(filter))).toEqual(filter); } }); - it('rejects trailing bytes after the filter', () => { - const encoded = encodeLocationFilter({ type: 'next-group-start' }); - const padded = new Uint8Array(encoded.length + 1); + it('selects the meaning by field count (§5.1.2)', () => { + expect(Array.from(encodeLocationFilter({ type: 'none' }))).toEqual([]); + expect(Array.from(encodeLocationFilter({ type: 'relative-group', groupsBeforeNext: 1 }))).toEqual([1]); + expect(Array.from(encodeLocationFilter({ type: 'next-object' }))).toEqual([0, 0]); + expect(Array.from(encodeLocationFilter({ type: 'absolute', start: { group: 3, object: 9 } }))).toEqual([3, 9]); + expect( + Array.from( + encodeLocationFilter({ type: 'absolute', start: { group: 3, object: 9 }, endGroupDelta: 2, endObject: 7 }) + ) + ).toEqual([3, 9, 2, 7]); + }); + + it('normalizes an open-ended absolute {0,0} to no filter rather than the Next Object spelling', () => { + expect(Array.from(encodeLocationFilter({ type: 'absolute', start: { group: 0, object: 0 } }))).toEqual([]); + // Bounded, {0,0} is a real absolute start. + expect( + Array.from(encodeLocationFilter({ type: 'absolute', start: { group: 0, object: 0 }, endGroupDelta: 3 })) + ).toEqual([0, 0, 3]); + }); - padded.set(encoded); - expect(() => decodeLocationFilter(padded)).toThrow(MoqtProtocolError); + it('rejects an end object without an end group', () => { + expect(() => encodeLocationFilter({ type: 'absolute', start: { group: 1, object: 0 }, endObject: 4 })).toThrow( + MoqtProtocolError + ); + }); + + it('rejects more than four fields', () => { + expect(() => decodeLocationFilter(Uint8Array.of(1, 2, 3, 4, 5))).toThrow(MoqtProtocolError); + }); + + it('rejects an end group past the supported range', () => { + const writer = new ByteWriter(); + + writer.writeVarint(Number.MAX_SAFE_INTEGER); + writer.writeVarint(0); + writer.writeVarint(1); + expect(() => decodeLocationFilter(writer.toBytes())).toThrow(MoqtProtocolError); }); }); diff --git a/packages/spf/src/network/moqt/tests/object-stream.test.ts b/packages/spf/src/network/moqt/tests/object-stream.test.ts index 8998e96819..de3e89f8f2 100644 --- a/packages/spf/src/network/moqt/tests/object-stream.test.ts +++ b/packages/spf/src/network/moqt/tests/object-stream.test.ts @@ -388,11 +388,17 @@ describe('readFetchEntries', () => { await expect(collect(readFetchEntries(reader))).rejects.toThrow(/payload length .* exceeds/); }); - it('yields end-of-range markers', async () => { + it('yields end-of-range markers for all three statuses (§11.4.4, Table 7)', async () => { const bytes = encodeFetchStream((w) => { w.writeVarint(0x8c); // End of Non-Existent Range w.writeVarint(4); w.writeVarint(20); + w.writeVarint(0x10c); // End of Unknown Range + w.writeVarint(5); + w.writeVarint(0); + w.writeVarint(0x20c); // End of Timed-Out Range + w.writeVarint(6); + w.writeVarint(2); }); const reader = new StreamReader(streamOf(bytes)); @@ -400,7 +406,11 @@ describe('readFetchEntries', () => { await readFetchHeader(reader); const entries = await collect(readFetchEntries(reader)); - expect(entries).toEqual([{ kind: 'end-of-range', status: 'non-existent', groupId: 4, objectId: 20 }]); + expect(entries).toEqual([ + { kind: 'end-of-range', status: 'non-existent', groupId: 4, objectId: 20 }, + { kind: 'end-of-range', status: 'unknown', groupId: 5, objectId: 0 }, + { kind: 'end-of-range', status: 'timed-out', groupId: 6, objectId: 2 }, + ]); }); it('rejects a first object that references the prior object', async () => { diff --git a/packages/spf/src/network/moqt/tests/session.test.ts b/packages/spf/src/network/moqt/tests/session.test.ts index 525a9d9932..53e882ca00 100644 --- a/packages/spf/src/network/moqt/tests/session.test.ts +++ b/packages/spf/src/network/moqt/tests/session.test.ts @@ -7,10 +7,12 @@ import { decodeControlMessage, encodePublishDone, encodePublishNamespace, + encodePublishStateNotify, encodeRequestError, encodeRequestOk, encodeSetup, encodeSubscribeOk, + type LocationFilter, PUBLISH_DONE_STATUS, REQUEST_ERROR_CODE, } from '../control-messages'; @@ -217,6 +219,9 @@ function encodeSubgroup(trackAlias: number, groupId: number, payload: Uint8Array return writer.toBytes(); } +/** The fetch range playback would ask for if it fetched: the current group from its start. */ +const CURRENT_GROUP: LocationFilter = { type: 'relative-group', groupsBeforeNext: 1 }; + function createSessionHarness(callbacks?: MoqtSessionCallbacks) { const fake = createFakeTransport(); const session = createMoqtSession(fake.transport, { callbacks, unknownAliasTimeoutMs: 200 }); @@ -544,12 +549,12 @@ describe('createMoqtSession', () => { harness.session.destroy(); }); - it('routes fetch streams by request id (catalog joining-fetch shape)', async () => { + it('routes fetch streams by request id', async () => { const harness = createSessionHarness(); harness.sendServerSetup(); - const subscription = harness.session.subscribe({ trackNamespace: ['live'], trackName: 'catalog' }); + harness.session.subscribe({ trackNamespace: ['live'], trackName: 'catalog' }); const subscribeStream = await harness.nextRequestStream(); await subscribeStream.firstMessage; @@ -558,7 +563,7 @@ describe('createMoqtSession', () => { const onEnd = vi.fn(); harness.session.fetch( - { type: 'relative-joining', joiningRequestId: subscription.requestId, joiningStart: 0 }, + { trackNamespace: ['live'], trackName: 'catalog', parameters: { locationFilter: CURRENT_GROUP } }, { onEntry: (entry) => entries.push(entry), onEnd } ); const fetchStream = await harness.nextRequestStream(); @@ -566,7 +571,12 @@ describe('createMoqtSession', () => { expect(fetchMessage).toMatchObject({ kind: 'fetch', - request: { type: 'relative-joining', requestId: 2, joiningRequestId: 0, joiningStart: 0 }, + request: { + requestId: 2, + trackNamespace: ['live'], + trackName: 'catalog', + parameters: { locationFilter: CURRENT_GROUP }, + }, }); // Fetch data stream: FETCH_HEADER + one object. @@ -597,7 +607,7 @@ describe('createMoqtSession', () => { harness.sendServerSetup(); - const subscription = harness.session.subscribe({ trackNamespace: ['live'], trackName: 'catalog' }); + harness.session.subscribe({ trackNamespace: ['live'], trackName: 'catalog' }); await harness.nextRequestStream(); @@ -605,7 +615,7 @@ describe('createMoqtSession', () => { const onEnd = vi.fn(); harness.session.fetch( - { type: 'relative-joining', joiningRequestId: subscription.requestId, joiningStart: 0 }, + { trackNamespace: ['live'], trackName: 'catalog', parameters: { locationFilter: CURRENT_GROUP } }, { onEntry: (entry) => entries.push(entry), onEnd } ); const fetchStream = await harness.nextRequestStream(); @@ -648,7 +658,7 @@ describe('createMoqtSession', () => { fake.sendServerSetup(); - const subscription = session.subscribe({ trackNamespace: ['live'], trackName: 'catalog' }); + session.subscribe({ trackNamespace: ['live'], trackName: 'catalog' }); await fake.nextRequestStream(); @@ -656,7 +666,7 @@ describe('createMoqtSession', () => { const entries: unknown[] = []; session.fetch( - { type: 'relative-joining', joiningRequestId: subscription.requestId, joiningStart: 0 }, + { trackNamespace: ['live'], trackName: 'catalog', parameters: { locationFilter: CURRENT_GROUP } }, { onEntry: (entry) => entries.push(entry), onError } ); const fetchStream = await fake.nextRequestStream(); @@ -723,7 +733,7 @@ describe('createMoqtSession', () => { harness.sendServerSetup(); - const subscription = harness.session.subscribe({ trackNamespace: ['live'], trackName: 'catalog' }); + harness.session.subscribe({ trackNamespace: ['live'], trackName: 'catalog' }); const subscribeStream = await harness.nextRequestStream(); await subscribeStream.firstMessage; @@ -733,7 +743,7 @@ describe('createMoqtSession', () => { const onReset = vi.fn(); harness.session.fetch( - { type: 'relative-joining', joiningRequestId: subscription.requestId, joiningStart: 0 }, + { trackNamespace: ['live'], trackName: 'catalog', parameters: { locationFilter: CURRENT_GROUP } }, { onEntry: (entry) => entries.push(entry), onEnd, onReset } ); const fetchStream = await harness.nextRequestStream(); @@ -906,4 +916,93 @@ describe('createMoqtSession', () => { await vi.waitFor(() => expect(onClosed).toHaveBeenCalled()); expect(harness.getCloseInfo()).toMatchObject({ closeCode: 0x3 }); }); + + it('surfaces PUBLISH_STATE_NOTIFY to the subscription without replying', async () => { + const harness = createSessionHarness(); + + harness.sendServerSetup(); + + const onStateNotify = vi.fn(); + + harness.session.subscribe({ trackNamespace: ['live'], trackName: 'video' }, { onStateNotify }); + const request = await harness.nextRequestStream(); + + await request.firstMessage; + await request.send(encodeSubscribeOk(7)); + await request.send(encodePublishStateNotify({ largestObject: { group: 12, object: 3 } })); + + await vi.waitFor(() => expect(onStateNotify).toHaveBeenCalled()); + expect(onStateNotify).toHaveBeenCalledWith({ largestObject: { group: 12, object: 3 } }); + + // §10.10: unilateral — no REQUEST_OK or REQUEST_ERROR goes back. + await new Promise((resolve) => setTimeout(resolve, 20)); + expect(request.messages).toHaveLength(1); + harness.session.destroy(); + }); + + it('closes the session on PUBLISH_STATE_NOTIFY over a fetch stream', async () => { + const onClosed = vi.fn(); + const harness = createSessionHarness({ onClosed }); + + harness.sendServerSetup(); + harness.session.fetch({ trackNamespace: ['live'], trackName: 'catalog' }); + const request = await harness.nextRequestStream(); + + await request.firstMessage; + await request.send(encodePublishStateNotify({})); + + await vi.waitFor(() => expect(onClosed).toHaveBeenCalled()); + expect(harness.getCloseInfo()).toMatchObject({ closeCode: 0x3 }); + }); + + // §10.1 counts REQUEST_UPDATE among the messages that consume a Request + // ID; reusing the subscription's would be a duplicate the peer closes on. + it('gives each REQUEST_UPDATE a fresh request id', async () => { + const harness = createSessionHarness(); + + harness.sendServerSetup(); + + const subscription = harness.session.subscribe({ trackNamespace: ['live'], trackName: 'video' }); + const request = await harness.nextRequestStream(); + + await request.firstMessage; + subscription.update({ forward: 0 }); + subscription.update({ forward: 1 }); + + await vi.waitFor(() => expect(request.messages).toHaveLength(3)); + expect(request.messages[1]).toMatchObject({ kind: 'request-update', requestId: 2, parameters: { forward: 0 } }); + expect(request.messages[2]).toMatchObject({ kind: 'request-update', requestId: 4, parameters: { forward: 1 } }); + harness.session.destroy(); + }); + + it('reports an uncountable PUBLISH_DONE stream count as undefined instead of failing the session', async () => { + const onClosed = vi.fn(); + const harness = createSessionHarness({ onClosed }); + + harness.sendServerSetup(); + + const onDone = vi.fn(); + + harness.session.subscribe({ trackNamespace: ['live'], trackName: 'video' }, { onDone }); + const request = await harness.nextRequestStream(); + + await request.firstMessage; + await request.send(encodeSubscribeOk(7)); + + // Status, the 9-byte varint 2^64-1 (§10.12's sentinel), empty reason. + const body = Uint8Array.of(PUBLISH_DONE_STATUS.TRACK_ENDED, ...new Array(9).fill(0xff), 0x00); + const frame = new ByteWriter(); + + frame.writeVarint(0x0b); + frame.writeUint16(body.length); + frame.writeBytes(body); + await request.send(frame.toBytes()); + + await vi.waitFor(() => expect(onDone).toHaveBeenCalled()); + expect(onDone).toHaveBeenCalledWith( + expect.objectContaining({ statusCode: PUBLISH_DONE_STATUS.TRACK_ENDED, streamCount: undefined, reason: '' }) + ); + expect(onClosed).not.toHaveBeenCalled(); + harness.session.destroy(); + }); }); diff --git a/packages/spf/src/network/moqt/varint.ts b/packages/spf/src/network/moqt/varint.ts index e4a9868230..9a7cf523d9 100644 --- a/packages/spf/src/network/moqt/varint.ts +++ b/packages/spf/src/network/moqt/varint.ts @@ -1,5 +1,5 @@ /** - * MOQT variable-length integers (moq-transport draft-19 §1.4.1). + * MOQT variable-length integers (moq-transport draft-20 §1.4.1). * * NOT the QUIC RFC 9000 varint: draft-15 replaced it with a leading-ones scheme. The number of leading 1 bits of the * first byte gives the encoded length minus one (1-9 bytes); the bits after the first 0, plus any subsequent bytes, diff --git a/packages/spf/src/playback/actors/dom/audio-renderer.ts b/packages/spf/src/playback/actors/dom/audio-renderer.ts index 3a5134b093..61f6b2ddc2 100644 --- a/packages/spf/src/playback/actors/dom/audio-renderer.ts +++ b/packages/spf/src/playback/actors/dom/audio-renderer.ts @@ -457,7 +457,7 @@ export function createAudioRendererActor(options: CreateAudioRendererOptions): A // Every audio sample is independently decodable — `isKey` is a // LOC group-boundary marker (meaningful for video's GOP // gating), not a decodability signal here. A live-edge - // (largest-object) join almost never lands on group object 0, + // (`next-object`) join almost never lands on group object 0, // and WebCodecs requires the first post-configure chunk to be // 'key', so gating on `next.isKey` would reject it. type: 'key', diff --git a/packages/spf/src/playback/actors/dom/tests/audio-renderer.test.ts b/packages/spf/src/playback/actors/dom/tests/audio-renderer.test.ts index dfc6e6273e..c8a08547d2 100644 --- a/packages/spf/src/playback/actors/dom/tests/audio-renderer.test.ts +++ b/packages/spf/src/playback/actors/dom/tests/audio-renderer.test.ts @@ -205,7 +205,7 @@ describe('createAudioRendererActor', () => { it('decodes a live-edge join whose first frame is mid-group (isKey: false)', async () => { const frames = await encodeTestFrames(3); - // A `largest-object` subscribe joins live, so the first delivered frame + // A `next-object` subscribe joins live, so the first delivered frame // is whatever object is newest right now — essentially never a LOC // group's object 0 (`isKey: true`). The regression: decode() gated the // WebCodecs chunk type on `isKey`, and WebCodecs rejects a 'delta' diff --git a/packages/spf/src/playback/actors/moq-session.ts b/packages/spf/src/playback/actors/moq-session.ts index e106cfd613..850f491e22 100644 --- a/packages/spf/src/playback/actors/moq-session.ts +++ b/packages/spf/src/playback/actors/moq-session.ts @@ -19,8 +19,8 @@ * empty — nothing rides a request's parameters. `refreshAuthToken()` always rejects: this actor connects once and never * reconnects (a `goaway` is only recorded, see `SessionMessage`'s `'goaway'` case), so a refreshed token has nowhere * left to attach — the jwt is fixed at connect time. Both stay on the interface (with `MoqAuthProvider.refreshToken`) - * for a future relay generation that accepts draft-19 AUTHORIZATION_TOKEN request parameters, at which point a token - * could ride a request instead of only the connect URL. + * for a future relay generation that accepts AUTHORIZATION_TOKEN request parameters, at which point a token could ride + * a request instead of only the connect URL. */ import { createTransitionActor, type TransitionActor } from '../../core/actors/create-transition-actor'; import type { MoqSource } from '../../media/moq/parse-source'; @@ -71,8 +71,8 @@ export interface MoqAuthProvider { * Unused today: `MoqSessionActor.refreshAuthToken()` rejects before ever calling this — see its doc. A refreshed * token has no connection left to attach to (the jwt rides only the connect URL, fixed at connect time), so calling * this here would mint a token from the provider that no code could ever use. Kept on the interface for a future - * relay generation that accepts draft-19 AUTHORIZATION_TOKEN request parameters, at which point a mid-session refresh - * becomes meaningful. + * relay generation that accepts AUTHORIZATION_TOKEN request parameters, at which point a mid-session refresh becomes + * meaningful. */ refreshToken?(): Promise | Uint8Array | string | undefined; /** MOQT auth Token Type codepoint. Default 0. */ @@ -173,9 +173,9 @@ function skipTokenResolution(url: string): boolean { * relays) authenticate with a JWT `?jwt=` query parameter on the connect URL and close the connection right after * CLIENT_SETUP when auth is required but missing — the same carriage `composePublishConnectUrl` uses on the publish * side (`publish/session/publish-session.ts`), for the same reason: this relay fleet hard-closes the session (`5 - * "invalid value"`) when a draft-19 AUTHORIZATION_TOKEN structure rides a request's parameters instead. An explicit - * `jwt` param already in the source URL wins, and an unparseable URL is returned verbatim so `new WebTransport(url)` - * raises the canonical error. + * "invalid value"`) when a AUTHORIZATION_TOKEN structure rides a request's parameters instead. An explicit `jwt` param + * already in the source URL wins, and an unparseable URL is returned verbatim so `new WebTransport(url)` raises the + * canonical error. */ export function composePlaybackConnectUrl(url: string, authToken?: string): string { if (!authToken) return url; @@ -392,13 +392,13 @@ export function createMoqSessionActor(options: CreateMoqSessionActorOptions): Mo void start(); // The token rides ONLY in the connect URL's `?jwt=` query parameter - // (`composePlaybackConnectUrl`). The known relay fleet (moq-lite-rs - // lineage, incl. Mux's relay-rs deployments) does not support draft-19 - // AUTHORIZATION_TOKEN structures yet and hard-closes the session - // (`5 "invalid value"`) when one appears in a request's parameters — - // the same defect fixed on the publish side in `publish-session.ts`. - // Re-attach via this seam (encodeAuthTokenUseValue, §10.2.2) once - // relays accept draft-19 auth. + // (`composePlaybackConnectUrl`). The known relay fleet (moq-relay, + // moq-dev/moq lineage, incl. Mux's deployments) does not accept the + // AUTHORIZATION_TOKEN request parameter (0x03 is not in its SUBSCRIBE + // parameter list) and hard-closes the session (`5 "invalid value"`) + // when one appears — the same defect fixed on the publish side in + // `publish-session.ts`. Re-attach via this seam + // (encodeAuthTokenUseValue, §10.2.2) once relays accept it. const tokenParameters = (): MessageParameters => ({}); return { diff --git a/packages/spf/src/playback/actors/tests/moq-session.test.ts b/packages/spf/src/playback/actors/tests/moq-session.test.ts index 5dfc05e26e..8aaf6c0bba 100644 --- a/packages/spf/src/playback/actors/tests/moq-session.test.ts +++ b/packages/spf/src/playback/actors/tests/moq-session.test.ts @@ -88,7 +88,7 @@ describe('createMoqSessionActor', () => { expect(actor.snapshot.get().context.status).toBe('connecting'); expect(makeCreateTransport.lastConnect).toMatchObject({ connectUrl: 'https://relay.example.com/live', - protocols: ['moqt-19'], + protocols: ['moqt-20'], }); fake.sendServerSetup(); @@ -176,7 +176,7 @@ describe('createMoqSessionActor', () => { }); // The known relay fleet (moq-lite-rs lineage) hard-closes the session on - // draft-19 AUTHORIZATION_TOKEN structures — the token must ride ONLY in + // AUTHORIZATION_TOKEN request parameters — the token must ride ONLY in // the connect URL's `?jwt=` query parameter, matching the publish side's // `composePublishConnectUrl` fix. it('composes the c4m fragment token onto the connect URL as ?jwt=, keeping auth parameters empty', () => { diff --git a/packages/spf/src/playback/actors/tests/track-subscriber.test.ts b/packages/spf/src/playback/actors/tests/track-subscriber.test.ts index e46f3b104a..05a195e53d 100644 --- a/packages/spf/src/playback/actors/tests/track-subscriber.test.ts +++ b/packages/spf/src/playback/actors/tests/track-subscriber.test.ts @@ -85,7 +85,7 @@ describe('createTrackSubscriberActor', () => { expect(subscriptions[0]!.options).toMatchObject({ trackNamespace: ['live'], trackName: 'video', - parameters: { locationFilter: { type: 'largest-object' } }, + parameters: { locationFilter: { type: 'next-object' } }, }); expect(subscriber.snapshot.get().context.status).toBe('pending'); diff --git a/packages/spf/src/playback/actors/track-subscriber.ts b/packages/spf/src/playback/actors/track-subscriber.ts index 3459c01e2b..c99ee32faf 100644 --- a/packages/spf/src/playback/actors/track-subscriber.ts +++ b/packages/spf/src/playback/actors/track-subscriber.ts @@ -94,7 +94,7 @@ export interface TrackSubscriberContext { export interface CreateTrackSubscriberOptions { session: MoqtSession; track: MoqTrack; - /** Where to join the track. Default: `{ type: 'largest-object' }` (live edge). */ + /** Where to join the track. Default: `{ type: 'next-object' }` (live edge). */ locationFilter?: LocationFilter; /** Extra request parameters (auth tokens, priority). */ parameters?: MessageParameters; @@ -140,7 +140,7 @@ export interface TrackSubscriberActor extends Pick< // Implementation // ============================================================================= -const DEFAULT_LOCATION_FILTER: LocationFilter = { type: 'largest-object' }; +const DEFAULT_LOCATION_FILTER: LocationFilter = { type: 'next-object' }; /** See `CreateTrackSubscriberOptions.stallTimeoutMs`. */ export const DEFAULT_STALL_TIMEOUT_MS = 10_000; diff --git a/packages/spf/src/playback/behaviors/adapt-latency-target.ts b/packages/spf/src/playback/behaviors/adapt-latency-target.ts index 1071eefa31..6f44fae4ab 100644 --- a/packages/spf/src/playback/behaviors/adapt-latency-target.ts +++ b/packages/spf/src/playback/behaviors/adapt-latency-target.ts @@ -10,7 +10,7 @@ * * ## What it can observe, and what it cannot * - * There is no transport RTT here. spf speaks its own draft-19 stack (no PROBE — that is a moq-lite extension) and + * There is no transport RTT here. spf speaks its own draft-20 stack (no PROBE — that is a moq-lite extension) and * browsers do not populate `WebTransport.getStats().smoothedRtt`, so the absolute one-way delay is simply not * available. The no-RTT path is therefore the only path, and the estimate is built from what _is_ observable: * diff --git a/packages/spf/src/playback/behaviors/resolve-catalog.ts b/packages/spf/src/playback/behaviors/resolve-catalog.ts index 6ae10c6095..0ae89365ad 100644 --- a/packages/spf/src/playback/behaviors/resolve-catalog.ts +++ b/packages/spf/src/playback/behaviors/resolve-catalog.ts @@ -1,8 +1,8 @@ /** * **Resolve a MoQ presentation from its MSF catalog track.** The MoQ analog of `resolve-presentation`: when the session - * is ready, subscribes to the source's catalog track — per msf-01 §5, SUBSCRIBE plus a joining FETCH (offset 0) to - * obtain the latest complete catalog and every subsequent update — parses catalog objects (independent and delta), and - * writes the projected `Presentation` to `state.presentation`. + * is ready, subscribes to the source's catalog track from the start of the current group — the independent catalog + * object plus every delta so far, then live updates — parses catalog objects (independent and delta), and writes the + * projected `Presentation` to `state.presentation`. * * 'preconditions-unmet' → 'awaiting-session' → 'catalog-active' * @@ -11,12 +11,18 @@ * `state.presentation` (delta re-parse). Stable track ids (`parse-catalog`) keep unchanged track lists from re-firing * selection. * - * Ordering: live delta objects can arrive while the joining fetch is still replaying the current group, so live objects - * buffer until the fetch settles, then apply in (group, object) order. A delta that lands with no prior catalog (fetch - * unavailable, e.g. nothing published) is dropped — the next independent object (object 0 of a group) recovers. + * Join shape: a `relative-group 1` Location Filter (draft-20 §5.1.2) asks for `{Largest.Group, 0}` onward, and relays + * serve the already-published head of that group from cache on the ordinary subgroup stream. msf-01 §5 still words the + * join as SUBSCRIBE plus a Joining FETCH; draft-20 removed Joining FETCH, and against moq-relay a FETCH never carried + * catalog data anyway — the catalog resolved from the relay's current-group replay. This filter asks for that replay + * explicitly, so nothing needs buffering or reordering: one stream per group, in order. + * + * A delta is applied only against the independent object of its own group. A delta with no base — a mid-group join + * under a publisher that does not replay — or from a group older than the current base is dropped; the next independent + * object (object 0 of a group) recovers. * * Auth-expiry retry (MSF §11.4): an EXPIRED_AUTH_TOKEN subscribe error refreshes the token via the session actor and - * recreates the catalog subscription + joining fetch once — same pattern as `track-subscriber`. + * recreates the catalog subscription once — same pattern as `track-subscriber`. * * Failure recovery: a _transient_ subscribe error retries with capped backoff (`subscribeRetry` config, honoring a * server-stated Retry Interval) — the common case is DOES_NOT_EXIST because play was pressed before the broadcast @@ -41,13 +47,13 @@ import { import { isMoqSourceUrl, parseMoqSource } from '../../media/moq/parse-source'; import type { MaybeResolvedPresentation } from '../../media/types'; import { utf8Decode } from '../../network/moqt/bytes'; -import type { MessageParameters } from '../../network/moqt/control-messages'; +import type { LocationFilter, MessageParameters } from '../../network/moqt/control-messages'; import { isRetryablePublishDoneStatus, isRetryableRequestErrorCode, REQUEST_ERROR_CODE, } from '../../network/moqt/control-messages'; -import type { FetchHandle, Subscription } from '../../network/moqt/session'; +import type { Subscription } from '../../network/moqt/session'; import { DEFAULT_SUBSCRIBE_RETRY_BACKOFF_CONFIG, MAX_SERVER_RETRY_INTERVAL_MS, @@ -75,13 +81,6 @@ export type ApplyCatalogUpdate = ( export interface ResolveCatalogConfig { /** Override MSF catalog parsing (alternate catalog formats/versions). */ applyCatalogUpdate?: ApplyCatalogUpdate; - /** - * Deadline for the joining fetch's replay. The session's request timeout only covers a fetch that never answers — a - * relay that sends FETCH_OK and then never opens (or never finishes) its data stream would leave `fetchSettled` false - * forever, buffering live deltas and never resolving a catalog. On expiry the behavior falls back to live-only, - * exactly as it does for an empty or truncated replay. Default 5000ms. - */ - catalogFetchTimeoutMs?: number; /** * Retry policy for a catalog subscription that fails or is ended by the publisher. A failed catalog SUBSCRIBE usually * means the track does not exist _yet_ — the viewer pressed play before the broadcast started, or the broadcaster is @@ -91,7 +90,8 @@ export interface ResolveCatalogConfig { subscribeRetry?: Partial; } -const DEFAULT_CATALOG_FETCH_TIMEOUT_MS = 5000; +/** The current group from its start: the independent catalog object and the deltas published since (§5.1.2). */ +const CATALOG_JOIN_FILTER: LocationFilter = { type: 'relative-group', groupsBeforeNext: 1 }; type ResolveCatalogFsmState = 'preconditions-unmet' | 'awaiting-session' | 'catalog-active'; @@ -109,7 +109,6 @@ function setupResolveCatalog({ config?: ResolveCatalogConfig; }): Reactor { const applyUpdate = config?.applyCatalogUpdate ?? applyMoqCatalogUpdate; - const fetchTimeoutMs = config?.catalogFetchTimeoutMs ?? DEFAULT_CATALOG_FETCH_TIMEOUT_MS; const retryConfig = resolveRetryBackoffConfig(DEFAULT_SUBSCRIBE_RETRY_BACKOFF_CONFIG, config?.subscribeRetry); const derivedStateSignal = computed(() => { @@ -150,26 +149,29 @@ function setupResolveCatalog({ }; let catalog: MoqCatalog | undefined; - let fetchSettled = false; - const bufferedLive: { groupId: number; objectId: number; text: string }[] = []; + // Group whose independent object `catalog` is built on. Deltas apply + // only within it; an older group's straggler is stale. + let baseGroup: number | undefined; let cancelled = false; let authRetried = false; let subscription: Subscription | undefined; - let fetchHandle: FetchHandle | undefined; - let settleTimer: ReturnType | undefined; let retryTimer: ReturnType | undefined; let retryAttempts = 0; - // Monotonic attempt token: cancelling a subscription/fetch does - // not stop callbacks already in flight (a cancelled fetch stream - // can still surface onEnd/onReset), so the auth-expiry retry - // guards every handler against its superseded attempt — a stale - // settle or object must not touch the fresh attempt's state. + // Monotonic attempt token: cancelling a subscription does not stop + // callbacks already in flight, so the retry paths guard every + // handler against its superseded attempt — a stale object must not + // touch the fresh attempt's state. let attempt = 0; - const apply = (text: string, objectId: number): void => { - // A delta with no prior catalog can't be interpreted (§5.1.6); - // drop it and recover on the next independent object. - if (catalog === undefined && objectId > 0) return; + const apply = (text: string, groupId: number, objectId: number): void => { + if (objectId === 0) { + baseGroup = groupId; + } else if (catalog === undefined || groupId !== baseGroup) { + // A delta with no base can't be interpreted (msf §5.1.6), and + // one from another group would apply against the wrong base; + // drop it and recover on the next independent object. + return; + } try { catalog = applyUpdate(catalog, text, updateOptions); @@ -180,37 +182,18 @@ function setupResolveCatalog({ } }; - const settleFetch = (): void => { - if (fetchSettled) return; - - fetchSettled = true; - clearTimeout(settleTimer); - settleTimer = undefined; - bufferedLive.sort((a, b) => a.groupId - b.groupId || a.objectId - b.objectId); - - for (const { text, objectId } of bufferedLive) apply(text, objectId); - - bufferedLive.length = 0; - }; - /** * Terminal stop: after this, nothing of the current attempt may write `state.presentation` — and no queued - * restart may reopen the subscription — until the state re-enters. Cancelling the handles alone is neither: - * the settle timer's callback never checks `isCurrent` and would still drain buffered objects, a cancel can - * itself surface in-flight onEnd/onReset, and a restart already booked by an earlier retryable report of the - * same death (an armed retry timer, or an in-flight auth refresh) would start a fresh attempt right over the - * terminal state. So the attempt token is bumped (invalidating every handler and the refresh restart, which - * check it), both timers are disarmed, and the buffer discarded before the handles go. + * restart may reopen the subscription — until the state re-enters. Cancelling the handle alone is neither: a + * cancel can itself surface in-flight callbacks, and a restart already booked by an earlier retryable report + * of the same death (an armed retry timer, or an in-flight auth refresh) would start a fresh attempt right + * over the terminal state. So the attempt token is bumped (invalidating every handler and the refresh + * restart, which check it) and the timer disarmed before the handle goes. */ const stopCatalog = (): void => { attempt++; - clearTimeout(settleTimer); - settleTimer = undefined; clearTimeout(retryTimer); retryTimer = undefined; - bufferedLive.length = 0; - fetchSettled = true; - fetchHandle?.cancel(); subscription?.cancel(); }; @@ -222,9 +205,9 @@ function setupResolveCatalog({ * * The local catalog base resets with the restart. Across a publisher restart the track's (group, object) * numbering starts over, and a delta applied against the pre-outage base would silently produce a wrong - * catalog — dropping deltas until the next independent object (or the new attempt's joining-fetch replay) is - * the safe recovery §5.1.6 prescribes. `state.presentation` keeps the last resolved value meanwhile, so - * playback state doesn't flicker. + * catalog — dropping deltas until the next independent object (which the new attempt's current-group join + * replays) is the safe recovery msf §5.1.6 prescribes. `state.presentation` keeps the last resolved value + * meanwhile, so playback state doesn't flicker. */ const scheduleRestart = (retryIntervalMs = 0): boolean => { if (cancelled || retryTimer !== undefined) return true; @@ -239,9 +222,9 @@ function setupResolveCatalog({ if (cancelled) return; - fetchHandle?.cancel(); subscription?.cancel(); catalog = undefined; + baseGroup = undefined; start(actor.getAuthParameters()); }, Math.max(delay, Math.min(retryIntervalMs, MAX_SERVER_RETRY_INTERVAL_MS)) @@ -250,31 +233,14 @@ function setupResolveCatalog({ }; const start = (parameters: MessageParameters): void => { - // Fresh attempt: the new joining fetch replays the current - // group again, so live deltas must buffer until it settles. const thisAttempt = ++attempt; const isCurrent = (): boolean => attempt === thisAttempt; - fetchSettled = false; - bufferedLive.length = 0; - clearTimeout(settleTimer); - settleTimer = - fetchTimeoutMs > 0 - ? setTimeout(() => { - // Deadline passed: fall back to live-only and stop the - // replay — a straggling fetch entry would overwrite the - // live catalog with stale state (or apply the next - // delta against the wrong base). - settleFetch(); - fetchHandle?.cancel(); - }, fetchTimeoutMs) - : undefined; - subscription = session.subscribe( { trackNamespace: source.namespace, trackName: source.trackName, - parameters: { ...parameters, locationFilter: { type: 'largest-object' } }, + parameters: { ...parameters, locationFilter: CATALOG_JOIN_FILTER }, }, { onOk: () => { @@ -293,14 +259,7 @@ function setupResolveCatalog({ if (object.status !== 'normal' || object.payload.length === 0) return; - const text = utf8Decode(object.payload); - - if (!fetchSettled) { - bufferedLive.push({ groupId: object.groupId, objectId: object.objectId, text }); - return; - } - - apply(text, object.objectId); + apply(utf8Decode(object.payload), object.groupId, object.objectId); }, onDone: (done) => { // PUBLISH_DONE: the publisher ended the catalog track — a @@ -314,10 +273,9 @@ function setupResolveCatalog({ if (!isRetryablePublishDoneStatus(done.statusCode)) { // Terminal: freeze the state — a subscription left open - // keeps delivering late objects (and the joining fetch - // its replay) into a presentation we just declared done - // updating. See `stopCatalog` for why cancelling the - // handles alone is not enough. + // keeps delivering late objects into a presentation we + // just declared done updating. See `stopCatalog` for why + // cancelling the handle alone is not enough. stopCatalog(); // TODO(error-management): route to a state-error slot once one exists. console.error('[resolveCatalog] catalog track ended with a non-retryable status:', done); @@ -338,8 +296,8 @@ function setupResolveCatalog({ if (error.errorCode === REQUEST_ERROR_CODE.EXPIRED_AUTH_TOKEN) { // Auth-expiry retry (MSF §11.4), same one-shot pattern // as track-subscriber: refresh the token and recreate - // the subscription + joining fetch with fresh - // parameters. `onOk` re-arms the shot. + // the subscription with fresh parameters. `onOk` re-arms + // the shot. if (!authRetried) { authRetried = true; // `.catch()` after `.then()` (not a rejection handler @@ -356,7 +314,6 @@ function setupResolveCatalog({ // double-start over a live newer attempt. if (cancelled || !isCurrent()) return; - fetchHandle?.cancel(); subscription?.cancel(); start(refreshed); }) @@ -387,9 +344,7 @@ function setupResolveCatalog({ // A permanent rejection — wrong credentials, malformed // request, unsupported feature — answers an identical - // retry identically: stop instead of looping forever, and - // stop the joining fetch with it (its replay must not - // keep writing into a presentation declared terminal). + // retry identically: stop instead of looping forever. if (!isRetryableRequestErrorCode(error.errorCode)) { stopCatalog(); // TODO(error-management): route to a state-error slot once one exists. @@ -418,52 +373,14 @@ function setupResolveCatalog({ }, } ); - - // Joining fetch (offset 0) replays the current group from its - // independent catalog object up to the subscription's start. - fetchHandle = session.fetch( - { - type: 'relative-joining', - joiningRequestId: subscription.requestId, - joiningStart: 0, - parameters, - }, - { - onEntry: (entry) => { - // Once settled (deadline passed or replay ended) the live - // subscription owns the catalog — late replay entries are - // stale and must not overwrite it. - if (!isCurrent() || fetchSettled) return; - - if (entry.kind !== 'object' || entry.payload.length === 0) return; - - apply(utf8Decode(entry.payload), entry.objectId); - }, - onEnd: () => { - if (isCurrent()) settleFetch(); - }, - // No history to replay (e.g. nothing published yet) or replay - // truncated — fall back to live-only: the next independent - // object resolves. - onError: () => { - if (isCurrent()) settleFetch(); - }, - onReset: () => { - if (isCurrent()) settleFetch(); - }, - } - ); }; start(actor.getAuthParameters()); return () => { cancelled = true; - clearTimeout(settleTimer); - settleTimer = undefined; clearTimeout(retryTimer); retryTimer = undefined; - fetchHandle?.cancel(); subscription?.cancel(); }; }, diff --git a/packages/spf/src/playback/behaviors/subscribe-selected-tracks.ts b/packages/spf/src/playback/behaviors/subscribe-selected-tracks.ts index 77394606ef..8728f484e9 100644 --- a/packages/spf/src/playback/behaviors/subscribe-selected-tracks.ts +++ b/packages/spf/src/playback/behaviors/subscribe-selected-tracks.ts @@ -3,7 +3,7 @@ * combined: reacts to `selected{Video,Audio}TrackId` (written by the reused `track-switching` behaviors) and keeps * exactly one live `track-subscriber` actor per type in context, feeding the renderers. * - * Switches are **make-before-break**: the new track is subscribed at an MSF time-aligned boundary (`next-group-start` — + * Switches are **make-before-break**: the new track is subscribed at an MSF time-aligned boundary (`relative-group 0` — * groups open with a random-access point, and alternate-group tracks share group numbers, §4.2) while the old * subscription keeps playing. Only once the new subscriber has buffered a decodable keyframe-led group * (`hasDecodableFrame`) _and_ its oldest frame is due at the playout clock (`currentTime`) does the swap happen: old @@ -475,7 +475,7 @@ function setupSubscribeSelectedTrack actor.refreshAuthToken(), stallTimeoutMs: config?.subscribeStallTimeoutMs, @@ -526,7 +526,7 @@ export const subscribeSelectedVideoTrack = defineBehavior({ selectionKey: 'selectedVideoTrackId', subscriberKey: 'videoSubscriberActor', pendingKey: 'pendingVideoSubscriberActor', - joinFilter: { type: 'next-group-start' }, + joinFilter: { type: 'relative-group', groupsBeforeNext: 0 }, }, deps ), @@ -567,7 +567,7 @@ export const subscribeSelectedAudioTrack = defineBehavior({ selectionKey: 'selectedAudioTrackId', subscriberKey: 'audioSubscriberActor', pendingKey: 'pendingAudioSubscriberActor', - joinFilter: { type: 'largest-object' }, + joinFilter: { type: 'next-object' }, }, deps, deps.state.audioSuspended diff --git a/packages/spf/src/playback/behaviors/tests/resolve-catalog.test.ts b/packages/spf/src/playback/behaviors/tests/resolve-catalog.test.ts index eb6c207d7a..88e5e062cd 100644 --- a/packages/spf/src/playback/behaviors/tests/resolve-catalog.test.ts +++ b/packages/spf/src/playback/behaviors/tests/resolve-catalog.test.ts @@ -9,7 +9,7 @@ import { PUBLISH_DONE_STATUS, REQUEST_ERROR_CODE, } from '../../../network/moqt/control-messages'; -import type { FetchHandlers, MoqtSession, SubscriptionHandlers } from '../../../network/moqt/session'; +import type { MoqtSession, SubscriptionHandlers } from '../../../network/moqt/session'; import type { MoqSessionActor, MoqSessionActorContext } from '../../actors/moq-session'; import { resolveCatalog } from '../resolve-catalog'; @@ -35,20 +35,25 @@ const CATALOG_WITH_AUDIO = JSON.stringify({ ], }); +/** The join every catalog attempt asks for: the current group from its independent object (§5.1.2). */ +const CURRENT_GROUP = { type: 'relative-group', groupsBeforeNext: 1 }; + // ============================================================================ // Fakes // ============================================================================ +interface SubscribeOptions { + trackNamespace: string[]; + trackName: string; + parameters?: MessageParameters; +} + function createFakeSessionActor() { - const subscriptions: { - options: { trackNamespace: string[]; trackName: string }; - handlers: SubscriptionHandlers; - cancelled: boolean; - }[] = []; - const fetches: { options: unknown; handlers: FetchHandlers; cancelled: boolean }[] = []; + const subscriptions: { options: SubscribeOptions; handlers: SubscriptionHandlers; cancelled: boolean }[] = []; + const fetches: unknown[] = []; const session = { ready: Promise.resolve(), - subscribe(options: { trackNamespace: string[]; trackName: string }, handlers: SubscriptionHandlers = {}) { + subscribe(options: SubscribeOptions, handlers: SubscriptionHandlers = {}) { const record = { options, handlers, cancelled: false }; subscriptions.push(record); @@ -60,16 +65,9 @@ function createFakeSessionActor() { }, }; }, - fetch(options: unknown, handlers: FetchHandlers = {}) { - const record = { options, handlers, cancelled: false }; - - fetches.push(record); - return { - requestId: 100, - cancel: () => { - record.cancelled = true; - }, - }; + fetch(options: unknown) { + fetches.push(options); + return { requestId: 100, cancel: () => {} }; }, trackStatus: () => {}, close: () => {}, @@ -115,17 +113,6 @@ function makeDeps(actor: MoqSessionActor | undefined, presentation: MaybeResolve }; } -function fetchEntry(groupId: number, objectId: number, text: string) { - return { - kind: 'object' as const, - groupId, - objectId, - priority: 128, - properties: [], - payload: utf8Encode(text), - }; -} - const publishDone = { statusCode: PUBLISH_DONE_STATUS.TRACK_ENDED, streamCount: 0, reason: 'broadcast ended' }; /** Signal effects re-run on the microtask queue; two turns settle a cascade. */ @@ -146,29 +133,31 @@ describe('resolveCatalog', () => { vi.useRealTimers(); }); - it('subscribes to the catalog track with a joining fetch once the session is ready', async () => { + it('subscribes to the catalog track from the start of the current group once the session is ready', async () => { const { actor, subscriptions, fetches } = createFakeSessionActor(); const deps = makeDeps(actor, { url: MOQ_URL }); const reactor = resolveCatalog.setup(deps); await vi.waitFor(() => expect(subscriptions).toHaveLength(1)); - expect(subscriptions[0]!.options).toMatchObject({ trackNamespace: ['live'], trackName: 'catalog' }); - expect(fetches).toHaveLength(1); - expect(fetches[0]!.options).toMatchObject({ type: 'relative-joining', joiningRequestId: 0, joiningStart: 0 }); + expect(subscriptions[0]!.options).toMatchObject({ + trackNamespace: ['live'], + trackName: 'catalog', + parameters: { locationFilter: CURRENT_GROUP }, + }); + // No FETCH: the relay replays the group on the subscription itself. + expect(fetches).toHaveLength(0); reactor.destroy(); expect(subscriptions[0]!.cancelled).toBe(true); - expect(fetches[0]!.cancelled).toBe(true); }); - it('resolves the presentation from fetched catalog objects', async () => { - const { actor, subscriptions, fetches } = createFakeSessionActor(); + it('resolves the presentation from the replayed independent catalog object', async () => { + const { actor, subscriptions } = createFakeSessionActor(); const deps = makeDeps(actor, { url: MOQ_URL }); const reactor = resolveCatalog.setup(deps); - await vi.waitFor(() => expect(fetches).toHaveLength(1)); - fetches[0]!.handlers.onEntry?.(fetchEntry(5, 0, CATALOG)); - fetches[0]!.handlers.onEnd?.(); + await vi.waitFor(() => expect(subscriptions).toHaveLength(1)); + subscriptions[0]!.handlers.onObject?.(catalogObject(5, 0, CATALOG)); await vi.waitFor(() => expect(isResolvedPresentation(deps.state.presentation.get())).toBe(true)); expect(getTracksByType(deps.state.presentation.get()!, 'video')).toHaveLength(1); @@ -177,17 +166,14 @@ describe('resolveCatalog', () => { reactor.destroy(); }); - it('applies live delta updates after the fetch settles', async () => { - const { actor, subscriptions, fetches } = createFakeSessionActor(); + it('applies deltas against the independent object of their own group', async () => { + const { actor, subscriptions } = createFakeSessionActor(); const deps = makeDeps(actor, { url: MOQ_URL }); const reactor = resolveCatalog.setup(deps); - await vi.waitFor(() => expect(fetches).toHaveLength(1)); - - // Live delta lands before the fetch replay finishes — it must buffer. + await vi.waitFor(() => expect(subscriptions).toHaveLength(1)); + subscriptions[0]!.handlers.onObject?.(catalogObject(5, 0, CATALOG)); subscriptions[0]!.handlers.onObject?.(catalogObject(5, 1, DELTA)); - fetches[0]!.handlers.onEntry?.(fetchEntry(5, 0, CATALOG)); - fetches[0]!.handlers.onEnd?.(); await vi.waitFor(() => { const presentation = deps.state.presentation.get(); @@ -199,13 +185,14 @@ describe('resolveCatalog', () => { reactor.destroy(); }); - it('recovers via the next independent object when the fetch fails', async () => { - const { actor, subscriptions, fetches } = createFakeSessionActor(); + // A publisher that does not replay the current group delivers from the + // next object: a delta with no base. + it('drops a delta with no base and recovers on the next independent object', async () => { + const { actor, subscriptions } = createFakeSessionActor(); const deps = makeDeps(actor, { url: MOQ_URL }); const reactor = resolveCatalog.setup(deps); - await vi.waitFor(() => expect(fetches).toHaveLength(1)); - fetches[0]!.handlers.onError?.({ errorCode: 0x11, retryInterval: 0, reason: 'invalid range' }); + await vi.waitFor(() => expect(subscriptions).toHaveLength(1)); // A dangling delta with no prior catalog is dropped... subscriptions[0]!.handlers.onObject?.(catalogObject(5, 1, DELTA)); @@ -218,6 +205,25 @@ describe('resolveCatalog', () => { reactor.destroy(); }); + // Groups travel on separate streams, so an older group's tail can land + // after a newer group's independent object. Applying it would land the + // old delta on the new base. + it('drops a straggling delta from a superseded group', async () => { + const { actor, subscriptions } = createFakeSessionActor(); + const deps = makeDeps(actor, { url: MOQ_URL }); + const reactor = resolveCatalog.setup(deps); + + await vi.waitFor(() => expect(subscriptions).toHaveLength(1)); + subscriptions[0]!.handlers.onObject?.(catalogObject(6, 0, CATALOG)); + await vi.waitFor(() => expect(isResolvedPresentation(deps.state.presentation.get())).toBe(true)); + + subscriptions[0]!.handlers.onObject?.(catalogObject(5, 1, DELTA)); + await flush(); + expect(getTracksByType(deps.state.presentation.get()!, 'audio')).toHaveLength(0); + + reactor.destroy(); + }); + // refreshAuthToken always rejects (see moq-session.ts) — a refreshed // token has no connection left to attach to. The one-shot retry must // give up as a terminal state like any other permanent rejection: @@ -225,7 +231,7 @@ describe('resolveCatalog', () => { // presentation and no queued restart reopens the subscription. it('gives up cleanly on EXPIRED_AUTH_TOKEN since refreshAuthToken cannot supply a usable token', async () => { vi.useFakeTimers(); - const { actor, subscriptions, fetches, refreshAuthToken } = createFakeSessionActor(); + const { actor, subscriptions, refreshAuthToken } = createFakeSessionActor(); const deps = makeDeps(actor, { url: MOQ_URL }); const reactor = resolveCatalog.setup(deps); const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}); @@ -233,10 +239,6 @@ describe('resolveCatalog', () => { await flush(); expect(subscriptions).toHaveLength(1); - // A live catalog object buffered behind the unsettled joining fetch — - // the settle timer's drain path, which never checks the attempt token. - subscriptions[0]!.handlers.onObject?.(catalogObject(5, 0, CATALOG)); - subscriptions[0]!.handlers.onError?.({ errorCode: REQUEST_ERROR_CODE.EXPIRED_AUTH_TOKEN, retryInterval: 0, @@ -247,14 +249,12 @@ describe('resolveCatalog', () => { expect(consoleError).toHaveBeenCalledWith('[resolveCatalog] auth refresh failed:', expect.any(Error)) ); - // Terminal freezes the state: no retry, handles cancelled, and past - // the fetch deadline the buffered object must NOT have drained into - // the presentation. + // Terminal freezes the state: no retry, handle cancelled, and a late + // object from the dead attempt must not reach the presentation. await vi.advanceTimersByTimeAsync(60_000); expect(subscriptions).toHaveLength(1); expect(subscriptions[0]!.cancelled).toBe(true); - expect(fetches).toHaveLength(1); - expect(fetches[0]!.cancelled).toBe(true); + subscriptions[0]!.handlers.onObject?.(catalogObject(5, 0, CATALOG)); expect(isResolvedPresentation(deps.state.presentation.get())).toBe(false); expect(vi.getTimerCount()).toBe(0); @@ -273,60 +273,13 @@ describe('resolveCatalog', () => { reactor.destroy(); }); - // A relay can answer FETCH_OK and then never open its data stream, so - // onEnd/onError/onReset never fire and the session's request timeout has - // nothing to catch. Without a settle deadline the catalog buffers live - // deltas forever and never resolves. - it('falls back to live-only when the joining fetch never settles', async () => { - const { actor, subscriptions } = createFakeSessionActor(); - const deps = makeDeps(actor, { url: MOQ_URL }); - const reactor = resolveCatalog.setup({ ...deps, config: { catalogFetchTimeoutMs: 10 } }); - - await vi.waitFor(() => expect(subscriptions).toHaveLength(1)); - subscriptions[0]!.handlers.onObject?.(catalogObject(5, 0, CATALOG)); - expect(isResolvedPresentation(deps.state.presentation.get())).toBe(false); - - await vi.waitFor(() => expect(isResolvedPresentation(deps.state.presentation.get())).toBe(true)); - expect(getTracksByType(deps.state.presentation.get()!, 'video')).toHaveLength(1); - - reactor.destroy(); - }); - - // The deadline switches to live-only, but the relay may still deliver - // the joining fetch's replay afterwards. Those entries are older than - // the live catalog by construction — applying one would roll the - // presentation back (or land the next delta on the wrong base). - it('ignores fetch entries that arrive after the settle deadline', async () => { - const { actor, subscriptions, fetches } = createFakeSessionActor(); - const deps = makeDeps(actor, { url: MOQ_URL }); - const reactor = resolveCatalog.setup({ ...deps, config: { catalogFetchTimeoutMs: 10 } }); - - await vi.waitFor(() => expect(fetches).toHaveLength(1)); - // The deadline also cancels the replay stream outright. - await vi.waitFor(() => expect(fetches[0]!.cancelled).toBe(true)); - - subscriptions[0]!.handlers.onObject?.(catalogObject(6, 0, CATALOG_WITH_AUDIO)); - await vi.waitFor(() => expect(isResolvedPresentation(deps.state.presentation.get())).toBe(true)); - expect(getTracksByType(deps.state.presentation.get()!, 'audio')).toHaveLength(1); - - // A straggling replay entry (an older group) must not overwrite it. - fetches[0]!.handlers.onEntry?.(fetchEntry(5, 0, CATALOG)); - fetches[0]!.handlers.onEnd?.(); - expect(getTracksByType(deps.state.presentation.get()!, 'audio')).toHaveLength(1); - expect(getTracksByType(deps.state.presentation.get()!, 'video')).toHaveLength(1); - - reactor.destroy(); - }); - - // The `attempt`/`isCurrent` guard got its live path back: `start()` runs - // again for every non-auth retry and PUBLISH_DONE resubscribe, so a - // cancelled first fetch's late callback must not disturb the retry - // attempt. (An earlier revision drove this through a successful auth - // refresh, which the current relay fleet's connect-URL-only jwt carriage - // made unreachable — the recovery restart is the reachable path now.) - it('keeps a cancelled first fetch from settling the retry attempt early', async () => { + // The `attempt`/`isCurrent` guard: `start()` runs again for every non-auth + // retry and PUBLISH_DONE resubscribe, and cancelling a subscription does + // not stop callbacks already in flight, so a cancelled first attempt's + // late object must not write the retry attempt's presentation. + it('ignores objects from a superseded attempt', async () => { vi.useFakeTimers(); - const { actor, subscriptions, fetches } = createFakeSessionActor(); + const { actor, subscriptions } = createFakeSessionActor(); const deps = makeDeps(actor, { url: MOQ_URL }); const reactor = resolveCatalog.setup(deps); @@ -339,22 +292,15 @@ describe('resolveCatalog', () => { reason: 'no such track', }); await vi.advanceTimersByTimeAsync(PAST_FIRST_BACKOFF_MS); - expect(fetches).toHaveLength(2); - - // Cancelling a fetch does not stop callbacks already in flight — the - // first fetch's late settle must not flush the retry's buffer early. - fetches[0]!.handlers.onEnd?.(); + expect(subscriptions).toHaveLength(2); - // Still buffering: the retry's live delta waits for its own fetch... - subscriptions[1]!.handlers.onObject?.(catalogObject(5, 1, DELTA)); + subscriptions[0]!.handlers.onObject?.(catalogObject(5, 0, CATALOG_WITH_AUDIO)); expect(isResolvedPresentation(deps.state.presentation.get())).toBe(false); - // ...and applies in order once that fetch replays the base catalog. - fetches[1]!.handlers.onEntry?.(fetchEntry(5, 0, CATALOG)); - fetches[1]!.handlers.onEnd?.(); + subscriptions[1]!.handlers.onObject?.(catalogObject(5, 0, CATALOG)); await flush(); expect(isResolvedPresentation(deps.state.presentation.get())).toBe(true); - expect(getTracksByType(deps.state.presentation.get()!, 'audio')).toHaveLength(1); + expect(getTracksByType(deps.state.presentation.get()!, 'audio')).toHaveLength(0); reactor.destroy(); }); @@ -363,7 +309,7 @@ describe('resolveCatalog', () => { // broadcast started, so the retry cadence is also the join latency. it('re-subscribes with backoff after a non-auth subscribe error', async () => { vi.useFakeTimers(); - const { actor, subscriptions, fetches } = createFakeSessionActor(); + const { actor, subscriptions } = createFakeSessionActor(); const deps = makeDeps(actor, { url: MOQ_URL }); const reactor = resolveCatalog.setup(deps); @@ -379,17 +325,11 @@ describe('resolveCatalog', () => { await vi.advanceTimersByTimeAsync(PAST_FIRST_BACKOFF_MS); expect(subscriptions).toHaveLength(2); - expect(fetches).toHaveLength(2); expect(subscriptions[0]!.cancelled).toBe(true); - expect(fetches[0]!.cancelled).toBe(true); - expect(fetches[1]!.options).toMatchObject({ type: 'relative-joining', joiningRequestId: 2, joiningStart: 0 }); + // Every attempt joins the same way: the current group from its start. + expect(subscriptions[1]!.options.parameters).toMatchObject({ locationFilter: CURRENT_GROUP }); // The broadcast appeared: the fresh attempt resolves from its own objects. - fetches[1]!.handlers.onError?.({ - errorCode: REQUEST_ERROR_CODE.INVALID_RANGE, - retryInterval: 0, - reason: 'no history', - }); subscriptions[1]!.handlers.onObject?.(catalogObject(1, 0, CATALOG)); await flush(); expect(isResolvedPresentation(deps.state.presentation.get())).toBe(true); @@ -483,7 +423,7 @@ describe('resolveCatalog', () => { it('does not re-subscribe after an auth-shaped PUBLISH_DONE', async () => { vi.useFakeTimers(); - const { actor, subscriptions, fetches } = createFakeSessionActor(); + const { actor, subscriptions } = createFakeSessionActor(); const deps = makeDeps(actor, { url: MOQ_URL }); const reactor = resolveCatalog.setup(deps); const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}); @@ -491,11 +431,6 @@ describe('resolveCatalog', () => { await flush(); expect(subscriptions).toHaveLength(1); - // A live catalog object buffered behind the unsettled joining fetch — - // the settle timer's drain path, which never checks the attempt token. - subscriptions[0]!.handlers.onObject?.(catalogObject(5, 0, CATALOG)); - expect(isResolvedPresentation(deps.state.presentation.get())).toBe(false); - // The re-subscribe would carry the same credentials the relay just // rejected — unlike TRACK_ENDED (covered below), this must not poll. subscriptions[0]!.handlers.onDone?.({ @@ -505,11 +440,10 @@ describe('resolveCatalog', () => { }); await vi.advanceTimersByTimeAsync(60_000); expect(subscriptions).toHaveLength(1); - // Terminal freezes the state: handles cancelled, and the settle timer - // disarmed with the buffer discarded — past the fetch deadline, the - // buffered object must NOT have drained into the presentation. + // Terminal freezes the state: handle cancelled, and a late object from + // the dead attempt must not reach the presentation. expect(subscriptions[0]!.cancelled).toBe(true); - expect(fetches[0]!.cancelled).toBe(true); + subscriptions[0]!.handlers.onObject?.(catalogObject(5, 0, CATALOG)); expect(isResolvedPresentation(deps.state.presentation.get())).toBe(false); expect(vi.getTimerCount()).toBe(0); consoleError.mockRestore(); @@ -548,12 +482,11 @@ describe('resolveCatalog', () => { }); // The refreshed token being rejected too is a terminal state like any - // other permanent rejection: freeze it. The second attempt's settle - // timer must not keep draining buffered objects into the presentation. + // other permanent rejection: freeze it. it('freezes the state when the refreshed token is rejected too', async () => { vi.useFakeTimers(); const base = createFakeSessionActor(); - const { subscriptions, fetches } = base; + const { subscriptions } = base; const refreshAuthToken = vi.fn(async () => ({})); const actor: MoqSessionActor = { ...base.actor, refreshAuthToken }; const deps = makeDeps(actor, { url: MOQ_URL }); @@ -571,10 +504,6 @@ describe('resolveCatalog', () => { await flush(); expect(subscriptions).toHaveLength(2); - // A live object buffered behind the refreshed attempt's unsettled - // joining fetch — the settle timer's drain path. - subscriptions[1]!.handlers.onObject?.(catalogObject(5, 0, CATALOG)); - subscriptions[1]!.handlers.onError?.({ errorCode: REQUEST_ERROR_CODE.EXPIRED_AUTH_TOKEN, retryInterval: 0, @@ -584,7 +513,7 @@ describe('resolveCatalog', () => { expect(refreshAuthToken).toHaveBeenCalledOnce(); expect(subscriptions).toHaveLength(2); expect(subscriptions[1]!.cancelled).toBe(true); - expect(fetches[1]!.cancelled).toBe(true); + subscriptions[1]!.handlers.onObject?.(catalogObject(5, 0, CATALOG)); expect(isResolvedPresentation(deps.state.presentation.get())).toBe(false); expect(vi.getTimerCount()).toBe(0); consoleError.mockRestore(); @@ -641,7 +570,7 @@ describe('resolveCatalog', () => { // not that the session is unhealthy — poll the track back into existence. it('re-subscribes when the publisher ends the catalog track', async () => { vi.useFakeTimers(); - const { actor, subscriptions, fetches } = createFakeSessionActor(); + const { actor, subscriptions } = createFakeSessionActor(); const deps = makeDeps(actor, { url: MOQ_URL }); const reactor = resolveCatalog.setup(deps); @@ -653,9 +582,7 @@ describe('resolveCatalog', () => { await vi.advanceTimersByTimeAsync(PAST_FIRST_BACKOFF_MS); expect(subscriptions).toHaveLength(2); - expect(fetches).toHaveLength(2); expect(subscriptions[0]!.cancelled).toBe(true); - expect(fetches[0]!.cancelled).toBe(true); reactor.destroy(); }); @@ -665,14 +592,13 @@ describe('resolveCatalog', () => { // produce a wrong track list. it('resets the catalog base across a restart so a delta cannot apply to the pre-outage catalog', async () => { vi.useFakeTimers(); - const { actor, subscriptions, fetches } = createFakeSessionActor(); + const { actor, subscriptions } = createFakeSessionActor(); const deps = makeDeps(actor, { url: MOQ_URL }); const reactor = resolveCatalog.setup(deps); await flush(); - fetches[0]!.handlers.onEntry?.(fetchEntry(5, 0, CATALOG)); - fetches[0]!.handlers.onEnd?.(); + subscriptions[0]!.handlers.onObject?.(catalogObject(5, 0, CATALOG)); await flush(); expect(isResolvedPresentation(deps.state.presentation.get())).toBe(true); @@ -680,13 +606,6 @@ describe('resolveCatalog', () => { await vi.advanceTimersByTimeAsync(PAST_FIRST_BACKOFF_MS); expect(subscriptions).toHaveLength(2); - // Nothing published yet on the restarted track — live-only from here. - fetches[1]!.handlers.onError?.({ - errorCode: REQUEST_ERROR_CODE.INVALID_RANGE, - retryInterval: 0, - reason: 'no history', - }); - // A delta from the restarted publisher has no base to apply to, so it is // dropped; the last resolved presentation stands. subscriptions[1]!.handlers.onObject?.(catalogObject(1, 1, DELTA)); @@ -767,7 +686,7 @@ describe('resolveCatalog', () => { // Leaving 'catalog-active' (here: the source went away) drops the timer. deps.state.presentation.set(undefined); await flush(); - expect(vi.getTimerCount()).toBe(0); // retry and settle timers both cleared + expect(vi.getTimerCount()).toBe(0); await vi.advanceTimersByTimeAsync(60_000); expect(subscriptions).toHaveLength(1); diff --git a/packages/spf/src/playback/behaviors/tests/subscribe-selected-tracks.test.ts b/packages/spf/src/playback/behaviors/tests/subscribe-selected-tracks.test.ts index 47b16bbfc5..98401567bd 100644 --- a/packages/spf/src/playback/behaviors/tests/subscribe-selected-tracks.test.ts +++ b/packages/spf/src/playback/behaviors/tests/subscribe-selected-tracks.test.ts @@ -208,7 +208,7 @@ describe('subscribeSelectedVideoTrack', () => { await vi.waitFor(() => expect(created).toHaveLength(1)); expect(created[0]!.options).toMatchObject({ track: { id: HD.id }, - locationFilter: { type: 'next-group-start' }, + locationFilter: { type: 'relative-group', groupsBeforeNext: 0 }, }); expect(deps.context.videoSubscriberActor.get()).toBe(created[0]); expect(deps.context.pendingVideoSubscriberActor.get()).toBeUndefined(); @@ -335,12 +335,12 @@ describe('subscribeSelectedVideoTrack', () => { expect(deps.context.videoSubscriberActor.get()).toBeUndefined(); expect(deps.context.pendingVideoSubscriberActor.get()).toBeUndefined(); - // Resume: a fresh initial join (next-group-start), not a handoff. + // Resume: a fresh initial join (relative-group 0), not a handoff. deps.state.mediaSuspended.set(undefined); await vi.waitFor(() => expect(created).toHaveLength(2)); expect(created[1]!.options).toMatchObject({ track: { id: HD.id }, - locationFilter: { type: 'next-group-start' }, + locationFilter: { type: 'relative-group', groupsBeforeNext: 0 }, }); expect(deps.context.videoSubscriberActor.get()).toBe(created[1]); expect(deps.context.pendingVideoSubscriberActor.get()).toBeUndefined(); @@ -487,7 +487,7 @@ describe('subscribeSelectedVideoTrack', () => { expect(created).toHaveLength(2); expect(created[1]!.options).toMatchObject({ track: { id: HD.id }, - locationFilter: { type: 'next-group-start' }, + locationFilter: { type: 'relative-group', groupsBeforeNext: 0 }, }); expect(deps.context.videoSubscriberActor.get()).toBe(created[1]); expect(deps.context.pendingVideoSubscriberActor.get()).toBeUndefined(); @@ -517,7 +517,7 @@ describe('subscribeSelectedVideoTrack', () => { expect(created).toHaveLength(2); expect(created[1]!.options).toMatchObject({ track: { id: HD.id }, - locationFilter: { type: 'next-group-start' }, + locationFilter: { type: 'relative-group', groupsBeforeNext: 0 }, }); expect(deps.context.videoSubscriberActor.get()).toBe(created[1]); @@ -553,7 +553,7 @@ describe('subscribeSelectedVideoTrack', () => { expect(created).toHaveLength(3); expect(created[2]!.options).toMatchObject({ track: { id: SD.id }, - locationFilter: { type: 'next-group-start' }, + locationFilter: { type: 'relative-group', groupsBeforeNext: 0 }, }); expect(deps.context.pendingVideoSubscriberActor.get()).toBe(created[2]); expect(deps.context.videoSubscriberActor.get()).toBe(created[0]); @@ -754,7 +754,7 @@ describe('subscribeSelectedVideoTrack', () => { expect(created).toHaveLength(2); expect(created[1]!.options).toMatchObject({ track: { id: SD.id }, - locationFilter: { type: 'next-group-start' }, + locationFilter: { type: 'relative-group', groupsBeforeNext: 0 }, }); expect(deps.context.videoSubscriberActor.get()).toBe(created[1]); @@ -783,7 +783,7 @@ describe('subscribeSelectedVideoTrack', () => { expect(created).toHaveLength(2); expect(created[1]!.options).toMatchObject({ track: { id: SD.id }, - locationFilter: { type: 'next-group-start' }, + locationFilter: { type: 'relative-group', groupsBeforeNext: 0 }, }); expect(deps.context.videoSubscriberActor.get()).toBe(created[1]); @@ -816,7 +816,7 @@ describe('subscribeSelectedVideoTrack', () => { expect(created).toHaveLength(3); expect(created[2]!.options).toMatchObject({ track: { id: LD.id }, - locationFilter: { type: 'next-group-start' }, + locationFilter: { type: 'relative-group', groupsBeforeNext: 0 }, }); expect(deps.context.pendingVideoSubscriberActor.get()).toBe(created[2]); expect(deps.context.videoSubscriberActor.get()).toBe(created[0]); @@ -836,7 +836,7 @@ describe('subscribeSelectedAudioTrack', () => { await vi.waitFor(() => expect(created).toHaveLength(1)); expect(created[0]!.options).toMatchObject({ track: { id: MAIN_AUDIO.id }, - locationFilter: { type: 'largest-object' }, + locationFilter: { type: 'next-object' }, }); // Autoplay started without a gesture: the adapter defers audio. @@ -850,7 +850,7 @@ describe('subscribeSelectedAudioTrack', () => { await vi.waitFor(() => expect(created).toHaveLength(2)); expect(created[1]!.options).toMatchObject({ track: { id: MAIN_AUDIO.id }, - locationFilter: { type: 'largest-object' }, + locationFilter: { type: 'next-object' }, }); expect(deps.context.audioSubscriberActor.get()).toBe(created[1]); @@ -904,7 +904,7 @@ describe('subscribeSelectedAudioTrack', () => { expect(created).toHaveLength(2); expect(created[1]!.options).toMatchObject({ track: { id: MAIN_AUDIO.id }, - locationFilter: { type: 'largest-object' }, + locationFilter: { type: 'next-object' }, }); expect(deps.context.audioSubscriberActor.get()).toBe(created[1]); expect(deps.context.pendingAudioSubscriberActor.get()).toBeUndefined(); diff --git a/packages/spf/src/playback/engines/moq/tests/engine.test.ts b/packages/spf/src/playback/engines/moq/tests/engine.test.ts index 56ee0b0e43..f76a449bbf 100644 --- a/packages/spf/src/playback/engines/moq/tests/engine.test.ts +++ b/packages/spf/src/playback/engines/moq/tests/engine.test.ts @@ -17,7 +17,7 @@ import type { CreateMoqTransport } from '../../../actors/moq-session'; import { createMoqEngine, type MoqEngineConfig, type MoqEngineSignals } from '../engine'; // ============================================================================ -// In-memory relay: speaks real draft-19 bytes over a fake WebTransport. +// In-memory relay: speaks real draft-20 bytes over a fake WebTransport. // ============================================================================ const CATALOG = JSON.stringify({ @@ -108,7 +108,8 @@ function createFakeRelay(catalog: string = CATALOG) { } if (message.kind === 'fetch') { - // No history — the engine falls back to live catalog objects. + // The engine never fetches (a draft-20 join is a subscription filter); + // anything that does is refused — no history is retained. await writer.write(encodeRequestError(REQUEST_ERROR_CODE.INVALID_RANGE, 'nothing published')); await writer.close(); return; @@ -389,7 +390,7 @@ describe('createMoqEngine', () => { await vi.waitFor(() => expect(trackIds()).toContain('live/video2'), { timeout: 5000 }); - // Resume: a fresh live-edge join (next-group-start), no catalog churn. + // Resume: a fresh next-group join (relative-group 0), no catalog churn. signals.state.paused.set(false); await vi.waitFor( () => { @@ -399,15 +400,16 @@ describe('createMoqEngine', () => { ); expect(relay.subscriptions.filter((s) => s.message.trackName === 'catalog')).toHaveLength(1); expect(relay.subscriptions.at(-1)!.message.parameters).toMatchObject({ - locationFilter: { type: 'next-group-start' }, + locationFilter: { type: 'relative-group', groupsBeforeNext: 0 }, }); await vi.waitFor(() => expect(signals.context.videoSubscriberActor.get()).toBeDefined()); await engine.destroy(); }); - // A draft-19 relay replays its recent groups to every joining subscriber, - // so the jitter buffer starts seconds deep. `latency.joinAtEdge` decides + // A relay can replay buffered groups to a joining subscriber (a draft-20 + // current-group join replays that group from cache; older relays replayed + // several), so the jitter buffer can start seconds deep. `latency.joinAtEdge` decides // whether playout starts at the front of that replay or at its edge. // // The canvas is attached after the replay lands so the assertion is about @@ -590,7 +592,7 @@ describe('createMoqEngine', () => { expect(() => createMoqEngine({ adaptiveLatency: { intervalMs: 100 } })).toThrow(RangeError); }); - it('subscribes to the catalog with the largest-object filter', async () => { + it('subscribes to the catalog from the start of the current group', async () => { const relay = createFakeRelay(); let signals!: MoqEngineSignals; const engine = createMoqEngine({ @@ -609,7 +611,7 @@ describe('createMoqEngine', () => { expect(relay.subscriptions[0]!.message).toMatchObject({ trackNamespace: ['live'], trackName: 'catalog', - parameters: { locationFilter: { type: 'largest-object' } }, + parameters: { locationFilter: { type: 'relative-group', groupsBeforeNext: 1 } }, }); await engine.destroy(); From 919450e8082cf20026c0419586e77d9f5fda03ba Mon Sep 17 00:00:00 2001 From: Matt McClure Date: Wed, 2 Sep 2026 23:44:32 +0000 Subject: [PATCH 3/6] docs(spf): record the moqt-20 migration status on the branch --- .agents/plans/moq-transport-20-migration.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/.agents/plans/moq-transport-20-migration.md b/.agents/plans/moq-transport-20-migration.md index 7d4ebdcfb9..a09686b17a 100644 --- a/.agents/plans/moq-transport-20-migration.md +++ b/.agents/plans/moq-transport-20-migration.md @@ -212,6 +212,14 @@ speaks `moqt-20` only and deletes the draft-19 filter tags, Fetch Type structures, and the catalog joining FETCH. The five branch points below are kept as the list of what changes, not as runtime switches. +**Status (2026-09-02):** Phases 1–4 landed on `feat/moq-transport-20` in +commit `feat(spf): speak moq-transport draft-20 (moqt-20)`. Node and browser +test projects pass, typecheck passes. Not yet done: an interop pass against +relay.mux.dev / mux.global through the `moq-relay-interop` and `spf-moq-player` +templates (the only verification a fake relay cannot give — in particular the +audio join now starting at the live edge, and the catalog resolving from the +relay's `relative-group 1` replay), and Phase 5 on `mmcc/moq-publisher`. + Branch points on a `draft: 19 | 20` value in `createMoqtSession` config: 1. LOCATION_FILTER encode/decode (tag form vs field list). From e41254377da891dcd0f9e74f17fda36ca342f2d6 Mon Sep 17 00:00:00 2001 From: Matt McClure Date: Thu, 3 Sep 2026 00:10:53 +0000 Subject: [PATCH 4/6] docs(spf): record the moqt-20 live interop pass against the relay fleet --- .agents/plans/moq-transport-20-migration.md | 38 ++++++++++++++++++--- 1 file changed, 33 insertions(+), 5 deletions(-) diff --git a/.agents/plans/moq-transport-20-migration.md b/.agents/plans/moq-transport-20-migration.md index a09686b17a..0934e1030d 100644 --- a/.agents/plans/moq-transport-20-migration.md +++ b/.agents/plans/moq-transport-20-migration.md @@ -214,11 +214,39 @@ kept as the list of what changes, not as runtime switches. **Status (2026-09-02):** Phases 1–4 landed on `feat/moq-transport-20` in commit `feat(spf): speak moq-transport draft-20 (moqt-20)`. Node and browser -test projects pass, typecheck passes. Not yet done: an interop pass against -relay.mux.dev / mux.global through the `moq-relay-interop` and `spf-moq-player` -templates (the only verification a fake relay cannot give — in particular the -audio join now starting at the live edge, and the catalog resolving from the -relay's `relative-group 1` replay), and Phase 5 on `mmcc/moq-publisher`. +test projects pass, typecheck passes. + +**Live pass (2026-09-03, headless Chromium → sjc.relay.mux.global, moq-relay +0.14.14, token-authenticated; publisher = the `mmcc/moq-publisher` sandbox's +synthetic draft-19 stream under `mattypoo/vjs-probe`):** + +- WebTransport negotiates `moqt-20` (`transport.protocol`); server SETUP + reports `moq-lite-rs` plus the RELAY_HOPS / SOLICIT setup options; session + ready in ~250 ms. +- Catalog with `relative-group 1`: SUBSCRIBE_OK, then object g0 o0 (the + independent catalog) on the subscription stream. The same track with + `next-object`: SUBSCRIBE_OK carrying LARGEST_OBJECT `{0,0}`, then an empty + subgroup stream — the relay is strict, so the old join would never have + resolved a catalog. Both confirm the Consequences section. +- Video with `relative-group 1`: SUBSCRIBE_OK carried LARGEST_OBJECT + `{group 35, object 28}` (length-prefixed, decoded correctly) and delivery + began at g35 o0 — the IDR — with 60 objects for that group before live + groups g36… each from o0. Audio likewise starts each group at o0 (one + object per group from this publisher). +- The real player (`moq-relay-interop` template): catalog resolved ~350 ms + after SETUP, both tracks subscribed, `playing` at ~2.5 s, measured latency + converged 0.27 s → 0.48 s against the 0.5 s target, playout `stable`, no + console errors over 36 s. Audio joining at the live edge did not upset the + latency controller. +- Relay quirks seen: REQUEST_ERROR `0x194` ("Broadcast not found", an HTTP + 404 as a MoQ code — unknown to us, so it retries with backoff as intended); + SUBSCRIBE_NAMESPACE under the token root answered REQUEST_OK but announced + nothing even while the broadcast was live. +- relay.mux.dev could not be tested: its `*.relay.mux.dev` certificate + expired 2026-08-26 and WebTransport does not honor certificate-error + overrides. + +Remaining: Phase 5 on `mmcc/moq-publisher`. Branch points on a `draft: 19 | 20` value in `createMoqtSession` config: From b612a18af942add563f565cdc32a37f684e9e554 Mon Sep 17 00:00:00 2001 From: Matt McClure Date: Thu, 3 Sep 2026 15:40:43 +0000 Subject: [PATCH 5/6] fix(spf): address codex review of the moqt-20 cutover - resolve-catalog: an independent catalog object from a group older than the current base is a reordered straggler; drop it instead of rolling the presentation back. - session: accepting an incoming PUBLISH sends a bare PUBLISH_OK. Draft-20 allows subscription parameters only on PUBLISH and REQUEST_UPDATE, and a parameter in the wrong message is a PROTOCOL_VIOLATION (section 10.2.1). --- .../spf/src/network/moqt/control-messages.ts | 4 ++- packages/spf/src/network/moqt/session.ts | 9 ++++--- .../src/playback/behaviors/resolve-catalog.ts | 5 ++++ .../behaviors/tests/resolve-catalog.test.ts | 25 +++++++++++++++++++ 4 files changed, 39 insertions(+), 4 deletions(-) diff --git a/packages/spf/src/network/moqt/control-messages.ts b/packages/spf/src/network/moqt/control-messages.ts index b6b7264c55..062a8647d9 100644 --- a/packages/spf/src/network/moqt/control-messages.ts +++ b/packages/spf/src/network/moqt/control-messages.ts @@ -968,7 +968,9 @@ export function encodeGoaway(timeout = 0): Uint8Array { /** * REQUEST_OK (§10.5). The subscriber sends this to accept an incoming PUBLISH (PUBLISH_OK). Track Properties are always * empty in that role, and since draft-20 so are the parameters — a subscriber changes subscription parameters with - * REQUEST_UPDATE, not in PUBLISH_OK (§10.11). + * REQUEST_UPDATE, not in PUBLISH_OK (§10.11); the session driver's `accept()` therefore takes none. The parameter slot + * stays for the publisher-side roles of REQUEST_OK (TRACK_STATUS_OK, REQUEST_UPDATE_OK), which the fake peer in tests + * exercises. */ export function encodeRequestOk(parameters: MessageParameters = {}): Uint8Array { const body = new ByteWriter(); diff --git a/packages/spf/src/network/moqt/session.ts b/packages/spf/src/network/moqt/session.ts index e4a3be06ee..aec5c83739 100644 --- a/packages/spf/src/network/moqt/session.ts +++ b/packages/spf/src/network/moqt/session.ts @@ -170,10 +170,13 @@ export interface MoqtSessionCallbacks { /** * A server-initiated PUBLISH arrived. Call exactly one of the responders. Absent, the session rejects with * UNINTERESTED (a subscribe-only client). + * + * `accept` sends a bare PUBLISH_OK: since draft-20 the subscription parameters (FORWARD, LOCATION_FILTER, …) are + * legal only on PUBLISH and REQUEST_UPDATE, and a parameter in the wrong message is a PROTOCOL_VIOLATION (§10.2.1). */ onIncomingPublish?( publish: IncomingPublish, - respond: { accept(parameters?: MessageParameters): void; reject(errorCode?: number, reason?: string): void } + respond: { accept(): void; reject(errorCode?: number, reason?: string): void } ): void; /** The session ended — transport closed, or a fatal protocol error. */ onClosed?(info: { error?: unknown }): void; @@ -985,11 +988,11 @@ class MoqtSessionImpl implements MoqtSession { let responded = false; callbacks.onIncomingPublish(message, { - accept: (parameters) => { + accept: () => { if (responded) return; responded = true; - void respond(encodeRequestOk(parameters ?? {})); + void respond(encodeRequestOk()); }, reject: (errorCode = REQUEST_ERROR_CODE.UNINTERESTED, reason = '') => { if (responded) return; diff --git a/packages/spf/src/playback/behaviors/resolve-catalog.ts b/packages/spf/src/playback/behaviors/resolve-catalog.ts index 0ae89365ad..fb747d3942 100644 --- a/packages/spf/src/playback/behaviors/resolve-catalog.ts +++ b/packages/spf/src/playback/behaviors/resolve-catalog.ts @@ -165,6 +165,11 @@ function setupResolveCatalog({ const apply = (text: string, groupId: number, objectId: number): void => { if (objectId === 0) { + // Groups travel on separate streams, so an older group's + // independent object can land after a newer group's. Applying + // it would roll the presentation back to a superseded catalog. + if (baseGroup !== undefined && groupId < baseGroup) return; + baseGroup = groupId; } else if (catalog === undefined || groupId !== baseGroup) { // A delta with no base can't be interpreted (msf §5.1.6), and diff --git a/packages/spf/src/playback/behaviors/tests/resolve-catalog.test.ts b/packages/spf/src/playback/behaviors/tests/resolve-catalog.test.ts index 88e5e062cd..f4ca0a63fe 100644 --- a/packages/spf/src/playback/behaviors/tests/resolve-catalog.test.ts +++ b/packages/spf/src/playback/behaviors/tests/resolve-catalog.test.ts @@ -224,6 +224,31 @@ describe('resolveCatalog', () => { reactor.destroy(); }); + it('drops a straggling independent object from a superseded group', async () => { + const { actor, subscriptions } = createFakeSessionActor(); + const deps = makeDeps(actor, { url: MOQ_URL }); + const reactor = resolveCatalog.setup(deps); + + await vi.waitFor(() => expect(subscriptions).toHaveLength(1)); + subscriptions[0]!.handlers.onObject?.(catalogObject(6, 0, CATALOG)); + await vi.waitFor(() => expect(isResolvedPresentation(deps.state.presentation.get())).toBe(true)); + expect(getTracksByType(deps.state.presentation.get()!, 'audio')).toHaveLength(0); + + // The older group's catalog arrives late: it must not roll the + // presentation back, and its deltas must stay dropped too. + subscriptions[0]!.handlers.onObject?.(catalogObject(5, 0, CATALOG_WITH_AUDIO)); + subscriptions[0]!.handlers.onObject?.(catalogObject(5, 1, DELTA)); + await flush(); + expect(getTracksByType(deps.state.presentation.get()!, 'audio')).toHaveLength(0); + + // The base group's own deltas still apply. + subscriptions[0]!.handlers.onObject?.(catalogObject(6, 1, DELTA)); + await flush(); + expect(getTracksByType(deps.state.presentation.get()!, 'audio')).toHaveLength(1); + + reactor.destroy(); + }); + // refreshAuthToken always rejects (see moq-session.ts) — a refreshed // token has no connection left to attach to. The one-shot retry must // give up as a terminal state like any other permanent rejection: From c1f23dfabc8d98788c25992ed1f727755a153f10 Mon Sep 17 00:00:00 2001 From: Matt McClure Date: Thu, 3 Sep 2026 15:44:50 +0000 Subject: [PATCH 6/6] fix(spf): address PR review findings on the moqt-20 cutover - resolve-catalog: move the base group only after its independent object parsed, so a malformed catalog cannot route the next group's deltas onto the previous catalog. - PUBLISH_DONE Stream Count: only the exact 2^64-1 sentinel reads as unknown; any other count past 2^53-1 stays a protocol error. - moq-session: name the relay fleet the same way in all three comments. - plan: the draft-19 pin is described as the state before this branch. --- .agents/plans/moq-transport-20-migration.md | 10 +++--- packages/spf/src/network/moqt/bytes.ts | 20 ++++++------ .../spf/src/network/moqt/control-messages.ts | 7 +++-- .../moqt/tests/control-messages.test.ts | 7 +++++ .../spf/src/playback/actors/moq-session.ts | 26 ++++++++-------- .../src/playback/behaviors/resolve-catalog.ts | 8 +++-- .../behaviors/tests/resolve-catalog.test.ts | 31 +++++++++++++++++++ 7 files changed, 77 insertions(+), 32 deletions(-) diff --git a/.agents/plans/moq-transport-20-migration.md b/.agents/plans/moq-transport-20-migration.md index 0934e1030d..fcf8f65e77 100644 --- a/.agents/plans/moq-transport-20-migration.md +++ b/.agents/plans/moq-transport-20-migration.md @@ -2,10 +2,12 @@ Planning pass dated 2026-09-02. `draft-ietf-moq-transport-20` was published 2026-08-31 and is vendored at `internal/specs/moq/draft-ietf-moq-transport-20.txt` -(its Appendix A.1 is the authoritative change list). The code on `mmcc/moq` -and `mmcc/moq-publisher` pins draft-19 (`MOQT_PROTOCOL_ID = 'moqt-19'`). -LOC-04 and MSF-01 did not change; loc.ts already uses the loc-04 property IDs -that draft-20 §15.8 now mirrors, so no LOC/MSF code moves. +(its Appendix A.1 is the authoritative change list). Before this branch the +code on `mmcc/moq` and `mmcc/moq-publisher` pinned draft-19 +(`MOQT_PROTOCOL_ID = 'moqt-19'`); `feat/moq-transport-20` moves the player to +`moqt-20`, and the publisher branch follows in Phase 5. LOC-04 and MSF-01 did +not change; loc.ts already uses the loc-04 property IDs that draft-20 §15.8 +now mirrors, so no LOC/MSF code moves. The relay fleet (mux.global and relay.mux.dev, both updated 2026-09-02) runs moq-relay 0.14.14, released 2026-09-01, which added `moqt-20` in moq-dev/moq diff --git a/packages/spf/src/network/moqt/bytes.ts b/packages/spf/src/network/moqt/bytes.ts index cfb7e66d9f..a5f36e7c96 100644 --- a/packages/spf/src/network/moqt/bytes.ts +++ b/packages/spf/src/network/moqt/bytes.ts @@ -5,7 +5,6 @@ * fully buffered — the 16-bit message length bounds them). `StreamReader` is the asynchronous counterpart for * unidirectional data streams, where headers and objects arrive incrementally over a WebTransport `ReadableStream`. */ -import { isMoqtProtocolError } from './errors'; import { decodeVarint, encodeVarintInto, varintByteLength, varintLengthFromFirstByte } from './varint'; const textEncoder = new TextEncoder(); @@ -45,19 +44,20 @@ export class ByteReader { } /** - * Read a varint whose legal range exceeds this codec's 2^53−1 ceiling — PUBLISH_DONE's Stream Count uses 2^64−1 as - * its "could not count" sentinel (§10.12). A value above the ceiling reads as `undefined` and is skipped, instead of - * failing the session the way `readVarint` does. + * Read a count whose "unknown" sentinel is the maximal varint 2^64−1 — PUBLISH_DONE's Stream Count (§10.12). Exactly + * that sentinel reads as `undefined`; any other value above this codec's 2^53−1 ceiling is still the protocol error + * `readVarint` raises, since no real count gets there. */ - readUnboundedVarint(): number | undefined { - try { - return this.readVarint(); - } catch (error) { - if (!isMoqtProtocolError(error)) throw error; + readCountVarint(): number | undefined { + const offset = this.#offset; - this.#offset += varintLengthFromFirstByte(this.#bytes[this.#offset]!); + // 2^64−1 has one encoding: the 9-byte form with every bit set. + if (this.remaining >= 9 && this.#bytes.subarray(offset, offset + 9).every((byte) => byte === 0xff)) { + this.#offset += 9; return undefined; } + + return this.readVarint(); } readUint8(): number { diff --git a/packages/spf/src/network/moqt/control-messages.ts b/packages/spf/src/network/moqt/control-messages.ts index 062a8647d9..9c75aaeb49 100644 --- a/packages/spf/src/network/moqt/control-messages.ts +++ b/packages/spf/src/network/moqt/control-messages.ts @@ -1231,9 +1231,10 @@ function decodeControlMessageBody(type: number, reader: ByteReader, end: number) case MESSAGE_TYPE.PUBLISH_DONE: { const statusCode = reader.readVarint(); // A publisher that cannot count its streams MUST send 2^64−1 (§10.12), - // which is above this codec's varint ceiling — read it as "unknown" - // rather than failing the session over a legitimate PUBLISH_DONE. - const streamCount = reader.readUnboundedVarint(); + // which is above this codec's varint ceiling — read that one value as + // "unknown" rather than failing the session over a legitimate + // PUBLISH_DONE. Any other count past the ceiling stays a protocol error. + const streamCount = reader.readCountVarint(); return { kind: 'publish-done', statusCode, streamCount, reason: readReasonPhrase(reader) }; } diff --git a/packages/spf/src/network/moqt/tests/control-messages.test.ts b/packages/spf/src/network/moqt/tests/control-messages.test.ts index 2b2976da4a..11a2eab7a5 100644 --- a/packages/spf/src/network/moqt/tests/control-messages.test.ts +++ b/packages/spf/src/network/moqt/tests/control-messages.test.ts @@ -200,6 +200,13 @@ describe('encodePublishDone', () => { reason: '', }); }); + + it('rejects a stream count above 2^53-1 that is not the sentinel', () => { + // A 9-byte varint one bit short of the sentinel: 2^63 + …, not a count any publisher can mean. + const body = Uint8Array.of(PUBLISH_DONE_STATUS.GOING_AWAY, 0xff, 0x80, ...new Array(7).fill(0xff), 0x00); + + expect(() => decodeControlMessage({ type: MESSAGE_TYPE.PUBLISH_DONE, body })).toThrow(MoqtProtocolError); + }); }); describe('encodePublishStateNotify', () => { diff --git a/packages/spf/src/playback/actors/moq-session.ts b/packages/spf/src/playback/actors/moq-session.ts index 850f491e22..f98cd3d126 100644 --- a/packages/spf/src/playback/actors/moq-session.ts +++ b/packages/spf/src/playback/actors/moq-session.ts @@ -15,12 +15,12 @@ * * Also the home of the MSF §11.4 auth seam: `authProvider` supplies the initial authorization token (defaulting to the * source's `c4m` fragment token), composed onto the connect URL's `?jwt=` query parameter — the only carriage the known - * relay fleet (moq-lite-rs lineage) accepts; see `composePlaybackConnectUrl`. `getAuthParameters()` always resolves - * empty — nothing rides a request's parameters. `refreshAuthToken()` always rejects: this actor connects once and never - * reconnects (a `goaway` is only recorded, see `SessionMessage`'s `'goaway'` case), so a refreshed token has nowhere - * left to attach — the jwt is fixed at connect time. Both stay on the interface (with `MoqAuthProvider.refreshToken`) - * for a future relay generation that accepts AUTHORIZATION_TOKEN request parameters, at which point a token could ride - * a request instead of only the connect URL. + * relay fleet (moq-relay, moq-dev/moq lineage) accepts; see `composePlaybackConnectUrl`. `getAuthParameters()` always + * resolves empty — nothing rides a request's parameters. `refreshAuthToken()` always rejects: this actor connects once + * and never reconnects (a `goaway` is only recorded, see `SessionMessage`'s `'goaway'` case), so a refreshed token has + * nowhere left to attach — the jwt is fixed at connect time. Both stay on the interface (with + * `MoqAuthProvider.refreshToken`) for a future relay generation that accepts AUTHORIZATION_TOKEN request parameters, at + * which point a token could ride a request instead of only the connect URL. */ import { createTransitionActor, type TransitionActor } from '../../core/actors/create-transition-actor'; import type { MoqSource } from '../../media/moq/parse-source'; @@ -169,13 +169,13 @@ function skipTokenResolution(url: string): boolean { } /** - * Compose the WebTransport connect URL for a source. moq-lite-rs lineage relays (Mux's relay-rs fleet, the Varnish lab - * relays) authenticate with a JWT `?jwt=` query parameter on the connect URL and close the connection right after - * CLIENT_SETUP when auth is required but missing — the same carriage `composePublishConnectUrl` uses on the publish - * side (`publish/session/publish-session.ts`), for the same reason: this relay fleet hard-closes the session (`5 - * "invalid value"`) when a AUTHORIZATION_TOKEN structure rides a request's parameters instead. An explicit `jwt` param - * already in the source URL wins, and an unparseable URL is returned verbatim so `new WebTransport(url)` raises the - * canonical error. + * Compose the WebTransport connect URL for a source. moq-relay (moq-dev/moq lineage — it still announces itself as + * `moq-lite-rs` in SETUP; Mux's fleet, the Varnish lab relays) authenticates with a JWT `?jwt=` query parameter on the + * connect URL and closes the connection right after CLIENT_SETUP when auth is required but missing — the same carriage + * `composePublishConnectUrl` uses on the publish side (`publish/session/publish-session.ts`), for the same reason: this + * relay fleet hard-closes the session (`5 "invalid value"`) when a AUTHORIZATION_TOKEN structure rides a request's + * parameters instead. An explicit `jwt` param already in the source URL wins, and an unparseable URL is returned + * verbatim so `new WebTransport(url)` raises the canonical error. */ export function composePlaybackConnectUrl(url: string, authToken?: string): string { if (!authToken) return url; diff --git a/packages/spf/src/playback/behaviors/resolve-catalog.ts b/packages/spf/src/playback/behaviors/resolve-catalog.ts index fb747d3942..a772bb295a 100644 --- a/packages/spf/src/playback/behaviors/resolve-catalog.ts +++ b/packages/spf/src/playback/behaviors/resolve-catalog.ts @@ -169,8 +169,6 @@ function setupResolveCatalog({ // independent object can land after a newer group's. Applying // it would roll the presentation back to a superseded catalog. if (baseGroup !== undefined && groupId < baseGroup) return; - - baseGroup = groupId; } else if (catalog === undefined || groupId !== baseGroup) { // A delta with no base can't be interpreted (msf §5.1.6), and // one from another group would apply against the wrong base; @@ -180,6 +178,12 @@ function setupResolveCatalog({ try { catalog = applyUpdate(catalog, text, updateOptions); + + // The base moves only once its independent object parsed: a + // malformed one leaves the previous catalog in place, and its + // group's deltas are dropped rather than applied to it. + if (objectId === 0) baseGroup = groupId; + state.presentation.set(moqCatalogToPresentation(catalog, presentation, source.sessionUri)); } catch (error) { // TODO(error-management): route to a state-error slot once one exists. diff --git a/packages/spf/src/playback/behaviors/tests/resolve-catalog.test.ts b/packages/spf/src/playback/behaviors/tests/resolve-catalog.test.ts index f4ca0a63fe..99ecb47f02 100644 --- a/packages/spf/src/playback/behaviors/tests/resolve-catalog.test.ts +++ b/packages/spf/src/playback/behaviors/tests/resolve-catalog.test.ts @@ -249,6 +249,37 @@ describe('resolveCatalog', () => { reactor.destroy(); }); + // A malformed independent object must not move the base: otherwise the + // new group's deltas would apply to the previous group's catalog. + it('keeps the previous base when an independent object fails to parse', async () => { + const { actor, subscriptions } = createFakeSessionActor(); + const deps = makeDeps(actor, { url: MOQ_URL }); + const reactor = resolveCatalog.setup(deps); + const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}); + + await vi.waitFor(() => expect(subscriptions).toHaveLength(1)); + subscriptions[0]!.handlers.onObject?.(catalogObject(5, 0, CATALOG)); + await vi.waitFor(() => expect(isResolvedPresentation(deps.state.presentation.get())).toBe(true)); + + subscriptions[0]!.handlers.onObject?.(catalogObject(6, 0, '{"version":"1","tracks":')); + expect(consoleError).toHaveBeenCalledWith('[resolveCatalog] catalog parse failed:', expect.anything()); + + // Group 6's delta has no valid base of its own; it must not land on + // group 5's catalog. + subscriptions[0]!.handlers.onObject?.(catalogObject(6, 1, DELTA)); + await flush(); + expect(getTracksByType(deps.state.presentation.get()!, 'video')).toHaveLength(1); + expect(getTracksByType(deps.state.presentation.get()!, 'audio')).toHaveLength(0); + + // The next well-formed independent object recovers. + subscriptions[0]!.handlers.onObject?.(catalogObject(7, 0, CATALOG_WITH_AUDIO)); + await flush(); + expect(getTracksByType(deps.state.presentation.get()!, 'audio')).toHaveLength(1); + consoleError.mockRestore(); + + reactor.destroy(); + }); + // refreshAuthToken always rejects (see moq-session.ts) — a refreshed // token has no connection left to attach to. The one-shot retry must // give up as a terminal state like any other permanent rejection: