Simple, lightweight and efficinent wallpaper daeemon for Wayland
Find a file
NotAShelf 0bc2decb7c
docs: add project README
Signed-off-by: NotAShelf <raf@notashelf.dev>
Change-Id: I6a6a696411e599829afb123a5f3c241768470163
2025-09-30 20:11:50 +03:00
include render: add OpenGL resource caching; optimize texture handling 2025-09-30 20:11:47 +03:00
protocols initial commit 2025-09-30 20:11:40 +03:00
src render: add OpenGL resource caching; optimize texture handling 2025-09-30 20:11:47 +03:00
systemd chore: add systemd service 2025-09-30 20:11:46 +03:00
.editorconfig meta: set up editorconfig 2025-09-30 20:11:42 +03:00
.envrc init nix tooling 2025-09-30 20:11:41 +03:00
.gitattributes meta: set vendored code manually 2025-09-30 20:11:48 +03:00
.gitignore meta: correctly ignore corrected files 2025-09-30 20:11:43 +03:00
chroma.conf.sample add sample configuration 2025-09-30 20:11:49 +03:00
flake.lock init nix tooling 2025-09-30 20:11:41 +03:00
flake.nix init nix tooling 2025-09-30 20:11:41 +03:00
LICENSE meta: release under MPL v2.0 2025-09-30 20:11:45 +03:00
Makefile chore: set up Makefile for building 2025-09-30 20:11:44 +03:00
README.md docs: add project README 2025-09-30 20:11:50 +03:00
shell.nix init nix tooling 2025-09-30 20:11:41 +03:00

Chroma

A simple, lightweight and efficientt wallpaper daeemon for Wayland compositors with multi-monitor & automatic hotplugging support. Born from my woes with Hyprpaper, swaybg and most ironically SWWW, which turned out to be NOT a solution to my Wayland wallpaper woes.

Features

I did not expect to be writing something too feature-rich, but I still ended up with something relatively convoluted. Chroma (mostly) reliably supports:

  • Multi-monitors: Automatically detects and manages wallpapers for all connected displays
  • Hotplugging: Dynamically handles monitor connection/disconnection events
  • Per-output configuration: Set different wallpapers for each monitor
  • Multiple image formats: Supports JPEG, PNG, BMP, TGA, PSD, GIF, HDR, PIC, PPM, PGM
  • EGL/OpenGL rendering: Hardware-accelerated wallpaper rendering
  • Configuration file support: Easy setup with INI-style config files
  • Signal handling: Graceful shutdown and configuration reload (SIGHUP)

Usage

Requirements

Dependencies

  • Wayland: wayland-client, wayland-egl
  • Graphics: EGL, OpenGL
  • System: glibc, libm, libdl

Development Dependencies

  • GCC or Clang compiler
  • Make
  • pkg-config
  • Wayland development headers
  • EGL/OpenGL development headers

Building

Quick Build

# Check dependencies
make check-deps

# Build the daemon
make

# Or build debug version
make debug

Installation

# Install to /usr/local (default)
sudo make install

# Install to /usr
sudo make PREFIX=/usr install

# Create systemd service file
make systemd-service

# Create sample configuration
make sample-config

Configuration

Configuration File

Chroma looks for configuration files in this order:

  1. ~/.config/chroma/chroma.conf
  2. $XDG_CONFIG_HOME/chroma/chroma.conf
  3. ./chroma.conf (current directory)

Sample Configuration

# Default wallpaper for outputs without specific mapping
default_image = ~/.config/chroma/default.jpg

# Output-specific wallpapers
# Format: output.OUTPUT_NAME = /path/to/image.jpg
output.DP-1 = ~/Pictures/monitor1.jpg
output.DP-2 = ~/Pictures/monitor2.png
output.HDMI-A-1 = ~/Pictures/hdmi_wallpaper.jpg

Finding Output Names

Use wlr-randr or similar tools to find your output names:

wlr-randr

Command Line Options

Usage: chroma [OPTIONS]

Options:
  -c, --config FILE    Configuration file path
  -d, --daemon         Run as daemon
  -v, --verbose        Verbose logging
  -h, --help          Show help
  --version           Show version information

Examples:
  chroma -c ~/.config/chroma/chroma.conf
  chroma --daemon

Running Manually

# Run in foreground
chroma

# Run as daemon
chroma --daemon

# Use custom config
chroma -c /path/to/config.conf

Systemd Service

# Enable and start the service
systemctl --user enable chroma.service
systemctl --user start chroma.service

# Check status
systemctl --user status chroma.service

# View logs
journalctl --user -u chroma.service -f

# Reload configuration
systemctl --user reload chroma.service

Auto-start with Desktop Session

# Enable the service for auto-start
systemctl --user enable chroma.service

# The service will start automatically with your graphical session

Supported Wayland Compositors

Chroma works with any Wayland compositor that supports:

  • wl_compositor interface
  • wl_output interface
  • EGL window surface creation

Tested only on Hyprland.

Development

Building Debug Version

make debug

Code Formatting

make format  # requires clang-format

Static Analysis

make analyze  # requires cppcheck

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Test thoroughly
  5. Submit a pull request

Code Style

  • C11 standard
  • 2-space indentation
  • No tabs
  • Function names: chroma_function_name
  • Constants: CHROMA_CONSTANT_NAME

License

This project is made available under Mozilla Public License (MPL) version 2.0. See LICENSE for more details on the exact conditions. An online copy is provided here.