wallr 0.2.1

Wallr

The wallpaper engine for Wayland.

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. Frames are cached in a zstd-compressed stream, so looping playback never re-decodes the file and stays CPU-light (measured on par with other native GIF wallpaper engines).
• Video wallpapers: native MP4/WebM/MKV support with hardware-accelerated decoding (VAAPI, NVDEC), PTS-based scheduling, seek, and seamless looping. Near-idle CPU usage.
• 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).
• Hybrid GPU support: automatic GPU selection (integrated/discrete) for optimal power efficiency.

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.

For video wallpapers: FFmpeg libraries (automatically detected at build time).

Install

cargo install wallr

or manually, 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

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 set video.mp4 --effect wave --duration 1s              # video 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 ipc pause            # pause video/GIF playback
wallr ipc resume           # resume playback
wallr ipc seek 1:30        # seek a video wallpaper
wallr ipc info             # decoder, codec, and GPU information
wallr quit                 # stop the daemon (removes its socket)
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, served from a zstd-compressed frame cache that avoids re-decoding on every loop. Videos are decoded by FFmpeg with hardware acceleration, streamed frame-by-frame, and rendered seamlessly after transitions complete.

Details: docs/architecture.md

Docs

• Changelog
• CLI reference
• Configuration reference
• Animation authoring
• Architecture
• Matugen integration
• Video wallpaper support

Troubleshooting

Desktop interaction blocked

wallr does NOT block desktop interaction. The wallpaper surface is configured with:

• Layer::Background (behind all windows)
• KeyboardInteractivity::None (no keyboard input)
• Empty input region (all clicks pass through)

If you experience blocked interaction:

1. Ensure you're using a compatible compositor (Hyprland, Sway, niri, KDE Plasma 6)
2. Check compositor logs for layer-shell errors
3. Restart the daemon: pkill wallr && wallr daemon
4. For niri: Add layer-shell rule to allow wallr on the background layer

The wallpaper behaves like any other background - windows, desktop icons, and clicks work normally over it.

Support

If Wallr has improved your workflow or desktop experience, consider supporting its continued development.

Your support helps fund new features, performance improvements, bug fixes, documentation, testing, and long term maintenance while keeping Wallr open source.

Star on GitHub

Starring the repository helps more people discover the project and shows that the work is valuable.

Sponsor

Financial support allows more time to be invested in building, maintaining, and improving Wallr.

Every contribution, regardless of size, directly supports the future of the project.

Thank you for supporting open source software.

Star History

Contributing

See CONTRIBUTING.md.

License

MIT. See LICENSE.