Monitor Behaviors & Synchronization

Relevant source files

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

• kaleidux-daemon/src/orchestration.rs
• kaleidux-daemon/src/monitor_manager.rs
• kaleidux-daemon/src/main.rs
• config.example.toml
• kaleidux-daemon/src/monitor.rs
• README.md

Monitor Behaviors and Synchronization in Kaleidux define how multiple display outputs interact with wallpaper queues and timing logic. The system allows users to configure whether monitors operate as entirely separate entities, act in perfect lockstep, or function in specific grouped sets. This orchestration is primarily handled by the MonitorManager and OutputOrchestrator components within the kaleidux-daemon.

The core logic ensures that wallpaper transitions, timing durations, and content selection strategies (such as "loveit" or "random") are applied consistently across the desired desktop layout. By abstracting the monitor behavior, Kaleidux supports complex multi-head setups on both Wayland and X11 backends while maintaining hardware-accelerated performance.

Behavior Modes

Kaleidux supports three primary monitor behaviors configured via the global section of the configuration file.

Independent Mode

The default mode where each monitor manages its own SmartQueue, current_path, and duration timers. Changes on one monitor do not affect others unless a global command is issued.
Sources: kaleidux-daemon/src/orchestration.rs:11-13, kaleidux-daemon/src/monitor_manager.rs:244-245

Synchronized Mode

All monitors share a single shared_queue and are updated simultaneously. A single shared_display_start_time is used to track the duration, ensuring all outputs switch to the same wallpaper at the exact same moment.
Sources: kaleidux-daemon/src/monitor_manager.rs:197, kaleidux-daemon/src/monitor_manager.rs:364-365

Grouped Mode

Monitors are organized into specific groups defined by the user. Each group maintains its own group_queues and group_display_start_times. Monitors within a group switch wallpapers in sync with each other but independently of other groups.
Sources: kaleidux-daemon/src/orchestration.rs:14, kaleidux-daemon/src/monitor_manager.rs:199-200

The Orchestration Layer

The synchronization logic is implemented through a hierarchy of managers and orchestrators that track the state of every connected display.

OutputOrchestrator

Each physical output is represented by an OutputOrchestrator. It tracks the individual state of a monitor, including its configuration, current wallpaper path, and the precise Instant when the current content actually started displaying.
Sources: kaleidux-daemon/src/monitor_manager.rs:16-27

Field	Type	Description
config	OutputConfig	Per-output settings (duration, transition, etc.)
queue	Option<SmartQueue>	The file selection source (None if sync/grouped)
current_path	Option<PathBuf>	Path to the currently rendered wallpaper
display_start_time	Option<Instant>	Timestamp when the transition finished
next_change	Option<Instant>	Fallback timer for the next switch

MonitorManager

The MonitorManager acts as the central controller. It processes "ticks" from the main loop to determine if any monitor or group has exceeded its duration setting.
Sources: kaleidux-daemon/src/monitor_manager.rs:194-209

Transition Synchronization

Kaleidux distinguishes between "scheduled" time and "display" time to ensure that the wallpaper duration only starts counting after the transition effect has completed.

1. Trigger: The MonitorManager picks a new path and triggers a switch_wallpaper_content call.
2. Transition: The Renderer begins the GLSL transition.
3. Completion: When transition_progress reaches 1.0, the renderer notifies the system.
4. Marking: The mark_transition_completed function is called, setting the display_start_time.
   Sources: kaleidux-daemon/src/monitor_manager.rs:141-146, kaleidux-daemon/src/main.rs:927-930

Synchronized Marking Logic

In synchronized or grouped modes, the display_start_time is set when the first output in the set completes its transition. This prevents outputs with different rendering speeds from drifting out of sync over long periods.
Sources: kaleidux-daemon/src/monitor_manager.rs:596-613

Configuration Options

The following table summarizes global behavior settings derived from the configuration schema.
Sources: kaleidux-daemon/src/orchestration.rs:78-95, config.example.toml:15-45

Option	Type	Default	Description
monitor-behavior	String / Enum	independent	Sets the sync mode (independent, synchronized, grouped).
video-ratio	u8	50	Chance (0-100) of picking a video over an image.
sorting	SortingStrategy	loveit	Selection logic: loveit, random, ascending, descending.
duration	Duration	5m	Time to display a wallpaper before switching.
script-tick-interval	u64	1	Frequency in seconds to run Rhai automation scripts.

IPC and External Control

Users can override the synchronization behavior at runtime using the kldctl utility. Commands like next can be targeted to specific outputs or applied globally.

• Global Next: kldctl next (advances all queues based on behavior mode).
• Targeted Next: kldctl next --output DP-1 (advances only the specified monitor).
• Pause/Resume: kldctl pause stops the MonitorManager from processing ticks, effectively freezing the current wallpapers across all monitors.
  Sources: kldctl/src/main.rs:70-130, kaleidux-daemon/src/main.rs:1134-1147

Conclusion

Monitor Behaviors and Synchronization form the backbone of Kaleidux's multi-display management. By providing flexible modes—Independent, Synchronized, and Grouped—the system caters to both simple and complex desktop environments. The decoupling of "transition time" from "display time" ensures that users get the full duration of their wallpapers as configured, while the MonitorManager maintains high-level coordination to prevent timing drift across displays.