Dynamic Wallpaper Manager for Wayland

A lightweight Go application to automate your wallpapers with `Swaybg` or `Hyprpaper`, featuring powerful `pywal` integration for dynamic theming.

View on GitHub

Showcase Video

Key Features

🔄

Intelligent Rotation

Automatically cycles through your wallpaper collection at customizable intervals.

🕹️

Manual Control

Easily switch to the next or previous wallpaper on demand using simple commands.

🖥️

Multi-Backend Support

Seamlessly works with either `Swaybg` or `Hyprpaper` to set your wallpapers.

🎨

Pywal Integration

Dynamically extracts colors from your wallpaper to theme your entire system.

⚙️

Highly Configurable

Manage all behavior, from rotation interval to backend choice, via a simple config file.

🔍

Current Wallpaper Query

Quickly find out which wallpaper is currently active with the `current` command.

How It Works

`hpaper` runs as a persistent daemon, listening for commands via a Unix socket. When a wallpaper change is triggered (manually or automatically), it communicates with your chosen backend and `pywal`.

hpaper next

(Client)

hpaper Daemon

(Unix Socket)

Swaybg / Hyprpaper

(Backend)

pywal

(Theming)

Installation

Arch Linux (AUR)

paru -S hpaper

Go Install

go install github.com/Hcode00/hpaper

From Release

You can also download a pre-compiled binary from the release page.

Configuration

`hpaper` is controlled by a simple config file at ~/.config/hpaper/hpaper.conf. If it doesn't exist, it's created on the first run. Try the controls below to see how it works!

Interactive Demo

Randomize

Backend

Enable Pywal

# General Settings
wallpaper_dir = /home/user/Pictures/wallpapers/
rotation_interval = 3600
randomize = true
backend = "swaybg"

# swaybg settings
swaybg_mode = "fill"
swaybg_output = ""

# hyprpaper settings
monitor_name = "all"

# pywal settings
pywal_enabled = false
pywal_command = "wal --cols16 -n"

Usage

Daemon Command

# Start the daemon, overriding the config's wallpaper directory
hpaper start <wallpaper_directory> [flags]

# Example:
hpaper start ~/wallpapers/

Client Commands

hpaper next
hpaper prev
hpaper current
hpaper quit

Hyprland Integration Example

# In ~/.config/hypr/hyprland.conf

# Start hpaper on login
exec-once = hpaper start ~/.config/hypr/wallpapers/

# Bind keys to control hpaper
bind = SUPER, W, exec, hpaper next
bind = SUPER SHIFT, W, exec, hpaper prev