diff --git a/quest/m1/README.md b/quest/m1/README.md index 589159cfc9c..a39beb22077 100644 --- a/quest/m1/README.md +++ b/quest/m1/README.md @@ -122,6 +122,7 @@ folded into Dropped sources. - [mp4-atom dOps mapping](/quest/m1/mp4-atom-dops-mapping.md) - a released mp4-atom reads and writes any `dOps` channel mapping family and table - [CMAF surround Opus](/quest/m1/cmaf-opus-surround.md) - fMP4 import and export carry an Opus channel mapping table - [GPU CI](/quest/m1/gpu-ci.md) - NVIDIA tests run nightly on a self-hosted GPU runner, and `just rs nvidia` runs them locally instead of skipping +- [A failed rendition fails alone](/quest/m1/rendition-failure.md) - when one `@moq/publish` rendition's encoder fails, only that rendition ends, loudly, while the others and the broadcast keep running under the same epoch - [Rendition preference](/quest/m1/rendition-preference.md) - automatic selection by ``, `Video::ranked`, and WHEP keeps the highest `preference` that decodes, so a compatibility transcode is only picked when nothing preferred decodes - [Simulcast rung disable](/quest/m1/simulcast-rung-disable.md) - JS, Rust/FFI, and OBS publishers stop encoding the top renditions their grant cannot fund, advertise `enabled: false`, and re-enable with hysteresis - [Discover media headroom](/quest/m1/quic-probe.md) - test useful-media pacing before adding redundant probe traffic diff --git a/quest/m1/largest.md b/quest/m1/largest.md index 3fda9f97ae3..9605b2f9ee5 100644 --- a/quest/m1/largest.md +++ b/quest/m1/largest.md @@ -7,7 +7,7 @@ arrives and follows it live. `largest()` replaces `latest()` on the track producer, consumer and subscriber in Rust and `@moq/net`, returning a `Location` (group and frame). It is seeded by the publisher's reported largest (moq-transport SUBSCRIBE_OK, lite-07 SUBSCRIBE_START) and advances as -groups and frames arrive or a newer value is reported. It never lives on +frames arrive or a newer value is reported. It never lives on `Info`, which is per-track and immutable. ## Plan @@ -20,6 +20,9 @@ Decided with the maintainer (2026-10-13), after moq-dev/moq#5369 proposed current location at once if known; each later call waits for a newer one, skipping values in between; it ends (`None`/`undefined`) when the track ends. +- **An empty group is not reported.** A group that has started but has no + frames yet leaves `largest()` at the previous real frame; a `Location` + names a frame, and the empty group has none yet. - **One name everywhere.** Rename on the producer, consumer and subscriber, and update every caller (moq-json, moq-flate, moq-mux, moq-relay, moq-hls, moq-c, and the rest) in the same PR. JS's buffered-only `largest()` takes @@ -34,5 +37,6 @@ Decided with the maintainer (2026-10-13), after moq-dev/moq#5369 proposed locally: a reported largest is a hint about the edge, not a cached group. - Bindings follow the cross-package table if any expose `latest()`. - Cover on mock time in both languages: known before the first group from - SUBSCRIBE_OK and SUBSCRIBE_START, advancing per frame, coalescing, and + SUBSCRIBE_OK and SUBSCRIBE_START, advancing per frame, holding through a + started group with no frames, coalescing, and ending with the track. diff --git a/quest/m1/rendition-failure.md b/quest/m1/rendition-failure.md new file mode 100644 index 00000000000..984ba341cc0 --- /dev/null +++ b/quest/m1/rendition-failure.md @@ -0,0 +1,71 @@ +# [M] A failed rendition fails alone + +## Goal + +When one rendition's encoder fails mid-stream in `@moq/publish`, only that +rendition goes down, and loudly: its track ends with the encoder's real +error, the catalog marks it disabled, and the application can see which +rendition failed and why. The other renditions, the catalog, and the network +broadcast keep running under the same epoch. A failure never starts a retry +loop. + +## Plan + +Raised as a declined Codex P1 on moq-dev/moq#5068, which made each track live +as long as its network broadcast. + +Current behaviour: + +- A video encoder error aborts its track (`producer.close(err)` in + `js/publish/src/video/encoder.ts`) and nothing reacts right away. The catalog + keeps advertising the rendition as enabled, so viewers keep selecting a + track that has ended. +- A fatal audio encoder error closes the current track and every later one + handed to that rendition, for the encoder's whole life. Its catalog entry + stays too. +- `Broadcast` (`js/publish/src/broadcast.ts`) notices the closed track only + when the rendition set next changes, for any rendition. It then bumps + `#restart`, which publishes a new network broadcast under a new epoch, so + every healthy rendition and the catalog restart with it. With a dead audio + encoder this repeats on every later rendition change, because the new + broadcast's audio track closes at once. + +Decided with the maintainer (2026-10-13): + +- **Scope: JS `@moq/publish` only**, where the library owns the rendition + tracks. Native publishers' apps own each track directly. +- **Fail locally and at once.** End the track with the encoder's error, + advertise the rendition as `enabled: false` with its last config (which + `@moq/watch` already skips; WHEP and HLS egress still serve a disabled + rendition, a consumer gap outside this quest), and expose the failure to + the application, for example as an error signal on the encoder or the + `Rendition`. Failing never republishes the network broadcast, so remove or + narrow the `#restart` path that does today. +- **Only a changed input or an explicit application call re-arms a failed + rendition.** No automatic or timed retry, so a deterministic failure stays + down instead of looping. +- **Do not resume numbering unless it's a continuation (same encoder).** A + recovered rendition publishes under a new track name or a new broadcast + epoch; when unsure, default to one of those, because that's safer. This + keeps #5068's decision 7 for any replacement encoder. A new track name + leaves the siblings running but needs + [catalog rendition IDs](/quest/m1/catalog-track-id.md) to keep the catalog + ID stable; a new epoch restarts the siblings, so reserve it for recovery, + never for the failure itself. +- **Milestone: m1**, as reliability of a shipped feature. + +Also: + +- Watch for the interaction with [simulcast rung disable](/quest/m1/simulcast-rung-disable.md), + which also drives `enabled`: a recovering grant must not re-enable a + failed rendition. +- Tests on mock time with a fake encoder: a failing video rendition leaves a + sibling rendition and the catalog writing under the same epoch; the + failed rendition is advertised `enabled: false`; a dead audio encoder + does not republish the broadcast when another rendition registers; a + re-armed rendition never reuses a closed track's sequences. + +## Related + +- [Simulcast rung disable](/quest/m1/simulcast-rung-disable.md) - the other driver of a rendition's `enabled` state +- [Catalog rendition IDs](/quest/m1/catalog-track-id.md) - lets a rendition move to a new track name without changing its catalog ID