Skip to content

README.md

Latest commit

 

History

History
280 lines (225 loc) · 13.7 KB

README.md

File metadata and controls

280 lines (225 loc) · 13.7 KB
Raw

wayland-feather-shot

Flameshot-style screenshot tool, built Wayland-first. 100% local — no upload button, no accounts, no telemetry, no network code at all.

Those are design rules, not just the current state: every capture goes through the desktop portal, nothing works around the compositor, and nothing leaves the machine. Changes that need otherwise are out of scope.

tools

Features

  • Region capture with in-place annotation — the screen is frozen via the xdg-desktop-portal, you drag a selection (with resize handles), and a Flameshot-style floating toolbar appears under it.
  • Tools: pen, line, arrow, rectangle, ellipse, highlighter, text, blur, pixelate, auto-numbered markers (①②③), crop, undo/redo, color & line-width pickers.
  • Ctrl+S saves instantly to ~/Pictures/Screenshots/, Ctrl+C copies to the clipboard, Ctrl+Shift+S = save-as, Ctrl+O opens the save folder, Esc cancels, Enter = copy & close.
  • Scrolling capture — records the screen while you scroll (ScreenCast portal + PipeWire), automatically keeps one frame per pause, and stitches them into one tall image. Sticky headers/footers are auto-detected and de-duplicated.
  • Wayland-native by design: every capture goes through org.freedesktop.portal.Screenshot / ScreenCast. No X11 fallbacks, no compositor-specific hacks — works on GNOME, KDE Plasma, Hyprland, Sway and anything else with a portal backend.
  • Default hotkeys: Ctrl+PrtSc for the full screen and Ctrl+Shift+PrtSc for a region (see below).
  • English / Japanese UI out of the box (follows LANG; override with WFS_LANG). More languages via gettext catalogs — see po/.

Install

On Arch / CachyOS, install from the project's signed pacman repository. These four commands trust the signing key, add the repository to /etc/pacman.conf (the grep guard skips the append when it is already there), and install; later releases then arrive with pacman -Syu:

$ curl -fsSLo /tmp/wayland-feather-shot.asc https://raw.githubusercontent.com/hjosugi/wayland-feather-shot/main/packaging/pacman/wayland-feather-shot.asc
$ sudo pacman-key --add /tmp/wayland-feather-shot.asc && sudo pacman-key --lsign-key A9C10C8ABD51260035B8EA525FEC84546891A5E4
$ grep -q '^\[wayland-feather-shot\]' /etc/pacman.conf || printf '\n[wayland-feather-shot]\nServer = https://github.com/hjosugi/wayland-feather-shot/releases/download/pacman-repo\n' | sudo tee -a /etc/pacman.conf >/dev/null
$ sudo pacman -Syu wayland-feather-shot

Dependencies for a source install (install.sh or pip): GTK 4, PyGObject and pycairo are all it needs.

Distro Command
Arch / CachyOS sudo pacman -S --needed python-gobject gtk4 python-cairo
Debian / Ubuntu sudo apt install python3-gi python3-gi-cairo gir1.2-gtk-4.0
Fedora sudo dnf install python3-gobject gtk4 python3-cairo

Optional: GStreamer's PipeWire plugin turns on the automatic scrolling capture (gst-plugin-pipewire gst-plugins-base, gstreamer1.0-pipewire gir1.2-gst-plugins-base-1.0, or pipewire-gstreamer), and numpy makes stitching faster. Without them scrolling capture still works in manual mode, and a copy outlives the window with or without wl-clipboard.

Then:

$ ./install.sh                # user install into ~/.local
$ ./install.sh --with-hotkey  # …and register the hotkeys (GNOME: automatic)

Remove files installed by install.sh:

$ wayland-feather-shot updater remove

(A pyproject.toml is also provided, so pip install . works if you prefer pip — the GTK/GStreamer stack itself still comes from your distro.)

You also need xdg-desktop-portal plus a backend, which every mainstream Wayland desktop already ships (-gnome, -kde, -wlr, -hyprland, -gtk).

Not sure what's missing? Run the built-in environment check:

$ wayland-feather-shot diagnose

Usage

$ wayland-feather-shot            # region capture (default)
$ wayland-feather-shot full       # whole screen, already selected in the overlay
$ wayland-feather-shot copy       # select a region, straight to the clipboard
$ wayland-feather-shot window     # pick a window via the portal picker
$ wayland-feather-shot scroll     # scrolling capture (you scroll)
$ wayland-feather-shot scroll --auto  # auto-scroll via RemoteDesktop portal (experimental)
$ wayland-feather-shot gif        # record a region to an animated GIF
$ wayland-feather-shot edit x.png # open an existing image in the overlay
$ wayland-feather-shot history    # gallery of recent screenshots
$ wayland-feather-shot settings   # edit the config in a window
$ wayland-feather-shot -d 3 gui   # 3-second delay
$ wayland-feather-shot daemon     # GlobalShortcuts-portal hotkey daemon
$ wayland-feather-shot diagnose   # check portals/GTK/GStreamer availability
$ wayland-feather-shot updater remove  # remove install.sh-managed files

Every picture opens in the overlay: a fresh capture, a file (edit), one reopened from the history with its annotations, and a window or scrolling capture. Besides the tools above it has, under "…" and when tesseract / zbarimg are installed, OCR / QR extraction that copies recognized text to the clipboard and smart redaction that proposes blurs over text that looks sensitive, and a background frame (fill, padding, rounded corners, shadow, border, watermark) for the result. Ctrl+O opens the save folder; images save as PNG/JPEG/WebP/AVIF by extension, with an editable <image>.wfs.json next to them when they have annotations.

Annotations stay editable after they are drawn. With the hand (S) you pick a shape (Shift- or Ctrl-click for several), then move it, resize it from eight handles, rotate it from the handles just outside the corners, nudge it with the arrow keys and reorder with Ctrl+↑ / Ctrl+↓; a double-click on a text or bubble types into it again. Holding Shift keeps a corner resize proportional and snaps a rotation to 15°.

The overlay has a camera: Ctrl+scroll or Ctrl + + / - to zoom, scroll to pan while zoomed in, Ctrl+1 to fit the selection and Ctrl+0 to see everything — so a 4K capture can be annotated at the pixel rather than guessed at while shrunk to fit.

Stroke widths, font sizes and badge diameters are authored against a reference image size, so the same settings look the same on a 1080p and a 4K capture.

Scripting

gui and full take non-interactive options so captures can be automated:

$ wayland-feather-shot full --no-editor                 # save, print the path, exit
$ wayland-feather-shot full --region 0,0,1280,720 -o a.png --no-editor
$ wayland-feather-shot full -o ~/shot.png               # open the overlay, Ctrl+S → that path

--region X,Y,W,H crops the capture (clamped to the screen), --output/-o PATH chooses the file (PNG/JPEG/WebP by extension), --no-editor skips the UI and prints the saved path. Exit codes: 0 ok, 1 error, 2 bad usage, 130 cancelled — suitable for shell scripts.

Region capture

  1. The screen freezes. Drag to select (click or Enter = full screen). With Ctrl+PrtSc (full) the whole screen starts out selected; the handles still cut a part out of it.
  2. Annotate right on the selection — toolbar keys: V move/resize the selection, S hand (pick, move, resize and rotate placed shapes), P pen, L line, A arrow, G numbered step arrow, R rect, E ellipse, H highlighter, T text, U speech bubble, B blur, X pixelate, O spotlight, M numbered marker, J emoji. OCR, QR, smart redaction and the background frame are under "…".
  3. Ctrl+S save • Ctrl+O open save folder • Ctrl+C / Enter copy • Ctrl+Z undo • Esc cancel.

Scrolling capture

  1. wayland-feather-shot scroll — pick the window/screen in the portal dialog.
  2. Scroll the content slowly top→bottom, pausing briefly after each scroll (each pause is captured automatically — watch the frame counter).
  3. Press Finish & stitch. The stitched tall image opens in the overlay, fitted to the width and scrolled to the top; Ctrl+S / Ctrl+C as usual.

The trick is to scroll slowly and pause for a moment after each scroll. Sticky headers and footers are detected and de-duplicated automatically; to pin them by hand instead, set scroll_top_margin / scroll_bottom_margin in ~/.config/wayland-feather-shot/config.json.

Optional auto-scroll (experimental)

wayland-feather-shot scroll --auto — or the Auto-scroll checkbox in the recording window — drives the scrolling for you through the org.freedesktop.portal.RemoteDesktop portal instead of you scrolling by hand. It is opt-in and never the default: injecting synthetic input needs a per-session permission dialog, so manual scrolling stays the safe, portable path. Hover the pointer over the scrollable content first — the portal delivers the scroll wheel wherever the pointer sits. Auto-scroll stops on its own at the bottom of the page (no new frames) or after scroll_auto_steps steps; tune scroll_auto_delta / scroll_auto_interval / scroll_auto_steps in config.json. It needs the GStreamer/PipeWire recorder too — the GStreamer-free fallback cannot be auto-driven.

Portal support varies by desktop; run wayland-feather-shot diagnose to see whether scroll --auto will work on your machine:

Desktop RemoteDesktop portal Notes
GNOME (Mutter) yes permission dialog once per session
KDE Plasma yes permission dialog once per session
Hyprland / wlroots (xdg-desktop-portal-wlr) usually no the checkbox stays disabled — scroll manually
Sway usually no scroll manually

Default hotkeys: Ctrl+PrtSc and Ctrl+Shift+PrtSc

On Wayland there is no portable way for an app to grab a global key — the compositor decides. Two mechanisms cover the field; pick the row for your desktop (or just run wayland-feather-shot diagnose, which detects your desktop and prints the exact command):

Desktop Recommended How
GNOME native shortcut ./scripts/setup-hotkey.sh (gsettings, idempotent)
GNOME 46+ portal daemon autostarted wayland-feather-shot daemon
KDE Plasma portal daemon autostarted wayland-feather-shot daemon (approve once)
Hyprland native shortcut bind = CTRL, Print, exec, wayland-feather-shot full (and CTRL SHIFT → gui)
Sway / wlroots native shortcut bindsym Ctrl+Print exec wayland-feather-shot full (and Ctrl+Shift → gui)
other native shortcut bind wayland-feather-shot full and gui in your settings

Ctrl+PrtSc takes the full screen (already selected, so the handles can still cut a part out) and Ctrl+Shift+PrtSc selects a region. wayland-feather-shot copy (select a region, straight to the clipboard) has no default key; bind it by hand if you want it. Step-by-step setup for each desktop, what the portal daemon needs, and every in-app key: docs/HOTKEYS.md.

If pressing the key does nothing, first check the capture itself works:

$ wayland-feather-shot gui        # if this opens the overlay, capture is fine
$ wayland-feather-shot diagnose   # detects your desktop + prints the binding
$ wayland-feather-shot daemon --bind-once   # test the portal binding, then exit

If gui works but the key doesn't, it's the binding mechanism — use the table above. The daemon logs every activation and the exact command it launches to stderr, so wayland-feather-shot daemon in a terminal shows what happens when you press the key. You can override the portal trigger with wayland-feather-shot daemon --shortcut SUPER+Print.

Configuration

~/.config/wayland-feather-shot/config.json (created on first run): save directory, filename pattern, default color/width, blur strength, scroll-capture margins and limits. See src/wayland_feather_shot/util/settings.py.

save_dir defaults to empty = automatic: the OS/XDG Pictures directory (localized, e.g. ~/画像) plus /Screenshots. The Ctrl+O save-folder button opens this same resolved folder. Set save_dir to a path to override.

Troubleshooting

Start with wayland-feather-shot diagnose — it checks GTK, pycairo, wl-clipboard, GStreamer/PipeWire and the portal interfaces, and tells you what's missing.

  • Nothing happens / error dialog about the portal — make sure xdg-desktop-portal and your desktop's backend are running (systemctl --user status xdg-desktop-portal). On wlroots compositors you need xdg-desktop-portal-wlr and xdg-desktop-portal-gtk (for the file chooser), plus XDG_CURRENT_DESKTOP exported to your session.
  • Copy disappears after closing — the copy is kept alive by a bundled holder process (or wl-copy if installed), so it should survive closing the window. If neither can start, the UI says to keep the window open until you paste.
  • Scroll capture without GStreamer — if the GStreamer PipeWire plugin (gst-plugin-pipewire / gstreamer1.0-pipewire) is missing, scroll falls back to a manual mode: pick an area, then scroll and press Capture frame for each step. Installing the plugin enables the smoother automatic frame-keeping instead.

Development

$ python3 tests/test_stitcher.py   # stitching engine unit tests (no GTK needed)
$ python3 tests/test_paths.py      # XDG paths + diagnostics tests (no GTK needed)
$ ./bin/wayland-feather-shot gui   # run from the repo without installing

Design notes live in docs/ARCHITECTURE.md and docs/SECURITY.md. Known limitations and the roadmap are tracked as GitHub issues.

License: MIT