gesso

Deterministic Wayland wallpaper daemon and controller with smooth, low-latency transitions.

gesso renders wallpapers using wlr-layer-shell, creating a dedicated background surface per output. It supports image and solid-colour wallpapers with carefully paced fade and wipe animations designed to stay smooth even under compositor quirks.

Wayland-only. Requires a compositor with layer-shell support (most wlroots-based compositors).

Features

• Image wallpapers with multiple modes (fill, fit, stretch, center, tile)
• Solid colour wallpapers
• Smooth fade and wipe transitions
• Per-output targeting
• Deterministic timing (no runaway frame pacing)
• SHM double-buffering with frame-callback fallback
• Cached last frames for instant re-apply
• Minimal dependencies, daemon-friendly design

Installation

Build from source

git clone <your-repo-url>
cd gesso
cargo build --release

Binary location:

./target/release/gesso

Usage

Start the daemon

In your wayland compositors autostart section start gesso daemon with:

gessod 

Set an image wallpaper

gesso set ~/Pictures/wallpaper.png

Image modes

gesso set ~/Pictures/wallpaper.png --mode fill
gesso set ~/Pictures/wallpaper.png --mode fit
gesso set ~/Pictures/wallpaper.png --mode stretch
gesso set ~/Pictures/wallpaper.png --mode center
gesso set ~/Pictures/wallpaper.png --mode tile

Background colour (for fit / center letterboxing)

gesso set ~/Pictures/wallpaper.png --mode fit --colour "#101010"

Transitions

Fade:

gesso set ~/Pictures/wallpaper.png --transition fade --duration 600

Wipe:

gesso set ~/Pictures/wallpaper.png --transition wipe --duration 750

Solid colour

gesso colour "#0b0f14"

With transition:

gesso colour "#0b0f14" --transition fade --duration 200
gesso colour "#0b0f14" --transition wipe --from right --duration 260

Target a specific output

Uses the compositor’s wl_output.name (e.g. DP-1, HDMI-A-1).

gesso set ~/Pictures/wallpaper.png --output DP-1
gesso colour "#111111" --output DP-1

Unset wallpaper

Unset all outputs:

gesso unset

Unset one output:

gesso unset --output DP-1

CLI Reference

gesso set

Set an image wallpaper (path or name resolved via GESSO_DIRS).

gesso set <target> [OPTIONS]

Options:

• -m, --mode <fill|fit|stretch|center|tile>
  Default: fill

• -c, --colour <hex>
  Background fill colour for fit/center letterboxing (e.g. #101010)

• -t, --transition <none|fade|wipe>
  Default: none

• -d, --duration <ms>
  Default: 850

• -f, --from <left|right> Wipe direction (only used when --transition wipe) Default: left

• -o, --output <name> Target a specific output

gesso colour

Set a solid colour wallpaper.

gesso colour <colour> [OPTIONS]

Options:

• -t, --transition <none|fade|wipe>
  Default: none

• -d, --duration <ms>
  Default: 850

• -f, --from <left|right> Default: left

• -o, --output <name>
  Target a specific output

gesso unset

Unset wallpaper on one output or all outputs.

gesso unset [--output <name>]

Other commands

gesso status
gesso doctor
gesso stop

Environment

WAYLAND_DISPLAY

Must be set (Wayland-only).

GESSO_DIRS

Optional search paths for gesso set <target> when <target> is not an absolute or relative path.

Example:

export GESSO_DIRS="$HOME/Pictures/Wallpapers:/usr/share/backgrounds"

Philosophy

gesso is designed to be boring in the best way:

• deterministic timing
• no runaway animations
• no daemon lockups
• graceful degradation when compositors misbehave

Silence is a feature.