Skip to content

Shared Data Types

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

Shared Data Types: Song, Playlist & Theme

Relevant source files

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

This page documents the core data structures defined in the aurora-protocol crate. These types serve as the shared language between the aurora-daemon and the aurora-player GUI, ensuring type safety and consistent serialization across the Unix socket IPC boundary.

Song Entities

The system distinguishes between internal metadata (including file system paths) and the song representation used by the UI.

SongMeta vs Song

  • SongMeta: Used primarily by the daemon for library management and audio playback. It includes the absolute path to the audio file on disk protocol/src/songs.rs:6-13.
  • Song: The primary structure for IPC and UI rendering. It excludes the local file path for security and abstraction, but adds a liked boolean flag to indicate if the song is in the user's favorites protocol/src/songs.rs:16-24.

A Song can be instantiated from a SongMeta reference using the From trait implementation, defaulting the liked status to false protocol/src/songs.rs:26-37.

Data Structure Comparison

Field SongMeta (Internal) Song (IPC/UI)
id Uuid Uuid
title String String
artists Vec<String> Vec<String>
duration Duration Duration
art_path Option<PathBuf> Option<PathBuf>
path PathBuf N/A
liked N/A bool

Sources: protocol/src/songs.rs:5-37

Playlist Structures

Playlists are represented in three distinct forms depending on the level of detail required by the UI view.

  • PlaylistMinimal: Used for the sidebar or grid overview. It contains the playlist metadata and a collection of art_paths (extracted from the first few songs) to generate a collage preview protocol/src/playlists.rs:9-14.
  • Playlist: A complete playlist object containing the full list of Song objects. This is returned when a user selects a specific playlist to view its contents protocol/src/playlists.rs:17-21.
  • PlaylistIn: A "Data Transfer Object" (DTO) used specifically for creating new playlists via Request::PlaylistCreate. It contains only the title and the initial set of songs protocol/src/playlists.rs:24-27.

Playlist Data Flow

The following diagram illustrates how different playlist types are used across the Request/Response lifecycle.

Playlist Type Usage Diagram

graph TD
    subgraph "aurora-player (Client)"
        UI_List["Library View"]
        UI_Detail["Playlist Detail View"]
        UI_Create["Create Playlist Dialog"]
    end

    subgraph "IPC Layer (Response)"
        R_List["Response::PlaylistList(Vec<PlaylistMinimal>)"]
        R_Detail["Response::PlaylistResults(Playlist)"]
    end

    subgraph "IPC Layer (Request)"
        Req_Create["Request::PlaylistCreate(PlaylistIn)"]
    end

    subgraph "aurora-daemon (Server)"
        DB[("SQLite Database")]
    end

    UI_List -->|Triggers| R_List
    R_List -.->|Populates| UI_List
    UI_Detail -->|Triggers| R_Detail
    R_Detail -.->|Populates| UI_Detail
    UI_Create -->|Sends| Req_Create
    Req_Create -->|Persists| DB
    DB --> R_List
    DB --> R_Detail
Loading

Sources: protocol/src/playlists.rs:8-28, protocol/src/interface.rs:10-16, protocol/src/interface.rs:42-43

System Status & Search

The Status Struct

The Status struct is the most frequently transmitted object in the system. It is broadcast by the daemon whenever the playback state changes (e.g., track change, pause, volume adjustment) protocol/src/lib.rs:13-20.

  • current_song: An Option<Song> representing the track currently loaded in the audio sink.
  • is_paused: Boolean state of the rodio sink.
  • position: The current elapsed time of the playing track.
  • volume: Floating point value (0.0 to 1.0).
  • shuffle: Boolean toggle for randomized queue traversal.
  • repeat: Integer representing the repeat mode (0: None, 1: Single, 2: All).

SearchType Enum

Used in Request::Search(SearchType) to filter the library index protocol/src/interface.rs:22. It supports two modes:

  • ByTitle(String): Matches against the song title field.
  • ByArtist(String): Matches against the artist names array.

Sources: protocol/src/lib.rs:12-26

Theming: The Theme Struct

The Theme struct defines the color palette used by the Slint UI. The daemon reads these values from a config.toml file and broadcasts them to the client protocol/src/lib.rs:29-40.

Field Purpose
bgd0 - bgd4 Background shades (Darkest to Lightest)
txt1 Primary text color
txt2 Secondary/dimmed text color
acct Accent color (used for progress bars, active states)
srch Search bar background
btns Button and interactive element colors

Theme Pipeline Diagram

This diagram shows how natural language color definitions in the config file become code entities in the protocol and finally visual elements in the GUI.

Theme Data Pipeline

graph LR
    subgraph "Configuration Space"
        TOML["config.toml [hex strings]"]
    end

    subgraph "Code Entity Space (aurora-protocol)"
        T_Struct["struct Theme"]
        T_Resp["Response::Theme(Theme)"]
    end

    subgraph "Visual Space (aurora-player)"
        S_Global["Slint global Theme singleton"]
        UI_Comp["CustomComp.slint Widgets"]
    end

    TOML -->|Parsed by theme_thread| T_Struct
    T_Struct -->|Wrapped in| T_Resp
    T_Resp -->|Sent over Socket| S_Global
    S_Global -->|Property Binding| UI_Comp
Loading

Sources: protocol/src/lib.rs:29-40, protocol/src/interface.rs:45

Entity Relationships

The following diagram maps the relationships between the shared structs defined in songs.rs, playlists.rs, and lib.rs.

Shared Type Relationships

classDiagram
    class Status {
        +Option~Song~ current_song
        +bool is_paused
        +Duration position
        +f32 volume
        +bool shuffle
        +u8 repeat
    }

    class Song {
        +Uuid id
        +String title
        +Vec~String~ artists
        +Duration duration
        +Option~PathBuf~ art_path
        +bool liked
    }

    class SongMeta {
        +Uuid id
        +String title
        +Vec~String~ artists
        +Duration duration
        +PathBuf path
        +Option~PathBuf~ art_path
    }

    class Playlist {
        +Uuid id
        +String title
        +Vec~Song~ songs
    }

    class PlaylistMinimal {
        +Uuid id
        +String name
        +usize len
        +Vec~Option~PathBuf~~ art_paths
    }

    class PlaylistIn {
        +String title
        +Vec~Song~ songs
    }

    Status "1" o-- "0..1" Song : contains
    Playlist "1" *-- "many" Song : contains
    PlaylistIn "1" *-- "many" Song : contains
    SongMeta ..> Song : converts to via From
Loading

Sources: protocol/src/songs.rs:5-24, protocol/src/playlists.rs:8-27, protocol/src/lib.rs:12-20

Home

Overview

aurora-daemon

aurora-protocol

aurora-player

Reference

Clone this wiki locally