> ## Documentation Index
> Fetch the complete documentation index at: https://docs.otter-shell.org/llms.txt
> Use this file to discover all available pages before exploring further.

# otter-wallpaper

> Wallpaper daemon with per-monitor paths, rotation, and lock screen sync.

`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

```bash theme={null}
otter-wallpaper
```

Autostart at login: see [Session setup](/desktop/session-setup).

## Configuration

Config file: `~/.config/otter-shell/otter-wallpaper.conf`

```conf theme={null}
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
```

| Key                    | Default                       | Description                              |
| ---------------------- | ----------------------------- | ---------------------------------------- |
| `path`                 | `/usr/share/wallpapers/pika/` | File or directory                        |
| `rotation_interval`    | `300`                         | Seconds between rotations (0 = disabled) |
| `rotation_order`       | `random`                      | `sequential` or `random`                 |
| `scale_mode`           | `cover`                       | `cover` (fill+crop) or `fit` (letterbox) |
| `same_on_all_displays` | `true`                        | Same image on all outputs                |
| `overview_enabled`     | `false`                       | Blurred overview surface for Niri        |
| `overview_blur_radius` | `20`                          | Blur 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](/desktop/otter-lock) reads this file for the lock screen background. [otter-theme-gen](/desktop/otter-theme-gen) uses the same state to build wallpaper-reactive themes.

## Niri overview

With `overview_enabled = true`, a blurred layer surface is created with namespace `otter-wallpaper-overview`. Add to your Niri config:

```kdl theme={null}
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.