`services.hyprland-headless-stream.sessions.stream.enable` (default **false**)
runs `hhstream-live` and hands the broker `/run/hhstream/live.sock`. Running it
still turns nothing on: a stream exists only for the sessions
`hhstream session stream enable` was run on, which is the plan's rule that a
stream is never on for all sessions at all times.
A fourth unit rather than a flag on an existing one, for the pointer driver's
reason: `grim` blocks tens to hundreds of milliseconds, so the capture must not
run where `touch` and `kill` are answered, and a LAN-facing HTTP parser must not
run in the frame server whose one-socket contract cannot grow one.
Two things the unit must be handed, both of them MEASURED failures rather than
precautions:
1. **The capture command, spelled out, with grim's store path.** A unit's
`PATH` has no `grim`
(`docs/TODO/capture-binary-and-the-unit-path.md`), and the symptom is a
stream that answers with an empty frame area and says why only in the
daemon's journal. Every word is passed as `--capture-command=<word>` and not
`--capture-command <word>`, because grim's last word is a bare `-` and
argparse reads a lone dash as an option prefix rather than a value -- a unit
crash-looping with "expected one argument", which is how that form was
chosen.
2. **The compositor's session.** `XDG_RUNTIME_DIR` on the unit plus `execLive`,
which discovers whichever `wayland-N` the compositor actually bound and
exports it -- `execServer`'s trick, for `execServer`'s reason: the name is
only known once the compositor is up, so it cannot be an `Environment=`
line. Without it the unit was `active (running)`, the broker attached,
`stream status` said `attached: true`, and every capture exited 1 with
"XDG_RUNTIME_DIR is invalid or not set in the environment" until the
publisher gave up after ten in a row. checks/vm-stream.nix found that on its
first real run, which is the whole reason that check reads bytes instead of
asserting a 200.
`SupplementaryGroups` gets the compositor's group for the pointer driver's
reason one step further -- this one has to *capture*, not merely find the
socket -- and there is deliberately no `RuntimeDirectory=`: a second one on
/run/hhstream would delete the broker's control socket when this unit stopped,
which the plan names as the Stage 3 risk.
`sessions.stream.fps` is the daemon's own default and nothing else sends one, so
the option changes what actually happens; the port and bind address are the
daemon's too, and the broker learns the URL from it.
`nix/package.nix` names `hhstream_live.control` and `hhstreamd.live` in
`pythonImportsCheck`: they are the one pair in this package that has to agree
with each other across two processes, so an import error in either is worth
finding at build time rather than the first time an operator enables a stream.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011ZeH65zd6pFTgBSu52W9PE