# nikhilvishwakarma00/velune architecture

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

- Interactive diagram: https://gitdiagram.com/nikhilvishwakarma00/velune
- Repository: https://github.com/nikhilvishwakarma00/velune

## Overview

1. **What this repo is**
   - Velune is an Android music player/client for YouTube Music, built as a modular Kotlin app.
   - The architecture is centered on a local-first Android app with a background playback service, a Room database, and several network-backed feature modules.

2. **Top-level module boundaries**
   - `app/` is the main Android application and contains most of the runtime code: UI, ViewModels, database, playback, settings, and feature orchestration.
   - `innertube/` is the core YouTube Music API client and page/model layer.
   - `lrclib/`, `kugou/`, `simpmusic/`, and `betterlyrics/` are lyrics-provider modules.
   - `lastfm/` and `kizzy/` are integration modules for external services.
   - `canvas/` is a small rendering module used for custom visual output.

3. **Presentation layer**
   - The app UI is built with Jetpack Compose and Material 3.
   - Screens are split by domain: home, browse, library, search, playlists, artist, settings, stats, history, and player.
   - Reusable composables live under `ui/component`, player-specific UI under `ui/player`, and screen-level navigation under `ui/screens`.

4. **State and orchestration**
   - The app follows MVVM/UDF: UI screens observe `ViewModel`s and render state, while actions flow back to ViewModels.
   - ViewModels live in `viewmodels/` and correspond closely to visible features such as Home, Browse, Library, Search, Lyrics, Stats, and Account.
   - This makes the UI layer mostly declarative; feature logic is not embedded in composables.

5. **Playback subsystem**
   - Playback is handled outside the UI by `playback/MusicService`, which acts as the long-lived audio engine.
   - `MediaLibrarySessionCallback` and `PlayerConnection` bridge UI commands to the service and expose playback state back to the app.
   - The playback stack includes queue management, crossfade, sleep timer, download support, and equalizer-related models.
   - This is the main boundary between foreground UI and background media execution.

6. **Local persistence layer**
   - The app uses Room (`db/`) for persistent state such as songs, albums, artists, playlists, lyrics, play counts, search history, tags, skips, and event/stat tracking.
   - The many schema files under `app/schemas/com.nikhil.yt.db.InternalDatabase/` show a mature, versioned database with frequent migrations.
   - DataStore is also used for preference-style settings, while Room stores the structured library and playback history data.

7. **YouTube Music data source**
   - `innertube/` encapsulates the YouTube Music private API surface: browse, search, player, next, queue, transcript, playlist, and related content.
   - Its page classes transform raw API responses into app-friendly page/domain models like albums, artists, home, charts, explore, library, playlists, and related tracks.
   - In architectural terms, this module is the main remote data adapter between Velune and YouTube Music.

8. **Lyrics subsystem**
   - Lyrics are aggregated from multiple providers rather than a single source.
   - `app/lyrics/` coordinates providers such as BetterLyrics, KuGou, LrcLib, SimpMusic, YouTube lyrics, and YouTube subtitle/transcript lyrics.
   - The app also contains preload/helper logic so lyrics can be fetched, cached, and synchronized around playback time.
   - This is a distinct integration boundary: playback metadata drives lyrics lookup, which then feeds the player UI.

9. **External integrations**
   - `lastfm/` likely supports scrobbling/authentication for listening stats.
   - `kizzy/` provides Discord RPC/websocket presence plumbing; the app-side utilities and settings screens expose Discord presence controls.
   - The app also contains dedicated settings and manager classes for sync and third-party account integrations.

10. **Social / collaborative playback**
   - The `together/` package is a separate feature subsystem for synchronized listening.
   - It includes client/server/online host pieces plus message, link, model, and playback-planning classes.
   - From an architecture standpoint, this behaves like an overlay service on top of the normal player state, enabling shared playback coordination.

11. **Discovery, search, and library flows**
   - Search and browse screens consume YouTube data from `innertube` and local library data from Room.
   - Library screens are backed by local entities and filtering/sorting constants, while online screens surface YouTube Music content and recommendations.
   - Home, explore, charts, new releases, and mood/genres are remote-content entry points, whereas library/history/playlists are local persistence entry points.

12. **Supporting infrastructure**
   - Dependency injection is provided by Hilt via `di/AppModule.kt` and `di/NetworkModule.kt`.
   - The app uses coroutines and Flow for async state, Media3/ExoPlayer for audio, and encrypted offline caching as part of the player/storage experience.
   - Utilities under `utils/`, `extensions/`, and `constants/` hold cross-cutting concerns such as connectivity, artwork, updates, scrobbling, playlist suggestions, and formatting.

13. **How data typically moves**
   - User action in Compose UI → ViewModel → repository/helper/service layer → local Room/DataStore and/or remote modules (`innertube`, lyrics providers, integrations) → state updated back into the UI.
   - Playback is a parallel path: UI controls → `PlayerConnection`/media session → `MusicService`/ExoPlayer → playback state, notifications, widget, history, and stats updates.
   - Lyrics and social presence are secondary consumers of playback state.

14. **Important architectural diagram boundaries**
   - Separate the app into: UI, state management, playback engine, local persistence, YouTube Music API adapter, lyrics providers, external integrations, and collaboration features.
   - Show `app/` as the orchestrator, with the other Gradle modules acting as specialized adapters/services.
   - The clearest external systems to draw are YouTube Music, lyrics services, Last.fm, Discord, and the Android media platform.

Main entry points: [`app/src/main/kotlin/com/nikhil/yt/viewmodels/HomeViewModel.kt`](https://github.com/nikhilvishwakarma00/velune/blob/main/app/src/main/kotlin/com/nikhil/yt/viewmodels/HomeViewModel.kt) (ViewModels), [`app/src/main/kotlin/com/nikhil/yt/playback/MusicService.kt`](https://github.com/nikhilvishwakarma00/velune/blob/main/app/src/main/kotlin/com/nikhil/yt/playback/MusicService.kt) (Playback engine), [`app/src/main/kotlin/com/nikhil/yt/ui/screens/settings/IntegrationScreen.kt`](https://github.com/nikhilvishwakarma00/velune/blob/main/app/src/main/kotlin/com/nikhil/yt/ui/screens/settings/IntegrationScreen.kt) (Settings integrations), [`app/src/main/kotlin/com/nikhil/yt/ui/screens/HomeScreen.kt`](https://github.com/nikhilvishwakarma00/velune/blob/main/app/src/main/kotlin/com/nikhil/yt/ui/screens/HomeScreen.kt) (UI layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App"]
  node_app_shell["App shell<br/>android app<br/>[App.kt]"]
  node_ui_layer["UI layer<br/>compose ui<br/>[HomeScreen.kt]"]
  node_viewmodels["ViewModels<br/>mvvm state<br/>[HomeViewModel.kt]"]
  node_playback["Playback engine<br/>media service<br/>[MusicService.kt]"]
  node_player_bridge["Player bridge<br/>session bridge"]
  node_local_db[("Local store<br/>room datastore<br/>[MusicDatabase.kt]")]
  node_preferences["Preferences<br/>datastore prefs<br/>[DataStore.kt]"]
  node_lyrics_coord["Lyrics coord<br/>lyrics orchestration<br/>[LyricsHelper.kt]"]
  node_together["Together<br/>shared playback<br/>[TogetherClient.kt]"]
  node_settings_integrations["Settings integrations<br/>integration ui"]
end

subgraph group_core["Core modules"]
  node_innertube["InnerTube<br/>yt music api<br/>[InnerTube.kt]"]
  node_lyrics_providers["Lyrics providers<br/>lyrics adapters<br/>[LrcLib.kt]"]
  node_betterlyrics["BetterLyrics<br/>ttml parser<br/>[BetterLyrics.kt]"]
  node_lastfm["Last.fm<br/>scrobble auth<br/>[LastFM.kt]"]
  node_kizzy["Discord RPC<br/>presence client<br/>[KizzyRPC.kt]"]
  node_canvas["Canvas<br/>rendering module<br/>[VeluneCanvas.kt]"]
end

subgraph group_external["External systems"]
  node_yt_music(("YouTube Music<br/>remote service"))
  node_lyrics_services(("Lyrics services<br/>remote services"))
  node_android_media(("Android media<br/>platform"))
end

node_app_shell -->|"hosts"| node_ui_layer
node_ui_layer -->|"observes"| node_viewmodels
node_viewmodels -->|"reads/writes"| node_local_db
node_viewmodels -->|"reads/writes"| node_preferences
node_viewmodels -->|"loads remote data"| node_innertube
node_viewmodels -->|"requests lyrics"| node_lyrics_coord
node_viewmodels -->|"coordinates"| node_together
node_ui_layer -->|"sends controls"| node_player_bridge
node_player_bridge -->|"controls"| node_playback
node_playback -->|"uses"| node_android_media
node_playback -->|"updates history"| node_local_db
node_playback -->|"publishes timing"| node_lyrics_coord
node_lyrics_coord -->|"queries"| node_lyrics_providers
node_lyrics_coord -->|"parses"| node_betterlyrics
node_lyrics_providers -->|"fetches from"| node_lyrics_services
node_innertube -->|"calls"| node_yt_music
node_together -->|"hooks playback"| node_android_media
node_settings_integrations -->|"configures"| node_lastfm
node_settings_integrations -->|"configures"| node_kizzy
node_settings_integrations -->|"configures"| node_together
node_settings_integrations -->|"manages"| node_local_db
node_ui_layer -->|"renders with"| node_canvas
node_playback -->|"feeds visuals"| node_canvas
node_viewmodels -->|"scrobbles"| node_lastfm
node_viewmodels -->|"updates presence"| node_kizzy

click node_app_shell "https://github.com/nikhilvishwakarma00/velune/blob/main/app/src/main/kotlin/com/nikhil/yt/App.kt"
click node_ui_layer "https://github.com/nikhilvishwakarma00/velune/blob/main/app/src/main/kotlin/com/nikhil/yt/ui/screens/HomeScreen.kt"
click node_viewmodels "https://github.com/nikhilvishwakarma00/velune/blob/main/app/src/main/kotlin/com/nikhil/yt/viewmodels/HomeViewModel.kt"
click node_playback "https://github.com/nikhilvishwakarma00/velune/blob/main/app/src/main/kotlin/com/nikhil/yt/playback/MusicService.kt"
click node_player_bridge "https://github.com/nikhilvishwakarma00/velune/blob/main/app/src/main/kotlin/com/nikhil/yt/playback/PlayerConnection.kt"
click node_local_db "https://github.com/nikhilvishwakarma00/velune/blob/main/app/src/main/kotlin/com/nikhil/yt/db/MusicDatabase.kt"
click node_preferences "https://github.com/nikhilvishwakarma00/velune/blob/main/app/src/main/kotlin/com/nikhil/yt/utils/DataStore.kt"
click node_lyrics_coord "https://github.com/nikhilvishwakarma00/velune/blob/main/app/src/main/kotlin/com/nikhil/yt/lyrics/LyricsHelper.kt"
click node_together "https://github.com/nikhilvishwakarma00/velune/blob/main/app/src/main/kotlin/com/nikhil/yt/together/TogetherClient.kt"
click node_settings_integrations "https://github.com/nikhilvishwakarma00/velune/blob/main/app/src/main/kotlin/com/nikhil/yt/ui/screens/settings/IntegrationScreen.kt"
click node_innertube "https://github.com/nikhilvishwakarma00/velune/blob/main/innertube/src/main/kotlin/com/nikhil/yt/innertube/InnerTube.kt"
click node_lyrics_providers "https://github.com/nikhilvishwakarma00/velune/blob/main/lrclib/src/main/kotlin/com/nikhil/yt/lrclib/LrcLib.kt"
click node_betterlyrics "https://github.com/nikhilvishwakarma00/velune/blob/main/betterlyrics/src/main/kotlin/com/nikhil/yt/betterlyrics/BetterLyrics.kt"
click node_lastfm "https://github.com/nikhilvishwakarma00/velune/blob/main/lastfm/src/main/kotlin/com/nikhil/yt/lastfm/LastFM.kt"
click node_kizzy "https://github.com/nikhilvishwakarma00/velune/blob/main/kizzy/src/main/kotlin/com/my/kizzy/rpc/KizzyRPC.kt"
click node_canvas "https://github.com/nikhilvishwakarma00/velune/blob/main/canvas/src/main/kotlin/com/nikhil/yt/canvas/VeluneCanvas.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_app_shell,node_ui_layer,node_viewmodels,node_playback,node_player_bridge,node_local_db,node_preferences,node_lyrics_coord,node_together,node_settings_integrations toneBlue
class node_innertube,node_lyrics_providers,node_betterlyrics,node_lastfm,node_kizzy,node_canvas toneAmber
class node_yt_music,node_lyrics_services,node_android_media toneMint
```

## Components

### App

Android application runtime and orchestration

- [App shell](https://github.com/nikhilvishwakarma00/velune/blob/main/app/src/main/kotlin/com/nikhil/yt/App.kt): android app · Process entry, activity hosting, and top-level app setup · `app/src/main/kotlin/com/nikhil/yt/App.kt`
- [UI layer](https://github.com/nikhilvishwakarma00/velune/blob/main/app/src/main/kotlin/com/nikhil/yt/ui/screens/HomeScreen.kt): compose ui · Declarative screens, reusable components, and navigation · `app/src/main/kotlin/com/nikhil/yt/ui/screens/HomeScreen.kt`
- [ViewModels](https://github.com/nikhilvishwakarma00/velune/blob/main/app/src/main/kotlin/com/nikhil/yt/viewmodels/HomeViewModel.kt): mvvm state · Screen state holders and action coordinators · `app/src/main/kotlin/com/nikhil/yt/viewmodels/HomeViewModel.kt`
- [Playback engine](https://github.com/nikhilvishwakarma00/velune/blob/main/app/src/main/kotlin/com/nikhil/yt/playback/MusicService.kt): media service · Background audio service, session callback, queue, and controls · `app/src/main/kotlin/com/nikhil/yt/playback/MusicService.kt`
- [Player bridge](https://github.com/nikhilvishwakarma00/velune/blob/main/app/src/main/kotlin/com/nikhil/yt/playback/PlayerConnection.kt): session bridge · Connects UI and app logic to the media session and service · `app/src/main/kotlin/com/nikhil/yt/playback/PlayerConnection.kt`
- [Local store](https://github.com/nikhilvishwakarma00/velune/blob/main/app/src/main/kotlin/com/nikhil/yt/db/MusicDatabase.kt): room datastore · Room entities, DAO, and structured playback/library history · `app/src/main/kotlin/com/nikhil/yt/db/MusicDatabase.kt`
- [Preferences](https://github.com/nikhilvishwakarma00/velune/blob/main/app/src/main/kotlin/com/nikhil/yt/utils/DataStore.kt): datastore prefs · App settings and lightweight persisted configuration · `app/src/main/kotlin/com/nikhil/yt/utils/DataStore.kt`
- [Lyrics coord](https://github.com/nikhilvishwakarma00/velune/blob/main/app/src/main/kotlin/com/nikhil/yt/lyrics/LyricsHelper.kt): lyrics orchestration · Provider selection, preload, and playback-synced lyrics lookup · `app/src/main/kotlin/com/nikhil/yt/lyrics/LyricsHelper.kt`
- [Together](https://github.com/nikhilvishwakarma00/velune/blob/main/app/src/main/kotlin/com/nikhil/yt/together/TogetherClient.kt): shared playback · Synchronized listening client, host, and guest planning · `app/src/main/kotlin/com/nikhil/yt/together/TogetherClient.kt`
- [Settings integrations](https://github.com/nikhilvishwakarma00/velune/blob/main/app/src/main/kotlin/com/nikhil/yt/ui/screens/settings/IntegrationScreen.kt): integration ui · Account, Discord, Last.fm, and sync settings surfaces · `app/src/main/kotlin/com/nikhil/yt/ui/screens/settings/IntegrationScreen.kt`

### Core modules

Remote API, lyrics, and integration modules

- [InnerTube](https://github.com/nikhilvishwakarma00/velune/blob/main/innertube/src/main/kotlin/com/nikhil/yt/innertube/InnerTube.kt): yt music api · YouTube Music API client plus page/model adapters · `innertube/src/main/kotlin/com/nikhil/yt/innertube/InnerTube.kt`
- [Lyrics providers](https://github.com/nikhilvishwakarma00/velune/blob/main/lrclib/src/main/kotlin/com/nikhil/yt/lrclib/LrcLib.kt): lyrics adapters · Provider implementations aggregated by the app lyrics layer · `lrclib/src/main/kotlin/com/nikhil/yt/lrclib/LrcLib.kt`
- [BetterLyrics](https://github.com/nikhilvishwakarma00/velune/blob/main/betterlyrics/src/main/kotlin/com/nikhil/yt/betterlyrics/BetterLyrics.kt): ttml parser · Parser and model module for lyric text formats · `betterlyrics/src/main/kotlin/com/nikhil/yt/betterlyrics/BetterLyrics.kt`
- [Last.fm](https://github.com/nikhilvishwakarma00/velune/blob/main/lastfm/src/main/kotlin/com/nikhil/yt/lastfm/LastFM.kt): scrobble auth · Listening-scrobble integration and authentication support · `lastfm/src/main/kotlin/com/nikhil/yt/lastfm/LastFM.kt`
- [Discord RPC](https://github.com/nikhilvishwakarma00/velune/blob/main/kizzy/src/main/kotlin/com/my/kizzy/rpc/KizzyRPC.kt): presence client · Discord presence gateway and RPC plumbing · `kizzy/src/main/kotlin/com/my/kizzy/rpc/KizzyRPC.kt`
- [Canvas](https://github.com/nikhilvishwakarma00/velune/blob/main/canvas/src/main/kotlin/com/nikhil/yt/canvas/VeluneCanvas.kt): rendering module · Custom visual rendering for app artwork or output · `canvas/src/main/kotlin/com/nikhil/yt/canvas/VeluneCanvas.kt`

### External systems

Outside services and platform boundaries

- **YouTube Music**: remote service · Primary remote music catalog, playback, and metadata source
- **Lyrics services**: remote services · Third-party lyrics backends used by the app
- **Android media**: platform · Media3/ExoPlayer, notifications, widgets, and OS media session

## Connections

- App shell → UI layer: hosts · Application bootstraps the Compose UI
- UI layer → ViewModels: observes · Screens render state from ViewModels
- ViewModels → Local store: reads/writes · Persistent library, history, stats, and playlists
- ViewModels → Preferences: reads/writes · Preference state and settings persistence
- ViewModels → InnerTube: loads remote data · Browse, search, page, and playback metadata
- ViewModels → Lyrics coord: requests lyrics · Lyrics state and menu actions
- ViewModels → Together: coordinates · Shared-listening controls and status
- UI layer → Player bridge: sends controls · Player UI invokes playback actions
- Player bridge → Playback engine: controls · Media session commands reach the service
- Playback engine → Android media: uses · Audio engine, session, notifications, and downloads
- Playback engine → Local store: updates history · Playback events feed history, stats, and queue state
- Playback engine → Lyrics coord: publishes timing · Current track position drives lyric sync
- Lyrics coord → Lyrics providers: queries · Aggregates multiple lyrics backends
- Lyrics coord → BetterLyrics: parses · Handles lyric format parsing and transformation
- Lyrics providers → Lyrics services: fetches from · Remote lyrics backends and subtitle/transcript sources
- InnerTube → YouTube Music: calls · Primary remote API boundary for YouTube Music
- Together → Android media: hooks playback · Shared playback overlay follows media state
- Settings integrations → Last.fm: configures · Last.fm account and scrobble settings
- Settings integrations → Discord RPC: configures · Discord presence controls and login flow
- Settings integrations → Together: configures · Music Together settings and session management
- Settings integrations → Local store: manages · Backup, restore, and local content settings
- UI layer → Canvas: renders with · Custom visual output used by app UI
- Playback engine → Canvas: feeds visuals · Playback state can drive rendered artwork
- ViewModels → Last.fm: scrobbles · Listening activity updates external stats
- ViewModels → Discord RPC: updates presence · Discord rich presence reflects current playback