Chroma

Super-fast, lightweight and efficient wallpaper daemon for Wayland compositors with multi-monitor & hotplugging support. Born from my woes with Hyprpaper, swaybg and most ironically SWWW (now called AWWW for some awful reason), which turned out to be NOT a solution to my Wayland wallpaper woes. Smaller, faster, cleaner and somehow still more feature-rich...

Features

Chroma combines simplicity with powerful performance optimizations and comprehensive monitor management. Here's what makes Chroma stand out:

Core Functionality

• Memory-efficient: Smart caching and resource management
  • Optimized rendering: VBO dirty flagging and reduced GPU overhead
• Multi-monitor support: Automatically detects and manages wallpapers for all connected displays
  • Configurable scaling modes: Fill, fit, stretch, and center options per monitor
• Hotplugging: Dynamically handles monitor connection/disconnection events
• Per-output configuration: Set different wallpapers and settings for each monitor
  • Global and per-output settings: Override defaults for specific monitors
  • Performance tuning: Adjustable downsampling limits and quality thresholds
• 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)
• Intelligent downsampling: Automatically reduces large image resolution to save memory (up to 94% memory savings for 8K images)
• Advanced filtering: Nearest, linear, bilinear, and trilinear filtering options

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

See development section for more details. This section might get outdated at any given moment, so refer to the Nix shell if in doubt.

Building

Quick Build

# Check dependencies
make check-deps

# Build the daemon
make

# Or build debug version
make debug

# Alternatively, create a static build
make static

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, but should work fine with any compositor that meets the above criteria. Which is basically all of them I think?

Contributing

You might want to contribute to Chroma for a variety of reasons. I usually will not judge, however, there are some conventions I expect you to adhere to. Mainly I would like for you to follow the project's code style:

• C11 standard (I really wished for C99)
• 2-space indentation (use make format)
• No tabs (except for the Makefile, obviously)
• Function names: chroma_function_name
• Constants: CHROMA_CONSTANT_NAME

Once your changes are done, fork this repository and create a feature branch. This is not a strict requirement but I'd rather not deal with rebase failures. Create your feature branch, make your changes, test thoroughly and submit your pull request when you are done. With your pull request, I'd really like a tiny snippet of text that explains your motive of changes. While I can infer what you are trying to do, I'd rather know what was going on in your head.

Development

A Nix shell is provided within the repository. You may use both nix-shell and nix develop to enter a development shell with all of the required dependencies for dynamic linking. Additionally, Direnv users may use direnv allow to use the shell provided by the repository.

A few convenience commands are provided by the Makefile, which you may invoke at your own discretion.

Building Debug Version

make debug

Code Formatting

make format  # requires clang-format

Static Analysis

make analyze  # requires cppcheck

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.