How theovilardo/pixelplayer works
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: MusicService.kt Music service · app Phone app · PixelPlayDatabase.kt Room DB · viewmodel ViewModels
Components 21
Repo
Multi-module Android music player
- Phone app · Main PixelPlay Android module
app - Wear app · Companion Wear OS client
wear - Shared contract · Cross-device protocol objects
shared - Entry points · Application and activity entry points
app/src/main/java/com/theveloper/pixelplay - Compose nav · Root navigation and routes
app/src/main/java/com/theveloper/pixelplay/presentation/navigation - Screens · Feature screens and UI components
app/src/main/java/com/theveloper/pixelplay/presentation/screens - ViewModels · Screen-facing state holders
app/src/main/java/com/theveloper/pixelplay/presentation/viewmodel - Music service · Long-lived playback and notification boundary
app/src/main/java/com/theveloper/pixelplay/data/service/MusicService.kt - Player core · Queue, transitions, audio processing, cast handoff
app/src/main/java/com/theveloper/pixelplay/data/service/player - Library data · MediaStore, paging, metadata, playback models
app/src/main/java/com/theveloper/pixelplay/data/repository - Room DB · PixelPlayDatabase and DAOs/entities
app/src/main/java/com/theveloper/pixelplay/data/database/PixelPlayDatabase.kt - Preferences · User, theme, equalizer, playlist, AI settings
app/src/main/java/com/theveloper/pixelplay/data/preferences - Providers · Cloud and service-specific repositories and proxies
app/src/main/java/com/theveloper/pixelplay/data - Artwork · Album art caching and Coil fetchers
app/src/main/java/com/theveloper/pixelplay/data/image - Lyrics · Lyrics repository, fetch, sync, and editing
app/src/main/java/com/theveloper/pixelplay/data/repository/LyricsRepositoryImpl.kt - AI system · Prompting, orchestration, client factory, generators
app/src/main/java/com/theveloper/pixelplay/data/ai - Backup · Manifest, validation, modules, restore planner
app/src/main/java/com/theveloper/pixelplay/data/backup - Sync/workers · WorkManager sync and AI tasks
app/src/main/java/com/theveloper/pixelplay/data/worker - System surfaces · Widgets, shortcuts, notifications, content provider, media server
app/src/main/java/com/theveloper/pixelplay/ui/glancewidget - Wear data · Wear repositories, transfer state, and local DB
wear/src/main/java/com/theveloper/pixelplay/data - Wear UI · Wear navigation, screens, and viewmodels
wear/src/main/java/com/theveloper/pixelplay/presentation
Connections 27
- 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