Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
ab0fec5
chore(quest): claim quest/m1/auto-layout.md
kixelated Nov 17, 2026
da270de
feat(scene): slots, roles, and a reflow that glides
kixelated Nov 17, 2026
d52f1be
feat(studio): slots on BUILD, roles, and guests that appear on their own
kixelated Nov 17, 2026
838767d
chore(quest): finish auto-layout, leaving its human check
kixelated Nov 17, 2026
d857dd3
chore: the slot views, for the PR body (deleted next)
kixelated Nov 17, 2026
b5829c5
chore: drop the slot views, hosted for the PR body
kixelated Nov 17, 2026
750ca0f
test(studio): a guest joining through the room appears in the next tile
kixelated Nov 17, 2026
5e785d3
fix: slots and roles through removal, copy, duplication, crop, and In…
kixelated Nov 17, 2026
4ed7c83
fix: a slot crops from what it shows, and a page takes input mid-glide
kixelated Nov 17, 2026
f3a5e12
fix(studio): a guest who left frees their place among the four
kixelated Nov 17, 2026
88056f8
fix: an appearance once per link, free layers outside the glide
kixelated Nov 17, 2026
f55a8b0
fix(studio): keep who appeared on their own beside the room key
kixelated Nov 17, 2026
5aba1c4
fix(studio): save the appearance latch before the guest goes on
kixelated Nov 17, 2026
93d7ec1
fix(studio): a returning guest makes no fifth tile
kixelated Nov 17, 2026
05d6b1c
fix(studio): take only a departed guest's camera tile, and only their…
kixelated Nov 17, 2026
c572ddf
docs: the reflow key's comment, and the latch kept across restarts
kixelated Nov 17, 2026
7e9ccee
fix(studio): mark the tiles the studio places, and take only those
kixelated Nov 17, 2026
6569079
fix(studio): a guest taking a tile gets one of their own
kixelated Nov 17, 2026
15effe1
Merge origin/main: drop and paste anything on the picture (#193)
kixelated Nov 17, 2026
b2fe89d
fix(studio): one broadcast under two names, a stuck latch, an unfille…
kixelated Nov 17, 2026
ac6d4a2
fix(studio): an unfilled role offers no copy of its own
kixelated Nov 17, 2026
ffd00c6
Merge origin/main: a multiview window (#195)
kixelated Nov 17, 2026
83a856e
fix: scenes swapping names keep their slots, and an appearance lets g…
kixelated Nov 17, 2026
f7465f2
fix(studio): a row dropped after a guest appears moves nothing
kixelated Nov 17, 2026
a221231
Merge origin/main: bump quest to v0.17.2 (#196, #197)
kixelated Nov 17, 2026
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
106 changes: 92 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -282,6 +282,14 @@ for the same menu, or the picture elsewhere to add a layer, paste, or set
**Snap**, **Grid**, and the grid's spacing. Escape ends cropping, then the
selection.

A layer in a [slot](#slots-and-roles) is outlined on the picture, dashed, with
a chip naming its role, or **Guest** or its slot, and a tag naming the source
it shows. It has no handles, nor Fit and Fill, since its slot places it: drag
it onto another slot, or drag a row of Layers onto a slot, to swap the two
layers' places. A row in a slot says **Main slot** or **Tile** before what it
shows. The row's menu puts a layer in the main slot or a tile, or sets it
free where it is drawn.

**Interact** passes the mouse and keyboard to the selected layer's web page
alone, even where another layer is over it, while the picture says so; Escape
or **Stop** ends it.
Expand All @@ -291,16 +299,17 @@ is named for it, with these sections:

| Section | Use it to |
| --- | --- |
| Place | Type or drag its position and size, and its crop, in percent off each edge, fit or fill it, and lock it. |
| Place | Pick its [slot](#slots-and-roles), or none; type or drag its position and size, and its crop, in percent off each edge, fit or fill it, and lock it. A layer in a slot has no position or size of its own to type. |
| Shape | Pick its outline, square, rounded, circle, or arch, give it a border inside that outline and the border's color, and give it a soft shadow, which follows the outline and is the layer's first drop shadow filter. |
| Look | Remove its source's background, which every layer showing the source loses (make it independent to cut out here alone); grade its color through a LUT source; add, order, set, and remove its filters, copy them, or paste copied filters after its own; and set its blend mode. |
| Shown in | See how many places show its source, **Linked in 3 scenes**, and **Make independent**, which points this layer at a copy of the source of its own, keeping its look, so editing that look no longer edits the others. A copy says what it copies. |
| Source | See what the source is and whether it and its own track are live. A camera or broadcast without a new picture, or a microphone or system audio without new sound, for a second reads as stalled; a broadcast says how far behind it plays, and a web page whether it is copied on the GPU or, as a fallback, uploaded from memory, saying why. A media file reads as ended once it plays to its end without looping: **Play** plays it from its start, **Stop** stops it at once, blank and silent, until played again, and **Reload** reads the file again; **Reload** restarts a web page, and opens a picked display or window again, as after the picker was cancelled or sharing stopped. Publish it independently (see [Published independently](#published-independently)), and set its own crop and filters, before the layer's, on every layer showing it. |
| Source | See what the source is and whether it and its own track are live. A camera or broadcast without a new picture, or a microphone or system audio without new sound, for a second reads as stalled; a broadcast says how far behind it plays, and a web page whether it is copied on the GPU or, as a fallback, uploaded from memory, saying why. A media file reads as ended once it plays to its end without looping: **Play** plays it from its start, **Stop** stops it at once, blank and silent, until played again, and **Reload** reads the file again; **Reload** restarts a web page, and opens a picked display or window again, as after the picker was cancelled or sharing stopped. Publish it independently (see [Published independently](#published-independently)), and set its own crop and filters, before the layer's, on every layer showing it. For a role, pick the source filling it. |

Its **Animate** tab holds the layer's keyframes (see [Keyframes](#keyframes)).
With no layer selected, the inspector shows the edited scene: rename it,
see its size, mark it **Safe**, switch on **Publish** and pick the audio scene
it carries (see [Published scenes](#published-scenes)), and pick the show's
it carries (see [Published scenes](#published-scenes)), arrange its slots and
fill their roles (see [Slots and roles](#slots-and-roles)), and pick the show's
transition and how long it takes, or for a stinger its media source and cut
point (see [Transitions](#transitions)). A scene on program, or still leaving
it in a transition, cannot be removed, even by an undo, until program cuts
Expand Down Expand Up @@ -406,8 +415,8 @@ this run says so, and is not editable there. A change applies the next time
you go live. A new relay or token is followed for broadcast sources and
guests at once off air, and once the stream ends on air. The recordings
folder (Settings, Recording) and the guests' room (Settings, Guests) are kept
in the same file, as `recordings`, `room`, `room_key`, `join_page`, and
`guest_expiry`.
in the same file, as `recordings`, `room`, `room_key`, `join_page`,
`guest_expiry`, and `guests_appear`.

### Settings

Expand All @@ -421,7 +430,7 @@ setting costs. Escape or a click outside closes it.
| Stream | Set the relay, its token, the failover relay, the broadcast's name, and on demand (see [Stream settings](#stream-settings)). |
| Recording | Change or open the recordings folder, and pick the picture and the audio scene a recording holds, and whether each source records a file of its own too (see [Recording](#recording)). |
| Hotkeys | Bind keys, by what they are for: going live, ending the stream, the panic key, and recording; Studio mode, TAKE, and AUTO; each scene; and replay and clips (see [Hotkeys](#hotkeys)). |
| Guests | Set the room guests join, its key, the join page, and how long a link lasts (see [Guests](#guests)). |
| Guests | Set the room guests join, its key, the join page, how long a link lasts, and whether guests appear on their own (see [Guests](#guests)). |
| Advanced | Publish scenes as broadcasts of their own and sources independently, turn the virtual camera of the program or of each published scene on, pick how the window's [effects](#effects) move, and open the [scene graph](#scene-graph). |

On air, a new canvas size or frame rate, or a published scene's new size,
Expand Down Expand Up @@ -649,6 +658,57 @@ and speeding up through the rest; a picture stall leaves the sound playing,
with the canvas showing the last picture meanwhile. Without audio, the picture plays 100 ms behind. The inspector's Source section shows how
far behind each broadcast plays.

### Slots and roles

A scene can lay out some of its layers by **slots** rather than by hand: one
**main** slot, the largest, and **tiles** beside it, in the order of their
layers. The scene's **arrangement** places them, each slot 16:9,
inside a margin, each picture covering its slot, cropped evenly to fit:

| Arrangement | Places |
| --- | --- |
| Side column | The main slot on the left, the tiles stacked in a column on the right. |
| Bottom row | The main slot on top, the tiles in a row under it. |
| Grid | Every slot the same size, in as square a grid as fits them. |
| Picture in picture | The main slot fills the canvas, the tiles small, stacked up from its bottom-right corner. |

A layer in a slot closes up when it has nothing to show: when it is hidden,
when its source is offline or failed, or when it shows a role nothing fills.
The others grow into its room, and they glide there over 0.4 s on program, as
a Move transition does, so a guest joining or leaving moves the rest rather
than cutting them. Layers set free, by their own `rect`, stay where they are,
so a scene can mix both: a backdrop behind the slots and a logo over them.

A **role** is a source that names another, once for the whole show:
`Main`, the main picture, or `Camera`, the host's camera. A layer showing a
role shows its source, through that source's crop and filters, and filling
the role with another source, from the scene inspector's Slots or the
layer's Source section, changes it in every scene at once. A role filled by
nothing draws nothing, and its slot closes up. Removing the source filling a
role leaves the role unfilled. A role takes no look of its own, and is not
cloned or published; its layers take their own.

The scene inspector's **Slots** section picks the arrangement, lists the
slots with the role or source in each and what fills each role, and adds a
**Main slot** or **Camera slot**, making the role if the show has none. Add, under
**Not in any scene**, puts a guest into the scene's next tile when it has
slots.

**Appear on their own**, in Settings, Guests, has a guest whose camera comes
online take the next tile of the scene on program, and be heard on program,
as an edit you can undo. Up to four guests still in the room take tiles that
Comment thread
kixelated marked this conversation as resolved.
Resolved
way, and more wait under Add. One who leaves keeps their tile, closed until
they are back, and frees their place: the next guest takes a new tile, or
once four tiles hold guests, a tile the studio gave one who has left. They
are no longer heard on program unless another layer shows them, and wait
under Add when back, as they appeared once already. A tile you gave a guest
yourself stays theirs, as does a copy of one, and the scene file marks the
studio's own with `auto = true`. A guest appears on their own once per link,
across restarts: after that, where they are shown is yours, so undoing their
appearance or removing their layer keeps them off when they reconnect, until
a new link. Since an appearance is your edit, it drops what you could redo.
Off, every guest waits under Add, as before.

### Audio scenes

Audio from every source is mixed whether or not its scene is live, and cuts
Expand Down Expand Up @@ -929,20 +989,22 @@ before it expires, and is then renewed for as long as they stay, until you
remove them. A guest's broadcasts become sources named after them (`alice`,
`alice screen`) when they first appear, in no scene or audio scene: place
them from BUILD's Add and send them to the audio scene on program on MIX
to put them on air. That includes a
to put them on air, or have them [appear on their own](#slots-and-roles) in
the next tile of the scene on program. That includes a
guest invited before a restart whose link still works. A guest's source is
saved to the scene file but is not your edit: it stays out of History, so undo
never removes it and a guest joining never loses what you could redo. A guest
never removes it and a guest joining never loses what you could redo, unless
they [appear on their own](#slots-and-roles). A guest
who reconnects after you removed their source comes back under a new name
(`alice 2`), since undoing the removal brings back the old one.
**Remove from scenes** is your edit, so it undoes: it takes a guest, any clone
of their sources, and any mask reading them out of every scene and the top
layer and mutes them. A signed token cannot be taken back, so it also stops
renewing theirs and ends their return feed, and they are disconnected within
`--guest-expiry`. That
holds across a restart, whichever scene file you open: removed guests are
kept beside the room key, as `room.guests.toml` for `room.jwk`, so its
directory must be writable. Undo puts them back in the scenes but not on
holds across a restart, whichever scene file you open: removed guests, and
those who appeared on their own, are kept beside the room key, as
`room.guests.toml` for `room.jwk`, so its directory must be writable. Undo puts them back in the scenes but not on
renewal; **New link** lets them back in and renews them again, under a new
generation, so a link from before the removal cannot read their renewals.

Expand Down Expand Up @@ -996,6 +1058,10 @@ path = "logo.png" # relative to the scene file
kind = "broadcast"
path = "room/guest"

[sources.Main] # a role: the show's main picture, wherever a scene shows it
kind = "role"
source = "camera" # the source filling it; none draws nothing

[sources.alerts]
kind = "browser"
url = "https://example.com/alerts"
Expand Down Expand Up @@ -1073,6 +1139,15 @@ items = [
{ source = "main-view", rect = { x = 80, y = 80, width = 640, height = 360 } },
]

[[scenes]]
name = "Guests"
arrangement = "column" # column (the default), row, grid, or inset
items = [
{ source = "Main", slot = "main" }, # a slot takes no rect
{ source = "guest", slot = "tile" },
{ source = "logo", rect = { x = 1600, y = 40, width = 280, height = 120 } },
]

[[scenes]]
name = "Portrait"
size = { width = 1080, height = 1920 } # its own size; the program's without one
Expand Down Expand Up @@ -1110,7 +1185,7 @@ Source kinds are `camera`, `display`, and `microphone` (each with an optional
(macOS), `image` (PNG or JPEG), `media` (a video or audio file; see
[Media files](#media-files)), `color` (`#rrggbb` or `#rrggbbaa`),
`broadcast`, `browser` (a `url`, and a `width` and `height` up to 4096),
`overlay` (its `html`, a `width` and `height` up to 4096, and whether it `restart`s, true by default), `clone` (with the `source` it shows), `lut` (a 3D Adobe or Resolve `.cube`
`overlay` (its `html`, a `width` and `height` up to 4096, and whether it `restart`s, true by default), `clone` (with the `source` it shows), `role` (with the `source` filling it, if any; see [Slots and roles](#slots-and-roles)), `lut` (a 3D Adobe or Resolve `.cube`
file, which no layer places, but which grades what a `lut` filter names it in),
`replay`, where REVIEW plays replays, `scene` (with the `scene` it
draws), and `program` (see [Scene sources](#scene-sources)). BUILD's Add fills in
Expand All @@ -1124,7 +1199,9 @@ at most. `safe = true` marks the scene the panic key cuts to, on one scene at
most, which must be able to go on program.

A scene's `audio` names the audio scene it carries while published, the
one on program without it.
one on program without it, and its `arrangement` how it places its slots:
`column`, the default, `row`, `grid`, or `inset` (see
[Slots and roles](#slots-and-roles)).

`[[audio_scenes]]` lists the audio scenes, in the order MIX lists
them, each with its `name`, the sources whose `sounds` it holds, and the other
Expand All @@ -1140,7 +1217,8 @@ default), and `delay`, in every audio scene holding it.

Each entry of a scene's `items` is one of its layers, back to front, and each
`[[top]]` an always-on-top layer: the `source` it shows and its `rect` on the
canvas, in pixels, and optionally `visible = false`, `locked = true`, which
canvas, in pixels, or, in a scene, its `slot`, `main` (one per scene) or
`tile`, in place of a `rect`, and optionally `visible = false`, `locked = true`, which
the picture's pointer passes through, and its `crop`, `filters`, `blend`,
`shape`, and `keyframes`.

Expand Down
24 changes: 24 additions & 0 deletions quest/m1/auto-layout-check.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# [XS] Watch the slots reflow with real guests

## Goal

The maintainer has seen a scene laid out by slots reflow on a real show, with
guests joining and leaving mid-stream, and it reads as a deliberate glide
rather than a glitch. If it does not, the reflow's length, easing, or what
closes a slot changes until it does.

## Plan

The geometry, the glide's frames on the program clock, and a guest taking a
tile are tested in moq-scene and the studio, and BUILD's views show the
slots. Whether the motion reads well is a judgment no test makes, so it waits
on a person watching.

## Waiting

- Maintainer: run a show with a scene laid out by slots on program and
**Appear on their own** on (Settings, Guests), have two guests join from
the join page and one leave, and watch the program and a recording. An
agent cannot judge how motion reads to a viewer; the GPU tests already
check the frames. Done when the glide reads as intended, or the change it
needs is written into this Plan.
37 changes: 0 additions & 37 deletions quest/m1/auto-layout.md

This file was deleted.

6 changes: 4 additions & 2 deletions quest/m1/auto-place.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,10 @@ ready; local first with a hosted model as an opt-in tie-breaker).
game is right from its first frame.
- **Where it lives:** the analysis and the choice are UI-free, in moq-scene,
tested on recorded frames with a paused clock. The move is the item's
rect animated as a Move transition eases.
rect animated as a Move transition eases: moq-scene's `Glide`
(`rs/moq-scene/src/glide.rs`), which glides a scene's slots when they
reflow, eases any list of items from one placement to the next on the
program clock, keyed by what changed.

Measure, per AGENTS.md: the frame time and GPU copies the analysis adds, and
that the encoder's load does not move. Should the signals prove too weak, a
Expand All @@ -48,4 +51,3 @@ a judgment no test makes.
## Related

- [moq-video's foreground app is pinned](/quest/m1/pin-capture-foreground.md) - when the app in front changes, and the key its slot is remembered under
- [Scenes that lay themselves out](/quest/m1/auto-layout.md) - slots chosen by role rather than by content
4 changes: 4 additions & 0 deletions quest/m1/dual-format.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,10 @@ program source, cropped. This quest makes that one switch.
- A portrait arrangement starts from the landscape one: the main picture
cropped around its subject, the camera stacked under it. It is then the
streamer's to move.
- A layer in a slot keeps no rect, so a scene laid out by slots needs only a
second `arrangement` for portrait (such as `portrait = { arrangement =
"row" }`), and the slots place themselves on the portrait canvas; only its
layers set free need a second rect.
- Each format is its own encode, so it costs an encoder session and its
bitrate; the checklist says whether the machine and the uplink carry both.
- Where a layer is shown is said under the pictures and in the inspector,
Expand Down
Loading