# pranav-lejith/tunes architecture

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

- Interactive diagram: https://gitdiagram.com/pranav-lejith/tunes
- Repository: https://github.com/pranav-lejith/tunes

## Overview

Tunes is an Android music player whose main user flow is selecting local or YouTube Music audio, managing it in playback queues, and listening through the app’s player. Its broader capabilities include library scanning and metadata extraction, offline downloads, lyrics, playback effects, Android Auto, and configurable Material 3 theming. The README documents these product-level links; the graph uses dashed, uncited edges where the provided excerpts do not show internal calls. The source index identifies MusicService.kt as read, but its excerpt is not included here.

Main entry points: [`app/src/main/java/com/amphibiar/tunes/playback/MusicService.kt`](https://github.com/pranav-lejith/tunes/blob/main/app/src/main/java/com/amphibiar/tunes/playback/MusicService.kt) (Music service), [`app/src/main/java/com/amphibiar/tunes/viewmodels`](https://github.com/pranav-lejith/tunes/tree/main/app/src/main/java/com/amphibiar/tunes/viewmodels) (View models), [`app/src/main/java/com/amphibiar/tunes/ui/screens`](https://github.com/pranav-lejith/tunes/tree/main/app/src/main/java/com/amphibiar/tunes/ui/screens) (Screens), [`app/src/main/java/com/amphibiar/tunes/utils/scanners/LocalMediaScanner.kt`](https://github.com/pranav-lejith/tunes/blob/main/app/src/main/java/com/amphibiar/tunes/utils/scanners/LocalMediaScanner.kt) (Local scanner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["App interface"]
  node_app["Tunes app<br/>[App.kt]"]
  node_screens["Screens"]
  node_viewmodels["View models"]
  node_library_ui["Library UI"]
  node_settings["Settings and backup"]
end

subgraph group_library["Music library"]
  node_scanner["Local scanner"]
  node_metadata["Tag extraction<br/>[MetadataScanner.kt]"]
  node_youtube["YouTube Music client<br/>[YouTubeClient.kt]"]
  node_downloader["Song downloader"]
  node_database[("Music database<br/>[MusicDatabase.kt]")]
end

subgraph group_playback["Playback"]
  node_music_service["Music service<br/>[MusicService.kt]"]
  node_player_connection["Player connection"]
  node_queue["Queue management<br/>[QueueBoard.kt]"]
  node_player_ui["Player UI<br/>[Player.kt]"]
end

subgraph group_capabilities["Player capabilities"]
  node_lyrics["Lyrics<br/>[LyricsHelper.kt]"]
  node_effects["Audio effects<br/>[MusicService.kt]"]
  node_auto["Android Auto"]
  node_themes["Dynamic theming<br/>[Theme.kt]"]
end

node_listener(("Listener"))

node_listener -.->|"uses"| node_screens
node_screens -.->|"requests data"| node_viewmodels
node_viewmodels -.->|"presents library"| node_library_ui
node_library_ui -.->|"browses local media"| node_scanner
node_scanner -.->|"extracts tags"| node_metadata
node_viewmodels -.->|"accesses library"| node_database
node_viewmodels -.->|"searches music"| node_youtube
node_youtube -->|"downloads songs"| node_downloader
node_listener -.->|"controls playback"| node_player_ui
node_player_ui -.->|"sends commands"| node_player_connection
node_player_connection -.->|"connects to"| node_music_service
node_music_service -->|"manages queues"| node_queue
node_music_service -->|"plays local audio"| node_scanner
node_music_service -->|"plays streamed music"| node_youtube
node_music_service -->|"applies effects"| node_effects
node_music_service -->|"supports synchronized lyrics"| node_lyrics
node_music_service -->|"supports Android Auto"| node_auto
node_screens -->|"uses theming"| node_themes
node_listener -.->|"configures app"| node_settings

click node_app "https://github.com/pranav-lejith/tunes/blob/main/app/src/main/java/com/amphibiar/tunes/App.kt"
click node_screens "https://github.com/pranav-lejith/tunes/tree/main/app/src/main/java/com/amphibiar/tunes/ui/screens"
click node_viewmodels "https://github.com/pranav-lejith/tunes/tree/main/app/src/main/java/com/amphibiar/tunes/viewmodels"
click node_library_ui "https://github.com/pranav-lejith/tunes/tree/main/app/src/main/java/com/amphibiar/tunes/ui/screens/library"
click node_scanner "https://github.com/pranav-lejith/tunes/blob/main/app/src/main/java/com/amphibiar/tunes/utils/scanners/LocalMediaScanner.kt"
click node_metadata "https://github.com/pranav-lejith/tunes/blob/main/app/src/main/java/com/amphibiar/tunes/utils/scanners/MetadataScanner.kt"
click node_youtube "https://github.com/pranav-lejith/tunes/blob/main/app/src/main/java/com/amphibiar/tunes/utils/youtube/YouTubeClient.kt"
click node_downloader "https://github.com/pranav-lejith/tunes/blob/main/app/src/main/java/com/amphibiar/tunes/utils/youtube/YoutubeDownloader.kt"
click node_database "https://github.com/pranav-lejith/tunes/blob/main/app/src/main/java/com/amphibiar/tunes/db/MusicDatabase.kt"
click node_music_service "https://github.com/pranav-lejith/tunes/blob/main/app/src/main/java/com/amphibiar/tunes/playback/MusicService.kt"
click node_player_connection "https://github.com/pranav-lejith/tunes/blob/main/app/src/main/java/com/amphibiar/tunes/playback/PlayerConnection.kt"
click node_queue "https://github.com/pranav-lejith/tunes/blob/main/app/src/main/java/com/amphibiar/tunes/playback/QueueBoard.kt"
click node_player_ui "https://github.com/pranav-lejith/tunes/blob/main/app/src/main/java/com/amphibiar/tunes/ui/player/Player.kt"
click node_lyrics "https://github.com/pranav-lejith/tunes/blob/main/app/src/main/java/com/amphibiar/tunes/lyrics/LyricsHelper.kt"
click node_effects "https://github.com/pranav-lejith/tunes/blob/main/app/src/main/java/com/amphibiar/tunes/playback/MusicService.kt"
click node_auto "https://github.com/pranav-lejith/tunes/blob/main/app/src/main/java/com/amphibiar/tunes/playback/MediaLibrarySessionCallback.kt"
click node_themes "https://github.com/pranav-lejith/tunes/blob/main/app/src/main/java/com/amphibiar/tunes/ui/theme/Theme.kt"
click node_settings "https://github.com/pranav-lejith/tunes/tree/main/app/src/main/java/com/amphibiar/tunes/ui/screens/settings"

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_screens,node_viewmodels,node_library_ui,node_settings toneBlue
class node_scanner,node_metadata,node_youtube,node_downloader,node_database toneAmber
class node_music_service,node_player_connection,node_queue,node_player_ui toneMint
class node_lyrics,node_effects,node_auto,node_themes toneRose
class node_listener toneIndigo
```

## Components

### App interface

- [Tunes app](https://github.com/pranav-lejith/tunes/blob/main/app/src/main/java/com/amphibiar/tunes/App.kt): `app/src/main/java/com/amphibiar/tunes/App.kt`
- [Screens](https://github.com/pranav-lejith/tunes/tree/main/app/src/main/java/com/amphibiar/tunes/ui/screens): `app/src/main/java/com/amphibiar/tunes/ui/screens`
- [View models](https://github.com/pranav-lejith/tunes/tree/main/app/src/main/java/com/amphibiar/tunes/viewmodels): `app/src/main/java/com/amphibiar/tunes/viewmodels`
- [Library UI](https://github.com/pranav-lejith/tunes/tree/main/app/src/main/java/com/amphibiar/tunes/ui/screens/library): `app/src/main/java/com/amphibiar/tunes/ui/screens/library`
- [Settings and backup](https://github.com/pranav-lejith/tunes/tree/main/app/src/main/java/com/amphibiar/tunes/ui/screens/settings): `app/src/main/java/com/amphibiar/tunes/ui/screens/settings`

### Music library

- [Local scanner](https://github.com/pranav-lejith/tunes/blob/main/app/src/main/java/com/amphibiar/tunes/utils/scanners/LocalMediaScanner.kt): `app/src/main/java/com/amphibiar/tunes/utils/scanners/LocalMediaScanner.kt`
- [Tag extraction](https://github.com/pranav-lejith/tunes/blob/main/app/src/main/java/com/amphibiar/tunes/utils/scanners/MetadataScanner.kt): `app/src/main/java/com/amphibiar/tunes/utils/scanners/MetadataScanner.kt`
- [YouTube Music client](https://github.com/pranav-lejith/tunes/blob/main/app/src/main/java/com/amphibiar/tunes/utils/youtube/YouTubeClient.kt): `app/src/main/java/com/amphibiar/tunes/utils/youtube/YouTubeClient.kt`
- [Song downloader](https://github.com/pranav-lejith/tunes/blob/main/app/src/main/java/com/amphibiar/tunes/utils/youtube/YoutubeDownloader.kt): `app/src/main/java/com/amphibiar/tunes/utils/youtube/YoutubeDownloader.kt`
- [Music database](https://github.com/pranav-lejith/tunes/blob/main/app/src/main/java/com/amphibiar/tunes/db/MusicDatabase.kt): `app/src/main/java/com/amphibiar/tunes/db/MusicDatabase.kt`

### Playback

- [Music service](https://github.com/pranav-lejith/tunes/blob/main/app/src/main/java/com/amphibiar/tunes/playback/MusicService.kt): `app/src/main/java/com/amphibiar/tunes/playback/MusicService.kt`
- [Player connection](https://github.com/pranav-lejith/tunes/blob/main/app/src/main/java/com/amphibiar/tunes/playback/PlayerConnection.kt): `app/src/main/java/com/amphibiar/tunes/playback/PlayerConnection.kt`
- [Queue management](https://github.com/pranav-lejith/tunes/blob/main/app/src/main/java/com/amphibiar/tunes/playback/QueueBoard.kt): `app/src/main/java/com/amphibiar/tunes/playback/QueueBoard.kt`
- [Player UI](https://github.com/pranav-lejith/tunes/blob/main/app/src/main/java/com/amphibiar/tunes/ui/player/Player.kt): `app/src/main/java/com/amphibiar/tunes/ui/player/Player.kt`

### Player capabilities

- [Lyrics](https://github.com/pranav-lejith/tunes/blob/main/app/src/main/java/com/amphibiar/tunes/lyrics/LyricsHelper.kt): `app/src/main/java/com/amphibiar/tunes/lyrics/LyricsHelper.kt`
- [Audio effects](https://github.com/pranav-lejith/tunes/blob/main/app/src/main/java/com/amphibiar/tunes/playback/MusicService.kt): `app/src/main/java/com/amphibiar/tunes/playback/MusicService.kt`
- [Android Auto](https://github.com/pranav-lejith/tunes/blob/main/app/src/main/java/com/amphibiar/tunes/playback/MediaLibrarySessionCallback.kt): `app/src/main/java/com/amphibiar/tunes/playback/MediaLibrarySessionCallback.kt`
- [Dynamic theming](https://github.com/pranav-lejith/tunes/blob/main/app/src/main/java/com/amphibiar/tunes/ui/theme/Theme.kt): `app/src/main/java/com/amphibiar/tunes/ui/theme/Theme.kt`

### Other components

- **Listener**

## Connections

- Listener → Screens: uses
- Screens → View models: requests data (evidence: `app/src/main/java/com/amphibiar/tunes/ui/screens/settings/fragments/StorageFrag.kt`)
- View models → Library UI: presents library
- Library UI → Local scanner: browses local media
- Local scanner → Tag extraction: extracts tags
- View models → Music database: accesses library
- View models → YouTube Music client: searches music
- YouTube Music client → Song downloader: downloads songs (evidence: `README.md`)
- Listener → Player UI: controls playback
- Player UI → Player connection: sends commands
- Player connection → Music service: connects to
- Music service → Queue management: manages queues (evidence: `README.md`)
- Music service → Local scanner: plays local audio (evidence: `README.md`)
- Music service → YouTube Music client: plays streamed music (evidence: `README.md`)
- Music service → Audio effects: applies effects (evidence: `README.md`)
- Music service → Lyrics: supports synchronized lyrics (evidence: `README.md`)
- Music service → Android Auto: supports Android Auto (evidence: `README.md`)
- Screens → Dynamic theming: uses theming (evidence: `README.md`)
- Listener → Settings and backup: configures app