# xing1p/pixelmusic architecture

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

- Interactive diagram: https://gitdiagram.com/xing1p/pixelmusic
- Repository: https://github.com/xing1p/pixelmusic

## Overview

Pixel Music is an Android hybrid music player: users browse a library or streaming source, select music, and control playback through a persistent media service. The map includes the documented local, YouTube, Telegram and Drive sources, plus lyrics, AI curation, backup, and device integrations. README capabilities help identify these branches; sampled excerpts confirm the playback engine’s URI resolution and some service integrations, but do not expose all wiring, so uncertain connections are omitted.

Main entry points: [`app/src/main/java/com/unshoo/pixelmusic/data/service/MusicService.kt`](https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/service/MusicService.kt) (Music service), [`app/src/main/java/com/unshoo/pixelmusic/MainActivity.kt`](https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/MainActivity.kt) (App interface), [`app/src/main/java/com/unshoo/pixelmusic/data/service/player/DualPlayerEngine.kt`](https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/service/player/DualPlayerEngine.kt) (Dual player), [`app/src/main/java/com/unshoo/pixelmusic/data/ai/AiOrchestrator.kt`](https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/ai/AiOrchestrator.kt) (AI music tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["App and playback"]
  node_app["App interface<br/>[MainActivity.kt]"]
  node_service["Music service<br/>[MusicService.kt]"]
  node_engine["Dual player"]
end

subgraph group_sources["Music sources"]
  node_local["Local library"]
  node_youtube["YouTube music<br/>[SongRepository.kt]"]
  node_telegram["Telegram music"]
  node_drive["Drive music"]
end

subgraph group_state["Library and state"]
  node_room[("Music database")]
  node_preferences[("User preferences")]
end

subgraph group_features["Music features"]
  node_lyrics["Lyrics retrieval"]
  node_lyrics_api["LRCLIB"]
  node_equalizer["Equalizer"]
  node_ai["AI music tools<br/>[AiOrchestrator.kt]"]
  node_ai_provider["AI providers<br/>[AiClientFactory.kt]"]
  node_backup["Backup and restore<br/>[BackupManager.kt]"]
end

subgraph group_integrations["Device and cloud"]
  node_cast["Cast playback<br/>[CastPlayer.kt]"]
  node_auto["Android Auto"]
  node_wear["Wear transfer"]
  node_watch["Wear companion"]
  node_cast_http["Cast media server"]
  node_scrobble["Last.fm scrobbling<br/>[ScrobbleManager.kt]"]
end

node_listener(("Listener"))

node_listener -->|"browses and selects"| node_app
node_app -->|"controls playback"| node_service
node_service -->|"manages playback"| node_engine
node_local -->|"indexes library"| node_room
node_service -->|"loads local tracks"| node_local
node_service -->|"requests streams"| node_youtube
node_service -->|"resolves streams"| node_telegram
node_service -.->|"resolves streams"| node_drive
node_engine -->|"resolves YouTube URIs"| node_youtube
node_engine -->|"resolves Telegram URIs"| node_telegram
node_engine -.->|"resolves Drive URIs"| node_drive
node_service -->|"loads lyrics"| node_lyrics
node_lyrics -->|"fetches lyrics"| node_lyrics_api
node_service -->|"applies audio effects"| node_equalizer
node_app -->|"requests music curation"| node_ai
node_ai -->|"generates results"| node_ai_provider
node_ai -->|"uses music context"| node_room
node_app -->|"manages backup"| node_backup
node_backup -->|"backs up and restores data"| node_room
node_service -->|"routes playback"| node_cast
node_cast -->|"serves cast media"| node_cast_http
node_service -->|"provides browse tree"| node_auto
node_service -->|"publishes playback state"| node_wear
node_wear -->|"transfers state and audio"| node_watch
node_service -.->|"reports listening"| node_scrobble
node_app -->|"reads and updates"| node_preferences

click node_app "https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/MainActivity.kt"
click node_service "https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/service/MusicService.kt"
click node_engine "https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/service/player/DualPlayerEngine.kt"
click node_local "https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/repository/MediaStoreSongRepository.kt"
click node_youtube "https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/remote/youtube/SongRepository.kt"
click node_telegram "https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/telegram/TelegramRepository.kt"
click node_drive "https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/gdrive/GDriveRepository.kt"
click node_room "https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/database/PixelMusicDatabase.kt"
click node_preferences "https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/preferences/UserPreferencesRepository.kt"
click node_lyrics "https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/repository/LyricsRepositoryImpl.kt"
click node_lyrics_api "https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/network/lyrics/LrcLibApiService.kt"
click node_equalizer "https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/equalizer/EqualizerManager.kt"
click node_ai "https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/ai/AiOrchestrator.kt"
click node_ai_provider "https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/ai/provider/AiClientFactory.kt"
click node_backup "https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/backup/BackupManager.kt"
click node_cast "https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/service/player/CastPlayer.kt"
click node_auto "https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/service/auto/AutoMediaBrowseTree.kt"
click node_wear "https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/service/wear/PhoneDirectWatchTransferCoordinator.kt"
click node_watch "https://github.com/xing1p/pixelmusic/blob/master/wear/src/main/java/com/unshoo/pixelmusic/data/WearDataListenerService.kt"
click node_cast_http "https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/service/http/MediaFileHttpServerService.kt"
click node_scrobble "https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/lastfm/ScrobbleManager.kt"

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_service,node_engine toneBlue
class node_local,node_youtube,node_telegram,node_drive toneAmber
class node_room,node_preferences toneMint
class node_lyrics,node_lyrics_api,node_equalizer,node_ai,node_ai_provider,node_backup toneRose
class node_cast,node_auto,node_wear,node_watch,node_cast_http,node_scrobble,node_listener toneIndigo
```

## Components

### App and playback

- [App interface](https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/MainActivity.kt): `app/src/main/java/com/unshoo/pixelmusic/MainActivity.kt`
- [Music service](https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/service/MusicService.kt): `app/src/main/java/com/unshoo/pixelmusic/data/service/MusicService.kt`
- [Dual player](https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/service/player/DualPlayerEngine.kt): `app/src/main/java/com/unshoo/pixelmusic/data/service/player/DualPlayerEngine.kt`

### Music sources

- [Local library](https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/repository/MediaStoreSongRepository.kt): `app/src/main/java/com/unshoo/pixelmusic/data/repository/MediaStoreSongRepository.kt`
- [YouTube music](https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/remote/youtube/SongRepository.kt): `app/src/main/java/com/unshoo/pixelmusic/data/remote/youtube/SongRepository.kt`
- [Telegram music](https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/telegram/TelegramRepository.kt): `app/src/main/java/com/unshoo/pixelmusic/data/telegram/TelegramRepository.kt`
- [Drive music](https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/gdrive/GDriveRepository.kt): `app/src/main/java/com/unshoo/pixelmusic/data/gdrive/GDriveRepository.kt`

### Library and state

- [Music database](https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/database/PixelMusicDatabase.kt): `app/src/main/java/com/unshoo/pixelmusic/data/database/PixelMusicDatabase.kt`
- [User preferences](https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/preferences/UserPreferencesRepository.kt): `app/src/main/java/com/unshoo/pixelmusic/data/preferences/UserPreferencesRepository.kt`

### Music features

- [Lyrics retrieval](https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/repository/LyricsRepositoryImpl.kt): `app/src/main/java/com/unshoo/pixelmusic/data/repository/LyricsRepositoryImpl.kt`
- [LRCLIB](https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/network/lyrics/LrcLibApiService.kt): `app/src/main/java/com/unshoo/pixelmusic/data/network/lyrics/LrcLibApiService.kt`
- [Equalizer](https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/equalizer/EqualizerManager.kt): `app/src/main/java/com/unshoo/pixelmusic/data/equalizer/EqualizerManager.kt`
- [AI music tools](https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/ai/AiOrchestrator.kt): `app/src/main/java/com/unshoo/pixelmusic/data/ai/AiOrchestrator.kt`
- [AI providers](https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/ai/provider/AiClientFactory.kt): `app/src/main/java/com/unshoo/pixelmusic/data/ai/provider/AiClientFactory.kt`
- [Backup and restore](https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/backup/BackupManager.kt): `app/src/main/java/com/unshoo/pixelmusic/data/backup/BackupManager.kt`

### Device and cloud

- [Cast playback](https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/service/player/CastPlayer.kt): `app/src/main/java/com/unshoo/pixelmusic/data/service/player/CastPlayer.kt`
- [Android Auto](https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/service/auto/AutoMediaBrowseTree.kt): `app/src/main/java/com/unshoo/pixelmusic/data/service/auto/AutoMediaBrowseTree.kt`
- [Wear transfer](https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/service/wear/PhoneDirectWatchTransferCoordinator.kt): `app/src/main/java/com/unshoo/pixelmusic/data/service/wear/PhoneDirectWatchTransferCoordinator.kt`
- [Wear companion](https://github.com/xing1p/pixelmusic/blob/master/wear/src/main/java/com/unshoo/pixelmusic/data/WearDataListenerService.kt): `wear/src/main/java/com/unshoo/pixelmusic/data/WearDataListenerService.kt`
- [Cast media server](https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/service/http/MediaFileHttpServerService.kt): `app/src/main/java/com/unshoo/pixelmusic/data/service/http/MediaFileHttpServerService.kt`
- [Last.fm scrobbling](https://github.com/xing1p/pixelmusic/blob/master/app/src/main/java/com/unshoo/pixelmusic/data/lastfm/ScrobbleManager.kt): `app/src/main/java/com/unshoo/pixelmusic/data/lastfm/ScrobbleManager.kt`

### Other components

- **Listener**

## Connections

- Listener → App interface: browses and selects
- App interface → Music service: controls playback
- Music service → Dual player: manages playback
- Local library → Music database: indexes library
- Music service → Local library: loads local tracks
- Music service → YouTube music: requests streams
- Music service → Telegram music: resolves streams
- Music service → Drive music: resolves streams
- Dual player → YouTube music: resolves YouTube URIs
- Dual player → Telegram music: resolves Telegram URIs
- Dual player → Drive music: resolves Drive URIs
- Music service → Lyrics retrieval: loads lyrics
- Lyrics retrieval → LRCLIB: fetches lyrics
- Music service → Equalizer: applies audio effects
- App interface → AI music tools: requests music curation
- AI music tools → AI providers: generates results
- AI music tools → Music database: uses music context
- App interface → Backup and restore: manages backup
- Backup and restore → Music database: backs up and restores data
- Music service → Cast playback: routes playback
- Cast playback → Cast media server: serves cast media
- Music service → Android Auto: provides browse tree
- Music service → Wear transfer: publishes playback state
- Wear transfer → Wear companion: transfers state and audio
- Music service → Last.fm scrobbling: reports listening
- App interface → User preferences: reads and updates