aurora daemon

aurora-daemon — Background Service

Relevant source files

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

• Cargo.lock
• daemon/Cargo.toml
• daemon/src/main.rs

The aurora-daemon is the central background service of the Aurora music player. It acts as a headless media server responsible for audio decoding, library management, and maintaining the playback state. It communicates with clients (like the aurora-player GUI) via a Unix domain socket using a custom JSON-based protocol.

System Overview

The daemon operates as a multi-threaded process. Upon startup, it can optionally "daemonize" itself to run in the background, detaching from the terminal and redirecting output to /tmp/aurora-daemon.out [daemon/src/main.rs:31-40]. It manages a centralized StateStruct which is shared across various specialized background threads and the main IPC server loop.

Core Components

Component	Responsibility
IPC Server	Listens on /tmp/aurora-daemon.sock and dispatches requests to handlers [daemon/src/main.rs:108-142].
Audio Engine	Manages the rodio::Sink and rodio::OutputStream for hardware playback [daemon/src/main.rs:65-69].
Library Manager	Indexes local music files into a SQLite database and monitors for filesystem changes [daemon/src/main.rs:71-76].
State Management	Thread-safe Arc<Mutex<StateStruct>> containing the queue, index, and playback settings [daemon/src/main.rs:80-94].

Daemon Architecture

The following diagram illustrates the relationship between the main entry point, the shared state, and the auxiliary threads that drive the system.

Logic Flow & Threading Model

graph TD
    subgraph "Main Process"
        START["main()"] --> ASYNC_MAIN["async_main()"]
        ASYNC_MAIN --> DB_INIT["helpers::db::open()"]
        ASYNC_MAIN --> RODIO_INIT["rodio::Sink::connect_new()"]
        ASYNC_MAIN --> STATE_INIT["StateStruct (Arc<Mutex>)"]
    end

    subgraph "Background Threads"
        STATE_INIT --> WT["watcher_thread::init()"]
        STATE_INIT --> FWT["file_watcher_thread::init()"]
        STATE_INIT --> MT["mpris_thread::init()"]
        STATE_INIT --> TT["theme_thread::init()"]
    end

    subgraph "IPC Server Loop"
        STATE_INIT --> LISTEN["UnixListener::bind(/tmp/aurora-daemon.sock)"]
        LISTEN --> ACCEPT["listener.accept()"]
        ACCEPT --> HANDLE["handlers::handle_client()"]
        HANDLE --> DISPATCH["Request Dispatcher"]
    end

    WT -- "Auto-advance queue" --> STATE_INIT
    FWT -- "Update index on disk change" --> STATE_INIT
    MT -- "D-Bus MPRIS2 Control" --> STATE_INIT
    TT -- "Config Hot-reload" --> STATE_INIT

Loading

Sources: daemon/src/main.rs:48-112, daemon/src/main.rs:125-142

Shared State (StateStruct)

The StateStruct is the single source of truth for the daemon. It is wrapped in an Arc<Mutex<...>> to allow concurrent access by the IPC handlers and background threads.

Field	Type	Description
current_song	Option<Song>	The metadata of the currently playing track.
queue	VecDeque<Song>	The list of upcoming tracks.
index	Vec<Song>	The full library of songs indexed from disk.
sink	Arc<Sink>	The Rodio audio sink used for playback control.
db	Connection	The SQLite connection for persistence.
clients	Vec<Arc<Mutex<OwnedWriteHalf>>>	List of connected IPC clients for broadcasting updates.

Sources: daemon/src/main.rs:80-94

Subsystem Overviews

Startup & Initialization

The daemon handles Unix signal cleanup (SIGTERM/SIGINT) to ensure /tmp/aurora-daemon.sock and the PID file are removed on exit. It initializes the Rodio output stream and builds the initial music index from the user's ~/Music folder. For details, see Daemon Startup & State Initialization.

IPC & Request Handling

The daemon uses tokio::net::UnixListener to accept connections. Each client is handled in a separate task. Requests are read as length-prefixed JSON strings and dispatched to specific modules (e.g., handlers::playback, handlers::queue). For details, see Request Handlers & Command Dispatch.

Playback & Audio Pipeline

Audio is decoded using Symphonia and fed into Rodio. The daemon supports seeking and volume control. A specialized watcher_thread monitors the rodio::Sink to automatically trigger the next song in the queue when the current one finishes. For details, see Playback Engine & Audio Pipeline.

Library & Persistence

The library is stored in a SQLite database. The daemon performs a recursive scan of the music directory, generating UUID-v5 identifiers for songs based on their file paths. It also manages "Liked" songs and playback history. For details, see Library Indexing & File Watching and Playlist, Liked Songs & History Persistence.

External Integration (MPRIS2 & Themes)

The daemon integrates with Linux desktop environments via MPRIS2 (D-Bus), allowing playback control from system media widgets. It also features a theme thread that watches config.toml for changes to broadcast UI color updates to clients. For details, see Background Threads: MPRIS2, Theme & Watcher.

Code Map: Entity Associations

The following table bridges high-level concepts to their specific implementation files within the daemon/src directory.

System Name	Primary Implementation Files
Process Lifecycle	main.rs
Request Dispatch	handlers/mod.rs, handlers/playback.rs, handlers/library.rs
Database Ops	helpers/db.rs, helpers/playlist.rs
Audio Decoding	types.rs (SeekableAudio, BufferSource)
D-Bus / MPRIS	mpris_thread.rs
Theme Engine	theme_thread.rs

Sources: daemon/src/main.rs:13-20, daemon/Cargo.toml:32-39