# 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`](../docs/CONTRACT.md). ```bash 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. ### It films a desktop, not a browser The browser is **windowed by default** (1040×560, floating, centred), so the session's wallpaper, gaps and window borders are all in shot — that is the difference between "a screen recording of a browser" and "here is the machine I look at". `--fullscreen` gives the old full-bleed kiosk window. The desktop furniture itself lives in `/etc/nixos/hyprland-stream.nix` (wallpaper via `swaybg`, `gaps_out = 36`, a catch-all float window rule), not in this repo: it is this machine's taste, not part of the kit. Two notes for anyone editing that file: - Window rules are **v3** syntax here (`windowrule = match:class .*, float on`). The v2 spelling (`float, class:^(chromium)$`) parses as an unknown field and Hyprland draws the error *across the screen*, which lands in the recording. Always check an edit with `Hyprland --verify-config --config ` — it does not need a display, so it costs seconds instead of a rebuild. - `hyprctl` **cannot connect** to this session: the compositor names its IPC socket `.socket.so`/`.socket.s` instead of `.socket.sock`, so nothing using the documented path works. Do not plan on `hyprctl` for window control — measure what you need from the frames instead. ### 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: ```bash buzz upload file --file agent-eyes.mp4 # -> {"url": ".../media/.mp4"} buzz media get -o check.mp4 "" # fetch it back and compare sha256 ``` `buzz upload file` takes `--file `, 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.