gnome-slideshow

A intentionally small, dependency-light CLI (slideshow) that turns a directory (or optionally, separate light/dark directories) of photos into a proper GNOME wallpaper slideshow. I was annoyed that this isnt a built in feature, and I didn't want to install a whole third party package to handle something simple, so this CLI allows for quick refresh/config of your wallpaper slideshow.

• Scans a flat directory of images (you choose on first run)
• Generates the classic two-XML definition (~/.local/share/backgrounds/... + gnome-background-properties/...)
• Applies via gsettings (supports picture-uri + picture-uri-dark)
• Optional lock screen / screensaver synchronization
• Appears in Settings > Background with the clock icon
• Fully configurable (duration, transitions, shuffle, auto-apply, etc.)
• Interactive first-run wizard

No third-party wallpaper apps or GNOME extensions required.

Installation

Quick one-liner (Linux)

curl -fsSL https://raw.githubusercontent.com/rafaelzasas/gnome-slideshow/main/install.sh | bash

From GitHub Releases

Download the latest .tar.gz (or .deb) from the Releases page, then:

tar -xzf gnome-slideshow_Linux_*.tar.gz
sudo install -m 755 slideshow /usr/local/bin/slideshow

# Completions (bash example)
slideshow completion bash | sudo tee /usr/share/bash-completion/completions/slideshow >/dev/null

From source

git clone https://github.com/rafaelzasas/gnome-slideshow.git
cd gnome-slideshow
make build
sudo make install   # installs binary + completions

Or simply:

go install github.com/rafaelzasas/gnome-slideshow/cmd/slideshow@latest

Quick Start

slideshow          # first run → interactive setup wizard
# Add / remove photos in your folder(s)
slideshow refresh  # or just `slideshow` if you like the wizard

The tool will:

1. Ask for your wallpaper directory(ies) on first run (or slideshow setup)
2. Generate the required XML files
3. Apply them (configurable)

Commands

• slideshow refresh — scan, (re)generate XMLs, apply (default behavior)
• slideshow apply — just apply the current configuration via gsettings
• slideshow reshuffle — shuffle the current images and refresh+apply
• slideshow list — show which photos will be used
• slideshow config — interactive editor (or use subcommands like config set light-dir ...)
• slideshow setup — re-run the first-run wizard
• slideshow completion ... — shell completion scripts (bash/zsh/fish)

Flags on refresh (and others) allow temporary overrides (--duration, --shuffle, --no-apply, --light-dir, etc.).

Configuration

Stored at ~/.config/gnome-slideshow/config.json.

Key fields:

• light_dir, dark_dir (dark falls back to light if empty)
• duration, transition (seconds)
• auto_apply_on_refresh
• register_properties (makes it appear in Settings)
• shuffle
• enable_lock_screen
• name (the label shown in the background picker)

You can edit the JSON directly or use the slideshow config command.

How it works (what the two XML files are for)

For some reason gnome uses XML to allow for wallpaper slideshows. I dindt want to manually edit them each time I added photos to my wallpapers directory. This tool simply automates the editing of the XML files by auto appending the newly found photos.

1. Timed slideshow definition (the actual cycling logic)
2. Properties registration (so it shows up nicely in the UI with a clock emblem)

It writes user-local files only (~/.local/share/...), no root required.

Lock Screen

Enable with:

slideshow config set enable-lock-screen true
# or during initial setup

The tool will then also set org.gnome.desktop.screensaver picture-uri (and -dark when possible).

Roadmap

[] watch / daemon mode (inotify / fsnotify) to auto-refresh when files change: would be nice but I dont feel like doing it yet. [] More image formats / recursive scan (opt-in) [] Better error recovery and validation

Contributing

PRs and issues welcome. Please run make test and go build before submitting.

License

MIT

Credits

Built with:

• cobra
• tap (Really neat, small mini TUI)
• Pure Go stdlib for the rest