Queue & Content Selection

Relevant source files

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

• kaleidux-daemon/src/queue.rs
• kaleidux-daemon/src/monitor_manager.rs
• kaleidux-daemon/src/cache.rs
• kaleidux-daemon/src/main.rs
• kldctl/src/main.rs
• config.example.toml

The Queue & Content Selection system in Kaleidux is responsible for discovering, filtering, and prioritizing media files (images and videos) to be displayed as desktop wallpapers. It operates as a multi-layered architecture where a central MonitorManager coordinates multiple SmartQueue instances based on configured monitor behaviors, ensuring efficient resource usage through shared caching and pre-buffering.

At its core, the system utilizes a persistent scoring mechanism called "Loveit," which tracks user preferences and file recency to create a dynamic, weighted selection process. This allows the daemon to transition between content types seamlessly while adhering to user-defined ratios and sorting strategies.

System Architecture

The selection logic is distributed across three primary components: the SmartQueue (selection logic), the MonitorManager (orchestration), and the FileCache (persistence).

Core Components

Component	Description
SmartQueue	Handles the actual file picking logic, maintains history, and manages the pool of discovered files.
OutputOrchestrator	A per-monitor wrapper that manages the timing and state transitions for a specific output.
MonitorManager	Coordinates multiple outputs, managing shared queues for synchronized or grouped monitor setups.
FileCache	A redb-backed persistent storage for file metadata, usage statistics, and blacklists.

Sources: kaleidux-daemon/src/queue.rs:43-55, kaleidux-daemon/src/monitor_manager.rs:13-24, kaleidux-daemon/src/cache.rs:18-20

Monitor Behavior Logic

The system supports three distinct behaviors that dictate how queues are mapped to physical outputs:

1. Independent: Every monitor has its own SmartQueue and cycles content separately.
2. Synchronized: All monitors share a single shared_queue and transition to the same file simultaneously.
3. Grouped: Monitors are partitioned into groups, where each group shares a queue.

Content Discovery & Validation

Content discovery is performed using jwalk for parallel directory traversal. To prevent UI blocking during daemon startup, discovery is offloaded to a background thread pool using tokio::task::spawn_blocking.

File Type Identification

The system identifies content types by reading the first 16 bytes of a file (magic numbers) rather than relying on file extensions.

Format	Magic Number / Signature	Content Type
JPEG	FF D8 FF	Image
PNG	89 50 4E 47	Image
GIF	GIF8	Image
WebP	RIFF ... WEBP	Image
MKV/WebM	1A 45 DF A3	Video
MP4	ftyp (at offset 4)	Video

Sources: kaleidux-daemon/src/queue.rs:114-148, kaleidux-daemon/src/queue.rs:150-165

Discovery Data Flow

The discovery process integrates with the FileCache to avoid redundant I/O operations.

Selection Strategies

The SmartQueue supports multiple SortingStrategy variants, which can be configured globally or per-output.

The Loveit Strategy

The "Loveit" strategy is a sophisticated weighted random selector. It calculates a score for each file based on three factors:

1. Love Multiplier: A user-defined weight (default 2.0 for "loved" files) that increases selection frequency.
2. Use Count: Files that have been seen more often receive a lower score to encourage variety.
3. Recency: A factor that favors items not seen in a long time, using a "hours since last seen" calculation.

Formula Concept: Score = LoveMultiplier / (1 + Count) * RecencyFactor

Sources: kaleidux-daemon/src/queue.rs:369-411, kldctl/src/main.rs:105-112

Sequential and Random Strategies

• Random: Pure random selection, but still obeys the video-ratio configuration.
• Ascending/Descending: Sequential alphabetical ordering.
• History Management: The queue maintains a history of the last 50 items to facilitate the pick_prev operation.

Sources: kaleidux-daemon/src/queue.rs:334-367, kaleidux-daemon/src/queue.rs:271-278

Playlists and Blacklisting

The system allows for granular control over the content pool through playlists and blacklists.

Playlist Logic

Playlists are defined as a collection of paths. When a playlist is loaded via set_playlist, the internal file pool of the SmartQueue is filtered to include only paths found within the playlist that are not currently blacklisted.

Blacklisting

Blacklisting a file removes it from the active pool across all queues and prevents it from being discovered in future scans. Blacklist state is persisted in the BLACKLIST_TABLE within the FileCache.

Sources: kaleidux-daemon/src/queue.rs:511-540, kaleidux-daemon/src/cache.rs:15-18

Performance Optimization

The content selection system implements several optimizations to minimize CPU and memory overhead:

Pre-buffering

OutputOrchestrator utilizes the peek_next() method to determine the next file in the sequence without consuming it. This allows the renderer to begin pre-loading assets (like decoding the first frame of a video or uploading an image to the GPU) before the current wallpaper's duration expires.

Sources: kaleidux-daemon/src/monitor_manager.rs:104-113, kaleidux-daemon/src/queue.rs:281-309

Shared Discovery Cache

When multiple monitors share the same directory path (common in "Independent" mode), the MonitorManager uses an in-memory discovered_files_cache. The first monitor to scan the directory populates the cache, and subsequent monitors reuse the file list to avoid redundant filesystem hits.

Sources: kaleidux-daemon/src/monitor_manager.rs:136-138, kaleidux-daemon/src/monitor_manager.rs:175-188

Batched Persistence

Statistics (usage counts, last seen timestamps) are not written to disk immediately. Instead, they are held in a pending_stats_updates map and flushed to the redb database every 5 seconds or when explicitly triggered.

Sources: kaleidux-daemon/src/queue.rs:438-447, kaleidux-daemon/src/main.rs:945-948

IPC Interface for Queue Control

The kldctl utility provides a command-line interface to interact with the queue system via a Unix domain socket.

Command	Action	Implementation Detail
next	Skips to next wallpaper	Triggers pick_next on the orchestrator.
prev	Goes to previous wallpaper	Retrieves item from SmartQueue.history.
love <PATH>	Increases frequency	Sets love_multiplier in FileStats.
playlist load	Switches active pool	Calls SmartQueue::set_playlist.
blacklist add	Excludes a file	Adds to HashSet and removes from active pool.

Sources: kldctl/src/main.rs:95-155, kaleidux-daemon/src/main.rs:1205-1235

Summary

The Queue & Content Selection system provides the logic for Kaleidux's dynamic wallpaper experience. By combining a flexible monitor orchestration layer with a persistent, weighted scoring system ("Loveit"), it ensures that wallpapers are selected efficiently and in accordance with user preferences. The integration of parallel discovery and pre-buffering ensures that transitions remain smooth even when managing large media libraries.