Home

Awesome

wpaperd

GitHub's release (latest by date) GitHub license GitHub Workflow Status

wpaperd is the modern wallpaper daemon for Wayland. It dynamically changes the current wallpaper, either after a certain amount of time or via a command-line interface. It uses OpenGL ES to render the images and have beautiful hardware-accelerated transitions, while being easy on resources.

Notice: wpaperd uses wlr_layer_shell wayland protocol, which is available on all wlroots based compositors (sway, hyprland, ...) and on KDE. Therefore it won't work on GNOME.

Features

Getting started

Dependencies

wpaperd is written in Rust and requires a working Cargo installation. It also depends on:

Build

To install wpaperd, clone the repository and build the project:

$ git clone https://github.com/danyspin97/wpaperd
$ cd wpaperd
$ cargo build --release

Generate the man pages by running scdoc:

$ scdoc < man/wpaperd-output.5.scd > man/wpaperd-output.5

Install

You can install both the daemon (wpaperd) and cli (wpaperctl) using rinstall:

$ rinstall --yes

To run wpaperd, run the daemon:

$ wpaperd

If you want to automatically run it at startup, add this line to your sway configuration (located in $HOME/.config/sway/config):

# Assuming it has been installed in ~/.local/bin/wpaperd
exec ~/.local/bin/wpaperd -d

Or in Hyprland:

exec-once=~/.local/bin/wpaperd -d

Image formats support

wpaperd uses the [image] create to load and display images. Have a look on its documentation for the supported formats.

Note: To enable avif format, build wpaperd with avif feature (requires libdav1d to be installed.

Cycling images

When path is set to a directory, you can cycle the images by running the commands next and previous using wpaperctl:

$ wpaperctl next
$ wpaperctl previous

When sorting is set to ascending and descending, wpaperd will use the wallpaper name to calculate the next wallpaper accordingly. When sorting is set to random, it will store all the wallpapers shown in a queue, so that the commands next and previous can work as intended.

Notice: the queue only works when queue-size setting (which defaults to 10) is bigger than the number of available images in the folder.

The cycling of images can also be paused/resumed by running the pause and resume commands, or just toggle-pause, using wpaperctl:

$ wpaperctl pause
$ wpaperctl resume
$ wpaperctl toggle-pause

Wallpaper Configuration

The configuration file for wpaperd is located in XDG_CONFIG_HOME/wpaperd/config.toml (which defaults to ~/.config/wpaperd/config.toml). Each section represents a different display and can contain the following keys:

The section default will be used as base for the all the display configuration; the section any will be used for all the displays that are not explictly listed. This allows to have a flexible configuration without repeating any settings. wpaperd will check the configuration at startup and each time it changes and provide help when it is incorrect.

This is the simplest configuration:

[DP-3]
path = "/home/danyspin97/github_octupus.png"

[DP-4]
path = "/home/danyspin97/Wallpapers"
duration = "30m"

This is a more complex configuration:

[default]
duration = "30m"
mode = "center"
sorting = "ascending"

[any]
path = "/home/danyspin97/default_wallpaper.png"

[DP-3]
path = "/home/danyspin97/Wallpapers"

[Dell Inc. DELL U2419H GY1VSS2]
path = "/home/danyspin97/Wallpapers/1080p"

If you're running sway, you can look for the available outputs and their ID (or description) by running:

$ swaymsg -t get_outputs

On Hyprland you can run:

$ hyprctl monitors

Output descriptions take priority over output IDs.

Wallpaper link

wpaperd creates a symlink in XDG_STATE_HOME/wpaperd/wallpapers (.local/state/wpaperd/wallpapers by default) for each display that points to the current wallpaper used. This is useful to integrate the current status with other components.

~ $ ls ~/.local/state/wpaperd/wallpapers
DP-3@      DP-4@

Transitions

Since version 1.1, wpaperd support multiple transitions types, taken from gl-transition. The transition can be changed at runtime and most of them are configurable, e.g. you can change the direction of directional transition or the speed for dissolve transition, etc. Every transition bring each own defaults, so you can just leave everything empty unless you want to customize the transition. The default transition-time for each transition is different, to provide a better experience out of the box. To switch between available transitions, add the following to wpaperd configuration:

[default]
path = "/home/danyspin97/Wallpapers"
duration = "30m"
sorting = "ascending"

[default.transition.hexagonalize]
# default values for hexagonalize
# steps = 50
# horizontal-hexagons = 20.0

This is the list of available transitions with their own settings and defaults:

FAQ

$ cargo build --release

License

wpaperd is licensed under the GPL-3.0+ license.