wayshot(5)

📦 version 1.6.0, in nixpkgs unstable

🌸 NAME 🌸

okay so bestie, welcome to wayshot(5) — the config file manual 💖 This is your guide to the Wayshot screenshot tool, made for compositors that implement zwlr_screencopy_v1, like sway and river. If that's your setup, you're literally in the right place ✨

🎀 SYNTAX 🎀

Wayshot's config file speaks TOML — that's the format, no cap. The full spec lives at https://toml.io/en/v1.0.0 if you wanna go read it (iconic of you tbh) 🦋

🦋 LOCATION 🦋

Heads up: Wayshot does not create the config file for you. She's not your mom 😭 She just looks for one in these places, in this order:

  1. A path you hand her via the CLI option: wayshot --config config.toml
  2. $XDG_CONFIG_HOME/wayshot/config.toml
  3. $HOME/.config/wayshot/config.toml

So yeah, you gotta make the file yourself. Main character behavior only 💅

👑 BASE 👑

This section is all about the [base] table of the config file. Let's go 💖

  • output = "<string>" | "None" — the name of the output you want to screenshot. The CLI option takes precedence over this one: wayshot --output "HDMI-A-1". Default: "None" (which means capture all outputs) 🌈
  • cursor = true | false — controls if the screenshot file should contain the cursor or not. The CLI option takes precedence: wayshot --cursor. Default: false
  • freeze = true | false — when true, freeze the screen before interactive region (--geometry) or point (--color) selection, so you get a nice stable view ✨. When false, selection happens on the live display and the capture is taken after selection (same as --no-freeze). The CLI --no-freeze takes precedence. Default: true
  • delay = <integer> | unset — number of milliseconds to wait before taking the screenshot. When unset or omitted, no delay is applied. Super useful for letting windows or overlays pop up before the capture. The CLI --delay takes precedence. Default: unset (no delay) ⏳
  • clipboard = true | false — controls if the screenshot file should be copied into the clipboard. Wayshot persists in the background offering the image until the clipboard is overwritten 🫶. The CLI option takes precedence: wayshot --clipboard. Requires the clipboard feature (enabled by default). Default: false
  • file = true | false — controls if the screenshot file should be written on disk. The CLI FILE takes precedence over it. If it's not used, then the [file] section's path and name_format are used as the path to save the file on disk. Examples:
    • file is true, CLI without args: wayshot -> screenshot file saved in path/name_format.encoding
    • file is true, CLI with FILE argument: wayshot foo.png -> screenshot file saved in current directory as foo.png
    • file is true, CLI with FILE argument as - (stdout): wayshot "-" -> screenshot file saved in path/name_format.encoding
    • file is false, CLI without args: wayshot -> screenshot file is not saved anywhere 🙈

Default: true

  • stdout = true | false — controls if the screenshot file should be sent to stdout. The CLI's FILE takes precedence: wayshot "-". Default: false
  • log_level = "info" | "trace" | "debug" | "warn" | "error" — the log level. Possible values:
    • "info"
    • "trace"
    • "debug"
    • "warn"
    • "error"

Requires the logger feature (enabled by default). Default: "info"

  • notifications = true | false — controls if desktop notifications should be shown. When enabled, wayshot will show notifications for screenshot events (e.g., successful capture, errors) 🔔. Requires the notifications feature (enabled by default). Default: true

🍓 FILE 🍓

This section documents the [file] table of the configuration file 💜

  • path = "<string>" | "None" — directory to save the screenshot file. Takes effect only if the [base] category's file is true and FILE is not provided in the CLI. Refer to the [base] category's file for examples 👀 Default: "None" (current working directory)
  • name_format = "<string>" | "None" — formatting of the screenshot file name to save on disk. Follows chrono formatting rules: https://docs.rs/chrono/latest/chrono/format/strftime/index.html. The CLI option takes precedence: wayshot --file-name-format "wayshot-%Y_%m_%d-%H_%M_%S". Default: "None" (fallbacks to "wayshot-%Y_%m_%d-%H_%M_%S")
  • encoding = "png" | "jpg" | "ppm" | "qoi" | "webp" | "avif" | "jxl" — the screenshot file encoding. Examples:
    • encoding is avif, CLI: wayshot foo -> screenshot file is foo.avif
    • encoding is avif, CLI: wayshot --encoding png foo -> screenshot file is foo.png
    • encoding is avif, CLI: wayshot --encoding png foo.jpg -> screenshot file is foo.jpg
    • encoding is avif, CLI: wayshot --encoding png foo.jpg --encoding png -> screenshot file is foo.png

Default: "png"

🌈 ENCODING 🌈

Encoding-specific configuration options, bestie ✨

Note: the avif and jxl formats are only available when the corresponding Cargo features are enabled (both are on by default). When a feature is disabled, the format is silently ignored and wayshot falls back to PNG. So don't be confused if your fancy format just... doesn't happen 💀

🎀 PNG 🎀

  • [encoding.png] compression = "default" | "fast" | "best" | "none" | "uncompressed" | 0-9 — PNG compression level. Controls the trade-off between file size and encoding speed. For detailed documentation, see: https://docs.rs/image/latest/image/codecs/png/enum.CompressionType.html
    • "default": Balanced compression and speed
    • "fast": Faster encoding, larger files (minimal compression)
    • "best": Slower encoding, smaller files (high compression level)
    • "none" or "uncompressed": No compression whatsoever
    • 0-9: Detailed numeric compression level (0=no compression, 9=maximum compression)

Default: "default"

  • [encoding.png] filter = "none" | "sub" | "up" | "avg" | "paeth" | "adaptive" — PNG filter type. Filters process image data to improve compression. For detailed documentation, see: https://docs.rs/image/latest/image/codecs/png/enum.FilterType.html
    • "none": No filtering (best for low bit depth grayscale or low color count)
    • "sub": Filters based on previous pixel in the same scanline
    • "up": Filters based on the scanline above
    • "avg": Filters based on average of left and right neighbor pixels
    • "paeth": Algorithm using left, upper left, and above pixels
    • "adaptive": Heuristic selection of filters per scanline (recommended)

Default: "adaptive"

🧚 JXL 🧚

  • [encoding.jxl] lossless = true | false — enable lossless compression for JPEG-XL encoding. When set to true, the image is compressed without any quality loss. When false, lossy compression is used with the specified distance parameter. Default: false
  • [encoding.jxl] distance = 0.0-25.0 — target visual distance in JND (Just Noticeable Difference) units for lossy compression. Lower values result in higher quality but larger file sizes. This parameter is ignored when lossless is set to true 🙅‍♀️
    • 0.0: Mathematically lossless (same as lossless=true)
    • 1.0: Visually lossless (recommended default)
    • 0.5-3.0: Recommended range for most use cases
    • 3.0-25.0: Higher compression, noticeable quality loss

Default: 1.0

  • [encoding.jxl] effort = 1-10 — encoder effort setting. Higher values allow more computation time for better compression. For lossless compression, higher effort generally produces smaller files. For lossy compression, higher effort should more accurately reach the target quality.
    • 1: Lightning (fastest)
    • 2: Thunder
    • 3: Falcon
    • 4: Cheetah
    • 5: Hare
    • 6: Wombat
    • 7: Squirrel (default, balanced)
    • 8: Kitten
    • 9: Tortoise
    • 10: Glacier (slowest, best compression)

Default: 7

🔔 NOTIFICATION 🔔

This section documents the [notification] table of the configuration file 💖

Requires the notifications feature (enabled by default).

  • action = "<string>" — command to execute when the user clicks the notification. The command is run exactly as provided with no arguments appended. If not set, opens the screenshot directory with xdg-open. Examples:
    • action = "xdg-open /home/user/Pictures" -> opens a fixed folder

Default: xdg-open <screenshot directory>

  • icon = "<string>" — icon name passed to the notification daemon. The daemon resolves it against its own configured icon theme — not XDG_ICON_THEME. Set the theme in your daemon's configuration (e.g. icon_theme in dunstrc). Examples:
    • icon = "accessories-camera" (candy-icons theme)
    • icon = "camera-photo"

Default: unset (daemon chooses its own default)

  • timeout_ms = <integer> — how long the notification stays visible, in milliseconds.
    • -1: never expire
    • 0: use the notification server's default
    • positive integer: display for this many milliseconds

Default: 5000

  • app_name = "<string>" — application name field sent with the notification. Visible in some notification daemons and used for daemon-side filtering rules. Default: "wayshot"
  • success_summary = "<string>" — title shown in the notification after a successful screenshot 🌸 Default: "Screenshot Taken"
  • failure_summary = "<string>" — title shown in the notification when a screenshot fails 😭 Default: "Screenshot Failed"
  • sound_name = "<string>" — XDG sound name hint sent with the notification. Only respected by notification daemons that implement the freedesktop sound hint (e.g. GNOME Shell, KDE Plasma). Standalone daemons such as dunst and mako ignore this field — use their scripting feature to play sounds instead 💀 Example: sound_name = "message-new-instant". Default: unset
  • transient = true | false — when true, marks the notification as transient. Transient notifications are not stored in notification history or the notification center after dismissal. Support depends on the notification daemon. Default: false
  • category = "<string>" — notification category hint (freedesktop standard). Can be used by notification daemons for filtering or styling rules. Examples:
    • category = "transfer.complete"
    • category = "im.received"

Default: unset

⭐ SEE ALSO ⭐

okay that's the config tables covered, and there's still more coming bestie — don't go anywhere 💖

💌 AUTHORS 💌

Okay so who's behind all this magic? Bestie, it's Shinyzenith — say hi 👋

  • Maintained by Shinyzenith <aakashsensharma@gmail.com> — literally the main character keeping the whole thing alive 🫶

And if you wanna peek behind the curtain and see what's cooking in development (iykyk 👀), the repo is right here:

That's the whole page, bestie — congrats, you ate that 🍓✨

github.com/waycrate/wayshot · version/date vibes: 1980-01-01 · go forth and screenshot iconicly 💅📸

📦 where this page comes from