# grapedjuice/ytm-rs architecture

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

- Interactive diagram: https://gitdiagram.com/grapedjuice/ytm-rs
- Repository: https://github.com/grapedjuice/ytm-rs

## Overview

ytm-rs is a native YouTube Music desktop player. The main workflow is browsing or searching music, selecting tracks, resolving and streaming audio, then controlling playback in the app. The graph also preserves documented capabilities for lyrics and visual themes, downloads, Spotify transfer, listening together, scrobbling, and desktop controls. Edges use README statements or SOURCE INDEX references; several feature modules were not sampled, so their internal call paths are not asserted.

Main entry points: [`src/ui/nowplaying.rs`](https://github.com/grapedjuice/ytm-rs/blob/main/src/ui/nowplaying.rs) (Now playing), [`src/backend.rs`](https://github.com/grapedjuice/ytm-rs/blob/main/src/backend.rs) (Network backend), [`src/ytm.rs`](https://github.com/grapedjuice/ytm-rs/blob/main/src/ytm.rs) (Music catalog), [`src/ui/shell.rs`](https://github.com/grapedjuice/ytm-rs/blob/main/src/ui/shell.rs) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Desktop experience"]
  node_shell["App shell<br/>[shell.rs]"]
  node_pages["Music pages<br/>[pages.rs]"]
  node_nowplaying["Now playing<br/>[nowplaying.rs]"]
  node_widgets["UI widgets<br/>[widgets.rs]"]
end

subgraph group_catalog["Music and network"]
  node_backend["Network backend<br/>[backend.rs]"]
  node_ytm["Music catalog<br/>[ytm.rs]"]
  node_ytmapi["YouTube API<br/>[ytmapi.rs]"]
  node_model["Music data<br/>[model.rs]"]
end

subgraph group_playback["Playback and media"]
  node_stream["Stream resolver<br/>[stream.rs]"]
  node_audio["Audio engine<br/>[audio.rs]"]
  node_downloads["Downloads<br/>[downloads.rs]"]
end

subgraph group_personal["Personalization"]
  node_lyrics["Lyrics<br/>[lyrics.rs]"]
  node_karaoke["Karaoke display<br/>[karaoke.rs]"]
  node_themes["Theme presets<br/>[preset.rs]"]
  node_theme["Visual styling<br/>[theme.rs]"]
  node_backdrop["Animated backdrop<br/>[shader.rs]"]
end

subgraph group_community["Sharing and integrations"]
  node_transfer["Spotify transfer<br/>[mod.rs]"]
  node_jam["Listen together<br/>[jam.rs]"]
  node_lastfm["Last.fm scrobbling<br/>[lastfm.rs]"]
  node_listenbrainz["ListenBrainz<br/>[listenbrainz.rs]"]
  node_discord["Discord presence<br/>[discord.rs]"]
end

node_listener(("Listener"))
node_youtube{{"YouTube Music"}}
node_spotify{{"Spotify"}}

node_listener -->|"uses"| node_shell
node_shell -->|"shows pages"| node_pages
node_listener -->|"browses music"| node_pages
node_pages -->|"requests music"| node_backend
node_backend -->|"dispatches catalog work"| node_ytm
node_ytm -->|"uses API transport"| node_ytmapi
node_ytmapi -->|"fetches music data"| node_youtube
node_ytm -->|"parses into"| node_model
node_backend -->|"resolves streams"| node_stream
node_backend -->|"hands off decoder"| node_audio
node_listener -->|"controls playback"| node_nowplaying
node_nowplaying -->|"requests playback"| node_backend
node_nowplaying -->|"shows synced lyrics"| node_lyrics
node_nowplaying -->|"renders lyrics"| node_karaoke
node_karaoke -->|"reads lyric styles"| node_themes
node_themes -->|"provides design tokens"| node_theme
node_shell -->|"uses widgets"| node_widgets
node_nowplaying -->|"draws animated art"| node_backdrop
node_listener -->|"saves songs"| node_downloads
node_downloads -->|"saves best-quality audio"| node_stream
node_listener -->|"starts transfer"| node_transfer
node_transfer -->|"reads playlists"| node_spotify
node_transfer -->|"searches and creates playlist"| node_ytm
node_listener -->|"starts a jam"| node_jam
node_listener -->|"connects account"| node_lastfm
node_listener -->|"connects account"| node_listenbrainz
node_listener -->|"connects presence"| node_discord

click node_shell "https://github.com/grapedjuice/ytm-rs/blob/main/src/ui/shell.rs"
click node_pages "https://github.com/grapedjuice/ytm-rs/blob/main/src/ui/pages.rs"
click node_nowplaying "https://github.com/grapedjuice/ytm-rs/blob/main/src/ui/nowplaying.rs"
click node_widgets "https://github.com/grapedjuice/ytm-rs/blob/main/src/ui/widgets.rs"
click node_backend "https://github.com/grapedjuice/ytm-rs/blob/main/src/backend.rs"
click node_ytm "https://github.com/grapedjuice/ytm-rs/blob/main/src/ytm.rs"
click node_ytmapi "https://github.com/grapedjuice/ytm-rs/blob/main/src/ytmapi.rs"
click node_model "https://github.com/grapedjuice/ytm-rs/blob/main/src/model.rs"
click node_stream "https://github.com/grapedjuice/ytm-rs/blob/main/src/stream.rs"
click node_audio "https://github.com/grapedjuice/ytm-rs/blob/main/src/audio.rs"
click node_downloads "https://github.com/grapedjuice/ytm-rs/blob/main/src/downloads.rs"
click node_lyrics "https://github.com/grapedjuice/ytm-rs/blob/main/src/lyrics.rs"
click node_karaoke "https://github.com/grapedjuice/ytm-rs/blob/main/src/ui/karaoke.rs"
click node_themes "https://github.com/grapedjuice/ytm-rs/blob/main/src/preset.rs"
click node_theme "https://github.com/grapedjuice/ytm-rs/blob/main/src/theme.rs"
click node_backdrop "https://github.com/grapedjuice/ytm-rs/blob/main/src/shader.rs"
click node_transfer "https://github.com/grapedjuice/ytm-rs/blob/main/src/transfer/mod.rs"
click node_jam "https://github.com/grapedjuice/ytm-rs/blob/main/src/jam.rs"
click node_lastfm "https://github.com/grapedjuice/ytm-rs/blob/main/src/lastfm.rs"
click node_listenbrainz "https://github.com/grapedjuice/ytm-rs/blob/main/src/listenbrainz.rs"
click node_discord "https://github.com/grapedjuice/ytm-rs/blob/main/src/discord.rs"

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_pages,node_nowplaying,node_widgets toneBlue
class node_backend,node_ytm,node_ytmapi,node_model toneAmber
class node_stream,node_audio,node_downloads toneMint
class node_lyrics,node_karaoke,node_themes,node_theme,node_backdrop toneRose
class node_transfer,node_jam,node_lastfm,node_listenbrainz,node_discord,node_listener,node_youtube,node_spotify toneIndigo
```

## Components

### Desktop experience

- [App shell](https://github.com/grapedjuice/ytm-rs/blob/main/src/ui/shell.rs): `src/ui/shell.rs`
- [Music pages](https://github.com/grapedjuice/ytm-rs/blob/main/src/ui/pages.rs): `src/ui/pages.rs`
- [Now playing](https://github.com/grapedjuice/ytm-rs/blob/main/src/ui/nowplaying.rs): `src/ui/nowplaying.rs`
- [UI widgets](https://github.com/grapedjuice/ytm-rs/blob/main/src/ui/widgets.rs): `src/ui/widgets.rs`

### Music and network

- [Network backend](https://github.com/grapedjuice/ytm-rs/blob/main/src/backend.rs): `src/backend.rs`
- [Music catalog](https://github.com/grapedjuice/ytm-rs/blob/main/src/ytm.rs): `src/ytm.rs`
- [YouTube API](https://github.com/grapedjuice/ytm-rs/blob/main/src/ytmapi.rs): `src/ytmapi.rs`
- [Music data](https://github.com/grapedjuice/ytm-rs/blob/main/src/model.rs): `src/model.rs`

### Playback and media

- [Stream resolver](https://github.com/grapedjuice/ytm-rs/blob/main/src/stream.rs): `src/stream.rs`
- [Audio engine](https://github.com/grapedjuice/ytm-rs/blob/main/src/audio.rs): `src/audio.rs`
- [Downloads](https://github.com/grapedjuice/ytm-rs/blob/main/src/downloads.rs): `src/downloads.rs`

### Personalization

- [Lyrics](https://github.com/grapedjuice/ytm-rs/blob/main/src/lyrics.rs): `src/lyrics.rs`
- [Karaoke display](https://github.com/grapedjuice/ytm-rs/blob/main/src/ui/karaoke.rs): `src/ui/karaoke.rs`
- [Theme presets](https://github.com/grapedjuice/ytm-rs/blob/main/src/preset.rs): `src/preset.rs`
- [Visual styling](https://github.com/grapedjuice/ytm-rs/blob/main/src/theme.rs): `src/theme.rs`
- [Animated backdrop](https://github.com/grapedjuice/ytm-rs/blob/main/src/shader.rs): `src/shader.rs`

### Sharing and integrations

- [Spotify transfer](https://github.com/grapedjuice/ytm-rs/blob/main/src/transfer/mod.rs): `src/transfer/mod.rs`
- [Listen together](https://github.com/grapedjuice/ytm-rs/blob/main/src/jam.rs): `src/jam.rs`
- [Last.fm scrobbling](https://github.com/grapedjuice/ytm-rs/blob/main/src/lastfm.rs): `src/lastfm.rs`
- [ListenBrainz](https://github.com/grapedjuice/ytm-rs/blob/main/src/listenbrainz.rs): `src/listenbrainz.rs`
- [Discord presence](https://github.com/grapedjuice/ytm-rs/blob/main/src/discord.rs): `src/discord.rs`

### Other components

- **Listener**
- **YouTube Music**
- **Spotify**

## Connections

- Listener → App shell: uses (evidence: `README.md`)
- App shell → Music pages: shows pages (evidence: `src/ui/shell.rs`)
- Listener → Music pages: browses music (evidence: `README.md`)
- Music pages → Network backend: requests music (evidence: `README.md`)
- Network backend → Music catalog: dispatches catalog work (evidence: `src/backend.rs`)
- Music catalog → YouTube API: uses API transport (evidence: `src/ytm.rs`)
- YouTube API → YouTube Music: fetches music data (evidence: `README.md`)
- Music catalog → Music data: parses into (evidence: `src/ytm.rs`)
- Network backend → Stream resolver: resolves streams (evidence: `src/backend.rs`)
- Network backend → Audio engine: hands off decoder (evidence: `src/backend.rs`)
- Listener → Now playing: controls playback (evidence: `README.md`)
- Now playing → Network backend: requests playback (evidence: `README.md`)
- Now playing → Lyrics: shows synced lyrics (evidence: `src/ui/nowplaying.rs`)
- Now playing → Karaoke display: renders lyrics (evidence: `src/ui/nowplaying.rs`)
- Karaoke display → Theme presets: reads lyric styles (evidence: `src/ui/karaoke.rs`)
- Theme presets → Visual styling: provides design tokens (evidence: `src/theme.rs`)
- App shell → UI widgets: uses widgets (evidence: `src/ui/shell.rs`)
- Now playing → Animated backdrop: draws animated art (evidence: `README.md`)
- Listener → Downloads: saves songs (evidence: `README.md`)
- Downloads → Stream resolver: saves best-quality audio (evidence: `src/downloads.rs`)
- Listener → Spotify transfer: starts transfer (evidence: `README.md`)
- Spotify transfer → Spotify: reads playlists (evidence: `README.md`)
- Spotify transfer → Music catalog: searches and creates playlist (evidence: `src/transfer/mod.rs`)
- Listener → Listen together: starts a jam (evidence: `README.md`)
- Listener → Last.fm scrobbling: connects account (evidence: `README.md`)
- Listener → ListenBrainz: connects account (evidence: `README.md`)
- Listener → Discord presence: connects presence (evidence: `README.md`)
