Quickstart and Installation

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• CONTRIBUTING.md
• PROJECT_STANDARDS.md
• config.example.toml
• Cargo.toml
• kaleidux-daemon/src/main.rs
• kldctl/src/main.rs

Kaleidux is a high-performance, hardware-accelerated wallpaper daemon designed for Linux environments supporting both Wayland and X11. It leverages the WGPU graphics API to provide smooth GLSL transitions between image and video content with minimal CPU overhead. The system is split into two primary components: the background daemon (kaleidux-daemon) and a command-line controller (kldctl) for real-time interaction.

The purpose of this guide is to provide a streamlined path for setting up the development environment, building the binaries from source, and executing the initial configuration required to run the daemon. This includes handling dependencies for graphics acceleration via Vulkan and video processing through GStreamer.

Sources: README.md:14-22, CONTRIBUTING.md:146-155

Prerequisites and Environment Setup

Before installation, the system must meet specific hardware and software requirements to ensure GPU acceleration and video playback function correctly.

System Requirements

• Operating System: Linux (Wayland or X11).
• Graphics: GPU with Vulkan or GLSL 450 support.
• Rust Toolchain: Rust 1.89+ stable (Nightly is explicitly discouraged).

Sources: README.md:76-80, CONTRIBUTING.md:46-51, PROJECT_STANDARDS.md:145-147

Dependency Installation (Arch Linux Example)

The following packages are required for building and running Kaleidux:

Category	Package Names
GStreamer	gstreamer, gst-plugins-base, gst-plugins-good, gst-plugins-bad, gst-libav
Graphics	vulkan-devel, libx11, wayland
Build Tools	pkgconf, cmake, cargo

Sources: README.md:84-88, CONTRIBUTING.md:55-61

Installation Options

Option 1: Arch User Repository (AUR)

For Arch-based distributions, users can install the git version of Kaleidux using an AUR helper:

# Using yay
yay -S kaleidux-git

# Using paru
paru -S kaleidux-git

Sources: README.md:60-64

Option 2: Nix Flake

Kaleidux supports Nix for reproducible builds. You can run it directly or add it to a flake configuration:

# Run directly
nix run github:Mjoyufull/Kaleidux

Sources: README.md:66-74

Option 3: Building from Source

Manual compilation provides the most control over the build process.

# Clone the repository
git clone https://github.com/Mjoyufull/Kaleidux && cd Kaleidux

# Compile in release mode
cargo build --release

# Install binaries
sudo cp target/release/kaleidux-daemon /usr/local/bin/
sudo cp target/release/kldctl /usr/local/bin/

Sources: README.md:92-96, CONTRIBUTING.md:120-130

Initial Execution Flow

The following diagram illustrates the sequence of starting the daemon and verifying the installation.

This diagram shows the internal initialization order of the daemon components during startup.
Sources: kaleidux-daemon/src/main.rs:250-320, kldctl/src/main.rs:252-258

Basic Configuration

The daemon expects a configuration file at ~/.config/kaleidux/config.toml. If missing, it will use internal defaults.

Quickstart Configuration Snippet

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

[any]
path = "~/Pictures/Wallpapers"
duration = "5m"
transition = { type = "fade" }

Sources: README.md:143-154, config.example.toml:1-35

Verification Commands

Once the daemon is running, use the controller to verify the system state:

• kldctl query: Lists connected monitors and current wallpaper status.
• kldctl check-config: Validates the TOML syntax of the configuration file.
• kldctl next: Forces a transition to the next available wallpaper.

Sources: kldctl/src/main.rs:105-160, README.md:120-138

Troubleshooting the Installation

• Long Initialization: On Wayland, WGPU may take up to 15 seconds to initialize the driver context.
• Socket Errors: If kldctl cannot connect, ensure the daemon is running and that the socket file (typically in XDG_RUNTIME_DIR or /tmp/kaleidux-{USER}.sock) has appropriate permissions (0600).
• Video Playback: Ensure GStreamer plugins (good/bad/ugly/libav) are installed, or video content will fail to render.

Sources: README.md:158-162, kaleidux-daemon/src/main.rs:434-442, CONTRIBUTING.md:55-58

Summary

To get Kaleidux running, a user must install the necessary GStreamer and Vulkan dependencies, build the workspace using cargo build --release, and launch the kaleidux-daemon. Control is managed via kldctl over a Unix domain socket, allowing for dynamic wallpaper switching and configuration reloading without restarting the background service.

Sources: README.md:27-40, PROJECT_STANDARDS.md:347-353