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
10 changes: 7 additions & 3 deletions quest/m1/vr-demo-try.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@

## Goal

The maintainer has played `demo/vr` in a WebXR headset, and once it plays
well there, it is hosted beside the web demo at moq.dev with a looping VR180
Someone has played `demo/vr` in a WebXR headset, and once it plays well
there, it is hosted beside the web demo at moq.dev with a looping VR180
broadcast to watch.

## Plan
Expand All @@ -22,6 +22,10 @@ headset's localhost, and make the relay reachable too: `localhost:4443` on the
headset is the headset itself, so forward that port as well or point the page
at the relay with `?url=`.

Decided 2026-11-15 (maintainer, /quest-complete): ✅ ask the contributor who
started the demo in [moq-dev/moq#6373](https://github.com/moq-dev/moq/pull/6373)
to try it in a headset, rather than the maintainer.

## Waiting

- Maintainer: try it in a headset (an agent has none) and say whether it plays well enough to host. Check by this quest's Plan recording the result.
- nuts-rice: try `demo/vr` in a WebXR headset (an agent has none) and say whether the per-eye render, recentring, and ambisonic audio play well enough to host, as asked in [moq-dev/moq#8781](https://github.com/moq-dev/moq/pull/8781#issuecomment-6901206041) on 2026-11-15. Check by reading that thread for a reply; this quest's Plan records the headset result.
31 changes: 31 additions & 0 deletions quest/m2/websocket-accept-driver.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# [S] moq-tokio's WebSocket accept hands back the qmux driver

## Goal

`moq_tokio::websocket::accept` returns the qmux driver to its caller instead
of spawning it on the tokio runtime, so a caller such as an io_uring worker
runs the driver on its own task set. Every existing caller (moq-relay's
`websocket.rs` and moq-tokio's own server tests) spawns the driver itself and
behaves as today.

## Plan

Decided 2026-11-15 (maintainer, /quest-complete): ✅ reshape
`websocket::accept` itself to return the session and its driver, as its own
m2 quest that [relay stream listeners](/quest/m9/stream-transports/relay.md)
requires (rejected: landing it with the rust2 migration; an additive sibling
beside `accept`).

Today `accept` builds the qmux session, hands it to `spawn_qmux`
(`rs/moq-tokio/src/lib.rs`), which spawns the `Driver` on the current
runtime, and then reads SETUP into a `server::Request`
(`rs/moq-tokio/src/websocket.rs`). The SETUP read needs the driver running,
so the driver cannot come back only at the end: return it once QMux is
established, beside whatever finishes the SETUP read and admission, and keep
the accept deadline covering both.

This breaks moq-tokio's published API, so the PR's title takes `!` and its
Impact section carries the migration note: a caller that used the old
`accept` spawns the returned driver itself.

Public API: breaking, `moq_tokio::websocket::accept`'s return type. Wire: none.
21 changes: 12 additions & 9 deletions quest/m3/capture-linux.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,9 @@

## Goal

Window capture and system audio work on a Wayland desktop, and app capture has
a stated answer rather than a runtime error.
Window capture and system audio work on a Wayland desktop. App capture stays
macOS-only (decided below), which `Source::App` already reports as
`Unsupported` here.

## Plan

Expand Down Expand Up @@ -31,9 +32,15 @@ unimplemented, because xdg-desktop-portal owns source selection:
- **System audio** needs a PipeWire monitor node.
`moq_audio::capture::Source::System` exists but is macOS-only and returns
`Unsupported` elsewhere. This is independent of the screencast portal.
- **Applications** have no portal concept behind them, so decide explicitly
whether Linux offers app capture rather than leaving a variant that errors at
runtime.
- **Applications** have no portal concept behind them. Decided 2026-11-15
(maintainer, /quest-complete, with
[Windows capture parity](/quest/m3/capture-windows.md)): ✅ (A) Linux offers
window capture only: `Source::App` stays macOS-only and fails with its
reason here, and a listing uses apps only to group windows
(rejected: (B) build app capture by composing an app's windows). No
consumer asks for it, and it matches the
[capture listing](/quest/m3/capture-list.md)'s rule that a listed app must
not hand out a source that fails at open.
- **Per-app audio** (decided 2026-10-26, maintainer: yes) captures one
application's output from its PipeWire stream node, so a creator can stream
a game without their music. Apps are listed from the nodes present, so only
Expand All @@ -43,10 +50,6 @@ unimplemented, because xdg-desktop-portal owns source selection:
Windows process tree and the macOS application. The Windows and macOS halves
share the same `moq_audio::capture` source.

## Waiting

- Maintainer: whether app capture exists off macOS, here and in [Windows capture parity](/quest/m3/capture-windows.md). (A) Linux and Windows offer window capture only: `Source::App` stays macOS-only and fails with its reason elsewhere, and a listing off macOS uses apps only to group windows. (B) Build app capture by composing an app's windows. I recommend A, since no consumer asks for B and it matches the capture listing's rule that a listed app must not hand out a source that fails at open.

## Related

- [Windows capture parity](/quest/m3/capture-windows.md) - the same gaps,
Expand Down
22 changes: 10 additions & 12 deletions quest/m3/capture-windows.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@

## Goal

App capture and system audio work on Windows. Display and window capture,
System audio works on Windows. App capture stays macOS-only (decided below),
which `Source::App` already reports as `Unsupported` here. Display and window capture,
including the cursor, already run on the Windows.Graphics.Capture backend
(`rs/moq-video/src/capture/wgc/native.rs`), which
[its own quest](/quest/m3/capture-wgc.md) verifies on real hardware.
Expand All @@ -11,9 +12,14 @@ including the cursor, already run on the Windows.Graphics.Capture backend

- **Applications** (every window of a process, including ones that open later)
are still `Unsupported` outside macOS, where `SCShareableContent` gives it
almost free. Windows has no direct equivalent, so this needs per-window
composition or an explicit decision that Windows offers window capture only.
Decide that rather than leaving a variant that errors at runtime.
almost free. Decided 2026-11-15 (maintainer, /quest-complete, with
[Linux capture parity](/quest/m3/capture-linux.md)): ✅ (A) Windows offers
window capture only: `Source::App` stays macOS-only and fails with its
reason here, and a listing uses apps only to group windows
(rejected: (B) build app capture by composing a process tree's windows). No
consumer asks for it, and it matches the
[capture listing](/quest/m3/capture-list.md)'s rule that a listed app must
not hand out a source that fails at open.
- **System audio** needs WASAPI loopback. `moq_audio::capture::Source::System`
exists but is macOS-only and returns `Unsupported` elsewhere. Unlike macOS
this does not go through the screen-capture API, so it is an independent path
Expand All @@ -26,14 +32,6 @@ including the cursor, already run on the Windows.Graphics.Capture backend
setup and refuse per-app audio with the reason where activation fails,
rather than gating on a build number.

WGC does not answer app capture. It captures one monitor or one window per
item and has no per-process source, so the per-window-composition or
window-only decision still stands now that the backend has landed.

## Waiting

- Maintainer: whether app capture exists off macOS, here and in [Linux capture parity](/quest/m3/capture-linux.md). (A) Windows and Linux offer window capture only: `Source::App` stays macOS-only and fails with its reason elsewhere, and a listing off macOS uses apps only to group windows. (B) Build app capture by composing a process tree's windows. I recommend A, since no consumer asks for B and it matches the capture listing's rule that a listed app must not hand out a source that fails at open.

## Related

- [Windows.Graphics.Capture](/quest/m3/capture-wgc.md) - display and window capture with the cursor, which this quest no longer owns
Expand Down
11 changes: 8 additions & 3 deletions quest/m3/cli-packaging.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,9 +68,14 @@ and `moq-audio/capture` explicitly, and `full` enables `capture`.

Renamed 2026-11-07 (maintainer, /quest-plan from the API sweep of open PRs and remaining quests): the moq-cli feature that enables everything is named `full`, not `release`, so this quest and its followers say `full`.

## Waiting

- Maintainer: what ships while cpal has no release that loads libasound at runtime (RustAudio/cpal#1421 is open; the last release is 0.18.2). (A) Wait: this quest stays blocked on [ALSA without a load-time link](/quest/m3/capture-alsa-link.md) until the cpal release ships. (B) Split: ship `full` now on macOS and Windows, which link no system audio library, and leave only Linux waiting on the cpal release. (C) Linux release binaries take libasound as a load-time requirement. (D) Fork cpal, alsa, and alsa-sys. I recommend B.
Decided 2026-11-15 (maintainer, /quest-complete): ✅ (A) wait for the cpal
release that loads libasound at runtime (RustAudio/cpal#1421 is open; the last
release is 0.18.2), so this stays blocked on
[ALSA without a load-time link](/quest/m3/capture-alsa-link.md), and ✅ (D)
fork cpal, alsa, and alsa-sys only once the wait becomes a blocker (rejected:
(B) ship `full` on macOS and Windows first and leave Linux waiting; (C) Linux
release binaries take libasound as a load-time requirement). In the
maintainer's words: "wait, then fork cpal when it's a blocker".

## Required

Expand Down
6 changes: 4 additions & 2 deletions quest/m3/cpal-alsa-runtime.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,8 +64,10 @@ fall-through goal, so prefer it.

Fallback if upstream declines: fork `cpal`, `alsa`, and `alsa-sys` as
published crates, as moq-v4l was. It is the only in-tree route that reaches
`cargo install moq-cli`, at the cost of carrying three forks for one library;
the maintainer decides if it comes to that.
`cargo install moq-cli`, at the cost of carrying three forks for one library.
Decided 2026-11-15 (maintainer, /quest-complete, on
[cli-packaging](/quest/m3/cli-packaging.md)): keep waiting, and take the
fork only once the wait becomes a blocker.

Rejected in-tree routes, for whoever retries this: a `[patch.crates-io]` fork
of `alsa-sys` does not reach `cargo install moq-cli` or crates.io consumers
Expand Down
5 changes: 5 additions & 0 deletions quest/m3/ffi-exporter.md
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,11 @@ dependency, so crates.io moq-ffi still builds (see the
with an error, which the fork still leaks (moq-ffi's errors hold no
handles today).

Deferred 2026-11-15 (maintainer, /quest-complete): the `Waiting` decision on
the generated binding renames stays open, kept out of that run's m0 to m2
scope, since the binding API changes anyway in the rust2 migration expected
around 2026-12-15.

Public API: moq-ffi's dependency names change, generated C type names become
CamelCase, and the generated record `MoqAudioEncoderFinished` becomes
`MoqAudioEncoderFinish` in every language; wrapper APIs do not change except
Expand Down
26 changes: 11 additions & 15 deletions quest/m3/gpu-ci.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,28 +47,24 @@ skipping inside the Nix shell.
NVENC and CUDA external-image import (the verification #4975 deferred here).
- Merge queue: a `merge_group` job in `.github/workflows/check.yml` (or
`video.yml`) runs `nix develop --command just rs nvidia`, a recipe and not
a script path, like every other workflow step, on a self-hosted runner VM
a script path, like every other workflow step, on a self-hosted runner
labeled for the NVIDIA host. Scope it like the other queue jobs: run when
the queue's diff touches moq-video, moq-nvenc, or what they depend on.
Read-only `permissions`, never `pull_request`.
- Decided 2026-10-20 (maintainer): GPU tests gate in the merge queue on the
NVIDIA card, because they gate correctness, not trends. The runner is a
persistent VM from the `github-runner-vm` module (#6040,
`nix/runner/README.md`). That module has no GPU passthrough today: add
VFIO passthrough of the NVIDIA card to the guest, with the driver in the
guest, and keep the runner registered only to this repository with
approval required for every external contributor's workflow, as the
README requires.
- Open since 2026-10-25: the [CI epic](/quest/m0/ci/README.md) dropped the
VM for the CI host in favor of kernel sandboxing, which conflicts with the
VFIO passthrough above. See `## Waiting`.
NVIDIA card, because they gate correctness, not trends. Keep the runner
registered only to this repository with approval required for every
external contributor's workflow.
- Decided 2026-11-15 (maintainer, /quest-complete): ✅ (a) a sandboxed runner
container on the CI host, like `nixos`'s existing runner containers, with
the NVIDIA device nodes and the host driver's libraries bound in, as
[GPU runners](/quest/m9/video-quality/gpu-runners.md) plans for the quality
job (rejected: (b) a VFIO-passthrough VM from `github-runner-vm`, which
conflicts with the [CI epic](/quest/m0/ci/README.md)'s choice of kernel
sandboxing over a VM).

Public API: none. Wire: none.

## Waiting

- Maintainer: pick the GPU runner's shape, since the 2026-10-20 VM decision conflicts with the CI epic's later no-VM decision. Options: (a) a sandboxed runner container on the CI host with the NVIDIA device nodes and the host driver's libraries bound in, as [GPU runners](/quest/m9/video-quality/gpu-runners.md) already plans for the quality job; (b) a VFIO-passthrough VM from `github-runner-vm`. Recommended: (a), then drop the VFIO text above.

## Related

- [Video hardware validation](/quest/m5/video-hardware.md) - hardware paths nothing runs yet
Expand Down
6 changes: 1 addition & 5 deletions quest/m3/lite-tail-drop-count.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,7 @@ Checked 2026-11-12 at a86433043: the counting half already exists. `Tail::accoun
- Count per version. lite-01..04 have no drop message, so they keep today's behaviour.
- On lite-05/06, account for holes left by lost datagrams. Lite-07 stream tracks carry no datagrams, which have their own track kind.
- Account for a stream reset before its header, so no gap is left only to the grace. Check whether the publisher already reports such a group in a SUBSCRIBE_DROP; if it needs a new signal, that is a lite-07-wip draft change, and the Wire line below changes with it.
- Guard against a peer that never accounts for a group as the `Waiting` decision settles. Don't add a new grace.
- Guard against a peer that never accounts for a group. Decided 2026-11-15 (maintainer, /quest-complete): ✅ (c) wait out the subscription's max delay where one is set, and ✅ (a) end the tail with an error on lite-07 when no max delay is set, so the 1 s constant goes away without a buggy peer hanging the tail forever (rejected: (a) alone, an error even where a max delay is set; (b) keep waiting until the session closes). ✅ A lite-05/06 tail with no max delay ends with the same error (rejected: keeping the 1 s constant there). Don't add a new grace.
- The IETF tail keeps its grace until the moq-transport gap-signal extension (planned in [moq-dev/moq#7425](https://github.com/moq-dev/moq/pull/7425)) lands, since moq-transport can't signal gaps.

Public API: none. Wire: none.

## Waiting

- Maintainer: decide what a lite-05+ tail does when the peer never accounts for a group. Options: (a) end the tail with an error; (b) keep waiting until the session closes; (c) wait out the subscription's max delay where one is set. Recommended: (c), and (a) on lite-07 when no max delay is set, so the 1 s constant goes away without a buggy peer hanging the tail forever.
15 changes: 8 additions & 7 deletions quest/m3/webrtc-dial-policy.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,16 +45,17 @@ Today:
Guidance:

- One policy type serves both crates, so a host states its rule once for
every destination kind. Propose its shape and its home; a value the host
builds is preferred over a callback, per the root `AGENTS.md`.
every destination kind. Decided 2026-11-15 (maintainer, /quest-complete):
✅ (a) a plain value type with no I/O in moq-net, which moq-webrtc and
moq-rtmp both already depend on, each crate checking it at connect time.
A host passes it through moq-webrtc's `#[non_exhaustive]` `client::Config`
and moq-rtmp's `#[non_exhaustive]` `Connect`, so neither needs a second
break (rejected: (b) moq-tokio, beside its own dial dispatch, though
moq-rtmp uses moq-tokio only as a dev-dependency; (c) a crate of its own).
A value the host builds, not a callback, per the root `AGENTS.md`.
- A refusal is terminal for that URL, and its error is distinct from a
failed connection, so a caller that redials on failure does not retry it.
- Check at connect time on the resolved address. Checking the URL and then
letting the HTTP client resolve again is the DNS rebinding hole.
- moq-srt's client takes a `SocketAddr` like moq-rtmp does today. It is out
of scope until it dials a URL.

## Waiting

- Maintainer: where the one dial-policy type lives. (a) A plain value type with no I/O in moq-net, which moq-webrtc and moq-rtmp both already depend on, each crate checking it at connect time; (b) moq-tokio, beside its own dial dispatch, though moq-rtmp uses moq-tokio only as a dev-dependency today; (c) a crate of its own. Recommended: (a), with the moq-webrtc half added through its `#[non_exhaustive]` `client::Config`, and moq-rtmp's through its `#[non_exhaustive]` `Connect`, so neither needs a second break.

43 changes: 20 additions & 23 deletions quest/m4/announce-interest-memory.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,14 @@
# [M] Announce interest streams share one route table
# [S] Cap the legacy versions' announce interest streams

## Goal

An announce-interest stream (lite ANNOUNCE_PLEASE or moq-transport
SUBSCRIBE_NAMESPACE) costs memory and CPU proportional to what it has in
flight, not to every route under its prefix. A subscriber opening thousands
of root-prefix streams on a relay holding N routes no longer makes it hold
thousands of times N entries, and a benchmark swept over streams and routes
shows per-stream cost flat in N.
A peer can open only as many announce-interest streams (lite-05/06
ANNOUNCE_PLEASE or moq-transport SUBSCRIBE_NAMESPACE) as a new
`session::Limits` field allows, so a subscriber opening thousands of
root-prefix streams on a relay holding N routes can no longer make it hold
thousands of times N entries. A stream past the cap is refused, and a test
shows the refusal on each of those versions while a stream under the cap is
served as today.

## Plan

Expand All @@ -30,22 +31,18 @@ Once [one route stream](/quest/m2/cluster-routes/route-stream.md)
lands, lite-07 holds one interest stream per side, so what remains exposed is
lite-05/06 and moq-transport.

Bound it by design, not with a cap: cursors walk a shared, refcounted table
snapshot lazily, materializing only what is in flight and gated on stream
write credit; lite-05/06 encodes its initial set incrementally under
`poll_flush`, as lite-07 does. The IETF SUBSCRIBE_NAMESPACE handler follows
the same pattern and gets the same fix.

Public API: none. Wire: none.

## Waiting

- Maintainer: how to bound the legacy versions' interest streams: the shared
snapshot redesign above, a `session::Limits` cap on outgoing interest
streams (which the Plan rules out today), or deleting this once lite-07 is
the oldest version served. Recommended: the cap for lite-05/06 and
moq-transport now, then delete, since redesigning `model/origin.rs` for
versions being retired costs more than it saves.
Decided 2026-11-15 (maintainer, /quest-complete): ✅ a `session::Limits` cap
on interest streams for lite-05/06 and moq-transport now, counted like
`announces` with a `Slots` acquire where each stream starts, and deleted with
this concern once lite-07 is the oldest version served (rejected: a shared,
refcounted table snapshot that cursors walk lazily, since redesigning
`model/origin.rs` for versions being retired costs more than it saves; and
deleting this later with no cap meanwhile). `Limits` is `#[non_exhaustive]`,
so the field is additive. Report its peak in the stats sessions rows, as
`announces` does, and mirror the field in `js/net` if it serves these
streams.

Public API: additive, a new `session::Limits` field. Wire: none.

## Related

Expand Down
Loading