Stable

garbg

Wallpaper Daemon

A multi-source wallpaper daemon with caching and animation support. Load backgrounds from local files, HTTP endpoints, or S3-compatible storage with intelligent caching.

View on GitHub Install

garbg screenshot 1200 × 700

Features

Local file and directory support
HTTP/HTTPS remote image fetching
S3-compatible cloud storage (AWS, MinIO)
Directory index scraping
LRU cache with blake3 hashing
Animated GIF and WebP support
Optional video playback via ffmpeg
Frame pre-rendering with ring buffer
Workspace-aware wallpaper switching
Systemd user service integration

Installation

bash

$ curl -fsSL https://gar.dev/install.sh | bash -s -- --component=garbg

Or use the universal installer to install all components.

Configuration

config.toml

# ~/.config/garbg/config.toml

[daemon]
# Cache settings
cache_dir = "~/.cache/garbg"
max_cache_size = "500MB"

[source]
# Local directory
type = "directory"
path = "~/Pictures/Wallpapers"
recursive = true

# Or HTTP source
# type = "http"
# url = "https://example.com/wallpapers/"

# Or S3 source
# type = "s3"
# bucket = "my-wallpapers"
# region = "us-east-1"

[display]
# Scaling mode: fill, fit, center, tile
mode = "fill"

# Animation settings for GIFs
animation = true
frame_rate = 30

[rotation]
# Rotate wallpaper automatically
enabled = true
interval = "30m"
random = true

Usage

$ garbg daemon # Start the daemon

$ garbg set ~/wallpaper.png # Set a specific wallpaper

$ garbg next # Next wallpaper in rotation

$ garbg prev # Previous wallpaper

$ garbg random # Random wallpaper from source

Supported Formats

PNG JPEG GIF WebP APNG BMP TIFF MP4* WebM*

* Video formats require ffmpeg-next feature

Systemd Service

Enable garbg as a user service for automatic startup:

$ systemctl --user enable --now garbg

Back to home