⚡ Beta v0.1.0

garbg

Async wallpaper daemon with animation support and native gar integration

garbg is the wallpaper management component of the gardesk ecosystem. Built in Rust with async Tokio runtime, it handles static images, animated GIFs, WebP, and APNG files with configurable frame rates. Supports multiple wallpaper sources including local files, HTTP URLs, and GitHub repositories. Features per-workspace and per-monitor wallpapers, slideshow rotation with shuffle, and comprehensive IPC control via garbgctl.

View on GitHub Download RPM

🎯 RPM Available

Features

✓
Animated Wallpapers
GIF, WebP, and APNG support with configurable max FPS
✓
Multiple Source Types
Local files, directories, HTTP URLs, GitHub repositories
✓
5 Scaling Modes
fill, fit, stretch, center, tile with per-source override
✓
Per-Workspace Wallpapers
Different wallpaper for each gar workspace via config
✓
Multi-Monitor Support
Per-monitor wallpapers or span across all displays
✓
Slideshow Mode
Automatic rotation with configurable interval and shuffle
✓
GitHub Integration
Load wallpapers directly from GitHub repos via github:// URL
✓
IPC Control
garbgctl CLI and JSON over Unix socket with event subscription

Installation

RPM (Fedora/RHEL)

terminal

$sudo dnf config-manager --add-repo https://repos.musicsian.com/musicsian.repo

$sudo dnf install garbg garbgctl

From Source

terminal

$git clone https://github.com/espadon/gardesk

$cd gardesk/garbg

$cargo build --release

$sudo cp target/release/garbg /usr/local/bin/

$sudo cp target/release/garbgctl /usr/local/bin/

Dependencies

garbg requires the following runtime dependencies:

xcb - X11 protocol bindings for pixmap management
image - Rust image loading and manipulation
gif - GIF decoding with frame timing

Quick Start

Set a wallpaper immediately with the set command:

terminal

$garbg set ~/Pictures/wallpaper.jpg

Set wallpaper: /home/user/Pictures/wallpaper.jpg

Set from Directory (Slideshow)

terminal

$garbg set ~/Pictures/Wallpapers --interval 300 --shuffle

Set wallpaper source: /home/user/Pictures/Wallpapers (12 images) Slideshow enabled: 300s interval, shuffle on

Set Animated Wallpaper

terminal

$garbg set ~/Pictures/animated.gif --animate --max-fps 30

Set animated wallpaper: /home/user/Pictures/animated.gif Animation: 24 frames at 30 FPS max

Set from GitHub

terminal

$garbg set github://catppuccin/wallpapers/landscapes

Fetching from GitHub: catppuccin/wallpapers/landscapes Found 47 images Set wallpaper: pexels-photo-1563355.jpg

Scaling Modes

Control how wallpapers are scaled to fit your screen:

terminal

$garbg set ~/wallpaper.jpg --mode fill # Crop to fill screen (default)

$garbg set ~/wallpaper.jpg --mode fit # Fit within screen, letterbox

$garbg set ~/wallpaper.jpg --mode stretch # Stretch to fill, may distort

$garbg set ~/wallpaper.jpg --mode center # Center at original size

$garbg set ~/wallpaper.jpg --mode tile # Tile to fill screen

Daemon Mode

Run garbg as a daemon for persistent wallpaper management and slideshow support:

terminal

$garbg daemon

INFO Starting garbg daemon INFO Listening on /run/user/1000/garbg.sock INFO Ready for commands

systemd Service

When using gar, garbg starts automatically via systemd user services:

# ~/.config/systemd/user/garbg.service
[Unit]
Description=garbg wallpaper daemon
PartOf=gar-session.target
After=gar.service

[Service]
ExecStart=/usr/bin/garbg daemon
Restart=on-failure

[Install]
WantedBy=gar-session.target

Controlling the Daemon

Use garbgctl to control the running daemon:

terminal

$garbgctl set ~/Pictures/new-wallpaper.jpg

$garbgctl next # Next in slideshow

$garbgctl prev # Previous in slideshow

$garbgctl random # Random from source

$garbgctl pause # Pause animations/slideshow

$garbgctl resume # Resume animations/slideshow

$garbgctl status # Get current status

File Locations

Config: ~/.config/garbg/config.toml
Cache: ~/.cache/garbg/
PID file: $XDG_RUNTIME_DIR/garbg.pid
Socket: $XDG_RUNTIME_DIR/garbg.sock
Playlist state: ~/.local/state/garbg/playlist.json
Logs: journalctl --user -u garbg.service

Configuration Reference

garbg configuration uses TOML format stored at ~/.config/garbg/config.toml. The configuration file is optional - garbg works with sensible defaults and command-line arguments.

General Options

Option	Type	Default	Description
`default_mode`	-	"fill"	Default scaling mode when not specified
`default_source`	-	""	Default wallpaper source on startup
`socket_path`	-	$XDG_RUNTIME_DIR/garbg.sock	Override IPC socket location
`pid_file`	-	$XDG_RUNTIME_DIR/garbg.pid	Override PID file location

Animation Options

Option	Type	Default	Description
`enabled`	-	true	Enable animated wallpaper support
`max_fps`	-	60	Maximum frames per second for animations
`frame_skip`	-	true	Allow frame skipping when behind schedule
`pause_on_battery`	-	false	Pause animations when on battery power

Cache Options

Option	Type	Default	Description
`enabled`	-	true	Enable image caching to disk
`directory`	-	~/.cache/garbg	Cache directory path
`max_size_mb`	-	500	Maximum cache size in megabytes
`ttl_days`	-	30	Cache entry time-to-live in days

Slideshow Options

Option	Type	Default	Description
`interval`	-	300	Seconds between wallpaper changes
`shuffle`	-	false	Randomize wallpaper order
`transition`	-	"none"	Transition effect (none, fade, slide)
`transition_duration`	-	500	Transition duration in milliseconds

Minimal Configuration

# ~/.config/garbg/config.toml

[general]
default_mode = "fill"
default_source = "~/Pictures/Wallpapers"

[animation]
enabled = true
max_fps = 60

[slideshow]
interval = 300
shuffle = true

Per-Workspace Configuration

Define different wallpapers for each gar workspace. When you switch workspaces, garbg automatically changes the wallpaper.

Workspace Config Options

Option	Type	Default	Description
`id`	-	-	Workspace number (1-indexed)
`source`	-	-	Wallpaper source for this workspace
`mode`	-	default_mode	Scaling mode override for this workspace

# Per-workspace wallpapers
[[workspaces]]
id = 1
source = "~/Pictures/workspace1.jpg"
mode = "fill"

[[workspaces]]
id = 2
source = "~/Pictures/workspace2.jpg"
mode = "fit"

[[workspaces]]
id = 3
source = "github://catppuccin/wallpapers/minimalistic"
mode = "fill"

[[workspaces]]
id = 4
source = "~/Pictures/animated-workspace.gif"
mode = "fill"

Per-Monitor Configuration

Configure different wallpapers for each monitor in a multi-monitor setup. Monitor names match the output names from xrandr.

Monitor Config Options

Option	Type	Default	Description
`name`	-	-	Monitor name from xrandr (e.g., DP-1, HDMI-1)
`source`	-	-	Wallpaper source for this monitor
`mode`	-	default_mode	Scaling mode override for this monitor
`slideshow`	-	false	Enable slideshow on this monitor
`interval`	-	slideshow.interval	Slideshow interval override for this monitor

# Per-monitor wallpapers
[[monitors]]
name = "DP-1"
source = "~/Pictures/main-monitor.jpg"
mode = "fill"
slideshow = true
interval = 600

[[monitors]]
name = "HDMI-1"
source = "~/Pictures/secondary-monitor.jpg"
mode = "fit"

[[monitors]]
name = "eDP-1"
source = "~/Pictures/laptop-screen.jpg"
mode = "fill"

Complete Configuration Example

# ~/.config/garbg/config.toml

[general]
default_mode = "fill"
default_source = "~/Pictures/Wallpapers"
# socket_path = "/run/user/1000/garbg.sock"
# pid_file = "/run/user/1000/garbg.pid"

[animation]
enabled = true
max_fps = 60
frame_skip = true
pause_on_battery = true

[cache]
enabled = true
directory = "~/.cache/garbg"
max_size_mb = 500
ttl_days = 30

[slideshow]
interval = 300
shuffle = true
transition = "fade"
transition_duration = 500

# Workspace-specific wallpapers
[[workspaces]]
id = 1
source = "~/Pictures/coding-wallpaper.jpg"
mode = "fill"

[[workspaces]]
id = 2
source = "~/Pictures/browser-wallpaper.jpg"
mode = "fill"

[[workspaces]]
id = 3
source = "github://dharmx/walls/anime"
mode = "fill"

# Monitor-specific wallpapers (overrides workspace settings)
[[monitors]]
name = "DP-1"
source = "~/Pictures/ultrawide.jpg"
mode = "fill"
slideshow = true
interval = 600

[[monitors]]
name = "HDMI-1"
source = "~/Pictures/portrait-display.jpg"
mode = "fit"

Configuration Priority

When multiple configuration sources apply, garbg uses this priority order:

Command-line arguments - Highest priority, override all config
IPC commands - Runtime changes via garbgctl
Monitor-specific config - Per-monitor overrides
Workspace-specific config - Per-workspace settings
General config - Default values in config.toml
Built-in defaults - Fallback when nothing is configured

Environment Variables

GARBG_CONFIG - Override config file path
GARBG_SOCKET - Override socket path
XDG_RUNTIME_DIR - Base directory for socket and PID file
XDG_CONFIG_HOME - Base directory for config file
XDG_CACHE_HOME - Base directory for image cache

Overview

garbg is an async wallpaper daemon built in Rust for the gardesk desktop environment. It manages X11 root window pixmaps to display wallpapers, with support for static images, animated GIFs, WebP, and APNG files. garbg integrates with the gar window manager to provide per-workspace wallpapers and multi-monitor support.

Unlike simple wallpaper setters that exit after setting the pixmap, garbg runs as a daemon to support animated wallpapers, slideshow rotation, and runtime control via IPC. The daemon uses async Tokio for non-blocking I/O when fetching remote wallpapers and managing multiple sources.

Architecture

Daemon Mode

In daemon mode, garbg runs persistently and manages wallpaper lifecycle:

IPC Server: Listens on Unix socket for garbgctl commands
Slideshow Timer: Advances wallpapers at configured intervals
Animation Loop: Renders animated wallpaper frames at configured FPS
Event Subscription: Notifies clients of wallpaper changes
Pixmap Retention: Uses CloseDownMode::RetainPermanent to keep pixmaps alive

// Daemon event loop structure
loop (
    tokio::select! (
        // Handle IPC commands from garbgctl
        cmd = ipc_rx.recv() => handle_command(cmd),

        // Handle workspace change events from gar
        ws = workspace_rx.recv() => handle_workspace_change(ws),

        // Slideshow timer tick
        _ = slideshow_interval.tick() => advance_slideshow(),

        // Animation frame timer
        _ = frame_timer.tick() => render_next_frame(),

        // Unix signals (SIGTERM, SIGHUP)
        sig = signal_rx.recv() => handle_signal(sig),
    )
)

Standalone Mode

When invoked without the daemon subcommand, garbg sets the wallpaper and exits. In standalone mode:

If daemon is running, garbg sends an IPC command and exits immediately
If no daemon is running, garbg sets the wallpaper directly
For animated wallpapers without daemon, animation runs in foreground until Ctrl+C
Slideshow mode requires the daemon - standalone shows first image only

Pixmap Lifetime

garbg manages X11 pixmaps carefully to prevent black screens:

// Set CloseDownMode::RetainPermanent so pixmaps survive daemon exit
xcb::set_close_down_mode(conn, CloseDownMode::RetainPermanent);

// Clean up old pixmap before setting new one
fn cleanup_old_pixmap(conn: &Connection) (
    // Query current root window pixmap
    let old_pixmap = get_root_pixmap(conn);
    if old_pixmap != 0 (
        // Free old pixmap to avoid memory leaks
        xcb::free_pixmap(conn, old_pixmap);
    )
)

// Set new pixmap as root window background
fn set_root_pixmap(conn: &Connection, pixmap: Pixmap) (
    xcb::change_window_attributes(conn, root, CW_BACK_PIXMAP, &[pixmap]);
    xcb::clear_area(conn, false, root, 0, 0, 0, 0);
    // Set _XROOTPMAP_ID and ESETROOT_PMAP_ID atoms for compositors
    set_root_pixmap_atoms(conn, pixmap);
)

Event Loop

The daemon uses a single-threaded Tokio runtime for efficient async I/O:

IPC is handled via tokio::net::UnixListener
HTTP requests use reqwest with async runtime
Animation frames are timed with tokio::time::interval
Signals are captured with tokio::signal

gar Integration

Compositor Role

While garbg is not a full compositor, it provides wallpaper rendering for the gar window manager. For transparency effects in garbar or other applications, garbg sets the _XROOTPMAP_ID atom that compositors like picom read to composite the desktop background.

Workspace Wallpapers

garbg integrates with gar's workspace system to provide per-workspace wallpapers:

gar sends workspace change events via the i3-IPC protocol
garbg subscribes to workspace events on the gar socket
On workspace change, garbg looks up the workspace config
If a workspace-specific source exists, garbg changes the wallpaper
The change is instant for cached images, async for remote sources

Monitor Management

garbg queries monitors via RandR and supports two multi-monitor modes:

Per-Monitor (default): Each monitor gets its own wallpaper, scaled to fit. A single image creates separate pixmaps per monitor.
Span Mode: A single image spans all monitors as one large wallpaper. Enable with --span flag or span = true in config.

// Per-monitor wallpaper setting
fn set_per_monitor(image: &Image, monitors: &[Monitor], mode: ScaleMode) (
    for monitor in monitors (
        let scaled = scale_image(image, monitor.width, monitor.height, mode);
        let pixmap = create_pixmap_from_image(&scaled);
        set_monitor_pixmap(monitor, pixmap);
    )
)

// Span mode - single pixmap across all monitors
fn set_span(image: &Image, monitors: &[Monitor], mode: ScaleMode) (
    let total_width = monitors.iter().map(|m| m.width).sum();
    let max_height = monitors.iter().map(|m| m.height).max();
    let scaled = scale_image(image, total_width, max_height, mode);
    let pixmap = create_pixmap_from_image(&scaled);
    set_root_pixmap(pixmap);
)

Lifecycle Management

garbg is managed by systemd as part of the gar session:

garbg.service starts with gar-session.target
SIGTERM triggers graceful shutdown (pixmaps retained)
SIGHUP reloads configuration without losing current wallpaper
On crash, systemd Restart=on-failure restarts the daemon

Animation System

GIF Support

garbg provides full animated GIF support with frame timing:

Decodes all frames on load, caching decoded RGBA data
Reads frame delay from GIF metadata (default 100ms if unspecified)
Handles disposal methods (None, Background, Previous)
Respects GIF loop count or loops infinitely if unset

// Animation loop for GIF wallpapers
fn run_animation_loop(gif: &GifData, max_fps: u32) (
    let min_frame_time = Duration::from_secs_f64(1.0 / max_fps as f64);

    loop (
        for frame in &gif.frames (
            let frame_start = Instant::now();

            // Render this frame to the root pixmap
            render_frame(frame);

            // Calculate actual delay (respect GIF timing but cap at max_fps)
            let gif_delay = Duration::from_millis(frame.delay_ms as u64);
            let actual_delay = gif_delay.max(min_frame_time);

            // Sleep until next frame
            let elapsed = frame_start.elapsed();
            if elapsed < actual_delay (
                thread::sleep(actual_delay - elapsed);
            )
        )
    )
)

WebP and APNG

Animated WebP and APNG are also supported:

WebP: Uses libwebp to decode animated WebP files
APNG: Uses png crate to decode animated PNG files
Same animation loop structure as GIF with format-specific decoders
Detection by file extension (.webp, .apng, .png with animation)

Frame Timing

garbg uses adaptive frame timing to balance smoothness and CPU usage:

max_fps: Upper limit on frame rate (default 60)
frame_skip: Skip frames if rendering falls behind
Original timing: Respects source animation timing when possible

Performance

Animation performance optimizations:

Frames are pre-scaled to screen resolution on load
XCopyArea for fast pixmap updates
Frame caching avoids repeated decoding
pause_on_battery option reduces power consumption on laptops

Scaling Modes

garbg supports five scaling modes to handle images of any size:

Fill Mode (default)

Scales the image to completely fill the screen, cropping if necessary. The image aspect ratio is preserved. Best for wallpapers that are close to your screen's aspect ratio.

// Fill: scale to cover, crop excess
fn scale_fill(image: &Image, screen_w: u32, screen_h: u32) -> Image (
    let scale = f64::max(
        screen_w as f64 / image.width() as f64,
        screen_h as f64 / image.height() as f64,
    );
    let scaled = image.resize((image.width() as f64 * scale) as u32,
                              (image.height() as f64 * scale) as u32);
    // Center crop to screen dimensions
    scaled.crop_center(screen_w, screen_h)
)

Fit Mode

Scales the image to fit entirely within the screen, adding letterbox/pillarbox bars if needed. The image aspect ratio is preserved. Best when you want to see the entire image.

Stretch Mode

Stretches the image to exactly fill the screen dimensions. The image aspect ratio is not preserved, which may cause distortion. Best for abstract or pattern-based wallpapers.

Center Mode

Displays the image at its original size, centered on screen. If the image is larger than the screen, it is cropped. If smaller, it is surrounded by the background color. Best for pixel-perfect display of specific-sized artwork.

Tile Mode

Tiles the image across the screen at its original size. Best for seamless patterns or textures designed to be tiled.

Wallpaper Sources

garbg supports multiple source types for loading wallpapers. Sources can be single files, directories (for slideshows), HTTP URLs, or GitHub repositories.

Local Files

The simplest source type - a path to an image file on disk:

terminal

$garbg set /home/user/Pictures/wallpaper.jpg

$garbg set ~/Pictures/wallpaper.png

$garbg set ./relative/path/image.webp

Supported formats: JPEG, PNG, WebP, GIF, BMP, TIFF, APNG

Local Directories

A directory path enables slideshow mode with all images in the directory:

terminal

$garbg set ~/Pictures/Wallpapers

Found 47 images in /home/user/Pictures/Wallpapers Set wallpaper: landscape-001.jpg

$garbg set ~/Pictures/Wallpapers --shuffle --interval 300

$garbgctl next # Advance to next image

$garbgctl prev # Go back to previous image

$garbgctl random # Random image from directory

Directory scanning is recursive by default. Images are sorted alphabetically unless --shuffle is specified.

HTTP URLs

Load wallpapers directly from HTTP/HTTPS URLs:

terminal

$garbg set https://example.com/wallpaper.jpg

$garbg set https://unsplash.com/photos/abc123/download

HTTP images are cached locally after first download. Cache location is ~/.cache/garbg/http/.

HTTP Directory Listing

If an HTTP URL returns an HTML page with directory listing, garbg parses the links to find images:

terminal

$garbg set https://example.com/wallpapers/

Parsing directory listing from https://example.com/wallpapers/ Found 23 images

GitHub Sources

garbg has native support for loading wallpapers from GitHub repositories using the github:// protocol:

Basic Syntax

github://owner/repo/path/to/directory

# Examples:
github://catppuccin/wallpapers/landscapes
github://dharmx/walls/anime
github://Gingeh/wallpapers

GitHub URL Conversion

garbg also accepts standard GitHub web URLs and converts them internally:

terminal

$garbg set https://github.com/catppuccin/wallpapers/tree/main/landscapes

# Converted to: github://catppuccin/wallpapers/landscapes

How GitHub Sources Work

garbg parses the github:// URL to extract owner, repo, and path
Uses GitHub API to list directory contents at the specified path
Filters for image files based on extension
Downloads images via raw.githubusercontent.com
Caches downloaded images to ~/.cache/garbg/github/

GitHub Examples

terminal

$garbg set github://catppuccin/wallpapers/minimalistic

Fetching from GitHub: catppuccin/wallpapers/minimalistic Found 15 images Downloading: cat-sounds.png Set wallpaper: cat-sounds.png

$garbg set github://dharmx/walls/anime --shuffle --interval 600

$garbgctl list github://Gingeh/wallpapers

Images in github://Gingeh/wallpapers: catppuccin-beach.png catppuccin-clouds.png catppuccin-forest.png ... (42 total)

Rate Limiting

GitHub API has rate limits for unauthenticated requests (60/hour). garbg caches API responses to minimize requests. For heavy usage, set the GITHUB_TOKEN environment variable.

Source Management

List Source Contents

terminal

$garbgctl list ~/Pictures/Wallpapers

Images in /home/user/Pictures/Wallpapers: forest-morning.jpg mountain-sunset.png ocean-waves.jpg ... (47 total)

$garbgctl list github://catppuccin/wallpapers/misc

Cache Management

Remote sources are cached to ~/.cache/garbg/ for faster subsequent access:

terminal

$ls ~/.cache/garbg/

github/ http/ metadata.json

$du -sh ~/.cache/garbg/

245M /home/user/.cache/garbg/

$garbgctl clear-cache

Cleared 245MB from cache

Playlist State

Slideshow state is persisted to ~/.local/state/garbg/playlist.json so position is retained across daemon restarts:

// ~/.local/state/garbg/playlist.json
(
  "source": "/home/user/Pictures/Wallpapers",
  "source_type": "directory",
  "images": [
    "forest-morning.jpg",
    "mountain-sunset.png",
    "ocean-waves.jpg"
  ],
  "current_index": 12,
  "mode": "fill",
  "shuffle": true,
  "shuffle_order": [5, 2, 12, 0, 8, ...]
)

garbgctl CLI

garbgctl is the command-line control tool for the garbg daemon. It sends commands over a Unix domain socket using JSON protocol.

Commands

Option	Type	Default	Description
`set SOURCE`	-	-	Set wallpaper from file, directory, URL, or GitHub
`next`	-	-	Next wallpaper in slideshow playlist
`prev`	-	-	Previous wallpaper in slideshow playlist
`random`	-	-	Random wallpaper from current source
`pause`	-	-	Pause animations and slideshow
`resume`	-	-	Resume animations and slideshow
`toggle`	-	-	Toggle pause state
`status`	-	-	Get current wallpaper status as JSON
`reload`	-	-	Reload configuration from disk
`list SOURCE`	-	-	List wallpapers from a source
`query monitors`	-	-	List connected monitors
`query current`	-	-	Get current wallpaper info
`clear-cache`	-	-	Clear the image cache

Set Command Options

terminal

$garbgctl set SOURCE [OPTIONS]

$ --mode MODE # fill, fit, stretch, center, tile

$ --monitor NAME # Target specific monitor

$ --interval SECS # Slideshow interval

$ --shuffle # Shuffle playlist order

$ --animate # Enable animation for GIF/WebP/APNG

$ --max-fps FPS # Max animation frame rate

$ --span # Span across all monitors

Usage Examples

terminal

$garbgctl set ~/Pictures/wallpaper.jpg --mode fill

Set wallpaper: /home/user/Pictures/wallpaper.jpg

$garbgctl set ~/Pictures/Wallpapers --interval 300 --shuffle

Set slideshow source: /home/user/Pictures/Wallpapers (47 images) Interval: 300s, Shuffle: enabled

$garbgctl set ~/animated.gif --animate --max-fps 30

Set animated wallpaper: /home/user/animated.gif Animation: 24 frames, max 30 FPS

$garbgctl set ~/ultrawide.jpg --monitor DP-1 --mode fill

Set wallpaper for DP-1: /home/user/ultrawide.jpg

$garbgctl next

Advanced to: mountain-sunset.png (13/47)

$garbgctl prev

Returned to: forest-morning.jpg (12/47)

$garbgctl random

Set random wallpaper: ocean-waves.jpg

$garbgctl pause

Paused animations and slideshow

$garbgctl resume

Resumed animations and slideshow

$garbgctl status

( "source": "/home/user/Pictures/Wallpapers", "current": "forest-morning.jpg", "index": 12, "total": 47, "mode": "fill", "paused": false, "animated": false )

Query Commands

terminal

$garbgctl query monitors

[ ("name": "DP-1", "width": 2560, "height": 1440, "x": 0, "y": 0, "primary": true), ("name": "HDMI-1", "width": 1920, "height": 1080, "x": 2560, "y": 180, "primary": false) ]

$garbgctl query current

( "source": "/home/user/Pictures/Wallpapers/forest-morning.jpg", "mode": "fill", "monitors": [ ("name": "DP-1", "wallpaper": "forest-morning.jpg"), ("name": "HDMI-1", "wallpaper": "forest-morning.jpg") ] )

Keybinding Integration

Bind garbgctl commands to keys in gar's init.lua:

gar.keybinds = (
  -- Cycle wallpapers with Super+W
  ( mods = ( "Mod4" ), key = "w", action = "spawn", args = "garbgctl next" ),

  -- Previous wallpaper with Super+Shift+W
  ( mods = ( "Mod4", "Shift" ), key = "w", action = "spawn", args = "garbgctl prev" ),

  -- Random wallpaper with Super+Alt+W
  ( mods = ( "Mod4", "Mod1" ), key = "w", action = "spawn", args = "garbgctl random" ),

  -- Toggle pause with Super+P
  ( mods = ( "Mod4" ), key = "p", action = "spawn", args = "garbgctl toggle" ),
)

IPC Protocol

garbg's IPC uses JSON over a Unix domain socket at $XDG_RUNTIME_DIR/garbg.sock. Each message is a single JSON object terminated by a newline.

Socket Location

$XDG_RUNTIME_DIR/garbg.sock
# Typically: /run/user/1000/garbg.sock

Command Format

Commands are JSON objects with a "command" field (snake_case) and command-specific fields:

// Set wallpaper with full options
(
  "command": "set",
  "source": "/home/user/Pictures/wallpaper.jpg",
  "mode": "fill",
  "monitor": null,
  "interval_secs": null,
  "shuffle": false,
  "animate": true,
  "max_fps": 60,
  "span": false
)

// Set workspace-specific wallpaper
(
  "command": "set_workspace",
  "workspace": 3,
  "source": "/home/user/Pictures/workspace3.jpg",
  "mode": "fill"
)

// Set monitor-specific wallpaper
(
  "command": "set_monitor",
  "monitor": "DP-1",
  "source": "/home/user/Pictures/main-monitor.jpg",
  "mode": "fill"
)

// Navigation commands
("command": "next", "monitor": null)
("command": "prev", "monitor": null)
("command": "random", "monitor": null)

// Playback control
("command": "pause")
("command": "resume")
("command": "toggle")

// Status and queries
("command": "status")
("command": "reload")
("command": "list", "source": "/home/user/Pictures")
("command": "clear_cache")
("command": "query_monitors")
("command": "query_current")

// Event subscription
("command": "subscribe", "events": ["wallpaper_changed", "slideshow_advanced"])
("command": "unsubscribe", "events": ["wallpaper_changed"])

Available Commands

Option	Type	Default	Description
`set`	-	-	Set wallpaper with source, mode, monitor, interval, shuffle, animate, max_fps, span options
`set_workspace`	-	-	Set wallpaper for specific workspace (workspace, source, mode)
`set_monitor`	-	-	Set wallpaper for specific monitor (monitor, source, mode)
`next`	-	-	Next wallpaper in playlist (optional monitor filter)
`prev`	-	-	Previous wallpaper in playlist (optional monitor filter)
`random`	-	-	Random wallpaper from source (optional monitor filter)
`pause`	-	-	Pause animations and slideshow
`resume`	-	-	Resume animations and slideshow
`toggle`	-	-	Toggle pause state
`status`	-	-	Get current status
`reload`	-	-	Reload configuration
`list`	-	-	List wallpapers from source
`clear_cache`	-	-	Clear image cache
`subscribe`	-	-	Subscribe to events (array of event types)
`unsubscribe`	-	-	Unsubscribe from events
`query_monitors`	-	-	Get list of connected monitors
`query_current`	-	-	Get current wallpaper information

Response Format

// Success response
("success": true)

// Success with data
(
  "success": true,
  "data": (
    "source": "/home/user/Pictures/Wallpapers",
    "current": "forest.jpg",
    "index": 5,
    "total": 47
  )
)

// Error response
("success": false, "error": "Source not found: /invalid/path")

Event Subscription

Clients can subscribe to events for reactive updates:

Available Events

Option	Type	Default	Description
`wallpaper_changed`	-	-	Fired when wallpaper changes (monitor, source, workspace)
`source_updated`	-	-	Fired when source content changes (source, count)
`animation_state`	-	-	Fired when animation state changes (playing boolean)
`slideshow_advanced`	-	-	Fired when slideshow advances (current, total, source)
`error`	-	-	Fired on error (message, optional context)

Event Examples

// WallpaperChanged event
(
  "event": "wallpaper_changed",
  "monitor": "DP-1",
  "source": "/home/user/Pictures/mountain.jpg",
  "workspace": 1
)

// SlideshowAdvanced event
(
  "event": "slideshow_advanced",
  "current": 13,
  "total": 47,
  "source": "forest-morning.jpg"
)

// AnimationState event
(
  "event": "animation_state",
  "playing": true
)

// Error event
(
  "event": "error",
  "message": "Failed to load image",
  "context": "HTTP 404: Not Found"
)

Raw Socket Example

terminal

$echo '{"command": "status"}' | socat - UNIX-CONNECT:$XDG_RUNTIME_DIR/garbg.sock

{"success":true,"data":{"source":"/home/user/Pictures","current":"forest.jpg",...}}

Python Example

#!/usr/bin/env python3
import socket
import json
import os

sock_path = os.path.join(os.environ.get('XDG_RUNTIME_DIR', '/tmp'), 'garbg.sock')

def send_command(cmd):
    with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as sock:
        sock.connect(sock_path)
        sock.sendall((json.dumps(cmd) + '\n').encode())
        response = sock.recv(4096).decode()
        return json.loads(response)

# Set wallpaper
result = send_command((
    "command": "set",
    "source": "/home/user/Pictures/wallpaper.jpg",
    "mode": "fill"
))
print("Success:", result["success"])

# Get status
status = send_command(("command": "status"))
print("Current:", status["data"]["current"])

# Next wallpaper
send_command(("command": "next"))

Signal Handling

garbg responds to Unix signals for lifecycle management:

SIGTERM: Graceful shutdown (pixmaps retained for compositor)
SIGHUP: Reload configuration without changing current wallpaper
SIGINT: Graceful shutdown (Ctrl+C when running in foreground)
SIGUSR1: Advance to next wallpaper in slideshow

terminal

$pkill -SIGHUP garbg

# Reloads configuration

$pkill -SIGUSR1 garbg

# Next wallpaper

$pkill -SIGTERM garbg

# Graceful shutdown

Troubleshooting

garbg not starting

Check if another instance is running and verify the socket/PID file:

terminal

$pgrep -a garbg

$cat $XDG_RUNTIME_DIR/garbg.pid

$ls -la $XDG_RUNTIME_DIR/garbg.sock

$# If stale files exist, remove them:

$rm $XDG_RUNTIME_DIR/garbg.pid $XDG_RUNTIME_DIR/garbg.sock

Check systemd service status

terminal

$systemctl --user status garbg.service

$journalctl --user -u garbg.service -f

Wallpaper not appearing

Verify the root window pixmap is set correctly:

terminal

$xprop -root | grep _XROOTPMAP_ID

_XROOTPMAP_ID(PIXMAP): pixmap id # 0x2a00001

$xprop -root | grep ESETROOT_PMAP_ID

ESETROOT_PMAP_ID(PIXMAP): pixmap id # 0x2a00001

$# If no pixmap is set, try setting manually:

$garbg set ~/Pictures/test.jpg --mode fill

Black screen after setting wallpaper

This usually means the pixmap was freed prematurely. In daemon mode, pixmaps should persist:

terminal

$# Make sure daemon is running:

$garbg daemon &

$# Then set wallpaper via daemon:

$garbgctl set ~/Pictures/wallpaper.jpg

$# Without daemon, use standalone with --keep:

$garbg set ~/Pictures/wallpaper.jpg --keep

Animation stuttering

Check if the animation is too complex or max_fps is too high:

terminal

$# Lower max FPS:

$garbgctl set ~/animated.gif --animate --max-fps 30

$# Check frame count and timing:

$identify -verbose ~/animated.gif | grep -E "Delay|Frame"

$# Monitor CPU usage during animation:

$top -p $(pgrep garbg)

GitHub source not working

Check API rate limits and network connectivity:

terminal

$# Check rate limit:

$curl -s https://api.github.com/rate_limit | jq .rate

( "limit": 60, "remaining": 42, "reset": 1706889600 )

$# Set token for higher limits:

$export GITHUB_TOKEN=ghp_xxxxxxxxxxxx

$garbgctl set github://user/repo/path

Per-workspace wallpapers not changing

Verify gar is sending workspace events and garbg is subscribed:

terminal

$# Check if gar socket exists:

$ls -la $XDG_RUNTIME_DIR/gar-i3.sock

$# Verify workspace config in garbg config.toml:

$cat ~/.config/garbg/config.toml | grep -A5 "workspaces"

$# Test workspace change manually:

$garbgctl set ~/Pictures/ws1.jpg

$# Switch to workspace 2 in gar, then check:

$garbgctl status

Multi-monitor issues

Check RandR monitor configuration and verify garbg sees all monitors:

terminal

$xrandr --query | grep " connected"

DP-1 connected primary 2560x1440+0+0 HDMI-1 connected 1920x1080+2560+180

$garbgctl query monitors

[ ("name": "DP-1", "width": 2560, "height": 1440, ...), ("name": "HDMI-1", "width": 1920, "height": 1080, ...) ]

$# Set per-monitor wallpaper:

$garbgctl set ~/Pictures/main.jpg --monitor DP-1

$garbgctl set ~/Pictures/secondary.jpg --monitor HDMI-1

Cache issues

If remote images are outdated or corrupted, clear the cache:

terminal

$garbgctl clear-cache

Cleared 245MB from cache

$# Or manually remove cache directory:

$rm -rf ~/.cache/garbg/*

$# Check cache size:

$du -sh ~/.cache/garbg/

Debug logging

Enable verbose logging to diagnose issues:

terminal

$RUST_LOG=debug garbg daemon 2>&1 | tee garbg.log

$# Or with specific module logging:

$RUST_LOG=garbg::source=debug garbg set github://user/repo

$RUST_LOG=garbg::animation=debug garbg set ~/animated.gif --animate

Image format issues

Verify the image format is supported and not corrupted:

terminal

$file ~/Pictures/wallpaper.jpg

/home/user/Pictures/wallpaper.jpg: JPEG image data, JFIF standard 1.01

$identify ~/Pictures/wallpaper.jpg

/home/user/Pictures/wallpaper.jpg JPEG 3840x2160 sRGB 2.5MB

$# Check if animated:

$identify ~/Pictures/animated.gif | wc -l

24 # 24 frames

Known Limitations

Wayland is not supported - garbg requires X11 for pixmap management
Transition effects (fade, slide) are not yet implemented
HDR images are tone-mapped to SDR during loading
Very large animated GIFs may use significant memory (all frames are decoded)
GitHub rate limits apply without GITHUB_TOKEN (60 requests/hour)

Getting Help

GitHub Issues: github.com/espadon/gardesk/issues
Check journalctl logs: journalctl --user -u garbg.service
Run with verbose logging: RUST_LOG=debug garbg daemon