How z-huang/innertune works
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: HomeViewModel.kt Feature ViewModels · LyricsHelper.kt Lyrics coordinator · MusicService.kt Music service · App.kt App & main activity
Components 21
Android app
Compose client, state, playback, and local storage.
- App & main activity
app/src/main/java/com/zionhuang/music/App.kt - App manifest
app/src/main/AndroidManifest.xml - Dependency module
app/src/main/java/com/zionhuang/music/di/AppModule.kt - Compose navigation
app/src/main/java/com/zionhuang/music/ui/screens/NavigationBuilder.kt - Feature ViewModels · Coordinates online, local, library, and account operations.
app/src/main/java/com/zionhuang/music/viewmodels/HomeViewModel.kt - App theme
app/src/main/java/com/zionhuang/music/ui/theme/Theme.kt - Music service · Owns player and Android media session.
app/src/main/java/com/zionhuang/music/playback/MusicService.kt - Player connection · Carries UI commands and playback state.
app/src/main/java/com/zionhuang/music/playback/PlayerConnection.kt - Queue strategies
app/src/main/java/com/zionhuang/music/playback/queues/YouTubeQueue.kt - Download service
app/src/main/java/com/zionhuang/music/playback/ExoDownloadService.kt - Music database · Stores library, playlists, history, formats, lyrics, and search history.
app/src/main/java/com/zionhuang/music/db/MusicDatabase.kt - DataStore preferences
app/src/main/java/com/zionhuang/music/utils/DataStore.kt - Lyrics coordinator
app/src/main/java/com/zionhuang/music/lyrics/LyricsHelper.kt - Discord RPC bridge
app/src/main/java/com/zionhuang/music/utils/DiscordRPC.kt
Service modules
Isolated protocol clients.
- InnerTube client · Normalizes endpoint responses into page models.
innertube/src/main/java/com/zionhuang/innertube/InnerTube.kt - LrcLib client
lrclib/src/main/java/com/zionhuang/lrclib/LrcLib.kt - KuGou client
kugou/src/main/java/com/zionhuang/kugou/KuGou.kt - Kizzy RPC
kizzy/src/main/java/com/my/kizzy/rpc/KizzyRPC.kt
Other components
- Android platform
- YouTube Music
- Discord
Connections 23
- 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