ducoterra
3f93481c54
**Phase 06 — final verification pass: 100% green.** - **Verified (all 6 tasks complete in working tree):** `#quality` select + `PRESETS` table; preset-driven capture request + `contentHint`; per-leg `legCap()`/`degradation` at both call sites; live `applyQuality()` with Overconstrained fallback + republish; `q` key cycle; `#stat-quality`/`#stat-codec` readouts; full e2e matrix (requests, committed params ×3, zero-cap, mid-share switch, unrescalable device, late-joiner first-offer, readout, `q`); realdisplay delivered-pixels `light` case. `test_sender_fidelity.py` **untouched and green** (regression canary). - **Gates:** `uv run ruff check . && uv run ruff format --check .` → clean (32 files); `uv run pyright` → 0 errors; `uv run pytest` → **284 passed, 5 skipped (realdisplay-gated), coverage 95%** (93s); `MIRROR_REALDISPLAY=1 uv run pytest -m realdisplay` → **4 passed, 1 skipped** (no audio source on host — documented platform condition). - **Completion criteria:** all 11 ✓ — sharp default reproduces old request; light ≤960×600@15fps/motion/round(cap×0.35)/maintain-framerate with moving viewer frames; mid-share re-prices with `peers.size` unchanged, no renegotiation, roster matches `getSettings()`; refused-rescale toasts "next share"; `q` cycles + toasts, text-field guard holds; readout exact + codec shape, both reset to `—` idle; realdisplay: light decoded ≤990px (measured 320×200), sharp clears `SHARP_FLOOR_PX`; no new env/wire/Python/asset; suite 100% green, coverage >90%. - **Docs:** README.md reviewed in full against code — Quality table, `q` key, env-var table, routes (`/share`), kiosk commands, key table, doc paths all consistent; **no fixes needed**. AGENTS.md — verified, no stale statements, no changes. PLAN.md untouched (diff = 0). - **Reported (per phase, not edited):** PLAN.md §6 line 204 still says "per-leg `maxBitrate` cap (default **12 Mbit/s**)" — code has defaulted to **25 Mbit/s** since phase 02; needs a user-approved one-line amendment. - **Next pending phase:** none — 06 is the last phase in `todo/`; the roadmap is complete.
245 lines
13 KiB
Markdown
245 lines
13 KiB
Markdown
# mirror
|
||
|
||
**Device-agnostic screen mirroring that lives entirely in the browser.**
|
||
|
||
`mirror` runs a small HTTP server on your machine. Open it from any device on
|
||
your network:
|
||
|
||
| Page | URL | What it does |
|
||
| ------------ | ------------------ | ----------------------------------------------------------------------- |
|
||
| **Share** | `/mirror` (also `/share`) | Picks a window, screen, or tab via the OS-native picker and mirrors it. |
|
||
| **Watch** | `/watch` | Shows every screen currently being mirrored; click a tile to take the stage. |
|
||
| **Index** | `/` | Signpost + live count of mirrors. |
|
||
|
||
Any number of people can mirror at the same time and any number of people can
|
||
watch. There are **no accounts and no passwords** — this is built for a trusted
|
||
local network, and that assumption is deliberate and documented in
|
||
[SECURITY.md](SECURITY.md). What *does* decide who gets in is the source address:
|
||
by default any address is welcome, and `--allow-cidr` / `MIRROR_ALLOW_CIDRS`
|
||
narrows that to the networks you name.
|
||
|
||
## Quickstart
|
||
|
||
```bash
|
||
uv sync --extra dev
|
||
uv run mirror serve # http://0.0.0.0:8055
|
||
```
|
||
|
||
Then, from another machine on the LAN:
|
||
|
||
```
|
||
http://<this-machine>:8055/mirror # to share
|
||
http://<this-machine>:8055/watch # to watch
|
||
```
|
||
|
||
Linux is the primary target. On Linux the native picker is X11/Wayland's own
|
||
(Chromium uses `xdg-desktop-portal` on Wayland/GNOME/KDE, and its built-in X11
|
||
picker on Xorg), so nothing has to be installed on the client side.
|
||
|
||
The share page works on a phone as well as a desktop: `/mirror` is usable
|
||
down to a 320 px-wide viewport, and the preview keeps its shape but never
|
||
shrinks below the controls it holds, so the Share button is always on screen.
|
||
|
||
The target *client* setup for an always-on display is Fedora Silverblue running
|
||
GNOME Kiosk — see [`docs/kiosk-silverblue.md`](docs/kiosk-silverblue.md).
|
||
|
||
## How it works
|
||
|
||
Media never touches the server. Each mirror is a WebRTC peer connection
|
||
established directly between the sharer's browser and each watcher's browser
|
||
(a "mesh" fan-out). The server is a **signaling relay and roster only**: it
|
||
tracks who is publishing what, forwards SDP/ICE between peers, and pushes
|
||
roster deltas to viewers.
|
||
|
||
```
|
||
sharer browser ──ws──► ┌──────────────────────┐ ◄──ws── watcher browser
|
||
│ │ FastAPI │ ▲
|
||
│ offer/ICE ───►│ /ws (signalling) │◄─── offer/ICE │
|
||
│ │ registry (in-mem) │ │
|
||
└────── WebRTC (SRTP, LAN, p2p) ─────────┴─────────────────┘
|
||
```
|
||
|
||
## Configuration
|
||
|
||
Environment variables (all optional; a `.env` file is loaded if present):
|
||
|
||
| Variable | Default | Meaning |
|
||
| ---------------------- | ------- | ---------------------------------------------------- |
|
||
| `MIRROR_HOST` | `0.0.0.0` | Bind address for `mirror serve`. |
|
||
| `MIRROR_PORT` | `8055` | Bind port. |
|
||
| `MIRROR_ICE_SERVERS` | `[]` | JSON array of RTCIceServer objects, if peers cannot reach each other directly. |
|
||
| `MIRROR_MAX_MIRRORS` | `0` | Cap on concurrent mirrors (`0` = unlimited). |
|
||
| `MIRROR_MAX_BITRATE` | `25000000` | Per-leg WebRTC bitrate cap in bits/s — the mesh uploads N × bitrate per sharer, so this is the ceiling. 25 Mbit/s suits a wired LAN at 1440p; a Wi-Fi sharer with many viewers may need less, not more. |
|
||
| `MIRROR_PING_INTERVAL` | `20` | Seconds between socket liveness pings. |
|
||
| `MIRROR_ALLOW_CIDRS` | *(unset)* | Comma-separated source networks allowed to connect, e.g. `10.2.0.0/22,fd00::/64`. Unset means unrestricted. A wall needs this range too, and its address is DHCP — give it a reservation. |
|
||
| `MIRROR_TRUSTED_PROXIES` | `127.0.0.0/8, ::1/128` | Which peers may speak for a client via `X-Forwarded-For`. Only a proxy that overwrites the header belongs here. |
|
||
| `DEBUGPY` | `0` | `1` opens a debugpy listener on `DEBUGPY_PORT`. |
|
||
| `DEBUGPY_PORT` | `5678` | debugpy port. |
|
||
| `DEBUGPY_WAIT` | `0` | `1` blocks the server at start until a debugger attaches. |
|
||
|
||
## Platform notes
|
||
|
||
**Screen capture needs a secure context.** `http://localhost` is one; a plain
|
||
`http://192.168.x.x` opened from another device is not, and the browser hides
|
||
`getDisplayMedia()` completely. The `/mirror` page detects this and prints the
|
||
three ways forward (share from localhost, serve HTTPS, or mark that one origin as
|
||
secure on the sharing device). Watching never needs permission.
|
||
|
||
This is why the fleet deployment terminates TLS in nginx rather than exposing
|
||
`mirror serve` directly — over `https://`, every device on the network can share
|
||
and none of this applies. A bare `mirror serve` is for the machine it runs on and
|
||
for testing.
|
||
|
||
**Linux.** On X11/Xorg Chromium uses its native capturer — the picker appears and
|
||
that is the end of it. On Wayland (GNOME/KDE) Chromium goes through
|
||
`xdg-desktop-portal`, so the compositor shows its **own permission dialog for
|
||
each share**, which mirror neither controls nor tries to bypass. Chrome's picker
|
||
offers whole screens and individual windows; on Wayland what the portal will
|
||
agree to depends on the compositor.
|
||
|
||
**Audio.** A share carries audio when the browser's picker offers it (Chrome's
|
||
"share audio" tickbox, or a tab's own audio); the sharer's panel says
|
||
`shared` / `silent` / `not offered`, and the wall shows an audio button only
|
||
when one exists. On the wall, only the staged mirror can be audible — **press
|
||
`m` on the wall to hear the staged mirror** (unmuting it mutes the others,
|
||
leaving the stage re-mutes it). What *system* audio a browser can capture is
|
||
a browser/platform fact, not a mirror one: Chrome on Linux gets it where
|
||
PipeWire offers it, Firefox's desktop capture does not offer it at all. See
|
||
[SECURITY.md](SECURITY.md) §4 "Audio".
|
||
|
||
**Quality.** The share page has a Quality control — `Sharp` (default),
|
||
`Balanced`, `Light` — because a sharer's machine is a resource the share
|
||
spends, and `MIRROR_MAX_BITRATE` alone cannot express "fewer pixels". Each
|
||
preset is one request to the capture device and one per-viewer encoder
|
||
budget:
|
||
|
||
| Preset | Requested pixel cap | Frame rate | Per-viewer bitrate | `degradationPreference` (what the encoder may sacrifice) |
|
||
| ------------ | ------------------- | ------------ | ------------------------------ | ------------------------------------------------------- |
|
||
| `Sharp` | ≤ 3840×2160 | 30 fps (up to 60) | 100% of `MIRROR_MAX_BITRATE` | `maintain-resolution` — frame rate |
|
||
| `Balanced` | ≤ 1920×1200 | 24 fps (up to 60) | 60% of `MIRROR_MAX_BITRATE` | `balanced` |
|
||
| `Light` | ≤ 960×600 | 15 fps (up to 30) | 35% of `MIRROR_MAX_BITRATE` | `maintain-framerate` — resolution |
|
||
|
||
`Sharp` is the default and is what the sharp-capture work shipped: its
|
||
request, cap and preference are the old hardcoded values verbatim, so nothing
|
||
it proved gets worse — the new presets only ever ask for less, and a preset
|
||
can never raise a leg above the server's ceiling. `MIRROR_MAX_BITRATE` stays
|
||
the ceiling the factor is applied to: a Wi-Fi sharer picks `Light` in the
|
||
page, an operator lowers the ceiling for everyone.
|
||
|
||
Who it is for: the software-encoding sharer. A Firefox/Linux box often has
|
||
no hardware video encoder (VA-API exposes no H.264 encode entrypoint on many
|
||
machines), where 4K at 30 fps burns roughly a whole core — `Light` trades
|
||
pixels and frame rate for a fan that does not spin, and under pressure the
|
||
encoder will in fact sacrifice what its `degradationPreference` allows.
|
||
Changing the preset applies to the share that is already running — the
|
||
per-viewer bitrate and frame rate always, and the capture size where the
|
||
browser allows a live rescale; when it does not, the panel says the size
|
||
lands on the next share instead of pretending it did. `q` cycles the preset.
|
||
The panel also shows the quality budget in force and the codec the legs
|
||
actually negotiated — `—` where a browser does not report it, never a guess.
|
||
|
||
## Deployment
|
||
|
||
The internal deployment is `https://mirror.reeseapps.com`, described and automated
|
||
in the deployments repo under `mirror/` (`app/` quadlet, `nginx/` edge, `certbot/`,
|
||
`route53/`, and a README with the VM SOP). Three things about it are worth knowing
|
||
from this side:
|
||
|
||
- **TLS ends at nginx on the service VM**, not in this process, so there is no
|
||
`--https` flag here. That is what makes `getDisplayMedia()` available on every
|
||
device, and it means an `Upgrade` header and a long idle timeout on `/ws` are
|
||
load-bearing.
|
||
- **The address list is enforced twice** — nginx `allow`/`deny`, and
|
||
`MIRROR_ALLOW_CIDRS` in the container for the path that bypasses nginx. Change
|
||
both in one commit.
|
||
- **The container has no internet egress.** Media goes browser-to-browser and the
|
||
server only relays JSON, so it dials nothing; `Internal=true` is what makes
|
||
that a fact rather than an intention.
|
||
|
||
### Kiosk client
|
||
|
||
A wall display is a Fedora Silverblue box running the locked-down GNOME Kiosk
|
||
session, auto-logged in as `kiosk`, with Firefox in `--kiosk` mode pointed at
|
||
`/watch`. It is set up and repaired entirely over SSH — no keyboard, no console,
|
||
no monitor. A brand-new box layers the kiosk packages once first
|
||
(`rpm-ostree install gnome-kiosk gnome-kiosk-script-session`, then a reboot);
|
||
after that these two commands are both the setup and the repair path:
|
||
|
||
```bash
|
||
scp -r docs/kiosk-silverblue client:/var/tmp/ && ssh client \
|
||
'cd /var/tmp/kiosk-silverblue && sudo sh install-kiosk.sh && sudo systemctl restart gdm'
|
||
ssh client 'sudo sh /usr/local/share/mirror-kiosk/check-kiosk.sh'
|
||
```
|
||
|
||
Because nobody is standing at the machine, every claim about it is verified from
|
||
the outside: `loginctl` for the session, the foreground VT for "is the wall
|
||
actually on screen", the server's `/api/streams` for the viewer, the sharer's own
|
||
peer state for the media, and a probe page for the rendered resolution. The
|
||
runbook records why each file lives where it does on an
|
||
otherwise read-only OS.
|
||
|
||
**When it hangs.** A wall is unattended, so a hang has to end without a person:
|
||
the kernel turns lockups and oopses into a reboot, and PID 1 must keep kicking the
|
||
hardware watchdog or the chipset resets the box. Being *quiet* is a different
|
||
failure than being hung, so the server watches `/healthz` for that and pages over
|
||
ntfy ([`docs/wall-watch/`](docs/wall-watch/)). Both are installed by the commands
|
||
above and asserted by `check-kiosk.sh`.
|
||
|
||
**Keys.** The whole wall works from a keyboard — and the box needs no keyboard
|
||
attached to be operated *or* debugged; the keys are there when one is plugged
|
||
in. On `/watch`:
|
||
|
||
| Key | Action |
|
||
| --- | --- |
|
||
| `j` / `↓` · `k` / `↑` | Select the next / previous mirror (wraps). |
|
||
| `Enter` / `f` | Stage the selected mirror fullscreen (`f` re-enters fullscreen when already staged). |
|
||
| `g` | Back to the wall. |
|
||
| `n` / `p` | Stage the next / previous mirror. |
|
||
| `1`–`9` | Stage the Nth mirror. |
|
||
| `m` | Mute / unmute the staged mirror — on the selected mirror it stages it first. |
|
||
| `?` | Show / hide this list on screen. |
|
||
| `Esc` | Close the key list, then leave the stage. |
|
||
|
||
A staged mirror's caption bar and control cluster are **hidden at rest**, so
|
||
the shared video — a terminal's bottom line included — is never covered by
|
||
them. A pointer move over the stage (a tap, for touch) or any key press
|
||
while staged reveals them briefly; after ~3 s without activity they fade
|
||
back, so a parked pointer or a one-time key press never pins them up.
|
||
|
||
A mirror's audio is only heard while it is on the stage: every mirror starts
|
||
muted, unmuting one (the tile's audio button or `m`) mutes the others, and
|
||
leaving the stage re-mutes it. Sound never starts without a click or a
|
||
keypress.
|
||
|
||
On `/mirror`: `s` starts a share, `x` stops one, `q` cycles the Quality
|
||
preset, and `Esc` stops while live. Keys
|
||
with `Ctrl`/`Cmd`/`Alt` are never intercepted, and a key typed in the display-
|
||
name field is text, not a command. `?` is the only key that needs Shift, and it
|
||
is matched on the character itself — on a layout where `?` is a dead key the
|
||
list is not reachable, so keep this table to hand.
|
||
|
||
## Development
|
||
|
||
```bash
|
||
uv run pytest # unit + API + browser E2E (~95s)
|
||
uv run pytest -m "not e2e" # everything except the browser (~0.5s)
|
||
uv run ruff check . && uv run ruff format --check . && uv run pyright
|
||
```
|
||
|
||
The browser suite drives **real capture**: Chromium's fake media device yields a
|
||
moving monitor stream (1280×720 by default; clamped to the capturing window when
|
||
a size is requested, as `/mirror` now asks), so the assertions are on decoded,
|
||
changing pixels at the watcher — not on log lines.
|
||
|
||
There is a second, opt-in rung that exercises Chromium's **real X11 capture
|
||
backend** on a private Xvfb display, isolated from your own session so it can
|
||
never prompt you or mirror your desktop:
|
||
|
||
```bash
|
||
MIRROR_REALDISPLAY=1 uv run pytest -m realdisplay
|
||
```
|
||
|
||
See [AGENTS.md](AGENTS.md) for the operating rules,
|
||
[.agents/PLAN.md](.agents/PLAN.md) for the locked architectural decisions, and
|
||
[SECURITY.md](SECURITY.md) for why there is no login.
|