Skip to content

aurora protocol

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

aurora-protocol — Shared Communication Schema

Relevant source files

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

The aurora-protocol crate serves as the single source of truth for all communication between the aurora-daemon and aurora-player protocol/Cargo.toml:1-15. It defines the shared data structures, request/response enums, and serialization logic required for IPC (Inter-Process Communication) over Unix domain sockets.

By centralizing these definitions, Aurora ensures that both the background service and the GUI frontend remain synchronized regarding the structure of audio metadata, playback states, and control commands.

Role in the Architecture

The protocol crate is a dependency for both the daemon and the player protocol/Cargo.lock:5-11. It uses serde for serialization, allowing complex Rust enums and structs to be transmitted as JSON payloads across the wire.

IPC Data Flow

The following diagram illustrates how aurora-protocol entities bridge the gap between the two main binaries.

Diagram: Protocol Entity Mapping

graph LR
    subgraph "aurora-player (Client)"
        UI["Slint UI"]
        INT["interface.rs"]
    end

    subgraph "aurora-protocol (Shared)"
        REQ["enum Request"]
        RES["enum Response"]
        ST["struct Status"]
    end

    subgraph "aurora-daemon (Server)"
        DIS["Command Dispatch"]
        ENG["Playback Engine"]
    end

    UI -- "Triggers" --> INT
    INT -- "Sends" --> REQ
    REQ -- "Handled by" --> DIS
    DIS -- "Updates" --> ENG
    ENG -- "Generates" --> ST
    ST -- "Wrapped in" --> RES
    RES -- "Updates UI" --> INT
Loading

Sources: protocol/src/interface.rs:5-50, protocol/src/lib.rs:12-20

Communication Enums

The core of the protocol consists of two primary enums defined in protocol/src/interface.rs. These enums represent the entire command set and data feedback loop of the system.

The Request Enum

The Request enum contains variants for every action a user can take in the GUI, from simple playback toggles to complex playlist management protocol/src/interface.rs:5-35.

  • Playback Control: Play, Pause, Next, Prev, Seek.
  • Queue Management: Enqueue, ReplaceQueue, RemoveSong, MoveQueue.
  • Library & Playlists: PlaylistCreate, PlaylistAddSongs, Search, GetArtistList.
  • Preferences: SetVolume, SetShuffle, SetRepeat.

For a full reference of variants and their parameters, see Request & Response Enums.

The Response Enum

The Response enum is sent by the daemon to update the client state or provide results for a specific query protocol/src/interface.rs:37-50.

  • State Updates: Status (heartbeat), Theme (visual updates), Volume.
  • Data Payloads: SearchResults, PlaylistList, Queue, ArtistList.
  • Error Handling: Error (containing err_id and err_msg).

For details on response semantics, see Request & Response Enums.

Shared Data Structures

Beyond the communication enums, the crate defines the fundamental objects that represent music and system state.

Structure Role Key Fields
Status The "Heartbeat" of the app. current_song, is_paused, position, volume protocol/src/lib.rs:13-20
Theme Color palette for the UI. bgd0 through bgd4, acct, srch protocol/src/lib.rs:29-40
SearchType Defines search scope. ByTitle, ByArtist protocol/src/lib.rs:23-26
Song Audio metadata and ID. Defined in songs.rs protocol/src/lib.rs:3
Playlist Collection of songs. Defined in playlists.rs protocol/src/lib.rs:2

Code-to-System Relationship

This diagram shows how the protocol structs relate to the internal state of the aurora-daemon.

Diagram: Data Structure Association

classDiagram
    class Status {
        +Option~Song~ current_song
        +bool is_paused
        +Duration position
        +f32 volume
    }
    class Theme {
        +String bgd0
        +String acct
        +String srch
    }
    class Request {
        <<enumeration>>
        Play(Uuid)
        Seek(Duration)
        SetVolume(f32)
    }
    class Response {
        <<enumeration>>
        Status(Status)
        Theme(Theme)
        Error(u8, String)
    }

    Status --* Response : "encapsulated in"
    Theme --* Response : "encapsulated in"
Loading

Sources: protocol/src/lib.rs:12-40, protocol/src/interface.rs:5-50

For detailed documentation on song metadata and playlist schemas, see Shared Data Types: Song, Playlist & Theme.

Serialization Strategy

The protocol uses serde to handle the conversion between Rust types and the wire format.

  1. Serialization: The aurora-player serializes a Request to JSON.
  2. Framing: The JSON is prefixed with its length (handled by the transport layer in the daemon/player crates) and sent over the Unix socket.
  3. Deserialization: The aurora-daemon receives the bytes and reconstructs the Request enum to dispatch it to the appropriate handler.

Sources: protocol/Cargo.toml:14-15, protocol/src/interface.rs:1-2

Child Pages:

Home

Overview

aurora-daemon

aurora-protocol

aurora-player

Reference

Clone this wiki locally