autoshot-lab

autoshot-lab is a small capture pipeline for producing polished, repeatable app screenshots and short video recordings without depending on the current desktop session.

It is designed for agent-driven iteration: launch an app in an isolated virtual display, capture the real rendered window, crop the useful scene, inspect the result, and adjust presets until the image or recording is README-ready.

The preferred renderer uses Kitty inside a nested Hyprland session, because Hyprland provides compositor-side rounded corners and blur while Kitty provides real terminal background transparency through background_opacity. A Weston-based fallback remains available for simpler environments, but it uses post-composition for the visual effects.

Kitty is launched with --config NONE, a temporary XDG_CONFIG_HOME, and explicit command-line overrides, so it does not read or modify the user's real Kitty config.

First Target

The first preset renders an unpipe demo:

scripts/render.py presets/unpipe-duf-hyprland.json

The older Weston fallback preset is still available:

scripts/render.py presets/unpipe-duf.json

There is also an intentionally exaggerated diagnostic preset for checking whether blur and transparency are visible:

scripts/render.py presets/unpipe-duf-extreme.json

To render with a random local background image:

scripts/render.py presets/unpipe-duf-random-bg.json

To record short Hyprland video demos:

scripts/render.py presets/unpipe-duf-batcat-video.json
scripts/render.py presets/unpipe-duf-watch-video.json

On Ubuntu or other hosts without packaged Hyprland, run the same presets through the Arch/Hyprland container:

scripts/render-arch-hyprland scripts/render.py presets/unpipe-duf-batcat-video.json
scripts/render-arch-hyprland scripts/render.py presets/unpipe-duf-watch-video.json

Output:

assets/screenshots/unpipe-duf.png
assets/screenshots/unpipe-duf-extreme.png
assets/screenshots/unpipe-duf-random-bg.png
assets/screenshots/unpipe-duf-hyprland.png
assets/videos/unpipe-duf-batcat.mp4
assets/videos/unpipe-duf-watch.mp4

Requirements

• Python 3 standard library
• Kitty
• ImageMagick magick
• unpipe and duf for the default preset
• batcat for the batcat video preset
• wf-recorder for Hyprland video capture
• Docker with /dev/dri access for the Arch/Hyprland container runner
• script from util-linux for demos that need a pseudo-terminal, such as unpipe --watch

For the preferred Hyprland real-effects backend on Arch:

sudo pacman -S hyprland xdg-desktop-portal-hyprland grim slurp swaybg kitty imagemagick jq wf-recorder

The container runner builds an archlinux:latest image with the same Hyprland stack and starts seatd inside the container. It uses --privileged plus /dev/dri access because headless Hyprland needs a working DRM/libseat backend. Set UNPIPE_BIN=/path/to/unpipe when the binary is not at /home/horo/Repositories/unpipe/target/release/unpipe.

For the current Weston fallback:

sudo pacman -S weston kitty imagemagick

Repo Layout

AGENTS.md              visual quality rules for agents
docker/                Arch/Hyprland container runner image
presets/               screenshot presets
backgrounds/           optional background images
scripts/render.py      renderer/compositor
assets/screenshots/    committed screenshot outputs
assets/videos/         generated video outputs
output/                temporary render intermediates

Notes

The renderer creates a throwaway Wayland compositor, starts the app there, captures the real rendered terminal, crops the useful content, and tears the processes down after the screenshot is written. The Hyprland backend uses a real wallpaper surface plus compositor blur/rounding; the Weston fallback keeps the older post-composited effects for compatibility.

Hyprland presets can set "capture": {"kind": "video"} to record the cropped terminal window with wf-recorder instead of taking a still screenshot. The renderer starts the recorder before releasing the terminal command, so short commands and alternate-buffer transitions are captured from the beginning. For bounded demos that intentionally use timeout, set "allowed_statuses" to include 124.

Some interactive commands require more than Kitty's normal child process. For example, unpipe --watch checks that stdin and stdout are terminals; when it is run through a non-PTY wrapper the recording can look blank even though the process exits successfully. Wrap those commands with script -qfec "..." /dev/null so the demo sees a real pseudo-terminal. Avoid appending a non-watch fallback command after the timeout, because that can clear or overwrite the visible watch state before the recorder stops.

When sharing generated MP4s through chat clients, send videos separately from screenshots and prefer document/file mode. Some clients delay or drop combined image-plus-video preview uploads even when the rendered file itself is valid.

The Hyprland backend disables Xwayland on purpose. On the current nested headless setup, Xwayland can crash during startup and surface a host desktop crash notification. This means the Hyprland backend can only screenshot Wayland-native apps. X-only apps are not supported unless a separate backend is added or Xwayland support is made reliable for this launch mode.

Transparency is handled conservatively. Terminal presets should use app-native support such as Kitty background_opacity so text stays fully opaque. Generic apps are treated as opaque unless the app itself supports transparency; if a generic app needs a tiny transparency effect, use whole-window post opacity only at very low values because it fades all content.

Local wallpapers can be placed in backgrounds/local/. That folder is ignored by git. Folder backgrounds support "selection": "random", plus "first" and "last" for deterministic checks.