5.8 KiB
swappy
A Wayland native snapshot and editor tool, inspired by Snappy on macOS. Works great with grim, slurp and sway. But can easily work with other screen copy tools that can output a final image to stdout
. See below.
Screenshot
Example usage
Output of grim
(or any tool outputing an image file):
grim -g "$(slurp)" - | swappy -f -
Swappshot a PNG file:
swappy -f "~/Desktop/my-gnome-saved-file.png"
Print final surface to stdout (useful to pipe with other tools):
grim -g "$(slurp)" - | swappy -f - -o - | pngquant -
Grab a swappshot from a specific window under Sway, using swaymsg
and jq
:
grim -g "$(swaymsg -t get_tree | jq -r '.. | select(.pid? and .visible?) | .rect | "\(.x),\(.y) \(.width)x\(.height)"' | slurp)" - | swappy -f -
Config
The config file is located at $XDG_CONFIG_HOME/swappy/config
or at $HOME/.config/swappy/config
.
The file follows the GLib conf
format. See the man
page for details. There is example config file here.
The following lines can be used as swappy's default:
[Default]
save_dir=$HOME/Desktop
save_filename_format=swappy-%Y%m%d-%H%M%S.png
show_panel=false
line_size=5
text_size=20
text_font=sans-serif
paint_mode=brush
early_exit=false
fill_shape=false
save_dir
is where swappshots will be saved, can contain env variables, when it does not exist, swappy attempts to create it first, but does not abort if directory creation failssave_filename_format
: is the filename template, if it contains a date format, this will be parsed into a timestamp. Format is detailed in strftime(3). If this date format is missing, filename will have no timestampshow_panel
is used to toggle the paint panel on or off upon startupline_size
is the default line size (must be between 1 and 50)text_size
is the default text size (must be between 10 and 50)text_font
is the font used to render text, its format is pango friendlypaint_mode
is the mode activated at application start (must be one of: brush|text|rectangle|ellipse|arrow|blur, matching is case-insensitive)early_exit
is used to make the application exit after saving the picture or copying it to the clipboardfill_shape
is used to toggle shape filling (for the rectangle and ellipsis tools) on or off upon startup
Keyboard Shortcuts
Ctrl+b
: Toggle Paint Panel
b
: Switch to Brusht
: Switch to Textr
: Switch to Rectangleo
: Switch to Ellipsea
: Switch to Arrowd
: Switch to Blur (d
stands for droplet)
R
: Use Red ColorG
: Use Green ColorB
: Use Blue ColorC
: Use Custom ColorMinus
: Reduce Stroke SizePlus
: Increase Stroke SizeEqual
: Reset Stroke Sizef
: Toggle Shape Fillingk
: Clear Paints (cannot be undone)
Ctrl
: Center Shape (Rectangle & Ellipse) based on draw start
Ctrl+z
: UndoCtrl+Shift+z
orCtrl+y
: RedoCtrl+s
: Save to file (see man page)Ctrl+c
: Copy to clipboardEscape
orq
orCtrl+w
: Quit swappy
Limitations
- Copy: If you don't have wl-clipboard installed, copy to clipboard won't work if you close swappy (the content of the clipboard is lost). This because GTK 3.24 has not implemented persistent storage on wayland backend yet. We need to do it on the Wayland level, or wait for GTK 4. For now, we use
wl-copy
if installed and revert togtk
clipboard if not found. - Fonts: Swappy relies on Font Awesome 5 being present to properly render the icons. On Arch you can simply install those with:
sudo pacman -S otf-font-awesome
Installation
Building from source
Install dependencies (on Arch, name can vary for other distros):
- meson
- ninja
- cairo
- pango
- gtk
- glib2
- scdoc
Optional dependencies:
wl-clipboard
(to make sure the copy is saved if you close swappy)otf-font-awesome
(to draw the paint icons properly)
Then run:
meson setup build
ninja -C build
i18n
This section is for developers, maintainers and translators.
To add support to a new locale or when translations are updated:
- Update
src/po/LINGUAS
(when new locales are added) - Generate a new
po
file (ignore and do not commit potential noise in other files):
ninja -C build swappy-update-po
To rebuild the base template (should happen less often):
ninja -C build swappy-pot
See the meson documentation for details.
Contributing
Pull requests are welcome. This project uses conventional commits to automate changelog generation.
Release
We rely on standard-version which is part of the JavaScript ecosystem but works well with any project.
./script/github-release
Make sure everything is valid in the Draft release, then publish the draft.
Release tarballs are signed with this PGP key: F44D05A50F6C9EB5C81BCF966A6B35DBE9442683
License
MIT