Daemon Service (kaleidux-daemon)
Relevant source files
The following files were used as context for generating this wiki page:
The kaleidux-daemon is the core background service of the Kaleidux project, responsible for high-performance, hardware-accelerated wallpaper rendering on Linux systems. It serves as the orchestration layer that manages display outputs, content selection, and transition execution for both static images and video files.
The daemon abstracts display server complexities by supporting both Wayland and X11 backends, utilizing WGPU for GPU-accelerated GLSL transitions and GStreamer for seamless video playback. It provides an IPC (Inter-Process Communication) interface via Unix domain sockets, allowing external utilities like kldctl to control playback, query status, and modify configuration at runtime.
Sources: README.md:43-47, kaleidux-daemon/src/main.rs:242-251
System Architecture
The daemon architecture is built on an asynchronous event loop powered by Tokio, managing several specialized modules:
| Component | Responsibility |
|---|---|
| Backend (Wayland/X11) | Manages surfaces/windows and handles display-specific events (resizes, frame callbacks). |
| Renderer | Executes WGPU pipelines, manages textures, and runs GLSL transition shaders. |
| Monitor Manager | Coordinates multiple outputs and their independent or synchronized states. |
| Queue Manager | Handles file discovery, sorting strategies (e.g., "loveit"), and history. |
| Video Player | Interfaces with GStreamer to decode video frames and sync them with the renderer. |
| Cache/Persistence | Uses redb to store file metadata, stats, playlists, and blacklists. |
Sources: kaleidux-daemon/src/main.rs:18-28, kaleidux-daemon/src/cache.rs:11-16, README.md:43-53
Initialization Flow
When the daemon starts, it performs environment detection to determine the appropriate backend and initializes the rendering context.
The daemon utilizes jemalloc for memory management to handle fragmentation in long-running processes and enforces a global semaphore to limit concurrent image decoding tasks, preventing memory spikes.
Sources: kaleidux-daemon/src/main.rs:11-16, kaleidux-daemon/src/main.rs:242-258
IPC and Command Handling
The daemon listens on a Unix domain socket (typically XDG_RUNTIME_DIR/kaleidux.sock) for JSON-encoded Request objects. Each request is processed asynchronously, and a Response is returned to the client.
Request Handling Sequence
Supported Commands
| Command | Action |
|---|---|
Next / Prev | Transitions to the next or previous wallpaper in the queue. |
QueryOutputs | Returns information about connected monitors and current wallpapers. |
Love / Unlove | Adjusts the selection frequency multiplier for specific files. |
Pause / Resume | Toggles video playback and automated wallpaper cycling. |
Reload | Hot-reloads the TOML configuration from disk. |
Clear | Removes content from an output, resulting in a black screen. |
Sources: kldctl/src/main.rs:66-126, kaleidux-daemon/src/main.rs:967-1090
Resource Management and Persistence
The daemon maintains a persistent database using redb to track file statistics and user preferences across sessions.
Database Schema (redb Tables)
| Table | Key | Value | Purpose |
|---|---|---|---|
file_cache | Path bytes | FileMetadata | Stores mtime, size, and content type. |
file_stats | Path bytes | FileStats | Tracks use counts and "love" multipliers. |
playlists | String | Playlist Data | Persists user-defined content groups. |
blacklist | Path bytes | Boolean | Excludes specific files from selection. |
history | Output Name | List of Paths | Tracks recently displayed wallpapers. |
Sources: kaleidux-daemon/src/cache.rs:11-16, kaleidux-daemon/src/cache.rs:32-47
Performance Monitoring
The PerformanceMetrics module tracks the health of the daemon, providing real-time data on:
- Frame Timing: Records average, p50, p95, and p99 frame times to detect stutters.
- Resource Leaks: Monitors texture counts, pipeline counts, and channel buffer sizes.
- CPU Utilization: Tracks time spent in rendering vs. video decoding vs. file discovery.
- Memory Tracking: Samples current and peak memory usage, calculating growth rates.
Sources: kaleidux-daemon/src/metrics.rs:7-60, kaleidux-daemon/src/metrics.rs:356-420
Content Switching Logic
Switching a wallpaper involves a complex handoff between the file system, the decoder (GStreamer or Image decoder), and the GPU.
To ensure stability, the daemon enforces a 60 FPS target frame time (approx. 16.6ms per loop). It also implements a "stale player" check: if a new video player is started for an output, the previous session's player is offloaded to a background task for graceful termination.
Sources: kaleidux-daemon/src/main.rs:65-98, kaleidux-daemon/src/main.rs:665-680, kaleidux-daemon/src/main.rs:728-735
Configuration
The daemon is configured via a TOML file located at ~/.config/kaleidux/config.toml. It supports global defaults with per-output overrides and regex-based monitor matching.
| Field | Type | Default | Description |
|---|---|---|---|
monitor-behavior | String | independent | independent, synchronized, or grouped. |
video-ratio | Integer | 50 | Probability (0-100) of picking a video over an image. |
sorting | String | loveit | Strategy: loveit, random, ascending, descending. |
transition-time | Integer | 1000 | Duration of the GLSL transition in milliseconds. |
Sources: config.example.toml:13-38, kaleidux-daemon/src/main.rs:305-316
Summary
The kaleidux-daemon provides a robust, high-performance foundation for dynamic desktop backgrounds on Linux. By combining asynchronous task management, hardware-accelerated rendering, and persistent state tracking, it delivers smooth transitions and efficient resource usage across multi-monitor setups. Its modular design allows for extensive customization through scripting and IPC-driven control.