# dhruvesh07/echomusic-desktop architecture

> Architecture diagram of the GitHub repository dhruvesh07/echomusic-desktop, 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/dhruvesh07/echomusic-desktop
- Repository: https://github.com/dhruvesh07/echomusic-desktop

## Overview

Echo Music Desktop is a Windows music-streaming client centered on discovering YouTube Music content and playing it through a desktop player. The main workflow runs from the desktop shell and search/home/library screens through the repository and Innertube API, then into queue management, stream resolution, and FFmpeg audio or video playback. Local playlists, listening history, taste-based recommendations, and lyrics are supporting product branches. The README documents additional UI and playback capabilities; some implementation paths are unsampled, so those relationships are shown only where documented.

Main entry points: [`desktop/src/main/kotlin/echo/music/desktop/playback/Playback.kt`](https://github.com/dhruvesh07/echomusic-desktop/blob/main/desktop/src/main/kotlin/echo/music/desktop/playback/Playback.kt) (Queue and playback), [`desktop/src/main/kotlin/echo/music/desktop/Main.kt`](https://github.com/dhruvesh07/echomusic-desktop/blob/main/desktop/src/main/kotlin/echo/music/desktop/Main.kt) (App shell), [`innertube/src/main/kotlin/com/music/innertube/YouTube.kt`](https://github.com/dhruvesh07/echomusic-desktop/blob/main/innertube/src/main/kotlin/com/music/innertube/YouTube.kt) (YouTube facade), [`desktop/src/main/kotlin/echo/music/desktop/data/YouTubeRepository.kt`](https://github.com/dhruvesh07/echomusic-desktop/blob/main/desktop/src/main/kotlin/echo/music/desktop/data/YouTubeRepository.kt) (YouTube repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Desktop experience"]
  node_shell["App shell<br/>[Main.kt]"]
  node_home["Home screen<br/>[HomeScreen.kt]"]
  node_search["Search screen<br/>[SearchScreen.kt]"]
  node_library["Library screen<br/>[LibraryScreen.kt]"]
  node_playerui["Player views<br/>[FullPlayer.kt]"]
end

subgraph group_catalog["Catalog and domain"]
  node_repo["YouTube repository"]
  node_youtube["YouTube facade<br/>[YouTube.kt]"]
  node_ytitems["Catalog items<br/>[YTItem.kt]"]
  node_searchpages["Search parsing"]
  node_song["Song model<br/>[Song.kt]"]
end

subgraph group_playback["Playback"]
  node_playback["Queue and playback<br/>[Playback.kt]"]
  node_resolver["Stream resolver<br/>[StreamResolver.kt]"]
  node_audio["Audio engine<br/>[FfmpegPlayer.kt]"]
  node_video["Video engine<br/>[VideoEngine.kt]"]
end

subgraph group_personal["Personalization"]
  node_history["Play history<br/>[PlayHistory.kt]"]
  node_taste["Taste model<br/>[TasteModel.kt]"]
  node_recommendations["Recommendations<br/>[Recommendations.kt]"]
  node_playlists["Local playlists<br/>[Playlists.kt]"]
  node_localstore[("Local state")]
end

subgraph group_lyrics["Lyrics"]
  node_lyricsservice["Lyrics service"]
  node_lyricsproviders["Lyrics providers<br/>[BetterLyrics.kt]"]
end

node_listener(("Listener"))
node_ffmpeg["FFmpeg"]

node_listener -->|"opens"| node_shell
node_shell -->|"shows"| node_home
node_shell -->|"shows"| node_search
node_shell -->|"shows"| node_library
node_shell -->|"shows"| node_playerui
node_search -->|"searches"| node_repo
node_home -.->|"loads content"| node_repo
node_library -.->|"loads content"| node_repo
node_repo -->|"requests content"| node_youtube
node_youtube -->|"returns items"| node_ytitems
node_youtube -->|"parses results"| node_searchpages
node_search -->|"records query"| node_taste
node_playerui -.->|"controls"| node_playback
node_playback -->|"loads playback data"| node_youtube
node_playback -->|"resolves stream"| node_resolver
node_playback -->|"starts audio"| node_audio
node_playback -.->|"starts video"| node_video
node_video -->|"uses resolved stream"| node_resolver
node_audio -.->|"decodes audio"| node_ffmpeg
node_video -->|"decodes video"| node_ffmpeg
node_playback -->|"records plays"| node_history
node_playback -->|"records starts"| node_taste
node_taste -.->|"informs picks"| node_recommendations
node_library -.->|"manages"| node_playlists
node_playback -.->|"plays selections"| node_playlists
node_playback -.->|"looks up lyrics"| node_lyricsservice
node_lyricsservice -->|"queries providers"| node_lyricsproviders
node_history -.->|"persists locally"| node_localstore
node_playlists -.->|"persists locally"| node_localstore
node_recommendations -.->|"uses local data"| node_localstore

click node_shell "https://github.com/dhruvesh07/echomusic-desktop/blob/main/desktop/src/main/kotlin/echo/music/desktop/Main.kt"
click node_home "https://github.com/dhruvesh07/echomusic-desktop/blob/main/desktop/src/main/kotlin/echo/music/desktop/ui/HomeScreen.kt"
click node_search "https://github.com/dhruvesh07/echomusic-desktop/blob/main/desktop/src/main/kotlin/echo/music/desktop/ui/SearchScreen.kt"
click node_library "https://github.com/dhruvesh07/echomusic-desktop/blob/main/desktop/src/main/kotlin/echo/music/desktop/ui/LibraryScreen.kt"
click node_playerui "https://github.com/dhruvesh07/echomusic-desktop/blob/main/desktop/src/main/kotlin/echo/music/desktop/ui/player/FullPlayer.kt"
click node_repo "https://github.com/dhruvesh07/echomusic-desktop/blob/main/desktop/src/main/kotlin/echo/music/desktop/data/YouTubeRepository.kt"
click node_youtube "https://github.com/dhruvesh07/echomusic-desktop/blob/main/innertube/src/main/kotlin/com/music/innertube/YouTube.kt"
click node_ytitems "https://github.com/dhruvesh07/echomusic-desktop/blob/main/innertube/src/main/kotlin/com/music/innertube/models/YTItem.kt"
click node_searchpages "https://github.com/dhruvesh07/echomusic-desktop/blob/main/innertube/src/main/kotlin/com/music/innertube/pages/SearchSummaryPage.kt"
click node_song "https://github.com/dhruvesh07/echomusic-desktop/blob/main/domain/src/main/kotlin/echo/music/domain/models/Song.kt"
click node_playback "https://github.com/dhruvesh07/echomusic-desktop/blob/main/desktop/src/main/kotlin/echo/music/desktop/playback/Playback.kt"
click node_resolver "https://github.com/dhruvesh07/echomusic-desktop/blob/main/desktop/src/main/kotlin/echo/music/desktop/playback/StreamResolver.kt"
click node_audio "https://github.com/dhruvesh07/echomusic-desktop/blob/main/desktop/src/main/kotlin/echo/music/desktop/playback/FfmpegPlayer.kt"
click node_video "https://github.com/dhruvesh07/echomusic-desktop/blob/main/desktop/src/main/kotlin/echo/music/desktop/playback/VideoEngine.kt"
click node_history "https://github.com/dhruvesh07/echomusic-desktop/blob/main/desktop/src/main/kotlin/echo/music/desktop/data/PlayHistory.kt"
click node_taste "https://github.com/dhruvesh07/echomusic-desktop/blob/main/desktop/src/main/kotlin/echo/music/desktop/data/TasteModel.kt"
click node_recommendations "https://github.com/dhruvesh07/echomusic-desktop/blob/main/desktop/src/main/kotlin/echo/music/desktop/data/Recommendations.kt"
click node_playlists "https://github.com/dhruvesh07/echomusic-desktop/blob/main/desktop/src/main/kotlin/echo/music/desktop/data/Playlists.kt"
click node_lyricsservice "https://github.com/dhruvesh07/echomusic-desktop/blob/main/desktop/src/main/kotlin/echo/music/desktop/lyrics/DesktopLyricsService.kt"
click node_lyricsproviders "https://github.com/dhruvesh07/echomusic-desktop/blob/main/betterlyrics/src/main/kotlin/com/music/echo/betterlyrics/BetterLyrics.kt"
click node_localstore "https://github.com/dhruvesh07/echomusic-desktop/tree/main/desktop/src/main/kotlin/echo/music/desktop/data"

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_shell,node_home,node_search,node_library,node_playerui toneBlue
class node_repo,node_youtube,node_ytitems,node_searchpages,node_song toneAmber
class node_playback,node_resolver,node_audio,node_video toneMint
class node_history,node_taste,node_recommendations,node_playlists,node_localstore toneRose
class node_lyricsservice,node_lyricsproviders,node_listener,node_ffmpeg toneIndigo
```

## Components

### Desktop experience

- [App shell](https://github.com/dhruvesh07/echomusic-desktop/blob/main/desktop/src/main/kotlin/echo/music/desktop/Main.kt): `desktop/src/main/kotlin/echo/music/desktop/Main.kt`
- [Home screen](https://github.com/dhruvesh07/echomusic-desktop/blob/main/desktop/src/main/kotlin/echo/music/desktop/ui/HomeScreen.kt): `desktop/src/main/kotlin/echo/music/desktop/ui/HomeScreen.kt`
- [Search screen](https://github.com/dhruvesh07/echomusic-desktop/blob/main/desktop/src/main/kotlin/echo/music/desktop/ui/SearchScreen.kt): `desktop/src/main/kotlin/echo/music/desktop/ui/SearchScreen.kt`
- [Library screen](https://github.com/dhruvesh07/echomusic-desktop/blob/main/desktop/src/main/kotlin/echo/music/desktop/ui/LibraryScreen.kt): `desktop/src/main/kotlin/echo/music/desktop/ui/LibraryScreen.kt`
- [Player views](https://github.com/dhruvesh07/echomusic-desktop/blob/main/desktop/src/main/kotlin/echo/music/desktop/ui/player/FullPlayer.kt): `desktop/src/main/kotlin/echo/music/desktop/ui/player/FullPlayer.kt`

### Catalog and domain

- [YouTube repository](https://github.com/dhruvesh07/echomusic-desktop/blob/main/desktop/src/main/kotlin/echo/music/desktop/data/YouTubeRepository.kt): `desktop/src/main/kotlin/echo/music/desktop/data/YouTubeRepository.kt`
- [YouTube facade](https://github.com/dhruvesh07/echomusic-desktop/blob/main/innertube/src/main/kotlin/com/music/innertube/YouTube.kt): `innertube/src/main/kotlin/com/music/innertube/YouTube.kt`
- [Catalog items](https://github.com/dhruvesh07/echomusic-desktop/blob/main/innertube/src/main/kotlin/com/music/innertube/models/YTItem.kt): `innertube/src/main/kotlin/com/music/innertube/models/YTItem.kt`
- [Search parsing](https://github.com/dhruvesh07/echomusic-desktop/blob/main/innertube/src/main/kotlin/com/music/innertube/pages/SearchSummaryPage.kt): `innertube/src/main/kotlin/com/music/innertube/pages/SearchSummaryPage.kt`
- [Song model](https://github.com/dhruvesh07/echomusic-desktop/blob/main/domain/src/main/kotlin/echo/music/domain/models/Song.kt): `domain/src/main/kotlin/echo/music/domain/models/Song.kt`

### Playback

- [Queue and playback](https://github.com/dhruvesh07/echomusic-desktop/blob/main/desktop/src/main/kotlin/echo/music/desktop/playback/Playback.kt): `desktop/src/main/kotlin/echo/music/desktop/playback/Playback.kt`
- [Stream resolver](https://github.com/dhruvesh07/echomusic-desktop/blob/main/desktop/src/main/kotlin/echo/music/desktop/playback/StreamResolver.kt): `desktop/src/main/kotlin/echo/music/desktop/playback/StreamResolver.kt`
- [Audio engine](https://github.com/dhruvesh07/echomusic-desktop/blob/main/desktop/src/main/kotlin/echo/music/desktop/playback/FfmpegPlayer.kt): `desktop/src/main/kotlin/echo/music/desktop/playback/FfmpegPlayer.kt`
- [Video engine](https://github.com/dhruvesh07/echomusic-desktop/blob/main/desktop/src/main/kotlin/echo/music/desktop/playback/VideoEngine.kt): `desktop/src/main/kotlin/echo/music/desktop/playback/VideoEngine.kt`

### Personalization

- [Play history](https://github.com/dhruvesh07/echomusic-desktop/blob/main/desktop/src/main/kotlin/echo/music/desktop/data/PlayHistory.kt): `desktop/src/main/kotlin/echo/music/desktop/data/PlayHistory.kt`
- [Taste model](https://github.com/dhruvesh07/echomusic-desktop/blob/main/desktop/src/main/kotlin/echo/music/desktop/data/TasteModel.kt): `desktop/src/main/kotlin/echo/music/desktop/data/TasteModel.kt`
- [Recommendations](https://github.com/dhruvesh07/echomusic-desktop/blob/main/desktop/src/main/kotlin/echo/music/desktop/data/Recommendations.kt): `desktop/src/main/kotlin/echo/music/desktop/data/Recommendations.kt`
- [Local playlists](https://github.com/dhruvesh07/echomusic-desktop/blob/main/desktop/src/main/kotlin/echo/music/desktop/data/Playlists.kt): `desktop/src/main/kotlin/echo/music/desktop/data/Playlists.kt`
- [Local state](https://github.com/dhruvesh07/echomusic-desktop/tree/main/desktop/src/main/kotlin/echo/music/desktop/data): `desktop/src/main/kotlin/echo/music/desktop/data`

### Lyrics

- [Lyrics service](https://github.com/dhruvesh07/echomusic-desktop/blob/main/desktop/src/main/kotlin/echo/music/desktop/lyrics/DesktopLyricsService.kt): `desktop/src/main/kotlin/echo/music/desktop/lyrics/DesktopLyricsService.kt`
- [Lyrics providers](https://github.com/dhruvesh07/echomusic-desktop/blob/main/betterlyrics/src/main/kotlin/com/music/echo/betterlyrics/BetterLyrics.kt): `betterlyrics/src/main/kotlin/com/music/echo/betterlyrics/BetterLyrics.kt`

### Other components

- **Listener**
- **FFmpeg**

## Connections

- Listener → App shell: opens (evidence: `README.md`)
- App shell → Home screen: shows (evidence: `desktop/src/main/kotlin/echo/music/desktop/Main.kt`)
- App shell → Search screen: shows (evidence: `desktop/src/main/kotlin/echo/music/desktop/Main.kt`)
- App shell → Library screen: shows (evidence: `desktop/src/main/kotlin/echo/music/desktop/Main.kt`)
- App shell → Player views: shows (evidence: `desktop/src/main/kotlin/echo/music/desktop/Main.kt`)
- Search screen → YouTube repository: searches (evidence: `desktop/src/main/kotlin/echo/music/desktop/ui/SearchScreen.kt`)
- Home screen → YouTube repository: loads content (evidence: `desktop/src/main/kotlin/echo/music/desktop/ui/HomeScreen.kt`)
- Library screen → YouTube repository: loads content
- YouTube repository → YouTube facade: requests content (evidence: `desktop/src/main/kotlin/echo/music/desktop/data/YouTubeRepository.kt`)
- YouTube facade → Catalog items: returns items (evidence: `innertube/src/main/kotlin/com/music/innertube/models/YTItem.kt`)
- YouTube facade → Search parsing: parses results (evidence: `innertube/src/main/kotlin/com/music/innertube/pages/SearchSummaryPage.kt`)
- Search screen → Taste model: records query (evidence: `desktop/src/main/kotlin/echo/music/desktop/ui/SearchScreen.kt`)
- Player views → Queue and playback: controls (evidence: `desktop/src/main/kotlin/echo/music/desktop/ui/player/FullPlayer.kt`)
- Queue and playback → YouTube facade: loads playback data (evidence: `desktop/src/main/kotlin/echo/music/desktop/playback/Playback.kt`)
- Queue and playback → Stream resolver: resolves stream (evidence: `desktop/src/main/kotlin/echo/music/desktop/playback/Playback.kt`)
- Queue and playback → Audio engine: starts audio (evidence: `desktop/src/main/kotlin/echo/music/desktop/playback/Playback.kt`)
- Queue and playback → Video engine: starts video (evidence: `desktop/src/main/kotlin/echo/music/desktop/playback/Playback.kt`)
- Video engine → Stream resolver: uses resolved stream (evidence: `desktop/src/main/kotlin/echo/music/desktop/playback/VideoEngine.kt`)
- Audio engine → FFmpeg: decodes audio
- Video engine → FFmpeg: decodes video (evidence: `desktop/src/main/kotlin/echo/music/desktop/playback/VideoEngine.kt`)
- Queue and playback → Play history: records plays (evidence: `desktop/src/main/kotlin/echo/music/desktop/playback/Playback.kt`)
- Queue and playback → Taste model: records starts (evidence: `desktop/src/main/kotlin/echo/music/desktop/playback/Playback.kt`)
- Taste model → Recommendations: informs picks (evidence: `desktop/src/main/kotlin/echo/music/desktop/data/TasteModel.kt`)
- Library screen → Local playlists: manages (evidence: `desktop/src/main/kotlin/echo/music/desktop/ui/LibraryScreen.kt`)
- Queue and playback → Local playlists: plays selections
- Queue and playback → Lyrics service: looks up lyrics
- Lyrics service → Lyrics providers: queries providers (evidence: `desktop/src/main/kotlin/echo/music/desktop/lyrics/DesktopLyricsService.kt`)
- Play history → Local state: persists locally (evidence: `desktop/src/main/kotlin/echo/music/desktop/data/TasteModel.kt`)
- Local playlists → Local state: persists locally
- Recommendations → Local state: uses local data (evidence: `desktop/src/main/kotlin/echo/music/desktop/data/TasteModel.kt`)
