{"id":13533399,"url":"https://github.com/LGFae/swww","last_synced_at":"2025-04-01T21:32:14.355Z","repository":{"id":38016744,"uuid":"443222557","full_name":"LGFae/swww","owner":"LGFae","description":"A Solution to your Wayland Wallpaper Woes","archived":false,"fork":false,"pushed_at":"2024-10-27T17:40:36.000Z","size":33725,"stargazers_count":2329,"open_issues_count":44,"forks_count":71,"subscribers_count":9,"default_branch":"main","last_synced_at":"2024-10-29T17:55:03.224Z","etag":null,"topics":["swww","wallpaper","wayland"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LGFae.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":"2021-12-31T01:21:49.000Z","updated_at":"2024-10-29T16:47:25.000Z","dependencies_parsed_at":"2022-07-09T05:00:16.285Z","dependency_job_id":"f60ca672-66a8-4068-9f61-4b741fba9179","html_url":"https://github.com/LGFae/swww","commit_stats":{"total_commits":884,"total_committers":38,"mean_commits":"23.263157894736842","dds":"0.17420814479638014","last_synced_commit":"2da1f57e6b0dbc2d6b62cb940a426486710cf14e"},"previous_names":["lgfae/swww","horus645/swww"],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LGFae%2Fswww","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LGFae%2Fswww/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LGFae%2Fswww/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LGFae%2Fswww/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LGFae","download_url":"https://codeload.github.com/LGFae/swww/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246365641,"owners_count":20765546,"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":["swww","wallpaper","wayland"],"created_at":"2024-08-01T07:01:19.483Z","updated_at":"2025-04-01T21:32:14.339Z","avatar_url":"https://github.com/LGFae.png","language":"Rust","funding_links":["https://www.patreon.com/waneella"],"categories":["Tools","Rust","others"],"sub_categories":["Wallpaper"],"readme":"# A Solution to your Wayland Wallpaper Woes\n### Efficient animated wallpaper daemon for wayland, controlled at runtime\n\n![animated gif demonstration](https://i.imgur.com/Leuh6wm.gif)\n![image transition demonstration](../demos/assets/grow.gif)\n\n## Dependencies\n\n - a compositor that implements:\n   * wlr-layer-shell (typically wlroots based compositors)\n   * xdg-output\n - [lz4](https://github.com/lz4/lz4) (for compressing frames when animating)\n\n**Note that this means `swww` will not run on Gnome, because it does not implement the `wlr-layer-shell` protocol**.\n\n## Build\n\n\u003ca href=\"https://repology.org/project/swww/versions\"\u003e\n    \u003cimg src=\"https://repology.org/badge/vertical-allrepos/swww.svg\" alt=\"Packaging status\" align=\"right\"\u003e\n\u003c/a\u003e\n\n### Dependencies:\n\n  - Up to date stable rustc compiler and cargo (specifically, MSRV is 1.82.0)\n\nTo build, clone this repository and run:\n```\ncargo build --release\n```\nThen, put **both binaries** `target/release/swww` and\n`target/release/swww-daemon` in your  path. Optionally, autocompletion scripts\nfor bash, zsh, fish and elvish are offered in the `completions` directory.\n\n#### Man pages:\n\nIn order to generate the man pages, **you must have `scdoc` installed**. Run\n\n```\n./doc/gen.sh\n```\n\nThe man pages will be in `doc/generated`. To install them, you must move them to\nto the appropriate location in your system. You should be able to figure out\nwhere that is by running `manpath`.\n\n### Nix\n\nNixOS users can directly use this repository to get the latest swww for their system.\n\nAdd in your `flake.nix`:\n\n```nix\n  inputs.swww.url = \"github:LGFae/swww\";\n```\n\nPass inputs to your modules using `specialArgs` and\nThen in `configuration.nix`:\n\n```nix\n  environment.systemPackages = [\n    inputs.swww.packages.${pkgs.system}.swww\n  ];\n```\n\n## Features\n\n - Display animated gifs on your desktop\n - Display any image in the formats:\n   * jpeg\n   * png\n   * gif\n   * pnm\n   * tga\n   * tiff\n   * webp\n   * bmp\n   * farbfeld\n - Clear the screen with an arbitrary rrggbb color\n - Smooth transition effect when you switch images\n - Do all of that without having to shutdown and reinitialize the daemon\n\n## Why\n\nThere are two main reasons that compelled me to make this: the first is that\n[`oguri`](https://github.com/vilhalmer/oguri) is unmaintained and archived,\ndespite there being serious problems with excess of memory use while displaying\ncertain gifs (see [this](https://github.com/vilhalmer/oguri/issues/38), for\nexample). The best alternative I've found for `oguri` was\n[`mpvpaper`](https://github.com/GhostNaN/mpvpaper), but if felt overkill for my\npurposes.\n\nComparing to `oguri`, `swww` uses less cpu power to animate once it has cached\nall the frames in the animation. It should also be **significantly** more\nmemory efficient.\n\nThe second is that, to my knowledge, there is no wallpaper daemon for wayland\nthat allows you to change the wallpaper at runtime. That is, in order to, for\nexample, cycle through the images of a directory, you'd have to kill the daemon\nand restart it. Not only does it make simple shell scripts a pain to write, it\nmakes switching from one image to the next to happen very abruptly.\n\n## Usage\n\nStart by initializing the daemon:\n```\nswww-daemon\n```\nThen, in a different terminal, simply pass the image you want to display:\n```\nswww img \u003cpath/to/img\u003e\n\n# You can also specify outputs:\nswww img -o \u003coutputs\u003e \u003cpath/to/img\u003e\n\n# Control how smoothly the transition will happen, as well as its frame rate.\n# --transition-step: smaller values = smoother. Default is 2 if --transition-type is `simple`, and 90 if it is not.\n# --transition-fps: Default = 30.\nswww img \u003cpath/to/img\u003e --transition-step \u003c1 to 255\u003e --transition-fps \u003c1 to 255\u003e\n\n# There are also many different transition effects:\nswww img \u003cpath/to/img\u003e --transition-type center\n\n# Note you may also control the above by setting up the SWWW_TRANSITION_FPS,\n# SWWW_TRANSITION_STEP, and SWWW_TRANSITION environment variables.\n\n# To see all options, run\nswww img --help\n```\nIf you would like to know the valid values for *\\\u003coutputs\\\u003e*, you can query the\ndaemon. This will also tell you what the current image being displayed is, as\nwell as the dimensions detected for the outputs. If you need more detailed\ninformation, I would recommend using\n[`wlr-randr`](https://sr.ht/~emersion/wlr-randr/).\n```\nswww query\n```\nFinally, to stop the daemon, kill it:\n```\nswww kill\n```\nFor a more complete description, run `swww --help` or `swww \u003csubcommand\u003e\n--help`.\n\nFinally, to get a feel for what you can do with some shell scripting, check out\nthe [example_scripts](/example_scripts/) folder. It can help you get started.\n\n## Transitions\n\n#### Example wipe transition:\n\n\u003e wipe transition with angle set to 30 deg\n\n![top transition demonstration](../demos/assets/wipe.gif)\n\nThe `left`, `right`, `top` and `bottom` transitions all work similarly.\n\n#### Example outer transition\n\n![outer transition demonstration](../demos/assets/outer.gif)\n\nThe `center` transition is the opposite: it starts from the center and goes\ntowards the edges.\n\nThere is also `simple`, which simply fades into the new image, `any`, which\nstarts at a random point with either `center` of `outer` transitions, and `random`,\nwhich selects a transition effect at random.\n\n## Troubleshooting\n\n### The image looks tilted and in grayscale on my laptop\n\nSee #233. Current workaround is to use `swww-daemon --format xrgb` when starting\nthe daemon.\n\n### High cpu usage during caching of a gif's frames\n\n`swww` will use a non-insignificant amount of cpu power while caching the\nimages. This will be specially noticeable if the images need to be resized\nbefore being displayed. So, if you have a very large gif, I would recommend\nresizing it **before** sending it to `swww`. That would make the caching phase\nmuch faster, and thus ultimately reduce power consumption. I can personally\nrecommend [`gifsicle`](https://github.com/kohler/gifsicle) for this purpose.\n\n### Wallpaper disappears when reconnecting monitor\n\n`swww` used to cache its images so that it could reload the current the last\ndisplayed image automatically. This lead to many problems and also proved to be\nvery annoying to keep working with when we updated to\n[`sctk 0.17`](https://github.com/Smithay/client-toolkit). So I decided to nuke\nit.\n\nIf you want a wallpaper to be set automatically when you reconnect to a monitor,\nyou should use a combination of scripts and a program that lets you run commands\nwhen a new output is connected, like [`kanshi`](https://sr.ht/~emersion/kanshi/).\n\n## About new features\n\nBroadly speaking, **NEW FEATURES WILL NOT BE ADDED, UNLESS THEY ARE EGREGIOUSLY\nSIMPLE**. I made `swww` with the specific usecase of making shell scripts in\nmind. So, for example, stuff like timed wallpapers, or a setup that loads a\ndifferent image at different times of the day, and so on, should all be done by\ncombining `swww` with other programs (see the [example_scripts](/example_scripts/) for some\nexamples).\n\nIf you really want some new feature within `swww` itself, I would recommend\nforking the repository.\n\n## Alternatives\n\n`swww` isn't really the simplest, mostest minimalest software you could find\nfor managing wallpapers. If you are looking for something simpler, have a look\nat the [awesome-wayland repository list of wallpaper programs\n](https://github.com/natpen/awesome-wayland#wallpaper). I can personally\nrecommend:\n\n - [`wbg`](https://codeberg.org/dnkl/wbg) - probably the simplest of them all.\n Strongly recommend if you just care about setting a single png as your\n permanent wallpaper on something like a laptop.\n - [`swaybg`](https://github.com/swaywm/swaybg) - made by the wlroots gods\n themselves.\n - [`mpvpaper`](https://github.com/GhostNaN/mpvpaper) - if you want to display\n videos as your wallpapers. This is also what I used for gifs before making\n `swww`.\n - [`kitty`](https://sw.kovidgoyal.net/kitty/) - you can use the kitty terminal emulator with its [panel](https://sw.kovidgoyal.net/kitty/kittens/panel/) kitten to have the output of an arbitrary TUI program such as htop or btop or similar as your desktop wallpaper.\n\n## Acknowledgments\n\nA huge thanks to everyone involved in the [smithay](https://github.com/Smithay)\nproject. Making this program would not have been possible without it. In fact,\nthe first versions of swww were quite literally copy pasted from the\n[layer shell example in the client-toolkit\n](https://github.com/Smithay/client-toolkit/blob/master/examples/layer_shell.rs).\n\nA big thank-you also to [HakierGrzonzo](https://github.com/HakierGrzonzo), for\nsetting up the AUR package.\n\n### Wallpapers used in this README\n\nPixel Art, by Waneella - https://www.patreon.com/waneella\n\nGradient - https://www.behance.net/gallery/86128681/Free-Unicorn-Vector-Gradients\n\nSilhouette of Skyway - https://unsplash.com/photos/silhouette-of-skyway-UUJzCuHUfYI\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLGFae%2Fswww","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FLGFae%2Fswww","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLGFae%2Fswww/lists"}