(dynamic desktop kaleidoscope)

High-performance, hardware-accelerated wallpaper daemon for Linux.
Supports Wayland & X11 with 50+ smooth GLSL transitions.

Table of Contents

• Quickstart
• Features
• Installation
• Usage Breakdown
• Configuration
• Troubleshooting
• Contributing
• License

More Info: Detailed Usage & Advanced Config

Quickstart

Get up and running in 30 seconds:

# Install with Nix (recommended)
nix run github:Mjoyufull/Kaleidux

# Or build from source
git clone https://github.com/Mjoyufull/Kaleidux && cd Kaleidux
cargo build --release
sudo cp target/release/kaleidux-daemon /usr/local/bin/
sudo cp target/release/kldctl /usr/local/bin/

# Start the daemon
kaleidux-daemon &

# Skip to next wallpaper
kldctl next

Features

• Video Support: Seamlessly loop videos as wallpapers using GStreamer.
• Image Support: High-quality image rendering and transitions.
• Hardware Accelerated: Powered by WGPU for near-zero CPU overhead during transitions.
• 50+ Transitions: Huge library of GLSL transitions (fade, cube, doom, wipe, ripple, etc.).
• Multi-Monitor: Independent queue management for each output.
• Monitor Behaviors: Independent, Synchronized, or Grouped monitor support.
• Rhai Scripting: Automate your wallpaper logic with Rust-like scripts.
• IPC Control: Control the daemon via kldctl (next, prev, pause, status, etc.).

Installation

Option 1: Aur (Recommended)

• Installing from the Arch User Repository

$ yay -S kaleidux-git
# or
$ paru -S kaleidux-git

Option 2: Nix Flake

• Build and run with Nix flakes:

  nix run github:Mjoyufull/Kaleidux

• Add to your flake.nix inputs:

  {
    inputs.kaleidux.url = "github:Mjoyufull/Kaleidux";
  }

Option 3: Build from Source

Build Requirements:

• Rust 1.89+ stable
• GStreamer 1.20+ with dev plugins
• Wayland and/or X11 development headers

Arch Linux Setup:

sudo pacman -S gstreamer gst-plugins-base gst-plugins-good \
               gst-plugins-bad gst-libav wayland libx11 \
               vulkan-devel pkgconf cmake

Build:

git clone https://github.com/Mjoyufull/Kaleidux && cd Kaleidux
cargo build --release

Usage Breakdown

Daemon (kaleidux-daemon)

The core background service handling rendering and display interop.

Usage: kaleidux-daemon [OPTIONS]

Options:
      --demo       Run in demo mode (rotating built-in shaders)
      --log <PATH> Specify log file path
  -h, --help       Show help

Controller (kldctl)

Swiss Army knife for interacting with the running daemon.

kldctl
├── next [n]      Skip to the next wallpaper
├── prev [p]      Go back to the previous wallpaper
├── query [q]     List connected outputs and current state
├── love <PATH>   Increase selection frequency for a file
├── unlove <PATH> Reset frequency for a file
├── lovelist [ll] List all "loved" wallpapers
├── pause         Pause video playback
├── resume        Resume video playback
├── reload        Reload configuration from disk
├── kill          Stop the daemon gracefully
├── playlist      Manage content playlists
├── blacklist     Manage excluded files
└── history       Show recently played wallpapers

Quick Usage Examples

# Love the current wallpaper on a specific monitor
kldctl love ~/wallpapers/nature.jpg

# List status of all monitors
kldctl query

# Sync all monitors to the next wallpaper
kldctl next --all

Configuration

Default location: ~/.config/kaleidux/config.toml

[global]
monitor-behavior = "independent"
sorting = "loveit"
video-ratio = 50

[any]
transition = { type = "cube", duration = 1000 }

See USAGE.MD for full configuration reference.

Troubleshooting

• Long Startup: WGPU may wait for driver initialization on Wayland (~15s).
• High CPU: Video frames currently use a CPU-RGBA roundtrip. Zero-copy is planned.
• Shader Errors: Ensure your GPU supports Vulkan or GLSL 450.

Contributing

See CONTRIBUTING.md and PROJECT_STANDARDS.md for guidelines.

Credits

• gSlapper
• wpaperd
• mpvpaper
• GStreamer
• Clapper
• swww

License

Kaleidux is licensed under the AGPL-3.0 License.