# z-huang/innertune architecture

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

- Interactive diagram: https://gitdiagram.com/z-huang/innertune
- Repository: https://github.com/z-huang/innertune

## Overview

#### Purpose and module layout
InnerTune is a native Android Material 3 client for YouTube Music, supporting online browsing/playback plus local library, downloads, lyrics, and integrations. Gradle defines a multi-module Kotlin/Android build: the user-facing app is `app`, while protocol/service adapters are isolated in `innertube`, `kugou`, `lrclib`, and `kizzy`. Key build boundaries: `settings.gradle.kts`, `app/build.gradle.kts`, `innertube/build.gradle.kts`.

#### Application entry and composition
Android starts the application and single main activity at `app/src/main/java/com/zionhuang/music/App.kt` and `app/src/main/java/com/zionhuang/music/MainActivity.kt`, declared through `app/src/main/AndroidManifest.xml`. Dependency setup is centralized in `app/src/main/java/com/zionhuang/music/di/AppModule.kt`. The app has `full` and `foss` source sets, notably allowing variant-specific utility/translation behavior under `app/src/full/java/com/zionhuang/music/utils/Utils.kt` and `app/src/foss/java/com/zionhuang/music/utils/Utils.kt`.

#### UI, navigation, and state boundary
Jetpack Compose screens form the presentation layer; routing/navigation is concentrated in `app/src/main/java/com/zionhuang/music/ui/screens/Screens.kt` and `app/src/main/java/com/zionhuang/music/ui/screens/NavigationBuilder.kt`. Feature ViewModels mediate UI state and operations across online, local, library, and account use cases—for example `app/src/main/java/com/zionhuang/music/viewmodels/HomeViewModel.kt`, `app/src/main/java/com/zionhuang/music/viewmodels/OnlineSearchViewModel.kt`, and `app/src/main/java/com/zionhuang/music/viewmodels/LibraryViewModels.kt`. This is the principal UI-to-data/service boundary.

#### YouTube Music acquisition
The `innertube` JVM/Kotlin module encapsulates YouTube/YouTube Music’s InnerTube interaction and response parsing. Its public/client side resides in `innertube/src/main/java/com/zionhuang/innertube/InnerTube.kt` and `innertube/src/main/java/com/zionhuang/innertube/YouTube.kt`; typed request and response models isolate endpoint payloads under `innertube/src/main/java/com/zionhuang/innertube/models/body` and `innertube/src/main/java/com/zionhuang/innertube/models/response`. App ViewModels consume normalized page models such as `innertube/src/main/java/com/zionhuang/innertube/pages/HomePage.kt` and `innertube/src/main/java/com/zionhuang/innertube/pages/SearchPage.kt`, rather than UI parsing API responses.

#### Playback, queues, and offline media
A background media-service subsystem owns active playback and Android media-session interoperability: `app/src/main/java/com/zionhuang/music/playback/MusicService.kt`, `app/src/main/java/com/zionhuang/music/playback/PlayerConnection.kt`, and `app/src/main/java/com/zionhuang/music/playback/MediaLibrarySessionCallback.kt`. UI issues commands/state subscriptions via the connection; queue strategies select sequential, local-radio, or YouTube-radio behavior under `app/src/main/java/com/zionhuang/music/playback/queues/Queue.kt` and `app/src/main/java/com/zionhuang/music/playback/queues/YouTubeQueue.kt`. Download/cache lifecycle is separated through `app/src/main/java/com/zionhuang/music/playback/ExoDownloadService.kt` and `app/src/main/java/com/zionhuang/music/playback/DownloadUtil.kt`.

#### Local persistence and user state
Room-style local persistence is represented by the database façade/DAO and relational media entities: `app/src/main/java/com/zionhuang/music/db/MusicDatabase.kt`, `app/src/main/java/com/zionhuang/music/db/DatabaseDao.kt`, and `app/src/main/java/com/zionhuang/music/db/entities/SongEntity.kt`. It stores library relationships, playlists, history/events, formats, lyrics, and search history; schema evolution snapshots are in `app/schemas/com.zionhuang.music.db.InternalDatabase`. App preferences/settings use a separate DataStore abstraction at `app/src/main/java/com/zionhuang/music/utils/DataStore.kt`.

#### Lyrics and external integrations
Lyrics resolution is provider-based: the coordinator and provider contract are `app/src/main/java/com/zionhuang/music/lyrics/LyricsHelper.kt` and `app/src/main/java/com/zionhuang/music/lyrics/LyricsProvider.kt`, with YouTube subtitles plus LrcLib and KuGou adapters. LrcLib and KuGou protocol clients are their own modules at `lrclib/src/main/java/com/zionhuang/lrclib/LrcLib.kt` and `kugou/src/main/java/com/zionhuang/kugou/KuGou.kt`. Discord Rich Presence is mediated by app utility code and the `kizzy` Discord WebSocket/RPC implementation: `app/src/main/java/com/zionhuang/music/utils/DiscordRPC.kt`, `kizzy/src/main/java/com/my/kizzy/rpc/KizzyRPC.kt`.

#### Runtime and platform dependencies
The runtime is Android/Kotlin with Compose UI, Android media sessions/Auto, background services, local database storage, and network access to YouTube Music/YouTube plus optional lyric and Discord services. Dynamic theming includes vendored Material color algorithms in `material-color-utilities/src/main/java/com/google/material/color/dynamiccolor/MaterialDynamicColors.java`; app theme integration is `app/src/main/java/com/zionhuang/music/ui/theme/Theme.kt`.

Main entry points: [`app/src/main/java/com/zionhuang/music/viewmodels/HomeViewModel.kt`](https://github.com/z-huang/innertune/blob/dev/app/src/main/java/com/zionhuang/music/viewmodels/HomeViewModel.kt) (Feature ViewModels), [`app/src/main/java/com/zionhuang/music/lyrics/LyricsHelper.kt`](https://github.com/z-huang/innertune/blob/dev/app/src/main/java/com/zionhuang/music/lyrics/LyricsHelper.kt) (Lyrics coordinator), [`app/src/main/java/com/zionhuang/music/playback/MusicService.kt`](https://github.com/z-huang/innertune/blob/dev/app/src/main/java/com/zionhuang/music/playback/MusicService.kt) (Music service), [`app/src/main/java/com/zionhuang/music/App.kt`](https://github.com/z-huang/innertune/blob/dev/app/src/main/java/com/zionhuang/music/App.kt) (App & main activity)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Android app"]
  node_entry["App &amp; main activity<br/>Android entry<br/>[App.kt]"]
  node_manifest["App manifest<br/>Android declaration"]
  node_di["Dependency module<br/>DI composition<br/>[AppModule.kt]"]
  node_navigation["Compose navigation<br/>presentation routing"]
  node_viewmodels["Feature ViewModels<br/>UI state boundary<br/>[HomeViewModel.kt]"]
  node_theme["App theme<br/>Compose theme<br/>[Theme.kt]"]
  node_playback["Music service<br/>background playback<br/>[MusicService.kt]"]
  node_connection["Player connection<br/>playback client"]
  node_queues["Queue strategies<br/>playback queue<br/>[YouTubeQueue.kt]"]
  node_downloads["Download service<br/>offline media"]
  node_database[("Music database<br/>Room database<br/>[MusicDatabase.kt]")]
  node_preferences[("DataStore preferences<br/>settings storage<br/>[DataStore.kt]")]
  node_lyrics["Lyrics coordinator<br/>provider orchestration<br/>[LyricsHelper.kt]"]
  node_discord["Discord RPC bridge<br/>integration<br/>[DiscordRPC.kt]"]
end

subgraph group_adapters["Service modules"]
  node_innertube["InnerTube client<br/>YouTube Music API<br/>[InnerTube.kt]"]
  node_lrclib["LrcLib client<br/>lyrics API<br/>[LrcLib.kt]"]
  node_kugou["KuGou client<br/>lyrics API<br/>[KuGou.kt]"]
  node_kizzy["Kizzy RPC<br/>Discord WebSocket RPC<br/>[KizzyRPC.kt]"]
end

node_android{{"Android platform"}}
node_youtube{{"YouTube Music<br/>remote service"}}
node_discord_service{{"Discord<br/>remote service"}}

node_manifest -->|"declares"| node_entry
node_android -->|"launches"| node_entry
node_entry -->|"initializes"| node_di
node_entry -->|"hosts"| node_navigation
node_navigation -->|"screens use"| node_viewmodels
node_navigation -->|"applies"| node_theme
node_di -->|"provides"| node_viewmodels
node_viewmodels -->|"requests pages"| node_innertube
node_viewmodels -->|"reads and writes"| node_database
node_viewmodels -->|"uses settings"| node_preferences
node_viewmodels -->|"controls playback"| node_connection
node_connection -->|"binds to"| node_playback
node_playback -->|"selects"| node_queues
node_playback -->|"manages offline media"| node_downloads
node_playback -->|"media session"| node_android
node_downloads -->|"persists media state"| node_database
node_lyrics -->|"queries"| node_lrclib
node_lyrics -->|"queries"| node_kugou
node_lyrics -->|"gets subtitles"| node_innertube
node_lyrics -->|"caches lyrics"| node_database
node_innertube -->|"API requests"| node_youtube
node_discord -->|"uses"| node_kizzy
node_kizzy -->|"RPC connection"| node_discord_service

click node_entry "https://github.com/z-huang/innertune/blob/dev/app/src/main/java/com/zionhuang/music/App.kt"
click node_manifest "https://github.com/z-huang/innertune/blob/dev/app/src/main/AndroidManifest.xml"
click node_di "https://github.com/z-huang/innertune/blob/dev/app/src/main/java/com/zionhuang/music/di/AppModule.kt"
click node_navigation "https://github.com/z-huang/innertune/blob/dev/app/src/main/java/com/zionhuang/music/ui/screens/NavigationBuilder.kt"
click node_viewmodels "https://github.com/z-huang/innertune/blob/dev/app/src/main/java/com/zionhuang/music/viewmodels/HomeViewModel.kt"
click node_theme "https://github.com/z-huang/innertune/blob/dev/app/src/main/java/com/zionhuang/music/ui/theme/Theme.kt"
click node_playback "https://github.com/z-huang/innertune/blob/dev/app/src/main/java/com/zionhuang/music/playback/MusicService.kt"
click node_connection "https://github.com/z-huang/innertune/blob/dev/app/src/main/java/com/zionhuang/music/playback/PlayerConnection.kt"
click node_queues "https://github.com/z-huang/innertune/blob/dev/app/src/main/java/com/zionhuang/music/playback/queues/YouTubeQueue.kt"
click node_downloads "https://github.com/z-huang/innertune/blob/dev/app/src/main/java/com/zionhuang/music/playback/ExoDownloadService.kt"
click node_database "https://github.com/z-huang/innertune/blob/dev/app/src/main/java/com/zionhuang/music/db/MusicDatabase.kt"
click node_preferences "https://github.com/z-huang/innertune/blob/dev/app/src/main/java/com/zionhuang/music/utils/DataStore.kt"
click node_lyrics "https://github.com/z-huang/innertune/blob/dev/app/src/main/java/com/zionhuang/music/lyrics/LyricsHelper.kt"
click node_discord "https://github.com/z-huang/innertune/blob/dev/app/src/main/java/com/zionhuang/music/utils/DiscordRPC.kt"
click node_innertube "https://github.com/z-huang/innertune/blob/dev/innertube/src/main/java/com/zionhuang/innertube/InnerTube.kt"
click node_lrclib "https://github.com/z-huang/innertune/blob/dev/lrclib/src/main/java/com/zionhuang/lrclib/LrcLib.kt"
click node_kugou "https://github.com/z-huang/innertune/blob/dev/kugou/src/main/java/com/zionhuang/kugou/KuGou.kt"
click node_kizzy "https://github.com/z-huang/innertune/blob/dev/kizzy/src/main/java/com/my/kizzy/rpc/KizzyRPC.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_entry,node_manifest,node_di,node_navigation,node_viewmodels,node_theme,node_playback,node_connection,node_queues,node_downloads,node_database,node_preferences,node_lyrics,node_discord toneBlue
class node_innertube,node_lrclib,node_kugou,node_kizzy toneAmber
class node_android,node_youtube,node_discord_service toneNeutral
```

## Components

### Android app

Compose client, state, playback, and local storage.

- [App & main activity](https://github.com/z-huang/innertune/blob/dev/app/src/main/java/com/zionhuang/music/App.kt): Android entry · `app/src/main/java/com/zionhuang/music/App.kt`
- [App manifest](https://github.com/z-huang/innertune/blob/dev/app/src/main/AndroidManifest.xml): Android declaration · `app/src/main/AndroidManifest.xml`
- [Dependency module](https://github.com/z-huang/innertune/blob/dev/app/src/main/java/com/zionhuang/music/di/AppModule.kt): DI composition · `app/src/main/java/com/zionhuang/music/di/AppModule.kt`
- [Compose navigation](https://github.com/z-huang/innertune/blob/dev/app/src/main/java/com/zionhuang/music/ui/screens/NavigationBuilder.kt): presentation routing · `app/src/main/java/com/zionhuang/music/ui/screens/NavigationBuilder.kt`
- [Feature ViewModels](https://github.com/z-huang/innertune/blob/dev/app/src/main/java/com/zionhuang/music/viewmodels/HomeViewModel.kt): UI state boundary · Coordinates online, local, library, and account operations. · `app/src/main/java/com/zionhuang/music/viewmodels/HomeViewModel.kt`
- [App theme](https://github.com/z-huang/innertune/blob/dev/app/src/main/java/com/zionhuang/music/ui/theme/Theme.kt): Compose theme · `app/src/main/java/com/zionhuang/music/ui/theme/Theme.kt`
- [Music service](https://github.com/z-huang/innertune/blob/dev/app/src/main/java/com/zionhuang/music/playback/MusicService.kt): background playback · Owns player and Android media session. · `app/src/main/java/com/zionhuang/music/playback/MusicService.kt`
- [Player connection](https://github.com/z-huang/innertune/blob/dev/app/src/main/java/com/zionhuang/music/playback/PlayerConnection.kt): playback client · Carries UI commands and playback state. · `app/src/main/java/com/zionhuang/music/playback/PlayerConnection.kt`
- [Queue strategies](https://github.com/z-huang/innertune/blob/dev/app/src/main/java/com/zionhuang/music/playback/queues/YouTubeQueue.kt): playback queue · `app/src/main/java/com/zionhuang/music/playback/queues/YouTubeQueue.kt`
- [Download service](https://github.com/z-huang/innertune/blob/dev/app/src/main/java/com/zionhuang/music/playback/ExoDownloadService.kt): offline media · `app/src/main/java/com/zionhuang/music/playback/ExoDownloadService.kt`
- [Music database](https://github.com/z-huang/innertune/blob/dev/app/src/main/java/com/zionhuang/music/db/MusicDatabase.kt): Room database · Stores library, playlists, history, formats, lyrics, and search history. · `app/src/main/java/com/zionhuang/music/db/MusicDatabase.kt`
- [DataStore preferences](https://github.com/z-huang/innertune/blob/dev/app/src/main/java/com/zionhuang/music/utils/DataStore.kt): settings storage · `app/src/main/java/com/zionhuang/music/utils/DataStore.kt`
- [Lyrics coordinator](https://github.com/z-huang/innertune/blob/dev/app/src/main/java/com/zionhuang/music/lyrics/LyricsHelper.kt): provider orchestration · `app/src/main/java/com/zionhuang/music/lyrics/LyricsHelper.kt`
- [Discord RPC bridge](https://github.com/z-huang/innertune/blob/dev/app/src/main/java/com/zionhuang/music/utils/DiscordRPC.kt): integration · `app/src/main/java/com/zionhuang/music/utils/DiscordRPC.kt`

### Service modules

Isolated protocol clients.

- [InnerTube client](https://github.com/z-huang/innertune/blob/dev/innertube/src/main/java/com/zionhuang/innertube/InnerTube.kt): YouTube Music API · Normalizes endpoint responses into page models. · `innertube/src/main/java/com/zionhuang/innertube/InnerTube.kt`
- [LrcLib client](https://github.com/z-huang/innertune/blob/dev/lrclib/src/main/java/com/zionhuang/lrclib/LrcLib.kt): lyrics API · `lrclib/src/main/java/com/zionhuang/lrclib/LrcLib.kt`
- [KuGou client](https://github.com/z-huang/innertune/blob/dev/kugou/src/main/java/com/zionhuang/kugou/KuGou.kt): lyrics API · `kugou/src/main/java/com/zionhuang/kugou/KuGou.kt`
- [Kizzy RPC](https://github.com/z-huang/innertune/blob/dev/kizzy/src/main/java/com/my/kizzy/rpc/KizzyRPC.kt): Discord WebSocket RPC · `kizzy/src/main/java/com/my/kizzy/rpc/KizzyRPC.kt`

### Other components

- **Android platform**: platform
- **YouTube Music**: remote service
- **Discord**: remote service

## Connections

- App manifest → App & main activity: declares
- Android platform → App & main activity: launches
- App & main activity → Dependency module: initializes
- App & main activity → Compose navigation: hosts
- Compose navigation → Feature ViewModels: screens use
- Compose navigation → App theme: applies
- Dependency module → Feature ViewModels: provides
- Feature ViewModels → InnerTube client: requests pages
- Feature ViewModels → Music database: reads and writes
- Feature ViewModels → DataStore preferences: uses settings
- Feature ViewModels → Player connection: controls playback
- Player connection → Music service: binds to
- Music service → Queue strategies: selects
- Music service → Download service: manages offline media
- Music service → Android platform: media session
- Download service → Music database: persists media state
- Lyrics coordinator → LrcLib client: queries
- Lyrics coordinator → KuGou client: queries
- Lyrics coordinator → InnerTube client: gets subtitles
- Lyrics coordinator → Music database: caches lyrics
- InnerTube client → YouTube Music: API requests
- Discord RPC bridge → Kizzy RPC: uses
- Kizzy RPC → Discord: RPC connection
