# wagefolabessy/bitperfectplayer architecture

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

- Interactive diagram: https://gitdiagram.com/wagefolabessy/bitperfectplayer
- Repository: https://github.com/wagefolabessy/bitperfectplayer

## Overview

BitPerfectPlayer is an offline Android music player. Users browse a local MediaStore/SAF library, select tracks or playlists, and control playback through the app; the playback coordinator manages queue state and delegates audio rendering to the output engine. Separate branches provide lyrics, diagnostics, safety controls, and local data management. The graph follows documented capabilities and indexed references; several UI and domain implementations were not excerpted, so some plausible connections are omitted or marked unverified.

Main entry points: [`app/src/main/java/com/cangkir/bitperfectplayer/audio/PlaybackController.kt`](https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/audio/PlaybackController.kt) (Playback coordinator), [`app/src/main/java/com/cangkir/bitperfectplayer/data/LocalPersistenceRepository.kt`](https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/data/LocalPersistenceRepository.kt) (Local persistence), [`app/src/main/java/com/cangkir/bitperfectplayer/ui/MainViewModel.kt`](https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/ui/MainViewModel.kt) (App view model), [`app/src/main/java/com/cangkir/bitperfectplayer/library/LocalLibraryRepository.kt`](https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/library/LocalLibraryRepository.kt) (Local library)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and UI"]
  node_activity["Main activity<br/>[MainActivity.kt]"]
  node_viewmodel["App view model<br/>[MainViewModel.kt]"]
  node_screens["Player screens"]
end

subgraph group_library["Library and discovery"]
  node_libraryrepo["Local library"]
  node_metadata["Audio metadata"]
  node_artwork["Artwork loader"]
  node_playlists["Playlist repository"]
end

subgraph group_playback["Playback and audio"]
  node_controller["Playback coordinator"]
  node_queue["Playback queue"]
  node_service["Foreground service"]
  node_engine["Audio output"]
  node_safety["Hearing safety"]
  node_diagnostics["Audio diagnostics"]
end

subgraph group_local["Local data features"]
  node_lyrics["Offline lyrics"]
  node_persistence["Local persistence"]
  node_database[("Room database")]
  node_preferences["User preferences"]
  node_backup["Backup repository"]
  node_backupcodec["Backup codec"]
end

node_listener(("Listener"))

node_listener -->|"opens app"| node_activity
node_activity -->|"creates"| node_viewmodel
node_listener -->|"uses"| node_screens
node_screens -.->|"uses"| node_viewmodel
node_viewmodel -.->|"requests library"| node_libraryrepo
node_libraryrepo -->|"reads metadata"| node_metadata
node_viewmodel -.->|"manages playlists"| node_playlists
node_screens -->|"loads artwork"| node_artwork
node_viewmodel -.->|"controls playback"| node_controller
node_controller -->|"manages queue"| node_queue
node_controller -->|"controls audio"| node_engine
node_service -->|"dispatches controls"| node_controller
node_controller -->|"coordinates safety"| node_safety
node_engine -->|"maps audio state"| node_diagnostics
node_controller -->|"saves playback"| node_persistence
node_controller -->|"reads settings"| node_preferences
node_libraryrepo -->|"caches tracks"| node_persistence
node_libraryrepo -->|"stores SAF access"| node_preferences
node_lyrics -->|"stores lyrics"| node_persistence
node_playlists -->|"uses local records"| node_persistence
node_persistence -->|"uses DAOs"| node_database
node_backup -->|"exports records"| node_persistence
node_backup -->|"encodes backup"| node_backupcodec

click node_activity "https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/MainActivity.kt"
click node_viewmodel "https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/ui/MainViewModel.kt"
click node_screens "https://github.com/wagefolabessy/bitperfectplayer/tree/main/app/src/main/java/com/cangkir/bitperfectplayer/ui"
click node_libraryrepo "https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/library/LocalLibraryRepository.kt"
click node_metadata "https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/audio/AudioMetadataReader.kt"
click node_artwork "https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/library/AlbumArtworkLoader.kt"
click node_playlists "https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/library/PlaylistRepository.kt"
click node_controller "https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/audio/PlaybackController.kt"
click node_queue "https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/audio/PlaybackQueueManager.kt"
click node_service "https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/audio/PlaybackForegroundService.kt"
click node_engine "https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/audio/AudioOutputEngine.kt"
click node_safety "https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/audio/AudioSafetyController.kt"
click node_diagnostics "https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/audio/AudioDiagnosticMapper.kt"
click node_lyrics "https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/lyrics/LyricsRepository.kt"
click node_persistence "https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/data/LocalPersistenceRepository.kt"
click node_database "https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/data/BitPerfectDatabase.kt"
click node_preferences "https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/data/UserPreferencesRepository.kt"
click node_backup "https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/data/LocalBackupRepository.kt"
click node_backupcodec "https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/data/LocalBackupCodec.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_activity,node_viewmodel,node_screens toneBlue
class node_libraryrepo,node_metadata,node_artwork,node_playlists toneAmber
class node_controller,node_queue,node_service,node_engine,node_safety,node_diagnostics toneMint
class node_lyrics,node_persistence,node_database,node_preferences,node_backup,node_backupcodec toneRose
class node_listener toneIndigo
```

## Components

### App and UI

- [Main activity](https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/MainActivity.kt): `app/src/main/java/com/cangkir/bitperfectplayer/MainActivity.kt`
- [App view model](https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/ui/MainViewModel.kt): `app/src/main/java/com/cangkir/bitperfectplayer/ui/MainViewModel.kt`
- [Player screens](https://github.com/wagefolabessy/bitperfectplayer/tree/main/app/src/main/java/com/cangkir/bitperfectplayer/ui): `app/src/main/java/com/cangkir/bitperfectplayer/ui`

### Library and discovery

- [Local library](https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/library/LocalLibraryRepository.kt): `app/src/main/java/com/cangkir/bitperfectplayer/library/LocalLibraryRepository.kt`
- [Audio metadata](https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/audio/AudioMetadataReader.kt): `app/src/main/java/com/cangkir/bitperfectplayer/audio/AudioMetadataReader.kt`
- [Artwork loader](https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/library/AlbumArtworkLoader.kt): `app/src/main/java/com/cangkir/bitperfectplayer/library/AlbumArtworkLoader.kt`
- [Playlist repository](https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/library/PlaylistRepository.kt): `app/src/main/java/com/cangkir/bitperfectplayer/library/PlaylistRepository.kt`

### Playback and audio

- [Playback coordinator](https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/audio/PlaybackController.kt): `app/src/main/java/com/cangkir/bitperfectplayer/audio/PlaybackController.kt`
- [Playback queue](https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/audio/PlaybackQueueManager.kt): `app/src/main/java/com/cangkir/bitperfectplayer/audio/PlaybackQueueManager.kt`
- [Foreground service](https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/audio/PlaybackForegroundService.kt): `app/src/main/java/com/cangkir/bitperfectplayer/audio/PlaybackForegroundService.kt`
- [Audio output](https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/audio/AudioOutputEngine.kt): `app/src/main/java/com/cangkir/bitperfectplayer/audio/AudioOutputEngine.kt`
- [Hearing safety](https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/audio/AudioSafetyController.kt): `app/src/main/java/com/cangkir/bitperfectplayer/audio/AudioSafetyController.kt`
- [Audio diagnostics](https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/audio/AudioDiagnosticMapper.kt): `app/src/main/java/com/cangkir/bitperfectplayer/audio/AudioDiagnosticMapper.kt`

### Local data features

- [Offline lyrics](https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/lyrics/LyricsRepository.kt): `app/src/main/java/com/cangkir/bitperfectplayer/lyrics/LyricsRepository.kt`
- [Local persistence](https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/data/LocalPersistenceRepository.kt): `app/src/main/java/com/cangkir/bitperfectplayer/data/LocalPersistenceRepository.kt`
- [Room database](https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/data/BitPerfectDatabase.kt): `app/src/main/java/com/cangkir/bitperfectplayer/data/BitPerfectDatabase.kt`
- [User preferences](https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/data/UserPreferencesRepository.kt): `app/src/main/java/com/cangkir/bitperfectplayer/data/UserPreferencesRepository.kt`
- [Backup repository](https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/data/LocalBackupRepository.kt): `app/src/main/java/com/cangkir/bitperfectplayer/data/LocalBackupRepository.kt`
- [Backup codec](https://github.com/wagefolabessy/bitperfectplayer/blob/main/app/src/main/java/com/cangkir/bitperfectplayer/data/LocalBackupCodec.kt): `app/src/main/java/com/cangkir/bitperfectplayer/data/LocalBackupCodec.kt`

### Other components

- **Listener**

## Connections

- Listener → Main activity: opens app (evidence: `README.md`)
- Main activity → App view model: creates (evidence: `app/src/main/java/com/cangkir/bitperfectplayer/MainActivity.kt`)
- Listener → Player screens: uses (evidence: `README.md`)
- Player screens → App view model: uses
- App view model → Local library: requests library
- Local library → Audio metadata: reads metadata (evidence: `app/src/main/java/com/cangkir/bitperfectplayer/library/LocalLibraryRepository.kt`)
- App view model → Playlist repository: manages playlists
- Player screens → Artwork loader: loads artwork (evidence: `app/src/main/java/com/cangkir/bitperfectplayer/ui/LibraryScreen.kt`)
- App view model → Playback coordinator: controls playback
- Playback coordinator → Playback queue: manages queue (evidence: `app/src/main/java/com/cangkir/bitperfectplayer/audio/PlaybackController.kt`)
- Playback coordinator → Audio output: controls audio (evidence: `app/src/main/java/com/cangkir/bitperfectplayer/audio/PlaybackController.kt`)
- Foreground service → Playback coordinator: dispatches controls (evidence: `app/src/main/java/com/cangkir/bitperfectplayer/audio/PlaybackForegroundService.kt`)
- Playback coordinator → Hearing safety: coordinates safety (evidence: `app/src/main/java/com/cangkir/bitperfectplayer/audio/PlaybackController.kt`)
- Audio output → Audio diagnostics: maps audio state (evidence: `app/src/main/java/com/cangkir/bitperfectplayer/audio/AudioOutputEngine.kt`)
- Playback coordinator → Local persistence: saves playback (evidence: `app/src/main/java/com/cangkir/bitperfectplayer/audio/PlaybackController.kt`)
- Playback coordinator → User preferences: reads settings (evidence: `app/src/main/java/com/cangkir/bitperfectplayer/audio/PlaybackController.kt`)
- Local library → Local persistence: caches tracks (evidence: `app/src/main/java/com/cangkir/bitperfectplayer/library/LocalLibraryRepository.kt`)
- Local library → User preferences: stores SAF access (evidence: `app/src/main/java/com/cangkir/bitperfectplayer/library/LocalLibraryRepository.kt`)
- Offline lyrics → Local persistence: stores lyrics (evidence: `app/src/main/java/com/cangkir/bitperfectplayer/lyrics/LyricsRepository.kt`)
- Playlist repository → Local persistence: uses local records (evidence: `app/src/main/java/com/cangkir/bitperfectplayer/library/PlaylistRepository.kt`)
- Local persistence → Room database: uses DAOs (evidence: `app/src/main/java/com/cangkir/bitperfectplayer/data/LocalPersistenceRepository.kt`)
- Backup repository → Local persistence: exports records (evidence: `app/src/main/java/com/cangkir/bitperfectplayer/data/LocalBackupRepository.kt`)
- Backup repository → Backup codec: encodes backup (evidence: `app/src/main/java/com/cangkir/bitperfectplayer/data/LocalBackupRepository.kt`)
