{"id":13490548,"url":"https://github.com/jtheoof/swappy","last_synced_at":"2025-10-22T06:27:04.071Z","repository":{"id":39980641,"uuid":"222614730","full_name":"jtheoof/swappy","owner":"jtheoof","description":"A Wayland native snapshot editing tool, inspired by Snappy on macOS","archived":false,"fork":false,"pushed_at":"2024-07-05T04:48:15.000Z","size":981,"stargazers_count":985,"open_issues_count":43,"forks_count":40,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-08-01T19:34:42.628Z","etag":null,"topics":["annotation-tool","screenshot","snappy","snapshot","sway","wayland"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jtheoof.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-11-19T05:21:04.000Z","updated_at":"2024-07-30T10:07:56.000Z","dependencies_parsed_at":"2023-12-16T12:28:16.691Z","dependency_job_id":"32351285-abf0-4898-b507-2bfe0f619042","html_url":"https://github.com/jtheoof/swappy","commit_stats":{"total_commits":291,"total_committers":23,"mean_commits":"12.652173913043478","dds":"0.30927835051546393","last_synced_commit":"596b9a8b17234303a9d4d2ea1d3107cb5442253e"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtheoof%2Fswappy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtheoof%2Fswappy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtheoof%2Fswappy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jtheoof%2Fswappy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jtheoof","download_url":"https://codeload.github.com/jtheoof/swappy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245984556,"owners_count":20704792,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["annotation-tool","screenshot","snappy","snapshot","sway","wayland"],"created_at":"2024-07-31T19:00:48.384Z","updated_at":"2025-10-22T06:27:04.066Z","avatar_url":"https://github.com/jtheoof.png","language":"C","funding_links":[],"categories":["C","Tools","Screenshots","Linux","Graphics"],"sub_categories":["Screenshotting","Other","Raster Graphics"],"readme":"# swappy\n\nA 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](#example-usage).\n\n## Screenshot\n\n![Swappy Screenshot](docs/images/screenshot-1.0.0.png)\n\n## Example usage\n\nOutput of `grim` (or any tool outputting an image file):\n\n```sh\ngrim -g \"$(slurp)\" - | swappy -f -\n```\n\nSwappshot a PNG file:\n\n```sh\nswappy -f \"~/Desktop/my-gnome-saved-file.png\"\n```\n\nPrint final surface to stdout (useful to pipe with other tools):\n\n```sh\ngrim -g \"$(slurp)\" - | swappy -f - -o - | pngquant -\n```\n\nGrab a swappshot from a specific window under Sway, using `swaymsg` and `jq`:\n\n```sh\ngrim -g \"$(swaymsg -t get_tree | jq -r '.. | select(.pid? and .visible?) | .rect | \"\\(.x),\\(.y) \\(.width)x\\(.height)\"' | slurp)\" - | swappy -f -\n```\n\n## Config\n\nThe config file is located at `$XDG_CONFIG_HOME/swappy/config` or at `$HOME/.config/swappy/config`.\n\nThe file follows the GLib `conf` format. See the `man` page for details. There is example config file [here](example/config).\n\nThe following lines can be used as swappy's default:\n\n```\n[Default]\nsave_dir=$HOME/Desktop\nsave_filename_format=swappy-%Y%m%d-%H%M%S.png\nshow_panel=false\nline_size=5\ntext_size=20\ntext_font=sans-serif\npaint_mode=brush\nearly_exit=false\nfill_shape=false\nauto_save=false\ncustom_color=rgba(193,125,17,1)\ntransparent=false\ntransparency=50\n```\n\n- `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 fails\n- `save_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)](https://man.archlinux.org/man/strftime.3). If this date format is missing, filename will have no timestamp\n- `show_panel` is used to toggle the paint panel on or off upon startup\n- `line_size` is the default line size (must be between 1 and 50)\n- `text_size` is the default text size (must be between 10 and 50)\n- `text_font` is the font used to render text, its format is pango friendly\n- `paint_mode` is the mode activated at application start (must be one of: brush|text|rectangle|ellipse|arrow|blur, matching is case-insensitive)\n- `early_exit` is used to make the application exit after saving the picture or copying it to the clipboard\n- `fill_shape` is used to toggle shape filling (for the rectangle and ellipsis tools) on or off upon startup\n- `auto_save` is used to toggle auto saving of final buffer to `save_dir` upon exit\n- `custom_color` is used to set a default value for the custom color\n- `transparency` is used to set transparency of everything that is drawn during startup\n- `transparent` is used to toggle transparency during startup\n\n\n## Keyboard Shortcuts\n\n- `Ctrl+b`: Toggle Paint Panel\n\n\u003chr\u003e\n\n- `b`: Switch to Brush\n- `e` `t`: Switch to Text (Editor)\n- `r` `s`: Switch to Rectangle (Square)\n- `c` `o`: Switch to Ellipse (Circle)\n- `a`: Switch to Arrow\n- `d`: Switch to Blur (`d` stands for droplet)\n\n\u003chr\u003e\n\n- `R`: Use Red Color\n- `G`: Use Green Color\n- `B`: Use Blue Color\n- `C`: Use Custom Color\n- `Minus`: Reduce Stroke Size\n- `Plus`: Increase Stroke Size\n- `Equal`: Reset Stroke Size\n- `f`: Toggle Shape Filling\n- `x` `k`: Clear Paints (cannot be undone)\n- `T`: Toggle Transparency\n\n\u003chr\u003e\n\n- `Ctrl`: Center Shape (Rectangle \u0026 Ellipse) based on draw start\n\n\u003chr\u003e\n\n- `Ctrl+z`: Undo\n- `Ctrl+Shift+z` or `Ctrl+y`: Redo\n- `Ctrl+s`: Save to file (see man page)\n- `Ctrl+c`: Copy to clipboard\n- `Escape` or `q` or `Ctrl+w`: Quit swappy\n\n## Limitations\n\n- **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](https://gitlab.gnome.org/GNOME/gtk/blob/3.24.13/gdk/wayland/gdkdisplay-wayland.c#L857). We need to do it on the [Wayland level](https://github.com/swaywm/wlr-protocols/blob/master/unstable/wlr-data-control-unstable-v1.xml), or wait for GTK 4. For now, we use `wl-copy` if installed and revert to `gtk` clipboard if not found.\n- **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`\n- **Output Format**: Only PNG is supported.\n\n## Installation\n\n- [Arch Linux](https://archlinux.org/packages/extra/x86_64/swappy/)\n- [Arch Linux (git)](https://aur.archlinux.org/packages/swappy-git)\n- [Fedora](https://src.fedoraproject.org/rpms/swappy)\n- [Gentoo](https://packages.gentoo.org/packages/gui-apps/swappy)\n- [openSUSE](https://build.opensuse.org/package/show/X11:Wayland/swappy)\n- [Void Linux](https://github.com/void-linux/void-packages/tree/master/srcpkgs/swappy)\n\n## Building from source\n\nInstall dependencies (on Arch, name can vary for other distros):\n\n- meson\n- ninja\n- cairo\n- pango\n- gtk\n- glib2\n- scdoc\n\nOptional dependencies:\n\n- `wl-clipboard` (to make sure the copy is saved if you close swappy)\n- `otf-font-awesome` (to draw the paint icons properly)\n\nThen run:\n\n```sh\nmeson setup build\nninja -C build\n```\n\n### i18n\n\nThis section is for developers, maintainers and translators.\n\nTo add support to a new locale or when translations are updated:\n\n1. Update `src/po/LINGUAS` (when new locales are added)\n2. Generate a new `po` file (ignore and do not commit potential noise in other files):\n\n```sh\nninja -C build swappy-update-po\n```\n\nTo rebuild the base template (should happen less often):\n\n```sh\nninja -C build swappy-pot\n```\n\nSee the [meson documentation](https://mesonbuild.com/Localisation.html) for details.\n\n## Contributing\n\nPull requests are welcome. This project uses [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) to automate changelog generation.\n\n## Release\n\nWe rely on [standard-version](https://github.com/conventional-changelog/standard-version) which is part of the JavaScript ecosystem but works well with any project.\n\n```sh\n./script/github-release\n```\n\nMake sure everything is valid in the Draft release, then publish the draft.\n\nRelease tarballs are signed with this PGP key: `F44D05A50F6C9EB5C81BCF966A6B35DBE9442683`\n\n## License\n\nMIT\n\n[snappy]: http://snappy-app.com/\n[slurp]: https://github.com/emersion/slurp\n[grim]: https://github.com/emersion/grim\n[sway]: https://github.com/swaywm/sway\n[wl-clipboard]: https://github.com/bugaevc/wl-clipboard\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjtheoof%2Fswappy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjtheoof%2Fswappy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjtheoof%2Fswappy/lists"}