Repository files navigation

If you are interested, you can read the reasons behind itin my blog.

• a compositor that implements the wlr-layer-shell (typically wlroots based compositors)
• lz4 (for compressing frames when animating)

Note that this meansswww will not run on Gnome, because it does not implement thewlr-layer-shell protocol.

• wayland-client and wayland-protocol.xml files installed in your system (pkg-config must be able to find it)
• Up to date stable rustc compiler and cargo (specifically, MSRV is 1.87.0)

To build, clone this repository and run:

cargo build --release

Then, putboth binariestarget/release/swww andtarget/release/swww-daemon in your path. Optionally, autocompletion scriptsfor bash, zsh, fish and elvish are offered in thecompletions directory.

In order to generate the man pages,you must havescdoc installed. Run

./doc/gen.sh

The man pages will be indoc/generated. To install them, you must move them toto the appropriate location in your system. You should be able to figure outwhere that is by runningmanpath.

NixOS users can directly use this repository to get the latest swww for their system.

Add in yourflake.nix:

inputs.swww.url="github:LGFae/swww";

Pass inputs to your modules usingspecialArgs andThen inconfiguration.nix:

environment.systemPackages=[inputs.swww.packages.${pkgs.system}.swww];

• Display animated gifs on your desktop
• Display any image in the formats:
  • avif(note: must havedav1d dependency and compile with--features=avif flag)
  • jpeg
  • png
  • gif
  • pnm
  • tga
  • tiff
  • webp
  • bmp
  • farbfeld
  • svg (only static svgs are supported)
• Clear the screen with an arbitrary rrggbb color
• Smooth transition effect when you switch images
• Do all of that without having to shutdown and reinitialize the daemon

There are two main reasons that compelled me to make this: the first is thatoguri is unmaintained and archived,despite there being serious problems with excess of memory use while displayingcertain gifs (seethis, forexample). The best alternative I've found foroguri wasmpvpaper, but if felt overkill for mypurposes.

Comparing tooguri,swww uses less cpu power to animate once it has cachedall the frames in the animation. It should also besignificantly morememory efficient.

The second is that, to my knowledge, there is no wallpaper daemon for waylandthat allows you to change the wallpaper at runtime. That is, in order to, forexample, cycle through the images of a directory, you'd have to kill the daemonand restart it. Not only does it make simple shell scripts a pain to write, itmakes switching from one image to the next to happen very abruptly.

Start by initializing the daemon:

swww-daemon

Then, in a different terminal, simply pass the image you want to display:

swww img <path/to/img># You can also specify outputs:swww img -o <outputs> <path/to/img># Control how smoothly the transition will happen, as well as its frame rate.# --transition-step: smaller values = smoother. Default is 2 if --transition-type is `simple`, and 90 if it is not.# --transition-fps: Default = 30.swww img <path/to/img> --transition-step <1 to 255> --transition-fps <1 to 255># There are also many different transition effects:swww img <path/to/img> --transition-type center# Note you may also control the above by setting up the SWWW_TRANSITION_FPS,# SWWW_TRANSITION_STEP, and SWWW_TRANSITION environment variables.# To see all options, runswww img --help

If you would like to know the valid values for<outputs>, you can query thedaemon. This will also tell you what the current image being displayed is, aswell as the dimensions detected for the outputs. If you need more detailedinformation, I would recommend usingwlr-randr.

swww query

Finally, to stop the daemon, kill it:

swww kill

For a more complete description, runswww --help orswww <subcommand> --help.

Finally, to get a feel for what you can do with some shell scripting, check outtheexample_scripts folder. It can help you get started.

wipe transition with angle set to 30 deg

Theleft,right,top andbottom transitions all work similarly.

Thecenter transition is the opposite: it starts from the center and goestowards the edges.

There is alsosimple, which simply fades into the new image,any, whichstarts at a random point with eithercenter ofouter transitions, andrandom,which selects a transition effect at random.

swww will use a non-insignificant amount of cpu power while caching theimages. This will be specially noticeable if the images need to be resizedbefore being displayed. So, if you have a very large gif, I would recommendresizing itbefore sending it toswww. That would make the caching phasemuch faster, and thus ultimately reduce power consumption. I can personallyrecommendgifsicle for this purpose.

swww used to cache its images so that it could reload the current the lastdisplayed image automatically. This lead to many problems and also proved to bevery annoying to keep working with when we updated tosctk 0.17. So I decided to nukeit.

If you want a wallpaper to be set automatically when you reconnect to a monitor,you should use a combination of scripts and a program that lets you run commandswhen a new output is connected, likekanshi.

Broadly speaking,NEW FEATURES WILL NOT BE ADDED, UNLESS THEY ARE EGREGIOUSLYSIMPLE. I madeswww with the specific usecase of making shell scripts inmind. So, for example, stuff like timed wallpapers, or a setup that loads adifferent image at different times of the day, and so on, should all be done bycombiningswww with other programs (see theexample_scripts for someexamples).

If you really want some new feature withinswww itself, I would recommendforking the repository.

swww isn't really the simplest, mostest minimalest software you could findfor managing wallpapers. If you are looking for something simpler, have a lookat theawesome-wayland repository list of wallpaper programs. I can personallyrecommend:

• wbg - probably the simplest of them all.Strongly recommend if you just care about setting a single png as yourpermanent wallpaper on something like a laptop.
• swaybg - made by the wlroots godsthemselves.
• mpvpaper - if you want to displayvideos as your wallpapers. This is also what I used for gifs before makingswww.
• kitty - you can use the kitty terminal emulator with itspanel kitten to have the output of an arbitrary TUI program such as htop or btop or similar as your desktop wallpaper.

A huge thanks to everyone involved in thesmithayproject. Making this program would not have been possible without it. In fact,the first versions of swww were quite literally copy pasted from thelayer shell example in the client-toolkit.

A big thank-you also toHakierGrzonzo, forsetting up the AUR package.

Pixel Art, by Waneella -https://www.patreon.com/waneella

Gradient -https://www.behance.net/gallery/86128681/Free-Unicorn-Vector-Gradients

Silhouette of Skyway -https://unsplash.com/photos/silhouette-of-skyway-UUJzCuHUfYI