Skip to content

Project Overview

Jump to bottom
Joseph Chacko edited this page Jul 22, 2026 · 2 revisions

Aurora Music Player — Project Overview

Relevant source files

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

Aurora is a local music player for Linux systems built with the Rust programming language. It utilizes a client-server (daemon/client) architecture to decouple audio engine management from the graphical user interface. The system is designed to provide a responsive, modern music experience with features such as library indexing, playlist management, and MPRIS2 integration.

System Architecture

The project is structured as a Cargo workspace containing three distinct crates. This separation ensures that the core logic of the music engine remains independent of the UI implementation.

Crate Role Primary Responsibilities
aurora-daemon Server Audio playback, library scanning, SQLite persistence, MPRIS2 D-Bus service.
aurora-player Client Slint-based GUI, user interaction, album art rendering, theme application.
aurora-protocol Bridge Shared data structures, IPC message definitions (Requests/Responses).

Sources: README.md:12-18, Cargo.toml:1-4

Component Interaction Model

The following diagram illustrates how the crates relate to one another and the external system components they interact with.

Diagram: Aurora High-Level Component Map

graph TD
    subgraph "Natural Language Space"
        UI["User Interface"]
        Audio["Audio Engine"]
        Storage["Library Storage"]
    end

    subgraph "Code Entity Space"
        AP["aurora-player (Crate)"]
        AD["aurora-daemon (Crate)"]
        PROTO["aurora-protocol (Crate)"]
        DB[("/tmp/aurora.db")]
        SOCK[("/tmp/aurora.sock")]
    end

    UI --> AP
    AP <--> PROTO
    AD <--> PROTO
    AP <--> SOCK
    SOCK <--> AD
    AD --> Audio
    AD --> DB
    Storage --> DB
Loading

Sources: README.md:12-18, run.sh:3-5

Core Features

  • Audio Engine: High-performance playback using rodio and symphonia for decoding README.md:16-16.
  • Library Management: Automatic filesystem scanning with metadata extraction and SQLite-backed persistence README.md:22-25.
  • IPC Communication: A custom Unix socket protocol using JSON-serialized messages README.md:12-12.
  • Modern UI: A reactive interface built with the Slint UI framework, supporting themes and album art README.md:17-17, README.md:30-30.
  • Linux Integration: Native support for MPRIS2 allows controlling playback via system media widgets README.md:29-29.

Project Structure & Data Flow

The system operates via a Request/Response cycle over a Unix domain socket. The aurora-protocol crate defines the "language" used by both sides.

Diagram: IPC Data Flow (Code Entity Space)

sequenceDiagram
    participant P as aurora-player
    participant S as /tmp/aurora.sock
    participant D as aurora-daemon

    Note over P, D: JSON Wire Protocol
    P->>S: aurora_protocol::Request (e.g., Playback)
    S->>D: handle_client()
    D->>D: Process via StateStruct
    D->>S: aurora_protocol::Response (e.g., Status)
    S->>P: interface.rs dispatch
Loading

Sources: README.md:12-12, run.sh:3-5

Getting Started

To run Aurora, you must be on a Linux environment with the Rust toolchain installed. The project requires a Nerd Font (specifically JetBrainsMono NFP) for rendering UI icons README.md:48-53.

The easiest way to launch the system is using the provided shell script:

./run.sh

This script handles killing any stale daemon instances and launching both the server and the client run.sh:1-10.

For detailed instructions on prerequisites and the build process, see Getting Started & Build Setup (#1.1).

Technical Deep Dives

For more specific information regarding the internal workings of Aurora, refer to the following child pages:

Home

Overview

aurora-daemon

aurora-protocol

aurora-player

Reference

Clone this wiki locally