Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
e88e9b0
chore(quest): claim quest/m2/phone-remote.md
kixelated Nov 19, 2026
ae4458e
feat(studio): remotes pair in the room and drive the action table
kixelated Nov 19, 2026
04b3410
feat(join): the remote page beside the join page
kixelated Nov 19, 2026
89cb678
feat(studio): Settings, Remote pairs a phone by its code
kixelated Nov 19, 2026
759a3f9
fix(studio): a reconnected remote's last press is not done again
kixelated Nov 19, 2026
be66709
test(studio): the desk is the palette's pads and mutes, and a press t…
kixelated Nov 19, 2026
9d608f6
docs: the phone remote, and its quest is done
kixelated Nov 19, 2026
a2dba16
test(studio): satisfy clippy's slice lint in the remote test
kixelated Nov 19, 2026
03b0440
chore: host the remote's views for the PR
kixelated Nov 19, 2026
1275cc5
chore: drop the hosted views
kixelated Nov 19, 2026
14ef45f
test(studio): a malformed or oversized press is refused, and the next…
kixelated Nov 19, 2026
ec31c4a
fix(studio): a press is its group's first frame alone, so a page cann…
kixelated Nov 19, 2026
fa1f753
fix(studio): Set up the room opens Guests from Remote
kixelated Nov 19, 2026
3cdd34a
fix(join): the remote's controls stay put across desks, so a tap lands
kixelated Nov 19, 2026
7b7ceda
chore(quest): add the try-the-phone-remote follow-up
kixelated Nov 19, 2026
54f4728
fix(studio): pace a remote's desk, and drop links into a room left
kixelated Nov 19, 2026
c2f36bd
Merge remote-tracking branch 'origin/main' into HEAD
kixelated Nov 19, 2026
ddc112a
Merge remote-tracking branch 'origin/main' into quest/m2/phone-remote
kixelated Nov 20, 2026
75c33f5
Merge remote-tracking branch 'origin/main' into quest/m2/phone-remote
kixelated Nov 20, 2026
d84cba1
fix(studio): a phone cannot drop a marker
kixelated Nov 20, 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
44 changes: 43 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -480,6 +480,7 @@ setting costs. Escape or a click outside closes it.
| 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; each sound's mute; and replay, clips, and markers (see [Hotkeys](#hotkeys)). |
| 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)). |
| Remote | Pair a phone as a remote by its QR code, see which are connected, and remove one (see [Phone remote](#phone-remote)). |
| 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 @@ -1118,7 +1119,9 @@ why under Guests, with a button to the pane.
without reconnecting. A guest's token may read only their own renewals and
return feed, at `.renew/<name>/<generation>` and `.return/<name>/<generation>`
in the room, and the program at `.program`, but anything else the relay lets
subscribe there can read every guest's, so grant that only to the studio. A guest who
subscribe there can read every guest's, so grant that only to the studio.
The same session publishes each [phone remote](#phone-remote)'s desk under
`.remote` and reads their presses under `.press`. A guest who
leaves needs a link, or a renewed token, that has not expired to come back.
BUILD's Add says, under Guests, when renewal is failing.
- **Upgrading from a studio without renewal:** generate a new room key, drop
Expand Down Expand Up @@ -1181,6 +1184,45 @@ encode of their mix-minus. A guest's
screen share stays in their feed, since only their camera's microphone is
taken out.

## Phone remote

A phone paired as a remote drives the show from wherever it reaches the
relay, with nothing installed: its page shows the scene pads with their
tally (ON AIR, FIRST, or NEXT, as the studio's own pads), TAKE and AUTO in
Studio mode, each sound's mute, and the live clock, and the whole page is
framed in the accent while the program is on air. A pad the studio cannot
take now is greyed out. Each press shows in the studio's status
bar, as a key's does, and on the phone.

Settings, Remote, pairs one: name it, **Pair a phone**, and scan the QR code
with the phone's camera, or **Copy link** to send it. A remote joins the
[guests' room](#guests), so it needs the room, its key, and the join page set
there first; its page is `remote.html` beside the join page, and the link
lasts as long as a guest's (`--guest-expiry`). The pane lists each phone
paired, whether it is connected, and its link, with **Show link** while that
link still works, **New link**, and **Remove**. Treat the link like a
password: anyone holding it can drive the show until you remove it.

- A remote presses only what is safe to press by mistake from a pocket: a
scene's pad, TAKE, AUTO, and a sound's mute. Going live, ending the
stream, the panic key, recording, and replay stay on the studio.
- A remote's token, signed by the room key like a guest's, may publish only
its presses, at `.press/<name>/<generation>` in the room, and read only the
desk the studio publishes it at `.remote/<name>/<generation>`, which carries
its renewed tokens. Remote names are their own, apart from guests'.
- The studio reads a remote's newest press only, at most one a program frame,
and refuses one that is not a single action of at most 4 KiB, so a page
pressing faster costs the studio nothing more. The page sends its next
press once the desk says how the last went, and the desk catches up with
what changed at the studio four times a second. A press the phone made
before the studio restarted or rejoined the room is not done again, since
it was most likely done before: the page asks you to check it first.
- **Remove** stops reading its presses at once, and stops renewing its token,
so it is disconnected within `--guest-expiry`; **New link** pairs it again
under a new generation, which a link from before cannot reach. Pairings and
removals outlast a restart, kept beside the room key as
`room.remotes.toml` for `room.jwk`.

## Scene file

The collection is TOML, so it diffs and reviews like code. It names devices,
Expand Down
2 changes: 2 additions & 0 deletions bun.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 3 additions & 1 deletion js/join/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
"private": true,
"type": "module",
"version": "0.0.0",
"description": "The page a guest opens to join a kixel.live Studio room",
"description": "The pages a guest opens to join a kixel.live Studio room, and a phone opens to drive it",
"license": "(MIT OR Apache-2.0)",
"repository": "github:moq-dev/studio",
"scripts": {
Expand All @@ -13,6 +13,8 @@
"test": "bun test"
},
"dependencies": {
"@moq/clock": "workspace:*",
"@moq/json": "workspace:*",
"@moq/net": "workspace:*",
"@moq/publish": "workspace:*",
"@moq/room": "workspace:*",
Expand Down
47 changes: 47 additions & 0 deletions js/join/remote.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
<!doctype html>
<html lang="en">

<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
<!-- The token is in the fragment, but keep the page itself out of every Referer. -->
<meta name="referrer" content="no-referrer">
<meta name="theme-color" content="#09090c">
<title>Studio remote</title>
<link rel="stylesheet" href="/src/remote.css">
</head>

<body>
<header class="top">
<span class="logo" aria-hidden="true"></span>
<b id="name" class="name"></b>
<span class="pill"><span id="status-dot" class="dot"></span><span id="status">Connecting</span></span>
<span id="air" class="air" role="status" aria-live="polite"></span>
</header>

<main>
<p id="error" class="error" hidden></p>
<p id="waiting" class="hint">Waiting for the studio. Keep the studio open with this phone paired.</p>

<div id="desk" hidden>
<section>
<h2 class="cap">Scenes</h2>
<div id="scenes" class="pads"></div>
<div id="take" class="take" hidden></div>
<p id="mode" class="hint"></p>
</section>

<section>
<h2 class="cap">Sound</h2>
<div id="sounds" class="sounds"></div>
<p id="no-sounds" class="hint" hidden>No sounds.</p>
</section>

<p id="said" class="said" role="status" aria-live="polite" hidden></p>
</div>
</main>

<script type="module" src="/src/remote.ts"></script>
</body>

</html>
42 changes: 42 additions & 0 deletions js/join/src/desk.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
import { expect, test } from "bun:test";
import { clock, type Desk, settled, tally } from "./desk.ts";

const desk = (change: Partial<Desk>): Desk => ({
air: "off",
clock: null,
studio: false,
program: "Gameplay",
cued: null,
scenes: [],
take_refused: null,
sounds: [],
done: null,
...change,
});

test("the clock reads hours, minutes, and seconds, past a day too", () => {
expect(clock(0)).toBe("00:00:00");
expect(clock(5047)).toBe("01:24:07");
expect(clock(100 * 3600 + 59)).toBe("100:00:59");
expect(clock(-3)).toBe("00:00:00");
});

test("the scene on program is on air only while live, and first before", () => {
expect(tally(desk({ air: "live" }), "Gameplay")).toEqual({ tag: "On air", on: "air" });
expect(tally(desk({ air: "ending" }), "Gameplay")?.on).toBe("air");
expect(tally(desk({ air: "off" }), "Gameplay")).toEqual({ tag: "First", on: "cue" });
expect(tally(desk({ air: "starting" }), "Gameplay")?.tag).toBe("First");
expect(tally(desk({ cued: "Chatting" }), "Chatting")).toEqual({ tag: "Next", on: "cue" });
expect(tally(desk({ cued: "Chatting" }), "BRB")).toBeUndefined();
});

test("a press is settled only by the desk naming this page and it or a later one", () => {
const done = (id: string, seq: number) => desk({ done: { id, seq, ok: true, said: "" } });
expect(settled(undefined, "a", 0)).toBe(false);
expect(settled(desk({}), "a", 0)).toBe(false);
expect(settled(done("a", 0), "a", 0)).toBe(true);
expect(settled(done("a", 3), "a", 2)).toBe(true);
expect(settled(done("a", 2), "a", 3)).toBe(false);
// Another page, such as this one before a reload.
expect(settled(done("b", 9), "a", 3)).toBe(false);
});
98 changes: 98 additions & 0 deletions js/join/src/desk.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
/**
* The desk: the show as the remote shows it, which the studio publishes at a
* path only the remote's own token may read, and the presses the remote
* publishes back. The shapes are `Desk` and `Press` in
* `rs/moq-studio/src/guests/remote.rs`.
*
* @module
*/

import * as Net from "@moq/net";

/** Where the studio publishes `name`'s desk in `generation`, with its renewed tokens. */
export function path(name: string, generation: number): Net.Path.Valid {
return Net.Path.from(`.remote/${name}/${generation}`);
}

/** Where the remote called `name` publishes its presses in `generation`. */
export function pressPath(name: string, generation: number): Net.Path.Valid {
return Net.Path.from(`.press/${name}/${generation}`);
}

/** The desk's track, a JSON snapshot. */
export const TRACK = "desk";

/** The presses' track, a JSON snapshot. */
export const PRESS_TRACK = "press";

/** Whether the program is on air. */
export type Air = "off" | "starting" | "live" | "ending";

/** The show as the studio last published it. */
export interface Desk {
air: Air;
/** Whole seconds on air, while live. */
clock: number | null;
/** Whether a pad cues its scene rather than taking it. */
studio: boolean;
program: string | null;
cued: string | null;
scenes: { name: string; refused: string | null }[];
/** Why TAKE and AUTO cannot run now, if they cannot. */
take_refused: string | null;
sounds: { name: string; muted: boolean }[];
/** How this page's last press went, once the studio has read one. */
done: Done | null;
}

/** How a press went. */
export interface Done {
id: string;
seq: number;
ok: boolean;
said: string;
}

/** What a remote may press: `Action` in `rs/moq-studio/src/controls.rs`, as serde writes it. */
export type Action = "Cut" | "Transition" | { Scene: string } | { Mute: string };

/** A press: this page, its number, and the action, or none to say the page is there. */
export interface Press {
id: string;
seq: number;
action: Action | null;
}

/**
* Whether `desk` says how the press numbered `seq` from the page `id` went:
* until it does, the page sends nothing more, so the studio, which reads only
* the newest press, never drops one.
*/
export function settled(desk: Desk | undefined, id: string, seq: number): boolean {
return desk?.done?.id === id && desk.done.seq >= seq;
}

/** `seconds` as the studio's live clock shows it: hours, minutes, and seconds. */
export function clock(seconds: number): string {
const whole = Math.max(0, Math.floor(seconds));
const two = (value: number) => value.toString().padStart(2, "0");
return `${two(Math.floor(whole / 3600))}:${two(Math.floor(whole / 60) % 60)}:${two(whole % 60)}`;
}

/** A pad's tally: on air in the accent, or first or next in amber. */
export type Tally = { tag: string; on: "air" | "cue" } | undefined;

/**
* The tally of the pad for `scene`, as the studio's own pads show it: the
* scene on program is ON AIR while live, and FIRST otherwise, the one the
* stream opens on; the scene cued is NEXT.
*/
export function tally(desk: Desk, scene: string): Tally {
if (desk.program === scene) {
return desk.air === "live" || desk.air === "ending"
? { tag: "On air", on: "air" }
: { tag: "First", on: "cue" };
}
if (desk.cued === scene) return { tag: "Next", on: "cue" };
return undefined;
}
40 changes: 3 additions & 37 deletions js/join/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,47 +13,13 @@ import { Local } from "@moq/room";
import { Effect, Signal } from "@moq/signals";
import * as Watch from "@moq/watch";
import * as Feed from "./feed.ts";
import { format, type Link, parse } from "./link.ts";
import { format, type Link } from "./link.ts";
import { element, fail, read, stored } from "./page.ts";
import * as Renew from "./renew.ts";

/** Where the fragment is kept once it leaves the address bar, so a reload rejoins. */
const STORED = "moq-studio-join";

function element<T extends HTMLElement>(id: string): T {
const found = document.getElementById(id);
if (!found) throw new Error(`missing #${id}`);
return found as T;
}

function fail(err: unknown): void {
const error = element("error");
error.textContent = err instanceof Error ? err.message : String(err);
error.hidden = false;
}

/**
* `use` on the page's session storage, or `undefined` where the browser denies
* it, which only costs rejoining after a reload.
*/
function stored<T>(use: (storage: Storage) => T): T | undefined {
try {
return use(sessionStorage);
} catch {
return undefined;
}
}

/** The link this page was opened with, moved out of the address bar. */
function read(): Link {
const fragment = location.hash.slice(1) || stored((storage) => storage.getItem(STORED));
if (!fragment) throw new Error("open the join link the host sent you");
const link = parse(fragment);
// Out of the address bar, history, and anything that shows them, such as a screen share.
stored((storage) => storage.setItem(STORED, fragment));
history.replaceState(null, "", location.pathname + location.search);
return link;
}

/** Publish into the room until the guest leaves. Returns how to leave. */
function join(link: Link): () => void {
const signals = new Effect();
Expand Down Expand Up @@ -141,7 +107,7 @@ function join(link: Link): () => void {
function main(): void {
let link: Link;
try {
link = read();
link = read(STORED);
} catch (err) {
fail(err);
return;
Expand Down
48 changes: 48 additions & 0 deletions js/join/src/page.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
/**
* What the join page and the remote share: finding their elements, saying what
* failed, and reading the link they were opened with out of the address bar.
*
* @module
*/

import { type Link, parse } from "./link.ts";

/** The element with `id`, which the page's HTML always has. */
export function element<T extends HTMLElement>(id: string): T {
const found = document.getElementById(id);
if (!found) throw new Error(`missing #${id}`);
return found as T;
}

/** Show `err` in the page's `#error`. */
export function fail(err: unknown): void {
const error = element("error");
error.textContent = err instanceof Error ? err.message : String(err);
error.hidden = false;
}

/**
* `use` on the page's session storage, or `undefined` where the browser denies
* it, which only costs rejoining after a reload.
*/
export function stored<T>(use: (storage: Storage) => T): T | undefined {
try {
return use(sessionStorage);
} catch {
return undefined;
}
}

/**
* The link this page was opened with, moved out of the address bar and kept
* under `key` in session storage, so a reload rejoins.
*/
export function read(key: string): Link {
const fragment = location.hash.slice(1) || stored((storage) => storage.getItem(key));
if (!fragment) throw new Error("open the link the host sent you");
const link = parse(fragment);
// Out of the address bar, history, and anything that shows them, such as a screen share.
stored((storage) => storage.setItem(key, fragment));
history.replaceState(null, "", location.pathname + location.search);
return link;
}
Loading