# angorroc/bitchord-x architecture

> Architecture diagram of the GitHub repository angorroc/bitchord-x, 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/angorroc/bitchord-x
- Repository: https://github.com/angorroc/bitchord-x

## Overview

BitChord-X is a cross-platform music player for Android and desktop, with TV and Wear OS companions and a backend supporting presence and shared listening. The main listener workflow is discovering music, resolving it from a selectable source, playing it through a configurable audio pipeline, and optionally saving it offline. Other major capabilities include lyrics and animated artwork, Spotify sync, device handoff, and Listen Together. The tree and excerpts support the main playback, download, and backend structure; several feature links are documented in the README rather than shown in sampled call sites.

Main entry points: [`app/src/main/java/com/music/bitchord/playback/PlaybackService.kt`](https://github.com/angorroc/bitchord-x/blob/main/app/src/main/java/com/music/bitchord/playback/PlaybackService.kt) (Android playback), [`shared/src/jvmSharedMain/kotlin/com/music/bitchord/data/innertube/StreamResolver.kt`](https://github.com/angorroc/bitchord-x/blob/main/shared/src/jvmSharedMain/kotlin/com/music/bitchord/data/innertube/StreamResolver.kt) (Stream resolution), [`backend/main.go`](https://github.com/angorroc/bitchord-x/blob/main/backend/main.go) (Party and presence backend), [`app/src/main/java/com/music/bitchord/MainActivity.kt`](https://github.com/angorroc/bitchord-x/blob/main/app/src/main/java/com/music/bitchord/MainActivity.kt) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["App experience"]
  node_app["App shell<br/>[MainActivity.kt]"]
  node_viewmodel["Main view model<br/>[MainViewModel.kt]"]
  node_settings["Playback settings<br/>[AppSettings.kt]"]
end

subgraph group_catalog["Discovery and sources"]
  node_ytmusic["Music discovery"]
  node_sources["Source registry<br/>[SourceRegistry.kt]"]
  node_stream["Stream resolution<br/>[StreamResolver.kt]"]
  node_lyrics["Lyrics providers<br/>[LyricsQuery.kt]"]
  node_canvas["Animated artwork"]
end

subgraph group_playback["Playback and audio"]
  node_playback["Android playback<br/>[PlaybackService.kt]"]
  node_crossfade["Automix and crossfade"]
  node_audio["Bit-perfect output"]
  node_desktop["Desktop audio engine"]
end

subgraph group_library["Library and downloads"]
  node_cache[("Audio cache<br/>[AudioCache.kt]")]
  node_downloads["Offline downloads<br/>[Downloads.kt]"]
  node_localmedia["Local and network media"]
end

subgraph group_connectivity["Accounts and connection"]
  node_spotify["Spotify sync<br/>[SpotifySync.kt]"]
  node_accounts["Account sign-in<br/>[AccountSessions.kt]"]
  node_party["Listen Together<br/>[ListenTogether.kt]"]
  node_backend["Party and presence backend<br/>[main.go]"]
  node_presence["Presence service<br/>[presence.go]"]
end

node_listener(("Listener"))
node_musicservice{{"YouTube Music"}}
node_device{{"Audio device"}}

node_listener -.->|"uses"| node_app
node_app -.->|"hosts"| node_viewmodel
node_viewmodel -.->|"browses"| node_ytmusic
node_ytmusic -->|"queries"| node_musicservice
node_sources -.->|"resolves streams"| node_stream
node_playback -.->|"plays resolved streams"| node_stream
node_playback -.->|"coordinates transitions"| node_crossfade
node_crossfade -->|"reads settings"| node_settings
node_playback -.->|"outputs audio"| node_audio
node_audio -.->|"routes audio"| node_device
node_desktop -->|"resolves streams"| node_stream
node_downloads -.->|"downloads streams"| node_stream
node_playback -.->|"uses cache"| node_cache
node_listener -.->|"saves tracks"| node_downloads
node_listener -.->|"plays local media"| node_localmedia
node_playback -.->|"shows synced lyrics"| node_lyrics
node_playback -.->|"shows artwork"| node_canvas
node_listener -.->|"imports playlists"| node_spotify
node_listener -.->|"signs in"| node_accounts
node_party -.->|"synchronizes sessions"| node_backend
node_backend -->|"serves party requests"| node_party
node_backend -.->|"records presence"| node_presence

click node_app "https://github.com/angorroc/bitchord-x/blob/main/app/src/main/java/com/music/bitchord/MainActivity.kt"
click node_viewmodel "https://github.com/angorroc/bitchord-x/blob/main/app/src/main/java/com/music/bitchord/ui/MainViewModel.kt"
click node_settings "https://github.com/angorroc/bitchord-x/blob/main/app/src/main/java/com/music/bitchord/data/settings/AppSettings.kt"
click node_ytmusic "https://github.com/angorroc/bitchord-x/blob/main/shared/src/jvmSharedMain/kotlin/com/music/bitchord/data/YtMusicRepository.kt"
click node_sources "https://github.com/angorroc/bitchord-x/blob/main/app/src/main/java/com/music/bitchord/data/sources/SourceRegistry.kt"
click node_stream "https://github.com/angorroc/bitchord-x/blob/main/shared/src/jvmSharedMain/kotlin/com/music/bitchord/data/innertube/StreamResolver.kt"
click node_playback "https://github.com/angorroc/bitchord-x/blob/main/app/src/main/java/com/music/bitchord/playback/PlaybackService.kt"
click node_crossfade "https://github.com/angorroc/bitchord-x/blob/main/app/src/main/java/com/music/bitchord/playback/CrossfadeController.kt"
click node_audio "https://github.com/angorroc/bitchord-x/blob/main/app/src/main/java/com/music/bitchord/playback/audio/bitperfect/BitPerfectOutput.kt"
click node_desktop "https://github.com/angorroc/bitchord-x/blob/main/desktopApp/src/main/kotlin/com/music/bitchord/desktop/DesktopAudioEngine.kt"
click node_cache "https://github.com/angorroc/bitchord-x/blob/main/app/src/main/java/com/music/bitchord/playback/AudioCache.kt"
click node_downloads "https://github.com/angorroc/bitchord-x/blob/main/app/src/main/java/com/music/bitchord/download/Downloads.kt"
click node_localmedia "https://github.com/angorroc/bitchord-x/blob/main/app/src/main/java/com/music/bitchord/data/LocalMediaRepository.kt"
click node_lyrics "https://github.com/angorroc/bitchord-x/blob/main/shared/src/jvmSharedMain/kotlin/com/music/bitchord/data/lyrics/LyricsQuery.kt"
click node_canvas "https://github.com/angorroc/bitchord-x/blob/main/app/src/main/java/com/music/bitchord/data/canvas/CanvasRepository.kt"
click node_spotify "https://github.com/angorroc/bitchord-x/blob/main/app/src/main/java/com/music/bitchord/data/spotify/SpotifySync.kt"
click node_accounts "https://github.com/angorroc/bitchord-x/blob/main/app/src/main/java/com/music/bitchord/auth/AccountSessions.kt"
click node_party "https://github.com/angorroc/bitchord-x/blob/main/app/src/main/java/com/music/bitchord/data/listentogether/ListenTogether.kt"
click node_backend "https://github.com/angorroc/bitchord-x/blob/main/backend/main.go"
click node_presence "https://github.com/angorroc/bitchord-x/blob/main/backend/presence/presence.go"

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,node_viewmodel,node_settings toneBlue
class node_ytmusic,node_sources,node_stream,node_lyrics,node_canvas toneAmber
class node_playback,node_crossfade,node_audio,node_desktop toneMint
class node_cache,node_downloads,node_localmedia toneRose
class node_spotify,node_accounts,node_party,node_backend,node_presence,node_listener,node_musicservice,node_device toneIndigo
```

## Components

### App experience

- [App shell](https://github.com/angorroc/bitchord-x/blob/main/app/src/main/java/com/music/bitchord/MainActivity.kt): `app/src/main/java/com/music/bitchord/MainActivity.kt`
- [Main view model](https://github.com/angorroc/bitchord-x/blob/main/app/src/main/java/com/music/bitchord/ui/MainViewModel.kt): `app/src/main/java/com/music/bitchord/ui/MainViewModel.kt`
- [Playback settings](https://github.com/angorroc/bitchord-x/blob/main/app/src/main/java/com/music/bitchord/data/settings/AppSettings.kt): `app/src/main/java/com/music/bitchord/data/settings/AppSettings.kt`

### Discovery and sources

- [Music discovery](https://github.com/angorroc/bitchord-x/blob/main/shared/src/jvmSharedMain/kotlin/com/music/bitchord/data/YtMusicRepository.kt): `shared/src/jvmSharedMain/kotlin/com/music/bitchord/data/YtMusicRepository.kt`
- [Source registry](https://github.com/angorroc/bitchord-x/blob/main/app/src/main/java/com/music/bitchord/data/sources/SourceRegistry.kt): `app/src/main/java/com/music/bitchord/data/sources/SourceRegistry.kt`
- [Stream resolution](https://github.com/angorroc/bitchord-x/blob/main/shared/src/jvmSharedMain/kotlin/com/music/bitchord/data/innertube/StreamResolver.kt): `shared/src/jvmSharedMain/kotlin/com/music/bitchord/data/innertube/StreamResolver.kt`
- [Lyrics providers](https://github.com/angorroc/bitchord-x/blob/main/shared/src/jvmSharedMain/kotlin/com/music/bitchord/data/lyrics/LyricsQuery.kt): `shared/src/jvmSharedMain/kotlin/com/music/bitchord/data/lyrics/LyricsQuery.kt`
- [Animated artwork](https://github.com/angorroc/bitchord-x/blob/main/app/src/main/java/com/music/bitchord/data/canvas/CanvasRepository.kt): `app/src/main/java/com/music/bitchord/data/canvas/CanvasRepository.kt`

### Playback and audio

- [Android playback](https://github.com/angorroc/bitchord-x/blob/main/app/src/main/java/com/music/bitchord/playback/PlaybackService.kt): `app/src/main/java/com/music/bitchord/playback/PlaybackService.kt`
- [Automix and crossfade](https://github.com/angorroc/bitchord-x/blob/main/app/src/main/java/com/music/bitchord/playback/CrossfadeController.kt): `app/src/main/java/com/music/bitchord/playback/CrossfadeController.kt`
- [Bit-perfect output](https://github.com/angorroc/bitchord-x/blob/main/app/src/main/java/com/music/bitchord/playback/audio/bitperfect/BitPerfectOutput.kt): `app/src/main/java/com/music/bitchord/playback/audio/bitperfect/BitPerfectOutput.kt`
- [Desktop audio engine](https://github.com/angorroc/bitchord-x/blob/main/desktopApp/src/main/kotlin/com/music/bitchord/desktop/DesktopAudioEngine.kt): `desktopApp/src/main/kotlin/com/music/bitchord/desktop/DesktopAudioEngine.kt`

### Library and downloads

- [Audio cache](https://github.com/angorroc/bitchord-x/blob/main/app/src/main/java/com/music/bitchord/playback/AudioCache.kt): `app/src/main/java/com/music/bitchord/playback/AudioCache.kt`
- [Offline downloads](https://github.com/angorroc/bitchord-x/blob/main/app/src/main/java/com/music/bitchord/download/Downloads.kt): `app/src/main/java/com/music/bitchord/download/Downloads.kt`
- [Local and network media](https://github.com/angorroc/bitchord-x/blob/main/app/src/main/java/com/music/bitchord/data/LocalMediaRepository.kt): `app/src/main/java/com/music/bitchord/data/LocalMediaRepository.kt`

### Accounts and connection

- [Spotify sync](https://github.com/angorroc/bitchord-x/blob/main/app/src/main/java/com/music/bitchord/data/spotify/SpotifySync.kt): `app/src/main/java/com/music/bitchord/data/spotify/SpotifySync.kt`
- [Account sign-in](https://github.com/angorroc/bitchord-x/blob/main/app/src/main/java/com/music/bitchord/auth/AccountSessions.kt): `app/src/main/java/com/music/bitchord/auth/AccountSessions.kt`
- [Listen Together](https://github.com/angorroc/bitchord-x/blob/main/app/src/main/java/com/music/bitchord/data/listentogether/ListenTogether.kt): `app/src/main/java/com/music/bitchord/data/listentogether/ListenTogether.kt`
- [Party and presence backend](https://github.com/angorroc/bitchord-x/blob/main/backend/main.go): `backend/main.go`
- [Presence service](https://github.com/angorroc/bitchord-x/blob/main/backend/presence/presence.go): `backend/presence/presence.go`

### Other components

- **Listener**
- **YouTube Music**
- **Audio device**

## Connections

- Listener → App shell: uses
- App shell → Main view model: hosts
- Main view model → Music discovery: browses
- Music discovery → YouTube Music: queries (evidence: `shared/src/jvmSharedMain/kotlin/com/music/bitchord/data/YtMusicRepository.kt`)
- Source registry → Stream resolution: resolves streams
- Android playback → Stream resolution: plays resolved streams
- Android playback → Automix and crossfade: coordinates transitions
- Automix and crossfade → Playback settings: reads settings (evidence: `app/src/main/java/com/music/bitchord/playback/CrossfadeController.kt`)
- Android playback → Bit-perfect output: outputs audio
- Bit-perfect output → Audio device: routes audio
- Desktop audio engine → Stream resolution: resolves streams (evidence: `desktopApp/src/main/kotlin/com/music/bitchord/desktop/DesktopAudioEngine.kt`)
- Offline downloads → Stream resolution: downloads streams
- Android playback → Audio cache: uses cache
- Listener → Offline downloads: saves tracks
- Listener → Local and network media: plays local media
- Android playback → Lyrics providers: shows synced lyrics
- Android playback → Animated artwork: shows artwork
- Listener → Spotify sync: imports playlists
- Listener → Account sign-in: signs in
- Listen Together → Party and presence backend: synchronizes sessions
- Party and presence backend → Listen Together: serves party requests (evidence: `backend/main.go`)
- Party and presence backend → Presence service: records presence
