wallr 0.5.0

The wallpaper engine for Wayland - animated transitions, theme pipeline integration, and a package ecosystem.
wallr-0.5.0 is not a library.

Wallr

GPU-accelerated wallpaper engine for Wayland, rendered natively with wgpu on wlr-layer-shell.

Wallr renders its own background surface on wlr-layer-shell compositors. It does not shell out to hyprpaper, swaybg, or swww.

Features

  • Static, GIF, and video wallpapers (MP4, WebM, MKV) with hardware-accelerated decode
  • 11 transitions: fade, blur, wipe, slide, zoom, pixelate, ripple, dissolve, wave, grow, outer
  • Per-monitor wallpapers and scaling modes
  • Background daemon over a Unix socket, with directory watching for auto-apply
  • Optional post-apply theming via Matugen, Wallust, or Pywal
  • YAML animation packages with an install/search registry
  • Near-zero idle overhead: static wallpapers render once and sleep; video and GIFs pace to frame boundaries
  • Zero-duration static sets can use a low-memory wl_shm compositor buffer; GPU rendering remains available for transitions and live media
  • Performance harness for live Wayland measurements against awww (scripts/benchmark-wallpapers.sh)

Screenshots

Install

cargo install wallr

yay -S wallr-bin

nix run github:programmersd21/wallr

Usage

# Basic wallpaper change
wallr set wallpaper.jpg

# Smooth transitions with ergonomic short flags
wallr set wallpaper.jpg -e grow -o center -d 850ms
wallr set wallpaper.jpg -e wipe -a 45 -d 800ms
wallr set video.mp4 -e wave -d 900ms

# Automatic directory rotation
wallr watch ~/Pictures/Wallpapers

wallr set starts the daemon automatically if it isn't already running. Full flag reference: docs/cli-reference.md.

Configuration

~/.config/wallr/config.yaml:

wallpaper:
  default: "~/Pictures/Wallpapers/default.png"
  mode: "fill"

animation:
  use: "smooth/crossfade"
  duration: "2000ms"

theme:
  provider: "matugen"

reload:
  - "waybar"
  - "dunst"

Full schema: docs/config-reference.md.

Requirements
Compositor Hyprland, Sway, niri (layer rule required), or KDE Plasma 6: any wlr-layer-shell implementation. GNOME/Mutter is unsupported.
Rust stable, for building from source
FFmpeg required only when building from source, for video wallpapers. Prebuilt release binaries statically link FFmpeg.

Building from source

# Arch
sudo pacman -S rust wayland wayland-protocols pkg-config ffmpeg

# Fedora
sudo dnf install rust cargo wayland-devel wayland-protocols-devel pkg-config ffmpeg-devel

# Ubuntu/Debian
sudo apt install rustc cargo libwayland-dev wayland-protocols pkg-config libavcodec-dev libavformat-dev libavutil-dev libswscale-dev

git clone https://github.com/programmersd21/wallr.git
cd wallr
cargo install --path wallr

Architecture

The wallr CLI talks to wallr daemon over a Unix socket. The daemon owns the layer-shell surface, the wgpu renderer, and the animation engine. Wallpaper changes render as GPU transitions from the previous image; GIFs continue playing after the transition ends, and video is decoded by FFmpeg with hardware acceleration where available.

Details: docs/architecture.md.

Performance measurements

Wallr is optimized around event-driven static rendering and bounded live playback. Use the included harness to measure the daemon on your compositor:

scripts/benchmark-wallpapers.sh

It requires a running Wayland session, hyperfine, awww, and release-built Wallr. Comparisons are machine- and workload-specific; do not interpret one run as a universal ranking.

Troubleshooting

error while loading shared libraries: libavutil.so.58: the installed binary was built against an older FFmpeg ABI. Reinstall the latest release (statically linked), or rebuild from source:

cargo install --path wallr --force

Wallpaper intercepts input: it shouldn't; the surface runs on Layer::Background with KeyboardInteractivity::None and an empty input region. If it happens: confirm your compositor is supported, check compositor logs for layer-shell errors, restart the daemon (pkill wallr && wallr daemon), and on niri add a layer-shell rule permitting Wallr on the background layer.

Documentation

Changelog · CLI reference · Config reference · Animation authoring · Architecture · Matugen integration · Video wallpapers

Last wallpaper per output is stored at ~/.cache/wallr/last_wallpaper/<OUTPUT>; see CLI reference and Architecture.

Contributing

See CONTRIBUTING.md.

Credits

Sample wallpapers in samples/ are mostly taken from:

All rights belong to their respective owners; thanks to the original authors for sharing their work.

License

MIT; see LICENSE.