Files
hyprland-headless-stream-pl…/docs/plans/2026-10-03-network-stream.md
T
Hermenix 9744d35945 feat(live): one port, a router, and a phrase per session (stage 1)
The session-stream web app: a single HTTP listener (9988) that serves a page
per enabled session, keyed by a spoken phrase. Off by default, so a stream
exists only for the sessions it was enabled on.

  src/hhstream_live/phrase.py     four EFF-large words + a 5-char base-36 tail
                                  (~77.5 bits); the phrase is the password
  src/hhstream_live/publisher.py  one capture thread + one frame slot per
                                  output; one slot/no queue; capture paused at
                                  zero viewers
  src/hhstream_live/server.py     the router: /, /<phrase>/, /stream.mjpg,
                                  /frame.jpg, /status.json; unknown phrase is
                                  an empty 404, rate-limited
  src/hhstream_live/pages.py      the built-in dark pages (no CDN, no build)
  src/hhstream_live/__main__.py   hhstream-live serve|phrase, standalone

The root page is a form, never a list: the phrase is known only by whoever
enabled the stream. Transport is MJPEG (multipart/x-mixed-replace), reusing
the JPEG grim already produces. Not yet wired to the broker -- that is
stage 2. Tests: tests/live (51).
2026-10-06 13:32:00 +00:00

15 KiB
Raw Blame History

Superseded (2026-10-04): the operator asked for one port (9988) with a router and a phrase per session, only for enabled sessions — see docs/plans/2026-10-04-session-stream-webapp.md. This file is kept for its transport table and its capture/idle-clock reasoning, which the new plan inherits.

I'll explore the frame server, session CLI, broker, contracts, and the NixOS module first, then write a plan only — no edits.The tree is a Python frame server, a session broker, and a pointer daemon. Next I’ll read the contracts and the capture/session paths those decisions depend on.The publisher cannot select a session today. hhstream-server serves one output on /run/hypr-stream/stream.sock and its command line is frozen. hhstream shot --output hh-<id> and record --output are separate grim -o one-shots. A phone view should be a new, view-only listener beside that, not a change to the socket Hermenix already reads.

Decisions

1. Transport

Primary: MJPEG over HTTP. Fallback: a WebSocket carrying the existing HHS1 frames, only if a real phone browser will not render the MJPEG. Not HLS, not VNC, not WebRTC.

Option Latency CPU on this box Already here Plain browser
MJPEG (multipart/x-mixed-replace) One frame. At the recommended 5 fps that is about 200 ms plus a ~46 ms grim JPEG. Reuses the JPEG the host already measured: 1280×720 q80 is ~46 ms; PNG is ~326 ms and is the wrong codec. One capture, many viewers. CommandCapture, the single-slot drop policy, JPEG size parsing. Stdlib HTTP only. Yes. An <img> needs no plugin and no script.
WebSocket of HHS1 Same pixels, same latency. Same capture cost. The framing code. No. A phone that opens the URL sees nothing unless we also serve a page that blits JPEGs.
HLS Seconds (segment delay). A second encode (libx264) on top of grim. ffmpeg is only used today to mux a finished recording. Nothing of the live path. Safari yes, Chrome only with a script.
VNC / RFB Fine. A new codec, and a client can click. Nothing. No. noVNC is a script, and clicks would bypass the pointer lease.
WebRTC Best, and irrelevant. An encoder plus ICE/DTLS. Worst cost for a two-core software renderer. Nothing. Only via a script and a signaling dance.

The URL we print is a tiny same-origin HTML page whose only job is <img src="stream.mjpg">. Top-level multipart documents are unreliable; the image tag is the one that works on phones. The same process also serves one frame.jpg for tests. No CDN, no extra Python dependencies. The WebSocket fallback is the same JPEG bytes and the same page, and it is not built in the first slice.

Capture rate for a session stream defaults to 5 fps, hard cap 10. The main publisher already spends roughly one core on its own grim. A second full-rate capture would take the other core. Five frames times ~46 ms is about a quarter of one core, and only while someone is connected.

2. Where the listener lives

A new long-lived unit, hhstream-live.service. One process, many session outputs. Not the frame server, not the broker, and not one unit per session.

It follows the pointer driver, not the frame server:

  • The frame server's contract is one socket, one output, one slot, and a command line of --socket, --fps, --format, and --capture-command. Clients send nothing. A LAN parser bug or a slow phone must not be able to take down the socket Hermenix reads. The server also does not know session ids, idle deadlines, or teardown.
  • The broker is the control plane (/run/hhstream/control.sock, newline JSON, mode 0660). grim takes tens to hundreds of milliseconds and its timeout is 5 s. That block must not freeze touch, kill, or the reaper. That is why the pointer is already a separate process.
  • A systemd template per session would be a second supervisor. Sessions are broker records, and SessionManager.teardown is deliberately the only kill path. A child unit also races KillMode= and adopt-on-restart.

hhstream-live is an executor. It holds no session policy. The broker tells it what to publish over a private socket, /run/hhstream/live.sock (mode 0660, next to pointer.sock). It must not take RuntimeDirectory=/run/hhstream; the pointer unit's comments record that a second owner deletes the broker's socket.

It runs as the compositor user hhstream, with video and render, ProtectHome and ProtectSystem=strict, the same shape as hyprland-headless-stream. It discovers WAYLAND_DISPLAY the way that unit already does. It does not run as hermes: a network process should not have the agent's home. Group hhstream can already open the broker socket; this does not widen that.

One session's picture. The broker sends the output name hh-<session-id> and the full capture argv, built from the module's captureCommand plus -o hh-<id>. On this host that is grim -o hh-<id> -c -t jpeg -q 80 -. One capture thread and one frame slot per output, same drop rule as FrameServer: a slow viewer skips frames and is never queued. The daemon does not touch stream.sock and does not capture the main output.

No container, no stream. If the session's container is missing or degraded, stream start returns the existing no_container error (exit 10). Falling back to the main output would put every other session on the phone. Containers are on in /etc/nixos/hyprland-stream.nix as a trial, and a window that ignores HHSTREAM_APP_ID still lands in quarantine. The stream will then honestly show an empty output. That is a container bug, not a reason to capture the main screen.

When the session dies. teardown (kill, reap, and gc) tells the daemon to stop that output and close its clients before hyprctl output remove. If the output disappears anyway, grim's "unknown output" ends the stream after a few failures. It does not retry forever the way the main publisher must. The port is freed when the listener closes.

A broker restart does not rebind anything. If the daemon is still up, the broker asks it for the list and reattaches those listeners to the session records so status and teardown still see them. If the daemon restarted too, the stream is gone and status says so. An open port is an explicit act.

3. Addressing and lifecycle

The caller may pass a port. Otherwise the broker takes the lowest free port in a configured range. Default range 9120–9131. Not a single configured port (two sessions must fit; max_containers is 2). Not an ephemeral port (a phone URL has to be writable, and a firewall cannot name port 0). 9120 starts just above 9119, which /etc/nixos/common.nix already opens for the Hermes dashboard. Twelve ports covers the container budget plus a restart where the old socket is still in TIME_WAIT.

hhstream session stream start <id> [--port N] [--bind ADDR] [--fps N]
hhstream session stream stop <id>
hhstream session stream status [id]

Nested like pointer: one precondition (a container output) and one warning (this is a network listener). start prints only the URL on stdout, the same trick as the session id and the lease id:

http://127.0.0.1:9120/<token>/

Stderr says it is view-only, names the output, and prints the stop command. --json adds url, port, bind, token, output, fps, and viewers. When bind is 0.0.0.0, the printed host is the default-route IPv4, overridable with --advertise ADDR, plus the loopback URL. Do not print 0.0.0.0.

start on a session that already has a listener returns that listener (and its token) when port and bind match, and stream_busy (exit 8) when they do not. request_id covers start and stop so a retry cannot open a second port. stop only stops the listener; the session keeps running. A port outside the range is exit 2. The range being full is stream_budget, exit 6. The daemon being down is stream_unavailable, exit 10. No new exit-code numbers.

The session record gains a stream object (port, bind, token, output, fps, pid or daemon id). Registry schema bumps to 4; older records migrate to stream: null and are adopted, not refused.

Idle clock. start, stop, and status do not touch. Same rule as pointer: setting something up is not "still wanted". A connected viewer is activity. About once a minute the broker asks the daemon for viewer counts and, if any are non-zero, stamps touch. That is the one new way the clock moves, and it is not a CLI verb. It has to be: the idle timeout is three hours, and a session the operator is watching from his phone must not be reaped out from under him. An open port with nobody connected does not stamp, and it does not run grim. The reaper then kills the session on the normal deadline, and teardown closes the listener. A forgotten URL is a bound socket, not a hot core and not a pinned session.

4. Security

This would be the first listener meant to be opened from another device. Everything else is a unix socket in a 0750 directory, mode 0660, group hhstream, with no authentication. The host firewall allows inbound TCP 22 and 9119 only. The pixels can be a logged-in browser.

Default bind is 127.0.0.1. The firewall stays closed. A path token is always required, including on loopback.

Loopback is still weaker than the group-gated frame socket: any local user can open a TCP port. The token is what replaces the group check. It is a 128-bit secrets.token_urlsafe value in the path, because an <img> will send a path and will not send a custom header:

GET /<token>/              the page
GET /<token>/stream.mjpg   the multipart stream
GET /<token>/frame.jpg     one JPEG

Anything else is a 404 with an empty body. Wrong-token responses do not echo the token. The audit log records port, bind, and output, and does not record the token. The token lives in the session record under the broker state dir (/var/lib/hermes/hhstream-sessions on this machine). stop then start rotates it.

LAN is opt-in twice, in the host config, not in the module defaults:

  • sessions.stream.bind = "0.0.0.0" (or a specific address). --bind on the CLI can do the same for one session.
  • sessions.stream.openFirewall, default false. The module must not add ports to networking.firewall.allowedTCPPorts unless that option is on. This machine should turn it on in /etc/nixos only when the phone path is wanted, and the range must not include 9119.

The token is cleartext on the LAN. The threat model is "another device on the LAN can watch if it has the URL", not "the URL is secret from the network". There is no TLS in this slice; a private CA and a phone trust prompt are a worse default. Until the firewall is opened, the phone path is an SSH forward to loopback (ssh -L 9120:127.0.0.1:9120), which keeps the current posture.

The listener is view-only. No pointer, no keyboard, no hyprctl. At most four viewers. The broker pulls viewer counts; the daemon cannot ask the broker to touch an arbitrary session.

5. Tests

Same layers as the rest of the repo. No GPU for unit tests. No browser in the VM checks. VM checks stay one at a time.

Test Proves
tests/unit for the publisher, with FakeCapture Multipart framing, one JPEG per part, Content-Type, token 404s with an empty body, a stalled viewer does not block another, capture does not run at zero viewers, "unknown output" ends the stream. This mirrors tests/unit/test_server.py.
tests/sessions/unit Port allocator (lowest free, range exhausted, clash), CLI parse, stdout is the bare URL, stderr carries the warning, start/stop/status do not touch, a viewer heartbeat does, teardown issues stop before the container is destroyed. New error names map to exits 2, 6, 8, and 10 without renumbering.
tests/sessions/integration A real daemon and a real hhstream-live on 127.0.0.1 with an ephemeral port. urllib reads two JPEGs, a wrong token fails, stream stop closes the port, and a real idle reap closes it too. Fake capture, no compositor.
A human browser pass, not a check On the host, stream start against a session whose window is actually on hh-<id> (the cooperating client from checks/vm-containers.nix, not foot or Chromium). Open the printed URL in the Chromium this machine already installs. Change pixels; they must show up without a reload. The phone pass is the same URL only after bind and firewall are opted in.

urllib reading a multipart body is the automated proof that a browser's <img> has something valid to decode. A headless-Chrome screenshot is optional and is not a VM check: two software-rendered compositors plus a browser will flake on two cores.

6. Stages

Contracts bump first. docs/CONTRACT.md stays as it is (stream.sock is untouched). docs/CONTRACT-sessions.md needs a sessions-v3 for the verbs, /run/hhstream/live.sock, the unit name, the viewer-touch exception, and the error names. Schema 4 is the record bump. No v1 or v2 field changes meaning.

Stage What Size Risk
0 Contract text only. S Freezing the wrong default. This plan is the review.
1 hhstream-live: HTTP, token, one output, injected capture, unit tests. No broker. M A phone that will not paint multipart/x-mixed-replace. That is the gate for the WebSocket fallback, and it is not built here.
2 Broker verbs, registry field, CLI, teardown order, viewer heartbeat, integration test. L A second port on retry; stop racing output remove; token leaking into events.jsonl; a heartbeat that keeps a session alive with zero viewers.
3 Module: the unit, the socket, portRange, fps default 5 cap 10, bind default loopback, openFirewall default false. No host firewall edit unless you ask for the phone path separately. M A second RuntimeDirectory on /run/hhstream deleting control.sock. Copy the pointer unit's avoidance.
4 Browser pass on the host, written down with what was actually on screen. S An empty container looking like a broken stream. Confirm the window is on hh-<id> first.

Open questions

  1. Viewer-connected stamps the idle clock; the verbs do not. Rejected alternative: the operator must touch while watching, which will reap a session at three hours mid-view.
  2. Listeners are not re-created after a restart. They are reattached if hhstream-live is still holding them.
  3. The phone does not work until /etc/nixos opts into 0.0.0.0 and the port range. Defaults stay loopback and firewalled. SSH -L works before that.
  4. The 5 fps cap is from the main output's ~46 ms JPEG, not from a measured grim -o of a container. Raise it only from a measurement.
  5. IPv6 is out of this slice.