wlr-shot

Screen capture for wlroots compositors, built on the shared wlr-capture engine (ext-image-copy-capture-v1, correct strides, occlusion-independent).

Status: early. It captures an output, a region (interactive -s or -g/slurp), or a window — as a screenshot (PNG/JPEG/PPM) or an H.264 recording / timelapse.

Usage

wlr-shot screenshot [-o NAME | -g GEOM | -w ID | --pick-window]
                    [-t png|jpeg|ppm] [-q QUALITY] [-c] [FILE|-]
wlr-shot screenshot --list-outputs
wlr-shot record [-o NAME | -g GEOM | -w ID | --pick-window | -s | -a]
                [--encoder auto|nvenc|vaapi|software] [--fps N]
                [--timelapse INTERVAL] [-d SECS] FILE

Source (pick one; defaults to the sole output):

• -s, --select — interactively drag a region on a frozen overlay (spans all outputs; Esc cancels, Enter confirms). No external tool needed.
• -o, --output NAME — a whole output (e.g. DP-4).
• --all — the whole layout: every output combined into one image.
• -g, --geometry "X,Y WxH" — a logical region (the format slurp prints), stitched across every output it covers. Pairs with slurp: wlr-shot screenshot -g "$(slurp)" shot.png.
• -w, --window ID — a window, by its ext-foreign-toplevel identifier (as printed by wlr-chooser).
• --pick-window — launch wlr-chooser to choose the window interactively.
• -a, --active-window — the focused window.
• --current-output — the focused output.

The last two need the compositor's focus info. Wayland exposes no portable way to query focus, so these use compositor IPC: Sway (swaymsg) is supported today; Hyprland / niri are natural future additions. Without a supported compositor they error with a hint (use --pick-window / -o NAME instead).

Encoding & destination:

• -t, --type — png (default), jpeg, or ppm.
• -q, --quality — JPEG quality, 1–100 (default 90).
• -c, --clipboard — copy to the Wayland clipboard instead of writing a file. A small daemon detaches to serve the selection (wlroots data-control, the protocol wl-copy uses) until another client replaces it — the clipboard is pull-based, so the data must outlive the command. --clipboard-foreground keeps it in the foreground (for scripts/debugging). Needs a compositor exposing zwlr_data_control_manager_v1.
• FILE — destination, or - for stdout (the default). Ignored with --clipboard.
• --list-outputs — print NAME<TAB>WxH+X,Y (logical geometry) and exit.

Resolution: a whole output, or a region within a single output, is captured at native (physical) resolution — so a fractionally-scaled monitor keeps full pixel detail. A region spanning several outputs is composited at logical resolution.

Recording (record)

Stream a source to a file whose format follows the extension: .mp4/.mkv for H.264 video, or .gif/.webp for an animated image (downscaled — GIF to 800 px, WebP to 1280 px on the long side — and best used on a region, since per-frame GIF quantization on a full 4K output is slow). The same source flags as screenshot apply — -o/sole output, --current-output, -w ID/--pick-window, -a, -g, and -s — except a region (-g/-s) records a single output for now (the one its top-left corner sits on). Recording a window (-w/--pick-window) follows it across workspaces and even while occluded.

wlr-shot record -o DP-4 out.mp4                 # an output, until Ctrl-C
wlr-shot record --pick-window -d 30 clip.mp4    # a window, 30 seconds
wlr-shot record -g "$(slurp)" region.mp4        # a region (single output)
wlr-shot record -g "$(slurp)" --fps 15 demo.gif # a region as an animated GIF
wlr-shot record -g "$(slurp)" demo.webp         # …or animated WebP (smaller)
wlr-shot record -o DP-4 --timelapse 2s day.mp4  # a frame every 2s, played at --fps
wlr-shot record -o DP-4 --no-audio clip.mp4     # video only (audio is on by default)

• --encoder — auto (default) prefers hardware (NVENC, then VAAPI) and falls back to software libx264. Force one with nvenc/vaapi/software.
• --device PATH — DRM render node for VAAPI (default /dev/dri/renderD128).
• --fps N — frame rate (default 30). Capture is damage-driven (a frame only arrives when the screen changes), so a normal recording emits a constant --fps, repeating the last frame through static stretches; --timelapse instead samples one frame per interval and plays them back at --fps, so the footage is sped up.
• --timelapse INTERVAL — sample one frame every INTERVAL (2s, 500ms, 1m).
• -d, --duration SECS — stop automatically; otherwise Ctrl-C ends and finalises the file. (Recording a window also ends when the window closes.)
• Audio — a video recording captures system audio (the default sink's monitor) as an AAC track by default, via native PipeWire. --no-audio records silently; --audio-source NODE captures a specific node instead (e.g. a microphone). Needs the audio build feature (on by default; links libpipewire). GIF/WebP carry no audio. For a PipeWire-less host, build with --features audio-fallback to add a Pulse/ALSA path (via FFmpeg's libavdevice, no extra system dep), tried after PipeWire.

Recording needs the video build feature (on by default), which links the system FFmpeg libraries. A screenshots-only build drops it: cargo build -p wlr-shot --no-default-features --features i18n.

Install

Want the whole suite? Install the bundle instead — cargo install wlr-utils gets every tool (wlr-chooser, wlr-switcher, wlr-peek, wlr-shot, wlr-draw) in one go. The single-tool install below is the lighter, à-la-carte option.

cargo install wlr-shot

Or build just this binary from the wlr-utils workspace:

cargo build --release -p wlr-shot

The default build records video and links the system FFmpeg libraries (see Requirements below). For a screenshots-only binary with no FFmpeg dependency: cargo build -p wlr-shot --no-default-features --features i18n.

Requirements

A wlroots compositor exposing ext-image-copy-capture-v1 with both the ext-output-image-capture-source-manager-v1 (outputs) and ext-foreign-toplevel-image-capture-source-manager-v1 (windows) sources — Sway ≥ 1.12 / wlroots ≥ 0.20, the floor for the window source. xdg-output is used for accurate logical geometry when present, and the clipboard (-c) needs zwlr_data_control_manager_v1. Run wlr-peek doctor to see what your compositor exposes.

The interactive region selector (-s) renders a frozen overlay through EGL/GLES, so every build needs a working GL stack (libegl1) at runtime. Screenshots use CPU shm capture, so no libgbm is required.

The default build (with record) additionally links the system FFmpeg libraries, so it needs their development packages at build time — on Debian/Ubuntu: libavcodec-dev libavformat-dev libavutil-dev libavfilter-dev libavdevice-dev libswscale-dev libswresample-dev libva-dev (and clang for the bindings). Hardware encoding needs the matching runtime: NVIDIA's libnvidia-encode for NVENC, or a VAAPI driver for your GPU. The default audio feature records system sound through PipeWire, linking libpipewire-0.3 (and clang to build); drop it with --features video (video only) or build screenshots-only (--no-default-features --features i18n) to need none of this.

Uninstall

cargo uninstall wlr-shot          # crates.io install; or: rm -f ~/.local/bin/wlr-shot

wlr-shot writes no config or state files — removing the binary is enough.

License

MIT OR Apache-2.0.