rwpspread

Features

• Wallpaper spanning across all monitors
• Monitor hotplugging detection
• Color palette generation
• Monitor ppi and bezel compensation
• Support for various wallpaper setters
  • 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.

# globally
cargo install rwpspread

Building

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

Usage

rwpspread 0.5.0 - Multi-Monitor Wallpaper Spanning 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, ct]
  -b, --backend <BACKEND>       Wallpaper setter backend [possible values: wpaperd, swaybg, hyprpaper]
  -l, --locker <LOCKER>         Lockscreen implementation to generate for [possible values: swaylock, hyprlock]
      --bezel <BEZEL>           Bezel amount in pixels to compensate for
  -m, --monitors <MONITORS>...  List of monitor containing their diagonal in inches [format: "<NAME>:<INCHES>"]
      --ppi                     Compensate for different monitor ppi values
  -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
  -w, --watch                   Watch for wallpaper source changes and resplit on changes
  -f, --force-resplit           Force resplit, skips all image cache checks
  -h, --help                    Print help
  -V, --version                 Print version

Examples

# Provide an input image
# screens are automatically read
rwpspread -i /some/path/wallpaper.png

# You can also specify a directory
# rwpspread will choose the image randomly
# supported formats: jpg, jpeg, png
rwpspread -i /some/wallpaper/dir/

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

# Use f.E. the wpaperd integration
# this autogenerates the config file
# and restarts wpaperd automatically
# you will need to have wpaperd installed
rwpspread -b wpaperd -i /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.

Monitor ppi compensation

Many users employ setups with different monitor resolutions and sizes. For example they might have a hig-resolution main monitor that is capable of 3840x2160 4K resolution, while their secondary monitor is only 1920x1080 Full-HD resolution. A 27' 4K monitor has a higher pixel density than a 27' Full-HD monitor, which is a problem for wallpaper splitters, because the image on the Full-HD monitor will look weirdly stretched out next to the higher resolution display. This is where ppi compensation comes into play.

rwpspread --ppi --monitors "DP-1:32 DP-2:27" -i /some/path/wallpaper.png

The above command tells rwpspread that you have a 32' monitor on DisplayPort 1 and a 27' monitor on DisplayPort 2. When combining this additional information with the resolution of the displays, a pixels-per-inch value can be calculated. Based on this value, rwpspread will scale split images for lower-resolution monitors and realign them accordingly, to compensate for their lower pixel density. The end result should be a more nicely aligned gap between different resolution displays.

Monitor bezel compensation

While ppi compensation takes the heavy-lifting off dealing with different resolution displays, bezel compensation can aid you in scenarios where you might have more distance between your monitors than you might want. In that case, splits may not fluid transitions from monitor to monitor, because the actual displays are not directly next to each other.

rwpspread --bezel 40 -i /some/path/wallpaper.png

Bezel compensation applies a fixed offset in pixels between touching edges of monitors, to make transition and splits look more fluid than without. You can also use it in combination with ppi compensation to get a perfect setup.

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.

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
• material-colors - Material Color Generation