Configuration Options
Relevant source files
The following files were used as context for generating this wiki page:
The Kaleidux configuration system is designed to provide high-performance, hardware-accelerated wallpaper management with a flexible, hierarchical structure. The configuration is primarily managed through a TOML file located at ~/.config/kaleidux/config.toml, which allows users to define global behaviors, fallback settings for all monitors, and specific overrides for individual displays.
The architecture employs a layered merging logic where specific output configurations take precedence over the [any] fallback section, which in turn inherits from the [global] settings. This ensures that the daemon can handle complex multi-monitor setups with minimal redundant configuration while allowing for precise control over transitions, display durations, and content selection strategies.
Sources: kaleidux-daemon/src/orchestration.rs:141-160, config.example.toml:1-12
Configuration Hierarchy and Resolution
The configuration resolution process follows a strict priority order. When an output is detected, the Config::get_config_for_output function determines the final parameters by merging multiple layers of settings.
The diagram shows the priority of configuration resolution, starting from the broadest global defaults to the most specific per-output overrides.
Resolution Steps
- Global Defaults: Loads settings from the
[global]block, such asmonitor-behaviorand defaultvideo-ratio. - Any Fallback: Merges settings from the
[any]section, which acts as a default for all outputs not specifically mentioned. - Specific Output: Checks for a section matching the output name (e.g.,
[DP-1]). - Regex Matching: If no direct name match is found, it attempts to match the output description using regex (e.g.,
["re:Dell.*"]).
Sources: kaleidux-daemon/src/orchestration.rs:162-205, config.example.toml:44-65
Global Settings
The [global] section defines parameters that affect the daemon's overall operation and cross-monitor synchronization.
| Option | Type | Default | Description |
|---|---|---|---|
monitor-behavior | Enum | independent | Defines how monitors coordinate (Independent, Synchronized, or Grouped). |
sorting | Enum | loveit | Default strategy for content selection (loveit, random, ascending, descending). |
video-ratio | Integer | 50 | Probability (0-100) of selecting a video over an image. |
transition-time | Integer | 1000 | Duration of the transition effect in milliseconds. |
volume | Float/Int | 1.0 | Global volume level for video wallpapers (0.0 to 10.0). |
script-path | String | None | Path to a Rhai script for automated logic. |
script-tick-interval | Integer | 1 | Frequency in seconds to execute the Rhai script. |
Sources: kaleidux-daemon/src/orchestration.rs:99-115, config.example.toml:12-40
Output Configuration Settings
These settings can be placed in [any] or specific output sections (e.g., [DP-1]).
| Option | Type | Default | Description |
|---|---|---|---|
path | Path | None | Directory containing image and video assets. |
duration | Duration | 5m | Time to display a wallpaper before cycling (supports humantime like 30s, 5m). |
transition | Table | {type="fade"} | The specific GLSL shader effect to use during changes. |
layer | Enum | background | Wayland layer shell level (background, bottom, top, overlay). |
default-playlist | String | None | Initial playlist to load for the output. |
Sources: kaleidux-daemon/src/orchestration.rs:32-47, config.example.toml:44-55
Monitor Behaviors
The monitor-behavior setting dictates the synchronization logic handled by the MonitorManager.
The diagram illustrates how monitors are mapped to content queues based on the chosen behavior.
- Independent: Each monitor operates its own
SmartQueueand timer. - Synchronized: All monitors share a single queue and switch content simultaneously.
- Grouped: Users define specific arrays of monitors (e.g.,
grouped = [["DP-1", "DP-2"], ["HDMI-A-1"]]) to share queues within groups.
Sources: kaleidux-daemon/src/orchestration.rs:9-15, kaleidux-daemon/src/monitor_manager.rs:188-264, config.example.toml:73-82
Transition Effects
Kaleidux supports over 50 built-in GLSL transitions. These are configured via a type and optional parameters.
Transition Configuration Examples
# Simple transition
transition = { type = "fade" }
# Parametric transition
transition = { type = "cube", persp = 0.7, unzoom = 0.3, reflection = 0.4, floating = 3.0 }
# Random built-in selection
transition = "random"
Sources: config.example.toml:92-140, transitions_examples.toml:10-15
Transition Parameter Mapping
The ShaderManager maps TOML parameters to GLSL uniforms using the getFromParams helper.
// Internal mapping example for the 'Angular' transition
Transition::Angular { .. } => "float startingAngle = getFromParams(0);",
// Internal mapping example for the 'Cube' transition
Transition::Cube { .. } => "float persp = getFromParams(0); float unzoom = getFromParams(1); float reflection = getFromParams(2); float floating = getFromParams(3);",
Sources: kaleidux-daemon/src/shaders.rs:184-205
Runtime Configuration Management
The daemon supports real-time configuration updates without restarting the service. This is triggered via the IPC mechanism using kldctl reload.
The sequence diagram shows the flow of a configuration reload command from the CLI to the internal modules.
Sources: kaleidux-daemon/src/main.rs:1186-1205, kldctl/src/main.rs:186-186
Configuration Validation
Users can validate their configuration files using the controller utility:
kldctl check-config
This performs a local TOML parsing check and path verification without communicating with the background daemon.
Sources: kldctl/src/main.rs:141-163
The configuration system serves as the central nervous system of Kaleidux, enabling seamless coordination between high-performance WGPU rendering and user-defined aesthetic preferences. By utilizing a hierarchical TOML structure, it provides power users with deep customization while maintaining sensible defaults for standard setups.