How pixelplayerhq/pixelplayer works
1. Repository shape
- This is an Android music player split into three product modules: app (phone/tablet main app), wear (Wear OS companion), and baselineprofile (performance profiling/benchmark support).
- A small shared module contains cross-device message/data contracts used by phone and watch.
2. Top-level runtime
- The main runtime is the app module, built in Kotlin with Jetpack Compose, Material 3, Hilt, Room, WorkManager, Retrofit/OkHttp, Coil, and Media3 ExoPlayer.
- The phone app is the system of record: it owns library data, playback state, preferences, backup/restore, and sync jobs.
3. Presentation layer
- UI lives under presentation/ and is organized by screens, reusable components, and ViewModels/state holders.
- Navigation is centralized in presentation/navigation, while screen-specific UI flows cover library browsing, player, search, playlists, settings, stats, lyrics, AI, casting, and cloud-service dashboards.
- The Compose UI is state-driven: screens observe ViewModels, and ViewModels adapt repository/service state into UI-ready models.
4. Core data flow
- The standard flow is: UI → ViewModel/state holder → repository/service → local database/network/device APIs.
- Domain models in data/model define the app’s shared concepts such as songs, albums, artists, playlists, queues, transitions, lyrics, and player state.
5. Local persistence and indexing
- Room is the primary local persistence layer (data/database) with many entities and DAOs for songs, playlists, favorites, search history, engagement stats, lyrics, AI cache/usage, transitions, album art themes, and several cloud-provider caches.
- Schema migration history is committed under app/schemas, which indicates database evolution is important to the app’s stability.
- Preferences are stored separately in DataStore-backed repositories under data/preferences.
6. Playback and media services
- data/service/MusicService.kt is the central background playback engine and likely the hub for media session, notification, queue control, and audio routing.
- Playback is extended by specialized components for cast, local-only notifications, wake/sleep timer handling, widgets, media button handling, replay gain, hi-res/downmix processing, and dual-player/transition logic.
- The player pipeline is therefore not just “play a file”; it is a service-centric media system with audio processing, queue management, and device-aware output routing.
7. Library ingestion and media access
- The library is built from local device media via repository and paging layers (MediaStoreSongRepository, MediaStorePagingSource, MediaStoreObserver), plus filesystem/folder scanning helpers.
- There is support for metadata reading/editing and playlist file handling (AudioMetadataReader, SongMetadataEditor, M3uManager), which means the app can both consume and modify local media metadata.
- This layer feeds the UI library views and also powers search, playlists, and statistics.
8. Cloud and external service integrations
- The app integrates with several external music sources and services: Deezer (artist images), LRCLIB (lyrics), GitHub services (announcements/contributors), Google Drive, Jellyfin, Navidrome, Netease, QQ Music, and Telegram.
- These integrations are split into repositories, API services, stream proxies, security/encryption utilities, and provider-specific models.
- Architecturally, these are pluggable remote sources that map remote catalogs/authentication into the app’s local domain and playback pipeline.
9. AI subsystem
- AI features are isolated under data/ai and include orchestration, prompt building, metadata generation, playlist generation, notifications, and user profile digests.
- Multiple AI providers are supported through a provider abstraction (Gemini, OpenAI, Groq, Mistral, DeepSeek, etc.), with client factory/support code handling provider-specific differences.
- The AI layer feeds features like Daily Mix and AI-generated playlists, and it tracks usage/cache data in the database.
10. Backup and restore
- Backup is a dedicated subsystem with manifest/model/format/validation/restore modules.
- It is modularized by content areas such as favorites, playlists, lyrics, settings, playback history, transitions, equalizer, AI usage, and more.
- This means backup/restore is not a simple export; it is a structured, validated, multi-section data migration pathway.
11. Background synchronization and jobs
- WorkManager drives sync and maintenance tasks in data/worker, including general sync, Navidrome sync, and AI-related work.
- These workers bridge remote service state into local storage and keep media/library metadata current outside the foreground UI.
- The app also includes diagnostics and performance monitoring, showing that background behavior and startup performance are first-class concerns.
12. Device ecosystem: widgets, cast, auto, wear
- The app exposes home-screen widgets via Glance, plus a ContentProvider for shared artwork and a set of widget update/broadcast components.
- Casting and remote playback are handled inside the app through cast-specific services and HTTP/media proxy infrastructure.
- Wear OS is a separate app module with its own database, repositories, playback service, and UI; it communicates with the phone through the shared message contracts and transfer/state repositories.
- Android Auto support is present in the codebase structure, but the main architectural pattern is still “phone as controller + service host, wear as companion, widgets as lightweight views.”
13. Cross-cutting concerns
- Dependency injection is centralized in di/, which wires repositories, services, and feature modules together.
- The project also includes release/debug build separation, localization, baseline profiles, benchmark tests, and extensive unit/instrumentation tests across data, service, and presentation layers.
- In an architecture diagram, the most important boundaries are: UI, domain/state, persistence, playback/service layer, external integrations, and companion-device communication.
Main entry points: MusicRepository.kt Repositories · PixelPlayDatabase.kt Room database · WearStateRepository.kt Wear data · MusicService.kt Music service
Components 21
Phone app
Main Android runtime and system of record.
- Main app · Compose-based Android app host and entry points.
app/src/main/java/com/theveloper/pixelplay/MainActivity.kt - Navigation · Central route and screen navigation coordination.
app/src/main/java/com/theveloper/pixelplay/presentation/navigation/AppNavigation.kt - Screens · Screen flows, reusable components, and feature surfaces.
app/src/main/java/com/theveloper/pixelplay/presentation/screens/HomeScreen.kt - ViewModels · State holders that adapt repositories and services for UI.
app/src/main/java/com/theveloper/pixelplay/presentation/viewmodel/MainViewModel.kt - Domain models · Core music, playback, search, lyrics, and queue models.
app/src/main/java/com/theveloper/pixelplay/data/model/LibraryModels.kt - Repositories · Library, lyrics, playlists, transitions, and media-store access.
app/src/main/java/com/theveloper/pixelplay/data/repository/MusicRepository.kt - Room database · Primary database for songs, playlists, stats, caches, and provider data.
app/src/main/java/com/theveloper/pixelplay/data/database/PixelPlayDatabase.kt - Preferences · User, theme, playlist, equalizer, and AI preference repositories.
app/src/main/java/com/theveloper/pixelplay/data/preferences/UserPreferencesRepository.kt - Music service · Foreground playback, media session, notification, queue, and routing hub.
app/src/main/java/com/theveloper/pixelplay/data/service/MusicService.kt - Player pipeline · Dual player, cast playback, replay gain, downmix, and transition logic.
app/src/main/java/com/theveloper/pixelplay/data/service/player/DualPlayerEngine.kt - Remote services · External catalogs and APIs: Deezer, lyrics, GDrive, Jellyfin, Navidrome, Netease, QQ Music, Telegram, GitHub.
app/src/main/java/com/theveloper/pixelplay/data/network/lyrics/LrcLibApiService.kt - AI subsystem · Prompting, metadata/playlist generation, provider abstraction, notifications, and usage cache.
app/src/main/java/com/theveloper/pixelplay/data/ai/AiOrchestrator.kt - Backup system · Structured manifest, validation, module handlers, and restore execution.
app/src/main/java/com/theveloper/pixelplay/data/backup/BackupManager.kt - Workers · WorkManager sync, maintenance, and AI work that updates local state.
app/src/main/java/com/theveloper/pixelplay/data/worker/SyncManager.kt - Device features · Widgets, shared artwork provider, cast, auto, wear transfer, and media buttons.
app/src/main/java/com/theveloper/pixelplay/data/service/wear/WearPhoneTransferSender.kt
Wear OS app
Companion watch runtime and local player surface.
- Wear app · Wear OS companion application entry point and UI host.
wear/src/main/java/com/theveloper/pixelplay/WearApp.kt - Wear data · Watch repositories, local player, transfer, volume, and library state.
wear/src/main/java/com/theveloper/pixelplay/data/WearStateRepository.kt - Wear DB · Wear-side Room database for cached songs and playback context.
wear/src/main/java/com/theveloper/pixelplay/data/local/WearMusicDatabase.kt - Wear UI · Watch navigation, screens, and compact playback controls.
wear/src/main/java/com/theveloper/pixelplay/presentation/WearNavigation.kt
Shared contracts
Cross-device message and state models.
- Shared contracts · Wear browse, playback, transfer, volume, and theme message schemas.
shared/src/main/java/com/theveloper/pixelplay/shared/WearIntents.kt
Baseline profile
Performance profiling and startup benchmarks.
- Profiles · Baseline profile generation and startup/player sheet benchmarks.
baselineprofile/src/main/java/com/theveloper/pixelplay/baselineprofile/BaselineProfileGenerator.kt
Connections 25
- Main app → Navigation: hosts · Main activity launches the centralized navigation graph.
- Navigation → Screens: routes to · Navigation resolves screens and feature flows.
- Screens → ViewModels: observes · Compose screens render ViewModel/state-holder output.
- ViewModels → Repositories: requests · UI state is assembled from repositories and services.
- Repositories → Room database: reads/writes · Repositories persist and query local data through Room.
- Repositories → Preferences: uses · Repositories read and write user and feature preferences.
- Repositories → Domain models: maps to · Repository results are converted into app domain models.
- Repositories → Music service: drives · Playback-related repositories and controllers feed the music service.
- Music service → Player pipeline: contains · The service coordinates playback engines and audio processing.
- Music service → Device features: publishes · Service state powers widgets, buttons, cast, auto, and wear sync.
- Remote services → Room database: syncs · Remote catalogs and provider caches are stored locally.
- Remote services → Repositories: feeds · Service-specific repositories expose remote data to the app.
- AI subsystem → Room database: caches · AI usage and generated content are tracked in local storage.
- AI subsystem → Repositories: produces · AI-generated playlists and metadata flow into app features.
- Backup system → Room database: exports/imports · Backup modules serialize and restore app data sections.
- Backup system → Preferences: exports/imports · Settings and preference state participate in backup/restore.
- Workers → Room database: updates · Workers reconcile remote and local state in the database.
- Workers → Remote services: calls · Background jobs fetch from cloud services and AI providers.
- Device features → Shared contracts: uses · Phone features exchange structured payloads with wear.
- Wear app → Wear UI: hosts · Wear activity launches the watch navigation and screens.
- Wear UI → Wear data: observes · Wear screens render repository-backed watch state.
- Wear data → Wear DB: reads/writes · Watch repositories persist cached music and player state.
- Wear data → Shared contracts: syncs · Wear data exchange is defined by shared cross-device models.
- Wear data → Device features: communicates with · Watch state and commands travel through phone-side transfer services.
- Profiles → Main app: optimizes · Generated profiles target app startup and player interactions.