Skip to main content
otter-wallpaper draws backgrounds on the Wayland background layer via zwlr_layer_shell_v1. Each image is decoded to an SHM buffer, then freed to keep memory use low.

​
Usage

otter-wallpaper
Autostart at login: see Session setup.

​
Configuration

Config file: ~/.config/otter-shell/otter-wallpaper.conf 
path = /usr/share/wallpapers/pika/
rotation_interval = 300
rotation_order = random
scale_mode = cover
same_on_all_displays = true
overview_enabled = false
overview_blur_radius = 20
KeyDefaultDescription
path/usr/share/wallpapers/pika/File or directory
rotation_interval300Seconds between rotations (0 = disabled)
rotation_orderrandomsequential or random
scale_modecovercover (fill+crop) or fit (letterbox)
same_on_all_displaystrueSame image on all outputs
overview_enabledfalseBlurred overview surface for Niri
overview_blur_radius20Blur strength for overview
Per-display overrides use display_0_name, display_0_path, through display_7_*.

​
Lockscreen integration

On wallpaper change, otter-wallpaper writes the current path per output to: 
$XDG_RUNTIME_DIR/otter-shell/wallpaper-state
Format: one output_name=path line per output. otter-lock reads this file for the lock screen background.

​
Niri overview

With overview_enabled = true, a blurred layer surface is created with namespace otter-wallpaper-overview. Add to your Niri config: 
layer-rule {
    match namespace="^otter-wallpaper-overview$"
    place-within-backdrop true
}

​
Hot reload

Config and theme changes apply via inotify without restart. Reload keeps the current wallpaper.