diff --git a/AGENTS.md b/AGENTS.md index b7da426a..c12549da 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,6 +11,7 @@ kixel.live Studio is a native, cross-platform streaming studio that composites s Media, transport, and protocol work belongs in moq-dev/moq, not here: capture, codecs, rendering import and export (moq-video), audio capture, mixing, and filters (moq-audio), the catalog (hang), and the transport (moq-net, moq-tokio). A studio feature that needs a moq change lands that change in moq first, with a moq-side test proving it, then bumps the `moq` gitlink here. +Use moq-net's API without inspecting the negotiated protocol version: a behavior that differs by version is moq-net's to hide, so change its API in moq instead. Never point the submodule at a commit off moq's `main`: CI's `sh/check-moq-main.sh` fails a PR that moves the pin there, and `just upgrade-moq` refuses one. # Rust diff --git a/quest/m0/pin-moq-tip.md b/quest/m0/pin-moq-tip.md index a9c95ad2..46c67291 100644 --- a/quest/m0/pin-moq-tip.md +++ b/quest/m0/pin-moq-tip.md @@ -24,13 +24,19 @@ tip's breaks, as tried on #208: `ladder::Joins` is rewritten on `Demand::poll_refresh`. - Route `Preference` became `Priority`, `Key::to_public` became `public`, and `Demand::wanted` became a bool. -- `Stream::check_failover` (`rs/moq-studio/src/stream.rs`) moves to moq's - public `lite::Version` instance query, and the health grade - (`health.rs`, `engine/air.rs`, `setup.rs`, `fx.rs`) to the republished +- `Stream::check_failover` (`rs/moq-studio/src/stream.rs`) stops inspecting + the protocol version and its one-`--connect-version` rule goes: failover + relies on moq-net to resume across relays. The rule's `--failover` doc + (`rs/moq-studio/src/main.rs`) and its two README lines (under the flags and + Stream settings' **Failover relay**) go with it. The health grade (`health.rs`, + `engine/air.rs`, `setup.rs`, `fx.rs`) moves to the republished `hang::health`. -Matching the version string instead of the instance query is rejected: it -hard-codes `moq-lite-07-wip`. +Decided 2026-11-20 (maintainer, /quest-plan): ✅ the studio never inspects +the negotiated moq-net version; moq-net handles failover transparently, and if +a failover relay then restarts viewers rather than resuming them, moq-net's API +changes in a moq quest of its own (rejected: a public `lite::Version` instance +query; a session capability query; matching the version string). ## Waiting @@ -38,8 +44,3 @@ hard-codes `moq-lite-07-wip`. [Client health in use](https://github.com/moq-dev/moq/blob/main/quest/m3/stats/health-consumers.md) plans ([moq-dev/moq#8956](https://github.com/moq-dev/moq/pull/8956) made it private). Check: `rs/hang/src/lib.rs` on moq's `main` exports `health`. -- moq-dev/moq: a public way to ask whether a `lite::Version` carries - instances ([moq-dev/moq#8931](https://github.com/moq-dev/moq/pull/8931) made - `has_instance` crate-private). Its quest is pending planning in moq's m1, so - it does not gate moq's 0.22.0 cut. Check: moq's `main` has a public query - `Stream::check_failover` can call. diff --git a/quest/m1/portrait-renditions.md b/quest/m1/portrait-renditions.md new file mode 100644 index 00000000..f7b24eae --- /dev/null +++ b/quest/m1/portrait-renditions.md @@ -0,0 +1,41 @@ +# [M] The portrait picture is renditions of the program + +## Goal + +With **Both at once** on, the program broadcast carries its portrait +renditions beside the landscape ones, in one catalog with one sound, and +`/portrait` is no longer published. A phone viewer in portrait gets +the portrait picture from the same link a desktop viewer opens. + +## Plan + +Decided 2026-11-20 (maintainer, /quest-plan): ✅ portrait and landscape are +renditions of one broadcast, which players tell apart by coded size +(rejected: a catalog field naming a sibling portrait broadcast; keeping the +`/portrait` path). ✅ The show's main format ranks first in the +catalog (`VideoConfig::preference`), so a consumer with no viewport, such as a +recorder or a restream, takes it (rejected: always landscape). + +[moq-dev/studio#200](https://github.com/moq-dev/studio/pull/200) built the +portrait picture as its own broadcast, with the same audio scene as the +program. The composition keeps placing landscape only and lists only the +landscape renditions. With the path gone, `moq_scene::PORTRAIT` and the rule +refusing a published scene named `portrait` (`rs/moq-scene/src/format.rs`) go +too. Update [the dual-format check](/quest/m1/dual-format-check.md), +which watches `/portrait` on a phone, in this PR. + +`VideoConfig::preference` is a decode tier today: `@moq/watch` keeps only a +catalog's highest preference before it selects (`preferredRenditions` in +`js/watch/src/video/source.ts`), so a lower-ranked orientation stays reachable +only once the orientation quest below filters by orientation before that +tier. + +## Waiting + +- moq-dev/moq: `@moq/watch` and `moq play` pick a rendition by the viewport's + orientation, as + [Players pick a rendition by the viewport's orientation](https://github.com/moq-dev/moq/blob/main/quest/m1/orientation.md) + plans (being planned in [moq-dev/moq#9247](https://github.com/moq-dev/moq/pull/9247)), + and a `@moq/watch` release carries it, so a desktop viewer never lands on + portrait. Check: that quest's PR has merged on moq's `main`, and npm's + newest `@moq/watch` is past it. diff --git a/quest/m2/compose/controls.md b/quest/m2/compose/controls.md index 5fc0499f..1d271226 100644 --- a/quest/m2/compose/controls.md +++ b/quest/m2/compose/controls.md @@ -40,6 +40,8 @@ priority off the publisher's aggregate subscription. ## Waiting - moq-dev/moq: `moq_video::decode::Options` and `moq_audio::decode::Options` - take the subscription priority, which each consumer fixes today at hang's + take the subscription priority, as + [Decode consumers take a subscription priority](https://github.com/moq-dev/moq/blob/main/quest/m1/decode-priority.md) + plans (being planned in [moq-dev/moq#9247](https://github.com/moq-dev/moq/pull/9247)), which each consumer fixes today at hang's `PRIORITY.video` and `PRIORITY.audio`. Check: both options carry a priority on moq's `main`. diff --git a/quest/m2/compose/layer-delay.md b/quest/m2/compose/layer-delay.md new file mode 100644 index 00000000..d171340d --- /dev/null +++ b/quest/m2/compose/layer-delay.md @@ -0,0 +1,31 @@ +# [S] A lost group stalls a layer no longer than its offset + +## Goal + +A layer's pictures wait in their subscription only as long as that layer +plays behind, its own offset plus the viewer's playout, so a lost group +stalls a guest close to live for that long, not for the fixed `LAYER_DELAY` +(two full playouts) every layer holds today. + +## Plan + +Decided 2026-11-20 (maintainer, /quest-plan): ✅ the studio sets each layer's +`Delay::max` from its own composition offset (rejected: a moq-net subscription +that skips by a reader's deadline apart from `Delay::max`, which is the same +thing once the max matches how far behind the reader plays; leaving it). + +`LAYER_DELAY` in `rs/moq-scene/src/source.rs` bounds every layer's video and +sound (`follow_video` and `follow_audio`), since its pictures wait undecoded +in the subscription. Its doc counts two playouts, the studio's of the layer's +broadcast, which the offset carries, and the viewer's of the program; keep +the viewer's in the per-layer max. A layer's offset changes with each +composition. Sound moves its max in place with +`moq_audio::decode::Consumer::set_max_delay`, as `moq play` does; moq_video's +decode consumer has no such setter, so recommended: resubscribe a layer's +video when its offset moves more than a frame from the one its max was set +for, shrinking as well as growing, rather than on every change. Alternatives: add a `set_max_delay` to moq_video's decode +consumer in moq first, mirroring moq_audio's, or have the layer read pictures +out at once into a queue of its own and keep the subscription's max small; +pick whichever measures better on a lossy link. + +Found by [moq-dev/studio#146](https://github.com/moq-dev/studio/pull/146). diff --git a/quest/m2/compose/msf.md b/quest/m2/compose/msf.md new file mode 100644 index 00000000..80fdeed1 --- /dev/null +++ b/quest/m2/compose/msf.md @@ -0,0 +1,30 @@ +# [S] The composition broadcast carries MSF beside hang + +## Goal + +The composition broadcast publishes its catalog through moq-mux's catalog +producer, so it carries MSF beside hang, each update still stamped with the +frame it applies at. + +## Plan + +[moq-dev/studio#146](https://github.com/moq-dev/studio/pull/146) publishes the +composition through a hang-only `moq_json::snapshot::Producer`, calling +`Timed::new` itself, because moq-mux's producer stamps each emit on its own +clock. Once the wait clears, advance the gitlink with `just upgrade-moq` in +this PR unless a bump already has, and move the composition onto +`moq_mux::catalog::Producer` with the caller's timestamp. + +## Waiting + +- moq-dev/moq: moq-mux's catalog producer publishes at the caller's + timestamp, as + [The catalog producer publishes at the caller's timestamp](https://github.com/moq-dev/moq/blob/main/quest/m1/catalog-timestamp.md) + plans (being planned in [moq-dev/moq#9247](https://github.com/moq-dev/moq/pull/9247), + so the link resolves once it merges). Check: that quest's PR has merged on + moq's `main`, deleting its file. A quest file that moved, or went away + without its work landing, does not count. + +## Required + +- [The studio catches up to moq's main](/quest/m0/pin-moq-tip.md) - absorbs the tip's other breaks, so this bump moves only by the producer diff --git a/quest/m2/pin-mp4-chapters.md b/quest/m2/pin-mp4-chapters.md index 9bede7b1..00458b00 100644 --- a/quest/m2/pin-mp4-chapters.md +++ b/quest/m2/pin-mp4-chapters.md @@ -23,9 +23,10 @@ fixing whatever the new API breaks here. ## Waiting -- moq-dev/moq: moq-mux's regular MP4 finish takes chapters. The change has - no quest in moq's tree yet; it was found by - [moq-dev/studio#209](https://github.com/moq-dev/studio/pull/209) and is - listed in its Follow-ups for `/quest-plan` there. Check: +- moq-dev/moq: moq-mux's regular MP4 finish takes chapters, as + [A finished MP4 carries chapters](https://github.com/moq-dev/moq/blob/main/quest/m1/mp4-chapters.md) + plans (being planned in [moq-dev/moq#9247](https://github.com/moq-dev/moq/pull/9247), + so the link resolves once it merges); it writes both `chpl` and a QuickTime + chapter track. Check: `rs/moq-mux/src/container/mp4.rs` on moq's `main` writes chapters into the finished `moov`.