~whynothugo/shotman

Uncompromising screenshot GUI for Wayland 
This has been fixed in wayland-rs
Explicitly match ()
Use empty type to identify Dispatch impls

refs

main
browse  log 
v0.4.5
release notes 

clone

read-only
https://git.sr.ht/~whynothugo/shotman
read/write
git@git.sr.ht:~whynothugo/shotman

You can also use your local clone with git send-email.

#shotman

Source | Issues | Patches | Chat

The uncompromising screenshot GUI for Wayland compositors.

shotman takes a screenshot and shows it in a small floating thumbnail window. The screenshot can then copied with ctrl+c, deleted with d, or dismissed with Esc.

shotman is designed to run in response to some global hotkey (e.g.: Super+P, PrintScreen, etc). It is designed for interactive usage.

#Goals

  • Fast (less than 80ms to render the screenshot window on a 2018 laptop)
  • Simple design (delegates as much as possible to the compositor; avoids unnecessary work)

#Requirements

#Build requirements

Building from source requires:

  • Rust and cargo (1.66 is known to work)
  • libxkbcommon (1.50 is known to work)

Note that slightly older Rust and libxkcommon versions may work, they are merely untested.

It is recommended to build by cloning the git repository, so the right version is extracted from version control. Otherwise, set SHOTMAN_VERSION explicitly.

#Runtime requirements

A wayland compositor which support the following is required:

  • wlr_layer_shell
  • wlr_screencopy
  • single-pixel-buffer-v1

Additionally, for taking screenshots of a region, slurp>=1.4.0 is required.

Taking screenshots of the currently active window works only on sway and requires swaymsg.

Currently, sway has been tested, but any wlroots-based compositor should work (except for the window command, as mentioned above). Feedback on results for other compatible compositors is most welcome.

#Shell completions

When building, an additional binary is compiled. This binary can generate shell completions for commons shells. It can be used via:

./target/release/shotman_completions zsh
./target/release/shotman_completions bash
./target/release/shotman_completions fish

Packagers are encouraged to ship the completions themselves, but not the binary (since it serves no additional purpose).

#Usage

  • shotman --capture output takes a screenshot of the currently active output.
  • shotman --capture window takes a screenshot of the currently active window (sway-only).
  • shotman --capture region takes a screenshot of a custom region (requires slurp).

The --copy parameter may be specified to automatically copy the screenshot into the clipboard.

#Keyboard controls

  • Esc or q: exit/quit, keeping the saved the screenshot
  • Del or d: deleting/discard the screenshot and exit
  • Ctrl+C or XF86Copy: copy the screenshot into the clipboard
  • Ctrl+X or XF86Cut: cut the screenshot file into the clipboard
  • Space: Unfocus screenshot window
  • f: Toggle fullscreen (not implemented)
  • e: Edit image (see below for details) (still unstable)
  • h,j,k,l: move preview to another corner

Hint: a deleted screenshot will remain in clipboard until something else is copied to the clipboard, or the shotman process is killed.

Hint: when copying a screenshot and closing shotman, it will continue running in the background to hold the clipboard. It will exit automatically when the another application takes over the clipboard.

Note: While the window can be focused with Space, it can only be focused again by hovering with a pointer. Consider closing it with Esc after copying/cutting instead.

#Mouse controls

Not yet implemented

  • Button for Done.
  • Button for Copy.
  • Button for Delete.
  • Dragging the image onto another application drags-and-drops it.

#Touch controls

Not yet implemented

The intent of touch-based controls is for this UI to be usable on tables and phones.

  • Buttons work the same.
  • Swiping the window towards another corner changes the anchor.
  • Swiping the window towards the edge of the screen dismissed it.

#Image editor

By default gimp will be used to edit a screenshot. This can be overridden by using --image-editor PROG or by defining the IMAGE_EDITOR environment variable. For example:

shotman --capture output --image-editor drawing
export IMAGE_EDITOR=drawing
shotman --capture output

#Building

shotman can be built using cargo build --release. The resulting binary will be located in ./target/release/shotman. Copy this into your $PATH.

#Sway configuration

A recommended sway configuration is:

bindsym $super+p       exec shotman --capture window
bindsym $super+Shift+p exec shotman --capture region
bindsym $super+Ctrl+p  exec shotman --capture output

#Caveats

Only a few common buffer formats are supported. Saving the PNG screenshot will fail for other formats. I'm not sure that any compositor implements screencopy and could return another format. If so, please report the issue.

#Prior art

This section is incomplete.

  • grim: works great, for its own use case. It is a lower-level cli tool, and saves into a file. Rendering that file as a thumbnail is slow because it requires an entire encoding -> decoding round trip. I still use and recommend grim for scripted usage or scenarios where the thumbnail window is not required.
  • grimshot: same as above.
  • swappy: doesn't save the file by default. Slow to start up and in general. The editor is pretty good. Its editor is worth considering as an editor for the e key mapping.
  • flameshot: doesn't work on wayland?.
  • spectacle: mentions it works on "non-KDE X11", but nothing about wayland (not: haven't tried it).

This section is incomplete.

#Changelog

#v0.4.5

  • Fix Makefile ignoring the PREFIX environment variable.

#v0.4.4

  • Implement --image-editor. The IMAGE_EDITOR environment variable is still used as a fallback.
  • Fix blank screenshots in some multi-display configurations.
  • Various documentation fixes.
  • Add a Makefile to simplify downstream packaging or installing from source.

#v0.4.3

  • Errata: the v0.4.2 changelog shows an entry that was dropped before release.

#v0.4.2

  • Introduced IMAGE_EDITOR environment variable (see README for further details).
  • Thumbnails are now slightly larger.
  • Fix build issue handling SHOTMAN_VERSION.
  • Add support for XRGB2101010 and XBGR2101010 pixel formats.
  • The --verbose flag now takes a named log level (e.g.: info, trace, etc).
  • The single-pixel-buffer-v1 protocol is now used to render single-pixel buffers. Only compositors with compatible with this protocol are supported.
  • The thumbnail window border colour now changes when focused.
  • Copying now also copies the file path into the clipboard as text/uri-list. File managers and other applications will paste by copying the file directly. This works on dolphin, and does not work on nemo. Cutting file is not possible on Wayland, so this new behaviour does not apply when cutting.

#v0.4.1

  • Fixed output of --version.
  • Added documentation for shell completions.

#v0.4.0

  • Added helper to generate shell completions.

#Prior versions

There's no changelog for prior versions; this was too experimental.

#Licence

shotman is licensed under the ISC licence. See LICENCE.md for details.