Satty: Modern Screenshot Annotation.

Satty is a screenshot annotation tool inspired by Swappy and Flameshot.

Satty has been created to provide the following improvements over existing screenshot annotation tools:

• very simple and easy to understand toolset (like Swappy)
• fullscreen annotation mode and post shot cropping (like Flameshot)
• extremely smooth rendering thanks to HW acceleration (OpenGL)
• working on wlroots based compositors (Sway, Hyprland, River, ...)
• minimal, modern looking UI, thanks to GTK and Adwaita
• be a playground for new features (post window selection, post paint editing, ...)

Install

Thanks to our package maintainers, Satty is available for many distributions on Linux and BSD:

For emoji support please install the "Noto Color Emoji" font.

Specifics

Distribution	Command	Note
Gentoo	emerge -av satty	You need guru overlay (see wiki). Pending PR
Alpine Linux	apk add satty	Available in Alpine Community

Cargo

You can install satty via cargo install satty and cargo binstall satty, the latter requires cargo-binstall. In that case, no manpage, LICENSE file, .Desktop file are available. But you can use the --man and --license arguments to display either.

cargo install and cargo binstall methods install satty to $HOME/.cargo/bin. Using rustup and/or installing distribution packages for the Rust toolchain should normally add this to the user's path. How environment variables such as path are set depends on shell, distribution, compositor/desktop environment etc. It's not really possible to anticipate every possible combination from an application perspective.

Prebuilt Sources

You can download a prebuilt binary for x86-64 on the Satty Releases page.

Flatpak ^0.20.1

Satty is available as a Flatpak bundle. Pre-built bundles are automatically created for each release and can be downloaded from the GitHub Releases page.

Installing from Flatpak bundle

# Download the .flatpak file from the latest release
# Then install it:
flatpak install satty-<version>.flatpak

Usage

See USAGE.md for all command line options.

Start by providing a filename or a screenshot via stdin and annotate using the available tools. Save to clipboard or file when finished. Tools and Interface have been kept simple.

# open a file
satty -f assets/usage.png
# get screenshot with slurp and grim
grim -g "$(slurp -o)" - | satty -f -
# get screenshot with DMS
dms screenshot --stdout | satty -f -

Configuration

See config.toml for the configuration.

The search order for configuration files is:

• builtin
• system wide config ($XDG_CONFIG_DIRS/satty/config.toml, usually /etc/xdg/satty/config.toml) if present ^NEXTRELEASE
• user config ($XDG_CONFIG_HOME/satty/config.toml, usually $HOME/.config/satty/config.toml) if present
• config specified in command line, if any. Please note: in this case Satty ignores the former two files, and a file not found error on the given config file becomes fatal
• command line options

Shortcuts

General

• Enter: as configured (see below), default: copy-to-clipboard (may be masked by active tool)
• Esc: as configured (see below), default: exit (may be masked by active tool)
• Shift+Delete reset (clear) ^{experimental NEXTRELEASE}
• Ctrl+C: Save to clipboard (may be masked by active tool)
• Ctrl+Shift+D or Ctrl+Shift+I: Open GTK inspector if not already opened
• Ctrl+S: Save to specified output file, creating missing folders in its path ^NEXTRELEASE
• Ctrl+Shift+S: Save using file dialog ^0.20.0. The dialog uses output-filename as initial filename/path when available and remembers the last selected folder. ^0.21.0
• Ctrl+Alt+C: Copy last saved filepath to clipboard ^0.20.1
• Ctrl+T: Toggle toolbars
• Ctrl+Y: Redo
• Ctrl+Z: Undo
• Alt+(Left/Right/Up/Down): Pan, also available with middle mouse button drag ^0.20.1

Mouse:

• Ctrl+Wheel: Zoom in/out ^0.22.0
• Middle: Pan

Touchpad: ^0.22.0

• Pinch: Zoom (two finger)
• Ctrl+Scroll: Zoom in/out (two finger scroll)
• Scroll: Pan (two finger scroll)

Color Selection Shortcuts ^0.20.1

1, 2, 3, …, 9, 0 — select nth color from the color palette

If out of range select custom color ^0.21.0

Size Selection ^0.22.0

In the bottom toolbar the size can be edited directly or by + and - buttons. Minimum is 0.1 and maximum to 99.99.

The bindings are:

• Mouse left-button, wheel and key up/down step size is 0.1
• Holding Shift will switch to 0.01 step size
• Holding Ctrl will switch to 1.0 step size
• Mouse middle-button and page up/page down step size is 1.0
• Mouse right-button jumps to minimum/maximum
• s focuses the annotation size factor input field

Tool Selection Shortcuts (configurable) ^0.20.0

Default single-key shortcuts:

• p: Pointer tool
• c: Crop tool
• b: Brush tool
• i: Line tool
• z: Arrow tool
• r: Rectangle tool
• e: Ellipse tool
• t: Text tool
• m: Numbered Marker tool
• u: Blur tool
• x: Fringe inpaint+Pixelate tool
• g: Block Highlight tool
• G: Freehand Highlight tool
• o: Image tool ^NEXTRELEASE

Overwriting Keybindings ^NEXTRELEASE

Shortcuts can be overwritten in the config by

[keybinds]
"BINDING" = "TOOL-OR-COMMAND"

Where BINDING follows the GTK syntax. This means modifiers are enclosed in angle brackets (e.g., <mod>) and keys are specified by name (for example, - must be written as minus).

Pressing any unbound key will print its name to the console.

Setting a binding to "none" will unbind it.

The defaults are listed in the config.toml.

Pointer Tool ^NEXTRELEASE

Annotations can be selected by click. This will update the toolbar to the annotation's style and allow style changes. Newly created annotations can be autoselected if enabled in the config.

• Hold Alt while clicking to select between overlapping annotations.
• Delete deletes the selected annotation.
• Drag the resize handles - mouse cursor will change - to change the size.
  • Hold Alt for centered resize
  • Hold Shift to snap to defined aspect ratios. ^NEXTRELEASE
  • Hold Control at corners for aspect ratio preserving resize. ^NEXTRELEASE
  • Hold mutiple to combine them.
• Grab an annotation - mouse cursor will change to a hand - to move.
• Scroll up/down with the mouse wheel to change the annotation's layer.
• Nudge (small move) with the cursor keys.
• Double-click on a text annotation to edit it.
• Horizontal resizing on a marker changes its number, and vertical resizing changes the extra ring.

Image Tool ^NEXTRELEASE

Click the screenshot with the tool to open a file chooser, and the picked image is inserted as an annotation centred where you clicked, scaled down to at most half the screenshot if it does not fit. Drag a box instead of clicking, and the image is scaled to fit into it with its aspect ratio kept. From there it behaves like any other annotation: select it with the pointer tool to move it, resize it by its handles or change its layer.

Images can also arrive without selecting the tool first:

• Ctrl+V pastes an image or a copied image file from the clipboard, centred on the mouse pointer. The text tool takes the shortcut for itself while it has input focus.
• Dropping an image or an image file anywhere on the window inserts it where it was dropped.

Formats are those gdk-pixbuf has a loader for, plus webp.

Tool Modifiers and Keys

Arrow and line:

• Shift to make tool snap to 15° steps.

Crop ^NEXTRELEASE, rectangle, ellipse, blur ^0.22.0, highlight block mode^0.22.0, pixelate^NEXTRELASE, fringe-pixelate^NEXTRELEASE, fringe^NEXTRELEASE, image^NEXTRELEASE:

• Alt to center the tool around origin.
• Shift to snap to defined aspect ratios. ^NEXTRELEASE
• Hold Control to preserve aspect ratio. Draws square if starting from zero size. ^NEXTRELEASE
• Hold mutiple to combine them.

Text:

• Press Shift+Enter to insert line break.
• Combine Ctrl with Left or Right for word jump or Ctrl with Backspace or Delete for word delete.
• Press Enter or switch to another tool to accept input, press Escape to discard entered text.
• Home and End go to the start/end of current line or previous/next line if already on first/last character of line (automatic wrapping is not considered for this). Ctrl with Home/End jumps to start/end of text buffer.
• Up or Down to jump to previous/next line (if already on first/last line, it jumps to the start/end of text buffer). ^0.20.1
• Combine Shift with other keys to select text (e.g. Shift+Home to select from start of line to cursor, Shift+Left to select characters before cursor, Ctrl+Shift+Left to select words before cursor,and so on) ^0.20.1
• Double-click to select word under cursor.Triple-click to select all text. ^0.20.1
• Ctrl+A to select all text. ^0.20.1
• Ctrl+C to copy selected text to clipboard. ^0.20.1
• Ctrl+X to cut selected text to clipboard. ^0.20.1
• Ctrl+V to paste text from clipboard. ^0.20.1
• Alt+Ctrl with Left or Right or Up or Down to move the text. Use Alt+Ctrl+Shift with arrow keys to nudge the text. ^0.20.1
• Press Alt to cycle the text effect: none → inverted outline → contrast outline (black/white) → drop shadow. ^{experimental 0.22.0}

Marker:

• Hold Alt to get extra ring. ^0.22.0

Brush:

• Hold Shift for a straight 15° aligned line. Release Shift to continue freehand, or hold it again to start another straight segment. ^NEXTRELEASE

Highlight:

• Hold Ctrl to switch between block and freehand mode (default configurable, see below). Removed in favour of distinct tool variants ^NEXTRELEASE
• Hold Shift in freehand mode for a straight 15° aligned line. Stop at some position and release and hold Shift again to achieve perfectly aligned turns.

Additional note on blur, fringe inpaint, pixelate and fringe inpaint-pixelate ^NEXTRELEASE:

• Maximum Privacy: For the paranoid among us, we recommend using a solid, filled rectangle instead.
• Optimized Pixelation: For best results when censoring text, ensure your block size matches the line height to guarantee unreadable characters.

CSS

Satty ships with minimal builtin CSS which can be overridden by $XDG_CONFIG_HOME/satty/overrides.css. Adwaita defaults for headerbar (@headerbar_fg_color and @headerbar_bg_color) which Satty uses ^0.21.0 may lack transparency, here's an override example:

.outer_box,
.toolbar {
    color: #000000;
    background-color: #ddddddaa;
}

You can discover styleable elements by using the GTK inspector with env variable GTK_DEBUG=interactive. Also, see wiki for more examples.

IME ^0.20.0

Satty supports IME via GTK with and without preediting. Please note, at this point Satty has no proper fallback font handling so the font used needs to contain the entered glyphs.

wlroots based compositors (Sway, Wayfire, River, ...)

You can bind a key to the following command:

grim -g "$(slurp -o -r -c '#ff0000ff')" -t ppm - | satty --filename - --fullscreen --output-filename ~/Pictures/Screenshots/satty-%Y%m%d-%H:%M:%S.png

Hyprland

The following Hyprland binding will use slurp and grim to make the screenshot, copy it to the clipboard by wl-copy and start Satty with a predefined output path:

hl.bind(
    "Print",
    hl.dsp.exec_cmd(
        'sh -c "grim -g \\"$(slurp -o -c \'#ff0000ff\')\\" -t ppm - | tee >(wl-copy --type image/png) | satty -f - --output-filename ~/Pictures/screenshot-%Y-%m-%d_%H-%M-%S.png"'
    ),
    { description = "Satty Screenshot" }
)

To make Satty a floating window in Hyprland, add a window rule:

hl.window_rule({
    match = { class = "com.gabm.satty" },
    no_anim = true,
    float = true,
    center = true,
    --min_size = { 200, 200 },
    --min_size = { 600, 600 },
})

Please note we're using ppm in both examples. Compared to png, ppm is uncompressed and this can save time.

Other examples

Image Resize

Satty does not provide a resize mechanism other than cropping. But you can pipe the result to other tools such as ImageMagick:

grim -g "0,0 3840x2160" -t ppm - | satty --filename - --output-filename - | convert -resize 50% - out.png

Sway mode

Add this to your ~/.config/sway/config. It needs grim and slurp.

# screenshots
# inspiration: https://www.reddit.com/r/swaywm/comments/ghnlea/comment/fqnzxkx/?utm_source=share&utm_medium=web3x&utm_name=web3xcss&utm_term=1&utm_content=share_button
set $satty satty -f - --initial-tool=arrow --copy-command=wl-copy --actions-on-escape="save-to-clipboard,exit" --brush-smooth-history-size=5 --disable-notifications
set $printscreen_mode 'printscreen (r:region, f:full, w:window)'
mode $printscreen_mode {
    bindsym r exec swaymsg 'mode "default"' && grim -t ppm -g "$(slurp -d)" - | $satty
    bindsym f exec swaymsg 'mode "default"' && grim -t ppm - | $satty
    bindsym w exec swaymsg 'mode "default"' && swaymsg -t get_tree | jq -r '.. | select(.focused?) | .rect | "\(.x),\(.y) \(.width)x\(.height)"' | grim -t ppm -g - - | $satty

    bindsym Return mode "default"
    bindsym Escape mode "default"
}
bindsym $mod+Shift+p mode $printscreen_mode

Build from source

You first need to install the native dependencies of Satty (see below) and then run:

# build release binary, located in ./target/release/satty
make build-release

# optional: install to /usr/local
PREFIX=/usr/local make install

# optional: uninstall from /usr/local
PREFIX=/usr/local make uninstall

Dependencies

Satty is based on GTK-4 and Adwaita. Dependencies, depending of each distributions are:

• glib2
• gtk4 (libgtk-4-x)
• gdk-pixbuf2
• libadwaita
• libepoxy
• fontconfig

Credits

Maintainers and Contributors

Satty wouldn't exist without the help of our contributors and maintainers. Current maintainers are: @RobertMueller2, @fabienjuif, @robertwidfen and @gabm (original author). Our contributors are:

Made with contrib.rocks.

Heavy Lifting in some areas

• femtovg
• Relm4
• GTK

Inspiration

• Swappy
• Flameshot
  • Fringe-Pixelate was inspired by https://github.com/flameshot-org/flameshot/pull/3765/changes

Star History

License

The source code is released under the MPL-2.0 license.

The Font 'Roboto Regular' from Google is released under Apache-2.0 license.