wlthumbs

A tiny Wayland client that captures thumbnails of every open window (and, optionally, every monitor) over a single Wayland connection, using the wlroots capture protocols:

• ext-foreign-toplevel-list-v1 — enumerate windows
• ext-image-capture-source-v1 — a capture source from a toplevel handle or output
• ext-image-copy-capture-v1 — copy a frame into a wl_shm buffer

It scales each frame in-process and writes a small PNG, printing one tab-separated row per source:

TYPE <TAB> ID <TAB> THUMBPATH <TAB> APP <TAB> TITLE

• TYPE — window or output
• ID — the window's foreign_toplevel_identifier (matches sway's foreign_toplevel_identifier) or the output name (e.g. DP-1)
• THUMBPATH — path to the PNG, or empty if that source failed to capture
• APP — app_id (window) or make model (output)
• TITLE — window title, or output name

It does one thing: dump window/monitor thumbnails for a shell front-end (e.g. a rofi grid) to consume. It does not draw any UI.

Usage

wlthumbs [-size N] [-dir DIR] [-windows] [-outputs]

• -size N max thumbnail dimension in px (default 256)
• -dir DIR output directory (default: a fresh temp dir under $XDG_RUNTIME_DIR)
• -windows capture windows (default true)
• -outputs also capture monitors (default false)

Each thumbnail is named <ID>.png (the ID column), so a caller that already knows the id can find the file directly — "$dir/$id.png" — without parsing stdout; a missing file means that source failed to capture.

The caller owns -dir's lifetime — wlthumbs never deletes thumbnails (a front-end typically reads them after wlthumbs exits). With no -dir, PNGs land in a temp dir under $XDG_RUNTIME_DIR that you should clean up yourself.

Set WLTHUMBS_TIME=1 to print phase timings to stderr.

Example — thumbnail every window, then feed a rofi grid:

wlthumbs -size 220 | while IFS=$'\t' read -r type id thumb app title; do
    printf '%s\x00icon\x1f%s\n' "$title" "$thumb"
done | rofi -dmenu -show-icons

Building

go build -o wlthumbs .

Requires a wlroots-based compositor (sway, etc.) advertising the three ext-* protocols above. Pure Go — no cgo.

Notes

• Captures run sequentially on the one connection (wlroots does not parallelize them); each frame is scaled/encoded on a worker goroutine while the next window is captured, so encode cost hides under capture time.
• The protocol bindings in proto/ are generated from the XML in protocol/ and committed. See generate.sh to regenerate (and the manual patch it documents).
• Two go-wayland quirks are worked around in the code: Registry.Bind writing a padded string length (rejected by newer libwayland — see bind in wayland.go), and no support for server-allocated objects (see proto/register.go).

Source layout

• main.go — CLI flags, orchestration, phase timing (WLTHUMBS_TIME)
• wayland.go — the Wayland client: connect/bind globals, enumerate toplevels and outputs, and capture one frame per source
• image.go — shm pixel-format handling, output-transform, scaling, PNG output
• proto/ — generated protocol bindings (+ register.go); see generate.sh