autoshot-lab

autoshot-lab is a small screenshot pipeline for producing polished, repeatable app screenshots 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 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

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

Requirements

• Python 3 standard library
• Kitty
• ImageMagick magick
• unpipe and duf for the default preset

For the preferred Hyprland real-effects backend on Arch:

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

For the current Weston fallback:

sudo pacman -S weston kitty imagemagick

Repo Layout

AGENTS.md              visual quality rules for agents
presets/               screenshot presets
backgrounds/           optional background images
scripts/render.py      renderer/compositor
assets/screenshots/    committed screenshot 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.

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.