Skip to content
<awesome-gh-repos>
vic

Satty-org/Satty

Satty - Modern Screenshot Annotation.
Source code at GitHub https://github.com/Satty-org/Satty
Satty-org/Satty.json
{
  "createdAt": "2023-09-21T11:21:05Z",
  "defaultBranch": "main",
  "description": "Satty - Modern Screenshot Annotation.",
  "fullName": "Satty-org/Satty",
  "homepage": "",
  "language": "Rust",
  "name": "Satty",
  "pushedAt": "2025-11-24T06:16:45Z",
  "stargazersCount": 1594,
  "topics": [],
  "updatedAt": "2025-11-27T00:34:21Z",
  "url": "https://github.com/Satty-org/Satty"
}

Satty: Modern Screenshot Annotation.

Section titled “ Satty: Modern Screenshot Annotation.”

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

![]!(assets/usage.gif)

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

Section titled “Install”

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

Packaging status

Specifics

Section titled “Specifics”
DistributionCommandNote
Gentooemerge -av sattyYou need guru overlay (see wiki). Pending PR
Alpine Linuxapk add sattyAvailable in Alpine Community

Prebuilt Sources

Section titled “Prebuilt Sources”

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

Usage

Section titled “Usage”

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.

All configuration is done either at the config file in XDG_CONFIG_DIR/.config/satty/config.toml or via the command line interface. In case both are specified, the command line options always override the configuration file.

Shortcuts

Section titled “Shortcuts”
  • Enter: as configured (see below), default: copy-to-clipboard
  • Esc: as configured (see below), default: exit
  • Ctrl+C: Save to clipboard
  • Ctrl+S: Save to specified output file
  • Ctrl+Shift+S: Save using file dialog 0.20.0
  • Ctrl+T: Toggle toolbars
  • Ctrl+Y: Redo
  • Ctrl+Z: Undo
  • Alt+(Left/Right/Up/Down): Pan, also available with middle mouse button drag NEXTRELEASE

Tool Selection Shortcuts (configurable) 0.20.0

Section titled “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
  • g: Highlight tool

Tool Modifiers and Keys

Section titled “Tool Modifiers and Keys”
  • Arrow: Hold Shift to make arrow snap to 15° steps
  • Ellipse: Hold Alt to center the ellipse around origin, hold Shift for a circle
  • Highlight: Hold Ctrl to switch between block and freehand mode (default configurable, see below), hold Shift for a square (if the default mode is block) or a straight line (if the default mode is freehand)
  • Line: Hold Shift to make line snap to 15° steps
  • Rectangle: Hold Alt to center the rectangle around origin, hold Shift for a square
  • 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.

Configuration File

Section titled “Configuration File”
[general]
# Start Satty in fullscreen mode
fullscreen = true
# Exit directly after copy/save action
early-exit = true
# Draw corners of rectangles round if the value is greater than 0 (0 disables rounded corners)
corner-roundness = 12
# Select the tool on startup [possible values: pointer, crop, line, arrow, rectangle, text, marker, blur, brush]
initial-tool = "brush"
# Configure the command to be called on copy, for example `wl-copy`
copy-command = "wl-copy"
# Increase or decrease the size of the annotations
annotation-size-factor = 2
# Filename to use for saving action. Omit to disable saving to file. Might contain format specifiers: https://docs.rs/chrono/latest/chrono/format/strftime/index.html
# starting with 0.20.0, can contain leading tilde (~) for home directory
output-filename = "/tmp/test-%Y-%m-%d_%H:%M:%S.png"
# After copying the screenshot, save it to a file as well
save-after-copy = false
# Hide toolbars by default
default-hide-toolbars = false
# Experimental (since 0.20.0): whether window focus shows/hides toolbars. This does not affect initial state of toolbars, see default-hide-toolbars.
focus-toggles-toolbars = false
# Fill shapes by default (since 0.20.0)
default-fill-shapes = false
# The primary highlighter to use, the other is accessible by holding CTRL at the start of a highlight [possible values: block, freehand]
primary-highlighter = "block"
# Disable notifications
disable-notifications = false
# Actions to trigger on right click (order is important)
# [possible values: save-to-clipboard, save-to-file, exit]
actions-on-right-click = []
# Actions to trigger on Enter key (order is important)
# [possible values: save-to-clipboard, save-to-file, exit]
actions-on-enter = ["save-to-clipboard"]
# Actions to trigger on Escape key (order is important)
# [possible values: save-to-clipboard, save-to-file, exit]
actions-on-escape = ["exit"]
# Action to perform when the Enter key is pressed [possible values: save-to-clipboard, save-to-file]
# Deprecated: use actions-on-enter instead
action-on-enter = "save-to-clipboard"
# Right click to copy
# Deprecated: use actions-on-right-click instead
right-click-copy = false
# request no window decoration. Please note that the compositor has the final say in this. At this point. requires xdg-decoration-unstable-v1.
no-window-decoration = true
# experimental feature: adjust history size for brush input smooting (0: disabled, default: 0, try e.g. 5 or 10)
brush-smooth-history-size = 10
# experimental feature (NEXTRELEASE): The pan step size to use when panning with arrow keys.
pan-step-size = 50.0
# experimental feature (NEXTRELEASE): The zoom factor to use for the image.
# 1.0 means no zooming.
zoom-factor = 1.1


# Tool selection keyboard shortcuts (since 0.20.0)
[keybinds]
pointer = "p"
crop = "c"
brush = "b"
line = "i"
arrow = "z"
rectangle = "r"
ellipse = "e"
text = "t"
marker = "m"
blur = "u"
highlight = "g"


# Font to use for text annotations
[font]
family = "Roboto"
style = "Regular"


# Custom colours for the colour palette
[color-palette]
# These will be shown in the toolbar for quick selection
palette = [
    "#00ffff",
    "#a52a2a",
    "#dc143c",
    "#ff1493",
    "#ffd700",
    "#008000",
]


# These will be available in the color picker as presets
# Leave empty to use GTK's default
custom = [
    "#00ffff",
    "#a52a2a",
    "#dc143c",
    "#ff1493",
    "#ffd700",
    "#008000",
]

Command Line

Section titled “Command Line”
» satty --help
Modern Screenshot Annotation.


Usage: satty [OPTIONS] --filename <FILENAME>


Options:
  -c, --config <CONFIG>
          Path to the config file. Otherwise will be read from XDG_CONFIG_DIR/satty/config.toml
  -f, --filename <FILENAME>
          Path to input image or '-' to read from stdin
      --fullscreen
          Start Satty in fullscreen mode
  -o, --output-filename <OUTPUT_FILENAME>
          Filename to use for saving action or '-' to print to stdout. Omit to disable saving to file. Might contain format specifiers: <https://docs.rs/chrono/latest/chrono/format/strftime/index.html>. Since 0.20.0, can contain tilde (~) for home dir
      --early-exit
          Exit directly after copy/save action
      --corner-roundness <CORNER_ROUNDNESS>
          Draw corners of rectangles round if the value is greater than 0 (Defaults to 12) (0 disables rounded corners)
      --initial-tool <TOOL>
          Select the tool on startup [aliases: --init-tool] [possible values: pointer, crop, line, arrow, rectangle, ellipse, text, marker, blur, highlight, brush]
      --copy-command <COPY_COMMAND>
          Configure the command to be called on copy, for example `wl-copy`
      --annotation-size-factor <ANNOTATION_SIZE_FACTOR>
          Increase or decrease the size of the annotations
      --save-after-copy
          After copying the screenshot, save it to a file as well Preferably use the `action_on_copy` option instead
      --actions-on-enter <ACTIONS_ON_ENTER>
          Actions to perform when pressing Enter [possible values: save-to-clipboard, save-to-file, exit]
      --actions-on-escape <ACTIONS_ON_ESCAPE>
          Actions to perform when pressing Escape [possible values: save-to-clipboard, save-to-file, exit]
      --actions-on-right-click <ACTIONS_ON_RIGHT_CLICK>
          Actions to perform when hitting the copy Button [possible values: save-to-clipboard, save-to-file, exit]
  -d, --default-hide-toolbars
          Hide toolbars by default
      --focus-toggles-toolbars
          Experimental (since 0.20.0): Whether to toggle toolbars based on focus. Doesn't affect initial state
      --default-fill-shapes
          Experimental feature (since 0.20.0): Fill shapes by default
      --font-family <FONT_FAMILY>
          Font family to use for text annotations
      --font-style <FONT_STYLE>
          Font style to use for text annotations
      --primary-highlighter <PRIMARY_HIGHLIGHTER>
          The primary highlighter to use, secondary is accessible with CTRL [possible values: block, freehand]
      --disable-notifications
          Disable notifications
      --profile-startup
          Print profiling
      --no-window-decoration
          Disable the window decoration (title bar, borders, etc.) Please note that the compositor has the final say in this. Requires xdg-decoration-unstable-v1
      --brush-smooth-history-size <BRUSH_SMOOTH_HISTORY_SIZE>
          Experimental feature: How many points to use for the brush smoothing algorithm. 0 disables smoothing. The default value is 0 (disabled)
      --right-click-copy
          Right click to copy. Preferably use the `action_on_right_click` option instead
      --action-on-enter <ACTION_ON_ENTER>
          Action to perform when pressing Enter. Preferably use the `actions_on_enter` option instead [possible values: save-to-clipboard, save-to-file, exit]
      --zoom-factor <ZOOM_FACTOR>
          Experimental feature (NEXTRELEASE): The zoom factor to use for the image. 1.0 means no zoom. defaults to 1.1
      --pan-step-size <PAN_STEP_SIZE>
          Experimental feature (NEXTRELEASE): The pan step size to use when panning with arrow keys. defaults to 50.0
  -h, --help
          Print help
  -V, --version
          Print version

IME 0.20.0

Section titled “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, …)

Section titled “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-$(date '+%Y%m%d-%H:%M:%S').png

Hyprland users must escape the # with another #:

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

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

Other examples

Section titled “Other examples”

Image Resize

Section titled “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

Section titled “Sway mode”

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

Terminal window
# 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

Section titled “Build from source”

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

Terminal window
# 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

Section titled “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

Maintainers and Contributors

Section titled “Maintainers and Contributors”

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

Made with contrib.rocks.

Star History

Section titled “Star History”

Star History Chart

License

Section titled “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.