# theovilardo/pixelplayer architecture

> Architecture diagram of the GitHub repository theovilardo/pixelplayer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/theovilardo/pixelplayer
- Repository: https://github.com/theovilardo/pixelplayer

## Overview

1. **Overall shape**
   - PixelPlayer is a multi-module Android music player, centered on an `app` module, with a companion `wear` module and a small `shared` module for cross-device data contracts.
   - The architecture is layered: **presentation (Compose/ViewModels)** → **repositories/services** → **Room/network/media system**.

2. **App entry points and runtime**
   - The main phone app starts from `PixelPlayApplication`, `MainActivity`, and a separate `ExternalPlayerActivity` for alternate playback UI flows.
   - Navigation is Compose-based, with a central app graph plus dedicated sub-flows for provider auth/dashboard screens and the main library/player experience.

3. **Primary domain: music playback**
   - Playback is handled by a long-lived `MusicService` and a set of player-focused helpers under `data/service/player`.
   - The service layer owns queue handling, transitions/crossfade logic, audio processing, replay gain, cast handoff, notification updates, media button handling, and sleep timer behavior.
   - This is the core runtime boundary: UI commands flow into the service, and player state flows back out to the UI, widgets, and wear companion.

4. **Local library and metadata**
   - Local media is sourced primarily from Android storage/MediaStore via repository and paging layers, with helpers for folder traversal, filtering, permissions, and media-item mapping.
   - Audio metadata, artwork, replay gain, tag editing, and search all sit in the data/util layers and feed the library, detail, and editing screens.
   - Room entities such as songs, albums, artists, playlists, favorites, search history, and engagement stats form the persistent local model.

5. **Database and persistence**
   - `PixelPlayDatabase` is the main persistence hub, using Room with many DAOs and a large migration history stored under `app/schemas`.
   - Persistence covers both library-derived state and app state: favorites, playlists, lyrics, AI usage/cache, transitions, equalizer settings, album art themes, and provider-specific caches.
   - Preferences are split into dedicated repositories backed by DataStore-like APIs, keeping user settings separate from media/content data.

6. **External music sources and cloud providers**
   - The app supports several remote music ecosystems: **GDrive, Jellyfin, Navidrome, Netease, QQ Music, and Telegram**.
   - Each provider has its own repository, API service/parsers, stream proxy, and in some cases custom security/encryption logic.
   - These provider modules are isolated from the main local library, but they feed the same UI and playback pipeline once content is resolved.

7. **Artwork and image loading**
   - Album/artist art is cached locally and loaded through custom Coil fetchers and repository layers.
   - There are provider-specific artwork fetchers for local, Jellyfin, Navidrome, and Telegram sources, which keeps image resolution aligned with the media source.

8. **Lyrics and discovery**
   - Lyrics are fetched and synchronized through a dedicated lyrics repository and network stack, with LRC support and editing features in the UI.
   - Search is full-text backed and also tracks search history, enabling both library discovery and playback-oriented lookups.

9. **AI subsystem**
   - AI features are implemented as a distinct subsystem under `data/ai`, with orchestration, prompts, profile digest generation, metadata generation, and playlist generation.
   - Multiple AI providers are supported through a client factory abstraction: Gemini, OpenAI-compatible, DeepSeek, Groq, and Mistral.
   - AI usage is persisted and can be backed up/restored, so it behaves like a first-class app capability rather than a one-off feature.

10. **Backup and restore**
   - Backup is modular: a manifest, validation pipeline, format detection, legacy adapter, reader/writer, and per-domain backup handlers.
   - Restore is planned and executed separately, which lets the app validate content before mutating local state.
   - The backup system spans settings, playlists, favorites, playback history, lyrics, transitions, equalizer data, and AI usage/history.

11. **Background work and sync**
   - WorkManager drives periodic and on-demand sync tasks such as media sync and provider-specific updates.
   - Sync workers populate/update the local database and cache layers, which then become the source of truth for the UI and playback service.
   - There is also observer-style integration for MediaStore changes so local library changes can be detected incrementally.

12. **Presentation layer**
   - The phone UI is entirely Jetpack Compose + Material 3, with a large component library for the player, bottom sheets, dialogs, and library screens.
   - `presentation/viewmodel` contains screen-facing state holders and ViewModels; these mediate between user interactions and repository/service calls.
   - The app is structured around feature screens like Home, Library, Search, Album/Artist details, Playlist detail, Settings, Stats, Equalizer, Daily Mix, and provider dashboards.

13. **Widgets, shortcuts, and system surfaces**
   - Home screen control is provided through Glance widgets, with multiple widget sizes and action callbacks wired into player state.
   - App shortcuts, content providers, notifications, and media controls extend the app beyond the main activity into Android system surfaces.
   - A custom HTTP media server and cast support allow playback to be exposed to remote clients and casting targets.

14. **Wear OS companion**
   - The `wear` module is a separate client with its own app, navigation, repository layer, and local database.
   - It communicates with the phone via the `shared` protocol objects, covering browse requests, playback commands/results, library state, volume, transfer state, and theme palette.
   - The wear app supports browse, downloads, queue, player, timer, volume, and output routing, making it a remote control and lightweight playback companion.

15. **Build/test/ops boundaries**
   - The repo includes benchmark and baseline profile modules, Android instrumentation tests, and extensive unit tests around backup, playback policies, security, and UI logic.
   - CI is wired through GitHub Actions for code scanning, APK builds, and device-targeted release/debug flows.
   - Remote config and release tooling are present, which indicates the app is meant to ship with controlled announcements or runtime-configured behavior.

Main entry points: [`app/src/main/java/com/theveloper/pixelplay/data/service/MusicService.kt`](https://github.com/theovilardo/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/data/service/MusicService.kt) (Music service), [`app`](https://github.com/theovilardo/pixelplayer/tree/master/app) (Phone app), [`app/src/main/java/com/theveloper/pixelplay/data/database/PixelPlayDatabase.kt`](https://github.com/theovilardo/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/data/database/PixelPlayDatabase.kt) (Room DB), [`app/src/main/java/com/theveloper/pixelplay/presentation/viewmodel`](https://github.com/theovilardo/pixelplayer/tree/master/app/src/main/java/com/theveloper/pixelplay/presentation/viewmodel) (ViewModels)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_root["Repo"]
  node_app["Phone app<br/>android app"]
  node_wear["Wear app<br/>wear module"]
  node_shared["Shared contract<br/>common module"]
  node_app_entry(("Entry points<br/>startup"))
  node_app_nav["Compose nav<br/>presentation nav"]
  node_app_ui["Screens<br/>compose UI"]
  node_app_vm["ViewModels<br/>ui state"]
  node_music_service[("Music service<br/>playback runtime<br/>[MusicService.kt]")]
  node_player_engine["Player core<br/>audio engine"]
  node_local_library["Library data<br/>local media"]
  node_database[("Room DB<br/>persistence")]
  node_preferences["Preferences<br/>settings store"]
  node_providers["Providers<br/>remote sources"]
  node_artwork["Artwork<br/>image loading"]
  node_lyrics["Lyrics"]
  node_ai["AI system<br/>ai features"]
  node_backup["Backup"]
  node_sync["Sync/workers<br/>background jobs"]
  node_system_surfaces["System surfaces<br/>android integration"]
  node_wear_data["Wear data<br/>wear runtime"]
  node_wear_ui["Wear UI<br/>wear compose"]
end

node_app -->|"contains"| node_app_entry
node_app -->|"hosts"| node_app_nav
node_app -->|"renders"| node_app_ui
node_app -->|"binds"| node_app_vm
node_app_vm -->|"controls"| node_music_service
node_app_vm -->|"queries"| node_local_library
node_app_vm -->|"reads/writes"| node_preferences
node_music_service -->|"owns"| node_player_engine
node_music_service -->|"persists"| node_database
node_local_library -->|"backed by"| node_database
node_local_library -->|"loads"| node_artwork
node_local_library -->|"enriches"| node_lyrics
node_providers -->|"syncs"| node_database
node_providers -->|"feeds"| node_music_service
node_backup -->|"captures"| node_database
node_backup -->|"captures"| node_preferences
node_sync -->|"updates"| node_database
node_sync -->|"fetches"| node_providers
node_system_surfaces -->|"observes"| node_music_service
node_app_vm -->|"uses"| node_ai
node_ai -->|"stores"| node_database
node_wear -->|"contains"| node_wear_data
node_wear -->|"renders"| node_wear_ui
node_wear_data -->|"serializes"| node_shared
node_app -->|"publishes"| node_shared
node_wear -->|"consumes"| node_shared
node_wear_data -->|"relays"| node_music_service

click node_app "https://github.com/theovilardo/pixelplayer/tree/master/app"
click node_wear "https://github.com/theovilardo/pixelplayer/tree/master/wear"
click node_shared "https://github.com/theovilardo/pixelplayer/tree/master/shared"
click node_app_entry "https://github.com/theovilardo/pixelplayer/tree/master/app/src/main/java/com/theveloper/pixelplay"
click node_app_nav "https://github.com/theovilardo/pixelplayer/tree/master/app/src/main/java/com/theveloper/pixelplay/presentation/navigation"
click node_app_ui "https://github.com/theovilardo/pixelplayer/tree/master/app/src/main/java/com/theveloper/pixelplay/presentation/screens"
click node_app_vm "https://github.com/theovilardo/pixelplayer/tree/master/app/src/main/java/com/theveloper/pixelplay/presentation/viewmodel"
click node_music_service "https://github.com/theovilardo/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/data/service/MusicService.kt"
click node_player_engine "https://github.com/theovilardo/pixelplayer/tree/master/app/src/main/java/com/theveloper/pixelplay/data/service/player"
click node_local_library "https://github.com/theovilardo/pixelplayer/tree/master/app/src/main/java/com/theveloper/pixelplay/data/repository"
click node_database "https://github.com/theovilardo/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/data/database/PixelPlayDatabase.kt"
click node_preferences "https://github.com/theovilardo/pixelplayer/tree/master/app/src/main/java/com/theveloper/pixelplay/data/preferences"
click node_providers "https://github.com/theovilardo/pixelplayer/tree/master/app/src/main/java/com/theveloper/pixelplay/data"
click node_artwork "https://github.com/theovilardo/pixelplayer/tree/master/app/src/main/java/com/theveloper/pixelplay/data/image"
click node_lyrics "https://github.com/theovilardo/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/data/repository/LyricsRepositoryImpl.kt"
click node_ai "https://github.com/theovilardo/pixelplayer/tree/master/app/src/main/java/com/theveloper/pixelplay/data/ai"
click node_backup "https://github.com/theovilardo/pixelplayer/tree/master/app/src/main/java/com/theveloper/pixelplay/data/backup"
click node_sync "https://github.com/theovilardo/pixelplayer/tree/master/app/src/main/java/com/theveloper/pixelplay/data/worker"
click node_system_surfaces "https://github.com/theovilardo/pixelplayer/tree/master/app/src/main/java/com/theveloper/pixelplay/ui/glancewidget"
click node_wear_data "https://github.com/theovilardo/pixelplayer/tree/master/wear/src/main/java/com/theveloper/pixelplay/data"
click node_wear_ui "https://github.com/theovilardo/pixelplayer/tree/master/wear/src/main/java/com/theveloper/pixelplay/presentation"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_wear,node_shared,node_app_entry,node_app_nav,node_app_ui,node_app_vm,node_music_service,node_player_engine,node_local_library,node_database,node_preferences,node_providers,node_artwork,node_lyrics,node_ai,node_backup,node_sync,node_system_surfaces,node_wear_data,node_wear_ui toneBlue
```

## Components

### Repo

Multi-module Android music player

- [Phone app](https://github.com/theovilardo/pixelplayer/tree/master/app): android app · Main PixelPlay Android module · `app`
- [Wear app](https://github.com/theovilardo/pixelplayer/tree/master/wear): wear module · Companion Wear OS client · `wear`
- [Shared contract](https://github.com/theovilardo/pixelplayer/tree/master/shared): common module · Cross-device protocol objects · `shared`
- [Entry points](https://github.com/theovilardo/pixelplayer/tree/master/app/src/main/java/com/theveloper/pixelplay): startup · Application and activity entry points · `app/src/main/java/com/theveloper/pixelplay`
- [Compose nav](https://github.com/theovilardo/pixelplayer/tree/master/app/src/main/java/com/theveloper/pixelplay/presentation/navigation): presentation nav · Root navigation and routes · `app/src/main/java/com/theveloper/pixelplay/presentation/navigation`
- [Screens](https://github.com/theovilardo/pixelplayer/tree/master/app/src/main/java/com/theveloper/pixelplay/presentation/screens): compose UI · Feature screens and UI components · `app/src/main/java/com/theveloper/pixelplay/presentation/screens`
- [ViewModels](https://github.com/theovilardo/pixelplayer/tree/master/app/src/main/java/com/theveloper/pixelplay/presentation/viewmodel): ui state · Screen-facing state holders · `app/src/main/java/com/theveloper/pixelplay/presentation/viewmodel`
- [Music service](https://github.com/theovilardo/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/data/service/MusicService.kt): playback runtime · Long-lived playback and notification boundary · `app/src/main/java/com/theveloper/pixelplay/data/service/MusicService.kt`
- [Player core](https://github.com/theovilardo/pixelplayer/tree/master/app/src/main/java/com/theveloper/pixelplay/data/service/player): audio engine · Queue, transitions, audio processing, cast handoff · `app/src/main/java/com/theveloper/pixelplay/data/service/player`
- [Library data](https://github.com/theovilardo/pixelplayer/tree/master/app/src/main/java/com/theveloper/pixelplay/data/repository): local media · MediaStore, paging, metadata, playback models · `app/src/main/java/com/theveloper/pixelplay/data/repository`
- [Room DB](https://github.com/theovilardo/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/data/database/PixelPlayDatabase.kt): persistence · PixelPlayDatabase and DAOs/entities · `app/src/main/java/com/theveloper/pixelplay/data/database/PixelPlayDatabase.kt`
- [Preferences](https://github.com/theovilardo/pixelplayer/tree/master/app/src/main/java/com/theveloper/pixelplay/data/preferences): settings store · User, theme, equalizer, playlist, AI settings · `app/src/main/java/com/theveloper/pixelplay/data/preferences`
- [Providers](https://github.com/theovilardo/pixelplayer/tree/master/app/src/main/java/com/theveloper/pixelplay/data): remote sources · Cloud and service-specific repositories and proxies · `app/src/main/java/com/theveloper/pixelplay/data`
- [Artwork](https://github.com/theovilardo/pixelplayer/tree/master/app/src/main/java/com/theveloper/pixelplay/data/image): image loading · Album art caching and Coil fetchers · `app/src/main/java/com/theveloper/pixelplay/data/image`
- [Lyrics](https://github.com/theovilardo/pixelplayer/blob/master/app/src/main/java/com/theveloper/pixelplay/data/repository/LyricsRepositoryImpl.kt): lyrics stack · Lyrics repository, fetch, sync, and editing · `app/src/main/java/com/theveloper/pixelplay/data/repository/LyricsRepositoryImpl.kt`
- [AI system](https://github.com/theovilardo/pixelplayer/tree/master/app/src/main/java/com/theveloper/pixelplay/data/ai): ai features · Prompting, orchestration, client factory, generators · `app/src/main/java/com/theveloper/pixelplay/data/ai`
- [Backup](https://github.com/theovilardo/pixelplayer/tree/master/app/src/main/java/com/theveloper/pixelplay/data/backup): backup/restore · Manifest, validation, modules, restore planner · `app/src/main/java/com/theveloper/pixelplay/data/backup`
- [Sync/workers](https://github.com/theovilardo/pixelplayer/tree/master/app/src/main/java/com/theveloper/pixelplay/data/worker): background jobs · WorkManager sync and AI tasks · `app/src/main/java/com/theveloper/pixelplay/data/worker`
- [System surfaces](https://github.com/theovilardo/pixelplayer/tree/master/app/src/main/java/com/theveloper/pixelplay/ui/glancewidget): android integration · Widgets, shortcuts, notifications, content provider, media server · `app/src/main/java/com/theveloper/pixelplay/ui/glancewidget`
- [Wear data](https://github.com/theovilardo/pixelplayer/tree/master/wear/src/main/java/com/theveloper/pixelplay/data): wear runtime · Wear repositories, transfer state, and local DB · `wear/src/main/java/com/theveloper/pixelplay/data`
- [Wear UI](https://github.com/theovilardo/pixelplayer/tree/master/wear/src/main/java/com/theveloper/pixelplay/presentation): wear compose · Wear navigation, screens, and viewmodels · `wear/src/main/java/com/theveloper/pixelplay/presentation`

## Connections

- Phone app → Entry points: contains · Phone module entry points and app bootstrap
- Phone app → Compose nav: hosts · Main Compose navigation graph
- Phone app → Screens: renders · Feature screens and reusable UI
- Phone app → ViewModels: binds · ViewModels mediate UI and data
- ViewModels → Music service: controls · Playback state and commands
- ViewModels → Library data: queries · Library, search, playlist, detail data
- ViewModels → Preferences: reads/writes · Settings and feature toggles
- Music service → Player core: owns · Core playback runtime and audio processing
- Music service → Room DB: persists · Queue-related, playback, and app state
- Library data → Room DB: backed by · Room tables, DAOs, search FTS, migrations
- Library data → Artwork: loads · Library artwork resolution and caching
- Library data → Lyrics: enriches · Lyrics lookup and editing support
- Providers → Room DB: syncs · Provider caches and remote library state
- Providers → Music service: feeds · Resolved media and stream proxies into playback
- Backup → Room DB: captures · Persistent app and library state
- Backup → Preferences: captures · Settings, theme, equalizer, AI usage state
- Sync/workers → Room DB: updates · Media and provider sync populate source of truth
- Sync/workers → Providers: fetches · Periodic and on-demand remote updates
- System surfaces → Music service: observes · Widgets, notifications, media controls, shortcuts
- ViewModels → AI system: uses · AI metadata, playlist, and profile generation
- AI system → Room DB: stores · AI cache and usage history
- Wear app → Wear data: contains · Wear repositories, transfer, and local storage
- Wear app → Wear UI: renders · Wear navigation and screens
- Wear data → Shared contract: serializes · Uses shared browse, playback, volume, and state contracts
- Phone app → Shared contract: publishes · Phone-side transfer and playback payloads
- Wear app → Shared contract: consumes · Wear-side protocol objects and intents
- Wear data → Music service: relays · Remote control and transfer coordination
