Files
hyprland-headless-stream-pl…/examples

examples

agent-eyes-demo.py

Puts a real browser on the headless screen, drives it, and films the result by reading frames off the published socket — the consumer side of docs/CONTRACT.md.

nix develop
sg hhstream -c 'python3 examples/agent-eyes-demo.py --query "Ari Sosnovsky"'

Output is an MP4 (default agent-eyes.mp4): the Google homepage, the query typed in a letter at a time, then the results page — captured from the compositor, not from a screencast API.

Everything else is a flag: --seconds, --capture-fps, --output, --work-dir, --keep-work, --debug-port, --clear-screen. --help is accurate.

What it checks rather than assumes

  • the session is up and the socket is readable (a clear message if your user is not in the stream's group);
  • the browser actually reached a results page — it presses Enter, then waits for the URL to change, and submits the form directly if Enter did nothing;
  • it fails on Google's /sorry/ bot wall instead of encoding a video of a CAPTCHA, because a video that looks like a working demo and is not one is worse than no video.

Three things that will bite you

  1. Your shell needs the group. The socket is 0660 hhstream:hhstream inside a 0750 directory; a browser also has to reach the session's Wayland socket in the same directory. Add yourself to hhstream (this is what /etc/nixos/hyprland-stream.nix does for hermes) and log in again — or use sg hhstream -c '...' for the shell you already have open.
  2. Google rate-limits you. The first search from a fresh profile usually passes; the third in a minute gets unusual traffic. It is the IP, not the browser. Wait a few minutes and re-run.
  3. The frame server tops out around 12 fps on a software-rendered VM (grim plus a PNG encode per frame, competing with the browser for two cores). Leave --capture-fps at its default of 30 so nothing is thrown away: the encoder uses the measured rate, so the video plays at real speed either way, and decimating only makes it choppier.

Posting the result to a chat

Xiph/Blossom media stores reject files that carry metadata. encode() in the script already strips it with -map_metadata -1 -fflags +bitexact -flags:v +bitexact; without those flags a Buzz relay answers 422 media contains metadata or a non-canonical metadata channel and the upload fails. Uploading from the command line, with the same script-encoded file:

buzz upload file --file agent-eyes.mp4          # -> {"url": ".../media/<sha256>.mp4"}
buzz media get -o check.mp4 "<url>"             # fetch it back and compare sha256

buzz upload file takes --file <path>, not a positional argument, and exits 0 with a JSON error on stdout when the relay refuses the type — read the output, never the exit status.