How cromaguy/rhythm works
1. What this repository is
Rhythm is a single-module Android music player app written in Kotlin. Its architecture is centered on a long-lived playback service, a Compose-based UI, and two interchangeable music backends: local-library playback and streaming-service playback.
2. Primary application boundary
The Android app lives under app/. RhythmApplication is the process-level entry point, while MainActivity, ExternalPlaybackActivity, CrashActivity, and RhythmGuardTimeoutActivity are the main UI/service-facing activities. The app is packaged with build variants for GitHub, F-Droid, and other distribution channels.
3. Overall layer split
The codebase follows MVVM plus a clean-architecture style:
- core/ defines shared domain concepts and repository contracts.
- shared/ contains cross-cutting models, repositories, UI, and viewmodels.
- features/local/ and features/streaming/ implement the two playback modes.
- infrastructure/ contains low-level playback, networking, widgets, workers, and audio processors.
- util/ and utils/ hold app-wide helpers that don’t belong to a single feature.
4. Domain and orchestration
The main domain abstractions are PlayableItem, MediaItems, AppMode, MusicRepository, and SongUseCases. These are the boundaries the UI and viewmodels depend on, so the rest of the app can switch between local and streaming behavior without rewriting the screens.
5. Local music subsystem
features/local/ owns the on-device library experience. It includes a Room database (RhythmDatabase) with song, artist, and join-table entities/DAOs, plus MusicRepositoryImpl to expose local library operations. Local presentation includes home/library screens, onboarding, playlist management, equalizer screens, and library metadata/notification managers.
6. Streaming subsystem
features/streaming/ mirrors the local stack but targets remote providers. It defines streaming domain models (StreamingSong, StreamingAlbum, StreamingArtist, StreamingPlaylist, etc.), provider clients (JellyfinApiClient, SubsonicApiClient), a streaming repository implementation, and a session repository. The streaming UI includes setup, integration, home/library, settings, and service-selection flows.
7. Playback engine and media service
The heart of audio playback is infrastructure/service/MediaPlaybackService backed by RhythmPlayerEngine. Supporting components handle queue transitions, preload/caching, and playback state transfer. This service boundary is what the UI, widgets, notifications, and external playback activity all ultimately talk to.
8. Audio processing chain
Audio enhancement is implemented in infrastructure/audio/ and infrastructure/service/player/replaygain/. The app includes bass boost, spatialization, adaptive dynamic range compression, ReplayGain processing, and device/output handling. Utility classes like AudioDeviceManager, AudioCapabilitiesMonitor, CodecMonitor, and AudioFormatDetector influence playback behavior and the “high-res” style audio features described in the README.
9. Network and metadata integrations
External metadata and content services live in infrastructure/network/ and features/streaming/data/provider/. The app talks to Deezer, Spotify search, YouTube Music, iTunes Search, LRCLib, and a Rhythm lyrics backend, plus GitHub for release/update data. These services feed artwork, search results, lyrics, and update checks rather than core playback.
10. State management and persistence
App state is split between persistent repositories and Compose viewmodels. Shared repositories such as UserPreferencesRepository and PlaybackStatsRepository store settings and listening history, while feature viewmodels (MusicViewModel, StreamingMusicViewModel, AppModeViewModel, ThemeViewModel, AppUpdaterViewModel) bridge repository data into UI state. Room handles the local library cache; preferences and stats handle user configuration and analytics-like insights on-device.
11. UI structure and navigation
The UI is entirely Compose-based and organized by shared versus feature-specific screens. shared/presentation/navigation and the feature navigation files define the main app routes, while screens are split across player, settings, search, home, library, onboarding, and streaming-specific pages. The shared UI layer also contains reusable components, dialogs, bottom sheets, theme, and mini-player variants.
12. Background work, widgets, and system integration
Background synchronization and maintenance are handled by WorkManager workers such as backup, update notifications, and pulse notifications. Home-screen widgets are supported through both legacy AppWidget and Glance-based implementations, with separate widget update/receiver/worker components. Additional system-facing pieces include crash reporting, ANR watchdogging, privacy-policy assets, and release/update automation in GitHub Actions and fastlane metadata.
13. Build-time and distribution boundaries
The repository uses product flavors and resource overlays for different builds (github, fdroid, debug), which affect configuration, feature availability, and distribution packaging. Release metadata, screenshots, and changelogs live alongside the app sources, indicating an Android release pipeline rather than a server/client split.
14. How data typically flows
User interaction starts in Compose screens, which call viewmodels. Viewmodels read from repositories/use cases, which delegate to either the local Room-backed repository or the streaming repository. Playback requests flow from UI to MediaPlaybackService/RhythmPlayerEngine; metadata, lyrics, and artwork may come from network providers; and side effects such as widgets, notifications, stats, and backups are updated asynchronously through workers and managers.
Main entry points: MediaPlaybackService.kt Player Engine · MusicViewModel.kt Shared VM · StreamingMusicRepositoryImpl.kt Streaming Repo · MusicRepository.kt Music Repo
Components 22
App Shell
Process entry, activities, and build/distribution boundaries.
- RhythmApp · Process-level application entry point.
app/src/main/java/chromahub/rhythm/app/RhythmApplication.kt - Main Activity · Primary Compose host and navigation entry.
app/src/main/java/chromahub/rhythm/app/activities/MainActivity.kt - Service Activities · External playback, crash, and guard-timeout UI surfaces.
app/src/main/java/chromahub/rhythm/app/activities/ExternalPlaybackActivity.kt
Core & Shared
Domain contracts, shared models, state, and reusable UI.
- Core Domain · Shared playback concepts and repository/use-case boundaries.
app/src/main/java/chromahub/rhythm/app/core/domain/model/PlayableItem.kt - Music Repo · App-wide music data abstraction used by UI and viewmodels.
app/src/main/java/chromahub/rhythm/app/core/domain/repository/MusicRepository.kt - Song UseCases · Orchestrates domain actions over music sources.
app/src/main/java/chromahub/rhythm/app/core/domain/usecase/SongUseCases.kt - Shared Models · App settings, music metadata, lyrics, transitions, and audio device models.
app/src/main/java/chromahub/rhythm/app/shared/data/model/Music.kt - Prefs & Stats · Persistent preferences and listening statistics.
app/src/main/java/chromahub/rhythm/app/shared/data/repository/UserPreferencesRepository.kt - Shared UI · Reusable player, settings, dialogs, theme, and navigation components.
app/src/main/java/chromahub/rhythm/app/shared/presentation/navigation/RhythmNavigation.kt - Shared VM · Bridges repositories into global UI state and app mode/theme/update flows.
app/src/main/java/chromahub/rhythm/app/shared/presentation/viewmodel/MusicViewModel.kt
Local Music
On-device library, Room persistence, and local playback UI.
- Local Library · On-device music experience with library, playlists, onboarding, and equalizer screens.
app/src/main/java/chromahub/rhythm/app/features/local/presentation/screens/HomeScreen.kt - Local DB · Song, artist, and join-table persistence for the local library.
app/src/main/java/chromahub/rhythm/app/features/local/data/database/RhythmDatabase.kt - Local Repo · Implements local music access on top of Room and media data.
app/src/main/java/chromahub/rhythm/app/features/local/data/repository/MusicRepositoryImpl.kt - Local VM · Coordinates local library state, queue state, and notification metadata.
app/src/main/java/chromahub/rhythm/app/features/local/presentation/viewmodel/MusicViewModel.kt
Streaming Music
Remote-provider models, repositories, and setup flows.
- Streaming Stack · Remote playback domain, provider clients, repositories, and setup screens.
app/src/main/java/chromahub/rhythm/app/features/streaming/presentation/screens/StreamingHomeScreen.kt - Provider Clients · Jellyfin and Subsonic clients plus provider models.
app/src/main/java/chromahub/rhythm/app/features/streaming/data/provider/JellyfinApiClient.kt - Streaming Repo · Streaming music repository and session persistence.
app/src/main/java/chromahub/rhythm/app/features/streaming/data/repository/StreamingMusicRepositoryImpl.kt
Infrastructure
Playback engine, audio processing, network clients, widgets, and workers.
- Player Engine · Long-lived media playback service and engine orchestration.
app/src/main/java/chromahub/rhythm/app/infrastructure/service/MediaPlaybackService.kt - Audio Chain · Bass boost, spatialization, replaygain, and dynamic range processing.
app/src/main/java/chromahub/rhythm/app/infrastructure/audio/RhythmAudioProcessor.kt - Network Layer · HTTP clients for metadata, lyrics, search, and update data.
app/src/main/java/chromahub/rhythm/app/infrastructure/network/NetworkClient.kt - Widgets & Workers · Home-screen widgets, update workers, backup tasks, and pulse notifications.
app/src/main/java/chromahub/rhythm/app/infrastructure/widget/WidgetUpdater.kt - Utilities · Audio device, cache, lyrics, crash, and playback helper utilities.
app/src/main/java/chromahub/rhythm/app/util/AudioDeviceManager.kt
Connections 27
- RhythmApp → Main Activity: starts · Application bootstraps the main UI host.
- Main Activity → Shared UI: navigates · Main activity renders the shared navigation and reusable UI.
- Main Activity → Service Activities: launches · Activity layer also handles external playback, crash, and guard flows.
- Shared UI → Shared VM: binds state · Shared UI is driven by global viewmodels.
- Shared VM → Prefs & Stats: reads/writes · Viewmodels persist settings and stats through shared repositories.
- Shared VM → Core Domain: depends on · Global state is expressed in core domain concepts.
- Shared VM → Music Repo: queries · Shared viewmodels use the music repository contract.
- Song UseCases → Music Repo: orchestrates · Use cases execute through the repository boundary.
- Local Library → Local VM: drives · Local screens are backed by the local feature viewmodel.
- Local VM → Local Repo: uses · Local viewmodel delegates to the Room-backed repository implementation.
- Local Repo → Local DB: persists · Local repository reads and writes the library database.
- Local Repo → Music Repo: implements · Local repository fulfills the app-wide music contract.
- Streaming Stack → Streaming Repo: drives · Streaming screens depend on the streaming repository layer.
- Streaming Repo → Provider Clients: calls · Streaming repository talks to provider clients and models.
- Streaming Repo → Music Repo: implements · Streaming repository also fulfills the shared music contract.
- Player Engine → Audio Chain: processes audio · Playback service applies enhancement and replaygain processing.
- Player Engine → Utilities: consults · Service relies on helpers for queues, cache, devices, and transfers.
- Player Engine → Widgets & Workers: broadcasts · Playback state feeds widgets and background workers.
- Player Engine → Service Activities: controls · External playback and guard flows connect back to the service boundary.
- Network Layer → Streaming Stack: feeds · Network metadata and provider data support streaming flows.
- Network Layer → Streaming Repo: supports · Streaming repository uses network client services as needed.
- Network Layer → Shared VM: updates · Network-backed update checks surface in shared app state.
- Utilities → Player Engine: supports · Utilities influence playback, devices, lyrics, crashes, and caching.
- Shared Models → Shared UI: renders in · Shared models inform UI state and screens.
- Shared Models → Prefs & Stats: stored by · Settings and listening-related models persist through repositories.
- Core Domain → Local Library: used by · Local feature screens consume the domain layer.
- Core Domain → Streaming Stack: used by · Streaming feature screens consume the same core abstractions.