wallr 0.1.0 - Docs.rs

wallr-0.1.0 is not a library.

Wallr

The wallpaper engine for Wayland.

demo

Wallr draws its own background surface with wlr-layer-shell and wgpu. It does not wrap hyprpaper, swww, or swaybg; it renders transitions itself and treats theme generation (Matugen, Wallust, Pywal) as an optional step after the fact, not the core of what it does.

Features

11 transition effects: fade, blur, wipe, slide, zoom, pixelate, ripple, dissolve, wave, grow, outer. Each tunable from the CLI or a YAML package (origin, direction, angle, easing, duration).
Live wallpapers: animated GIFs play frame-by-frame once the transition completes, starting from the transition's incoming image so playback eases in cleanly.
Circular reveals: grow, outer, and ripple expand as true, aspect-corrected circles.
Wall-clock timing: transition duration holds exactly, regardless of refresh rate.
Background daemon: wallr daemon owns the surface over a Unix socket; wallr set starts it automatically.
Directory watching: wallr watch <dir> applies new files as they land.
Animation packages: YAML timelines with inheritance and a registry (install, search, publish, validate).
Preview window: judge an effect before it touches your desktop.
Per-monitor control: independent wallpapers and scaling modes (fill, fit, stretch, center, tile).

Requirements

Rust toolchain, Wayland client headers, and a compositor with wlr-layer-shell support: Hyprland, Sway, niri (with a layer rule), or KDE Plasma 6. GNOME/Mutter doesn't implement the protocol.

Install

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

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

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

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

Usage

wallr set wallpaper.jpg                                     # starts the daemon if needed
wallr set wallpaper.jpg --effect grow --origin bottom_right --duration 1.2s
wallr set animated.gif --effect fade --duration 500ms        # live wallpaper
wallr preview wallpaper.jpg --effect wave --angle 45         # test before applying

wallr daemon               # run the background daemon
wallr watch ~/Pictures     # auto-apply new files dropped into a folder
wallr doctor                # check compositor, GPU, and theme providers
wallr validate anim.yaml    # lint an animation package

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

If Matugen is configured to call wallr set as its own wallpaper command, pass --no-theme on that call to avoid a feedback loop.

Animation packages

Effects and timelines are plain YAML:

name: liquid
duration: 2000ms
timeline:
  - at: 0ms
    fade: { from: 0.0, to: 1.0 }
  - at: 150ms
    ripple: { origin: center, frequency: 15.0, amplitude: 0.02, speed: 6.0 }

wallr validate <file> checks a package before you use it. Full authoring guide: docs/animation-authoring.md

Architecture

The wallr CLI talks to wallr daemon over a Unix socket. The daemon owns the layer-shell surface, a wgpu renderer, and the animation engine. Every change is a GPU-rendered transition from the previous wallpaper, timed to wall-clock duration regardless of refresh rate; GIFs keep playing frame-by-frame once the transition ends.

Details: docs/architecture.md

Docs

Star History

Contributing

See CONTRIBUTING.md.

License

MIT. See LICENSE.