wallr 0.1.0

The wallpaper engine for Wayland — animated transitions, theme pipeline integration, and a package ecosystem.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

<div align="center">

### Wallr

**The wallpaper engine for Wayland.**

![demo](https://raw.githubusercontent.com/programmersd21/wallr/main/assets/demo.gif)

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.

[![License](https://img.shields.io/badge/License-MIT-000000?style=for-the-badge&labelColor=000000&color=8b5cf6)](LICENSE)
[![Rust](https://img.shields.io/badge/Rust-stable-000000?style=for-the-badge&labelColor=000000&color=dea584&logo=rust&logoColor=white)](https://www.rust-lang.org)
[![Wayland](https://img.shields.io/badge/Wayland-native-000000?style=for-the-badge&labelColor=000000&color=22d3ee&logo=wayland&logoColor=white)](https://wayland.freedesktop.org)
[![GPU](https://img.shields.io/badge/GPU-wgpu-000000?style=for-the-badge&labelColor=000000&color=4ade80)](https://wgpu.rs)
[![Crates.io](https://img.shields.io/crates/v/wallr?style=for-the-badge&labelColor=000000&color=f97316&label=Crates.io)](https://crates.io/crates/wallr)
[![CI](https://img.shields.io/github/actions/workflow/status/programmersd21/wallr/ci.yml?style=for-the-badge&labelColor=000000&color=22c55e&label=CI)](https://github.com/programmersd21/wallr/actions/workflows/ci.yml)
[![Downloads](https://img.shields.io/github/downloads/programmersd21/wallr/total?style=for-the-badge&labelColor=000000&color=38bdf8&label=Downloads)](https://github.com/programmersd21/wallr/releases)
[![Stars](https://img.shields.io/github/stars/programmersd21/wallr?style=for-the-badge&labelColor=000000&color=facc15&label=Stars)](https://github.com/programmersd21/wallr/stargazers)
[![PRs Welcome](https://img.shields.io/badge/PRs%20Welcome-welcome-000000?style=for-the-badge&labelColor=000000&color=ec4899)](CONTRIBUTING.md)
[![Made with love](https://img.shields.io/badge/Made%20with-%E2%9D%A4-000000?style=for-the-badge&labelColor=000000&color=f43f5e)](https://github.com/programmersd21)

</div>

## 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

```bash
# 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
```

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

## Usage

```bash
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
```

```bash
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](docs/cli-reference.md)

## Configuration

`~/.config/wallr/config.yaml`:

```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](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:

```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](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/architecture.md)

## Docs

- [CLI reference](docs/cli-reference.md)
- [Configuration reference](docs/config-reference.md)
- [Animation authoring](docs/animation-authoring.md)
- [Architecture](docs/architecture.md)
- [Matugen integration](docs/matugen-integration.md)

## Star History

[![RepoStars](https://repostars.dev/api/embed?repo=programmersd21%2Fwallr&theme=sunset)](https://repostars.dev/?repos=torvalds%2Flinux&theme=sunset)

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT. See [LICENSE](LICENSE).