Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
21 changes: 11 additions & 10 deletions quest/m0/pin-moq-tip.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,22 +24,23 @@ 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

- moq-dev/moq: `hang::health` is public again, as
[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.
41 changes: 41 additions & 0 deletions quest/m1/portrait-renditions.md
Original file line number Diff line number Diff line change
@@ -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
`<broadcast>/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
`<broadcast>/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 `<broadcast>/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.
4 changes: 3 additions & 1 deletion quest/m2/compose/controls.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
31 changes: 31 additions & 0 deletions quest/m2/compose/layer-delay.md
Original file line number Diff line number Diff line change
@@ -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).
30 changes: 30 additions & 0 deletions quest/m2/compose/msf.md
Original file line number Diff line number Diff line change
@@ -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
9 changes: 5 additions & 4 deletions quest/m2/pin-mp4-chapters.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.