rwpspread

Wallpaper Utility written in Rust

Features

• Spans an input wallpaper across all monitors
• Automatically re-splits when monitors are hotplugged
• Color-Palette generation
• Various wallpaper setter backends
  • wpaperd
  • swaybg
  • hyprpaper
• Configuration generation for lockers
  • swaylock
  • hyprlock

Installing

# stable
paru -S rwpspread
# git
paru -S rwpspread-git

# try it out
nix run nixpkgs#rwpspread
# or add to any user/system package list as
pkgs.rwpspread
# master
take `rwpspread` from this repos flake directly.

Building

git clone https://github.com/0xk1f0/rwpspread.git
cd rwpspread/
cargo build --release

Usage

Multi-Monitor Wallpaper Utility

Usage: rwpspread [OPTIONS] <--image <IMAGE>|--info>

Options:
  -i, --image <IMAGE>      Image file or directory path
      --info               Show detectable information
  -o, --output <OUTPUT>    Output directory path
  -a, --align <ALIGN>      Do not downscale the base image, align the layout instead [possible values: tl, tr, tc, bl, br, bc, rc, lc, c]
  -b, --backend <BACKEND>  Wallpaper setter backend [possible values: wpaperd, swaybg, hyprpaper]
  -l, --locker <LOCKER>    Lockscreen implementation to generate for [possible values: swaylock, hyprlock]
  -d, --daemon             Enable daemon mode and resplit on output changes
  -p, --palette            Generate a color palette from input image
      --pre <PRE>          Script to execute before splitting
      --post <POST>        Script to execute after splitting
  -f, --force-resplit      Force resplit, skips all image cache checks
  -h, --help               Print help
  -V, --version            Print version

Examples

# it takes an input image
# screens are automatically read
# if running a wlroots based compositor
rwpspread -i /some/path/wallpaper.png

# you can also specify a directory
# as input and rwpspread will choose
# an image from it randomly
# supported formats: jpg, jpeg, png
rwpspread -i /some/wallpaper/dir/

# to align the layout if the input image
# is big enough, instead of resizing
# for example, to align it top-right
rwpspread -a tr -i /some/path/wallpaper.png

# to use f.E. the wpaperd integration
# this autogenerates the config file
# you will need to have wpaperd installed
rwpspread -b wpaperd -i /some/path/wallpaper.png

# if you want automatic resplits when
# connecting new monitors
# start with daemon mode
rwpspread -di /some/path/wallpaper.png

[!NOTE]
rwpspread will try to force close any backend instances already running, this may fail in some cases and prevent it from setting any wallpapers at all. See Issue https://github.com/0xk1f0/rwpspread/issues/100

Make sure rwpspread is the first to start any swaybg, hyprpaper or wpaperd process, although the two latter ones may not be affected.

swaylock Integration

A drop-in string for swaylock will be put in /home/$USER/.cache/rwpspread/rwps_swaylock.conf which can look something like:

-i <image_path_1> -i <image_path_2>

This file can be sourced and used with your swaylock command, for exmaple:

#!/usr/bin/env bash

# source the command options
IMAGES=$(cat /home/$USER/.cache/rwpspread/rwps_swaylock.conf)
# execute with them
swaylock $IMAGES --scaling fill

hyprlock Integration

Just include /home/$USER/.cache/rwpspread/rwps_hyprlock.conf in your normal hyprlock.conf like this:

# include generate rwpspread
source=/home/$USER/.cache/rwpspread/rwps_hyprlock.conf

This allows you to configure additional hyprlock stuff after the import statement.

Custom Scripts

You can specify custom scripts or programs to execute before and after splitting takes place.

# before splitting
rwpspread --pre /some/pre/script.sh -di /some/path/wallpaper.png
# after splitting
rwpspread --post /some/post/script.sh -di /some/path/wallpaper.png
# or both
rwpspread --pre /some/pre/script.sh --post /some/post/script.sh -di /some/path/wallpaper.png

When in daemon mode, these script will also execute on re-splits f.E. monitor hotplugs.

[!NOTE]
rwpspread will wait for these scripts to finish executing before continuing its own execution

So make sure you don't supply scripts that block execution indefinitely

Save Locations

If used just to split images, output images are saved to the current working directory.

# output files in $PWD
rwpspread -i /some/path/wallpaper.png

When used with the backend or daemon option, output images are stored in /home/$USER/.cache/rwpspread/ with the rwps_ prefix.

# output files in /home/$USER/.cache/rwpspread/
rwpspread -b swaybg -i /some/path/wallpaper.png
# output files in /home/$USER/.cache/rwpspread/
rwpspread -di /some/path/wallpaper.png

To get all files simply do:

ls /home/$USER/.cache/rwpspread/

[!NOTE] If you are using the wpaperd backend, rwpspread will use its default config path /home/$USER/.config/wpaperd/ for the auto-generated configuration.

If you want to customize the output folder. use the -o option:

# output files in /some/other/dir/
rwpspread -o /some/other/dir/ -i /some/path/wallpaper.png

[!NOTE] Be aware that rwpspread will take full control of this folder and potentially delete files you may not want to be deleted!

Pretty filenames

In general the split files that rwpspread stores are not constant, they changed based on the configuration it receives. This includes what type of options it was run with and how many monitors are currently attached. Files are formatted in a specific way.

# actual output file
rwps_<monitor-name>_<config-hash>.png

This can make these file a bit cumbersome to use in external tools or wallpaper setters. This is why rwpspread also creates additional symlinks that have a predictable name, which point to the output file. It is important to note that it will do this only if one of either -b or -d are specified.

# symlink to actual file
rwps_<monitor-name>.png

You can use this in any other tool that uses the output files of rwpspread without worrying about changing names.

Troubleshooting

If you encounter issues after an update or with a new version please do the following:

# clear cached images
rm -r /home/$USER/.cache/rwpspread/
# clear wpaperd config (if you use it)
rm /home/$USER/.config/wpaperd/wallpaper.toml

And try again.

If this doesn't fix your issue, feel free to open a PR and I'll look into it when I find the time.

Checklist

• splitting for dual screen layout
• splitting for any screen layout (two or more screens)
• Hyprland/wlroots Integration
• wpaperd Integration
• wallpaper caching (don't resplit if we don't need to)
• color palette generation from wallpaper
• watchdog auto-resplit on output change
• center if wallpaper is big enough
• swaylock integration
• parallel image processing
• more alignment options if wallpaper is big enough
• palette generation rework (broken in some cases)
• swaybg integration
• hyprpaper integration
• hyprlock integration
• monitor bezel compensation

Credits and Thanks

• fsnkty - Nix Package Maintainer
• smithay-client-toolkit - Rust Interaction with Wayland
• wpaperd - Excellent Wallpaper Daemon
• swaylock - Screen Locking Utility
• swaybg - Wallpaper Utility
• hyprpaper - Hypr Wallpaper Daemon
• hyprlock - Hypr Screen Locker