rwpspread 0.4.0

Multi-Monitor Wallpaper Spanning Utility
rwpspread-0.4.0 is not a library.

rwpspread

GitHub Release Crates.io Release AUR

Multi-Monitor Wallpaper Spanning Utility

Features

  • Wallpaper spanning across all monitors
  • Monitor hotplugging detection
  • Color palette generation
  • Monitor bezel compensation
  • Support for various wallpaper setters
  • Configuration generation for lockers

Installing

Arch Linux

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

Nix

# 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.

Crates.io

# globally
cargo install rwpspread

Building

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

Usage

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]
  -c, --compensate <COMPENSATE>  Compensate for bezel amount in pixels
  -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.

Credits and Thanks