Skip to Content
Matuwall

Backends

Apply wallpapers through awww, sweetbg, KDE Plasma or your own command

After Enter, Matuwall sends the selected path to a backend.

BackendCommand used
awww (default)awww img -- <path>
sweetbgsweetbg img <path>
plasmaplasma-apply-wallpaperimage <path>
commandYour own command
autoFirst running backend: plasma, sweetbg, then awww

Set it in the config:

[general]
backend = "awww"

Or for one run:

matuwall -b sweetbg

Backend Flags

Add flags with args. One argument per item:

[backend.awww]
args = ["--transition-type", "grow", "--transition-duration", "1.5"]

[backend.sweetbg]
args = ["--persist"]   # keep the wallpaper after a sweetbg restart

Flags go before the path:

awww img --transition-type grow --transition-duration 1.5 -- <path>

Override them for one run. The first --backend-arg replaces the configured args:

matuwall -b awww --backend-arg --transition-type --backend-arg grow
matuwall --no-backend-args

Use flags only, no -- or path. Matuwall does not check them. An unknown flag makes the daemon fail.

KDE Plasma

[general]
backend = "plasma"

[backend.plasma]
args = ["--fill-mode", "preserveAspectCrop"]

--fill-mode takes stretch, preserveAspectFit, preserveAspectCrop or pad. The wallpaper is set on every desktop.

Plasma refuses paths that contain '. Rename those files.

Custom Command

Use any other setter. {path} is required and becomes the absolute wallpaper path:

[general]
backend = "command"

[backend.command]
apply = "swww img {path}"
Setterapply
swww"swww img {path}"
hyprpaper"hyprctl hyprpaper wallpaper ,{path}"
swaybg"/home/you/.local/bin/set-swaybg {path}"

For one run:

matuwall --backend-command "swww img {path}"
  • Runs without a shell. Quotes, ~ and $VARS are not expanded
  • Use absolute paths
  • Matuwall waits for it. A non-zero exit fails the apply
  • args and --backend-arg do not apply. Put flags in apply

swaybg

swaybg never exits, so use a wrapper that starts it and returns:

#!/bin/sh
# ~/.local/bin/set-swaybg
# Start the new swaybg first, stop the old ones once it has drawn
old=$(pgrep -x swaybg)
setsid -f swaybg -i "$1" -m fill >/dev/null 2>&1
if [ -n "$old" ]; then
	setsid -f sh -c 'sleep 2; kill "$@"' sh $old >/dev/null 2>&1
fi
chmod +x ~/.local/bin/set-swaybg

The new image draws on top of the old one, so there is no blank frame. The same pattern works for wbg.

How auto Works

A backend is picked when its client is in PATH and it is running:

BackendRunning means
plasmaXDG_CURRENT_DESKTOP contains KDE
sweetbgDaemon socket exists
awwwDaemon socket exists

auto never picks command. It only probes the default awww namespace. With awww-daemon --namespace, select awww explicitly.

On this page