# chenqi92/primuse architecture

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

- Interactive diagram: https://gitdiagram.com/chenqi92/primuse
- Repository: https://github.com/chenqi92/primuse

## Overview

Primuse is a native Apple-ecosystem music player that unifies local and remote music sources in a shared library and playback queue. Its principal workflow is to connect or import a source, browse or search its catalog, resolve a playable item, and play it with format-aware decoding and system controls. The product also includes radio, recommendations, lyrics and metadata tooling, synchronization, and companion experiences across Apple platforms. Several important modules are named in the source index but were not excerpted; their internals and call relationships are therefore not inferred here.

Main entry points: [`PrimuseTV/App.swift`](https://github.com/chenqi92/primuse/blob/main/PrimuseTV/App.swift) (Primuse apps), [`Primuse/Services/Library/MusicLibrary.swift`](https://github.com/chenqi92/primuse/blob/main/Primuse/Services/Library/MusicLibrary.swift) (Music library), [`PrimuseKit/Sources/PrimuseKit/Models/MusicSource.swift`](https://github.com/chenqi92/primuse/blob/main/PrimuseKit/Sources/PrimuseKit/Models/MusicSource.swift) (Music sources), [`PrimuseTV/Audio/TVAudioEngine.swift`](https://github.com/chenqi92/primuse/blob/main/PrimuseTV/Audio/TVAudioEngine.swift) (TV audio engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sources["Sources and library"]
  node_source_catalog["Music sources<br/>[MusicSource.swift]"]
  node_source_resolver["Stream resolution"]
  node_library[("Music library<br/>[MusicLibrary.swift]")]
  node_song_model["Song model<br/>[Song.swift]"]
  node_credential_store[("Credential storage")]
  node_cloud_sync["Cloud sync"]
  node_apple_music["Apple Music"]
end

subgraph group_playback["Playback and audio"]
  node_audio_engine["Audio engine<br/>[AudioEngine.swift]"]
  node_tv_audio["TV audio engine"]
  node_tv_sfb["TV format fallback<br/>[TVSFBEngine.swift]"]
  node_audio_formats["Format support<br/>[AudioFormat.swift]"]
  node_radio["Radio playback"]
end

subgraph group_discovery["Discovery and lyrics"]
  node_smart_playlists["Smart playlists"]
  node_music_intelligence["Music intelligence"]
  node_metadata_scraper["Metadata scraping"]
  node_lyrics["Lyrics model<br/>[LyricLine.swift]"]
  node_lyrics_translation["Lyrics translation"]
end

subgraph group_platforms["Apple experiences"]
  node_app["Primuse apps<br/>[App.swift]"]
  node_watch["Watch controls"]
  node_widgets["Now playing widgets"]
  node_mac_desktop["Mac desktop tools"]
  node_relay["Share relay<br/>[main.go]"]
end

node_listener(("Listener"))

node_listener -->|"uses"| node_app
node_app -->|"connects sources"| node_source_catalog
node_source_catalog -->|"feeds catalog"| node_library
node_library -->|"stores songs"| node_song_model
node_library -->|"resolves streams"| node_source_resolver
node_source_resolver -->|"uses credentials"| node_credential_store
node_library -->|"syncs library"| node_cloud_sync
node_app -->|"plays audio"| node_audio_engine
node_app -->|"plays on TV"| node_tv_audio
node_tv_audio -->|"decodes fallback"| node_tv_sfb
node_tv_audio -->|"selects formats"| node_audio_formats
node_app -->|"plays radio"| node_radio
node_library -->|"builds playlists"| node_smart_playlists
node_app -->|"offers recommendations"| node_music_intelligence
node_app -->|"scrapes metadata"| node_metadata_scraper
node_app -->|"displays lyrics"| node_lyrics
node_lyrics -->|"translates lyrics"| node_lyrics_translation
node_source_catalog -->|"includes source"| node_apple_music
node_app -->|"supports remote control"| node_watch
node_app -->|"provides widgets"| node_widgets
node_app -->|"offers desktop tools"| node_mac_desktop
node_app -.->|"supports transfer relay"| node_relay

click node_app "https://github.com/chenqi92/primuse/blob/main/PrimuseTV/App.swift"
click node_source_catalog "https://github.com/chenqi92/primuse/blob/main/PrimuseKit/Sources/PrimuseKit/Models/MusicSource.swift"
click node_source_resolver "https://github.com/chenqi92/primuse/blob/main/PrimuseKit/Sources/PrimuseKit/Streaming/StreamResolverRegistry.swift"
click node_library "https://github.com/chenqi92/primuse/blob/main/Primuse/Services/Library/MusicLibrary.swift"
click node_song_model "https://github.com/chenqi92/primuse/blob/main/PrimuseKit/Sources/PrimuseKit/Models/Song.swift"
click node_credential_store "https://github.com/chenqi92/primuse/blob/main/Primuse/Utilities/KeychainService.swift"
click node_cloud_sync "https://github.com/chenqi92/primuse/blob/main/Primuse/Services/Cloud/CloudKitSyncService.swift"
click node_audio_engine "https://github.com/chenqi92/primuse/blob/main/Primuse/Services/Audio/AudioEngine.swift"
click node_tv_audio "https://github.com/chenqi92/primuse/blob/main/PrimuseTV/Audio/TVAudioEngine.swift"
click node_tv_sfb "https://github.com/chenqi92/primuse/blob/main/PrimuseTV/Audio/TVSFBEngine.swift"
click node_audio_formats "https://github.com/chenqi92/primuse/blob/main/PrimuseKit/Sources/PrimuseKit/Models/AudioFormat.swift"
click node_radio "https://github.com/chenqi92/primuse/blob/main/Primuse/Services/Radio/RadioPlaybackController.swift"
click node_smart_playlists "https://github.com/chenqi92/primuse/blob/main/Primuse/Services/Library/SmartPlaylistEngine.swift"
click node_music_intelligence "https://github.com/chenqi92/primuse/blob/main/Primuse/Services/AI/MusicIntelligenceService.swift"
click node_metadata_scraper "https://github.com/chenqi92/primuse/blob/main/Primuse/Services/Metadata/ScraperManager.swift"
click node_lyrics "https://github.com/chenqi92/primuse/blob/main/PrimuseKit/Sources/PrimuseKit/Models/LyricLine.swift"
click node_lyrics_translation "https://github.com/chenqi92/primuse/blob/main/Primuse/Services/Lyrics/LocalLyricsTranslationEngine.swift"
click node_apple_music "https://github.com/chenqi92/primuse/blob/main/Primuse/Services/AppleMusic/AppleMusicService.swift"
click node_watch "https://github.com/chenqi92/primuse/blob/main/PrimuseWatch/Stores/WatchPlayerStore.swift"
click node_widgets "https://github.com/chenqi92/primuse/blob/main/PrimuseWidgetExtension/NowPlayingWidget.swift"
click node_mac_desktop "https://github.com/chenqi92/primuse/blob/main/Primuse/App/MacMenuBarController.swift"
click node_relay "https://github.com/chenqi92/primuse/blob/main/ShareRelay/main.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_source_catalog,node_source_resolver,node_library,node_song_model,node_credential_store,node_cloud_sync,node_apple_music toneBlue
class node_audio_engine,node_tv_audio,node_tv_sfb,node_audio_formats,node_radio toneAmber
class node_smart_playlists,node_music_intelligence,node_metadata_scraper,node_lyrics,node_lyrics_translation toneMint
class node_app,node_watch,node_widgets,node_mac_desktop,node_relay toneRose
class node_listener toneIndigo
```

## Components

### Sources and library

- [Music sources](https://github.com/chenqi92/primuse/blob/main/PrimuseKit/Sources/PrimuseKit/Models/MusicSource.swift): `PrimuseKit/Sources/PrimuseKit/Models/MusicSource.swift`
- [Stream resolution](https://github.com/chenqi92/primuse/blob/main/PrimuseKit/Sources/PrimuseKit/Streaming/StreamResolverRegistry.swift): `PrimuseKit/Sources/PrimuseKit/Streaming/StreamResolverRegistry.swift`
- [Music library](https://github.com/chenqi92/primuse/blob/main/Primuse/Services/Library/MusicLibrary.swift): `Primuse/Services/Library/MusicLibrary.swift`
- [Song model](https://github.com/chenqi92/primuse/blob/main/PrimuseKit/Sources/PrimuseKit/Models/Song.swift): `PrimuseKit/Sources/PrimuseKit/Models/Song.swift`
- [Credential storage](https://github.com/chenqi92/primuse/blob/main/Primuse/Utilities/KeychainService.swift): `Primuse/Utilities/KeychainService.swift`
- [Cloud sync](https://github.com/chenqi92/primuse/blob/main/Primuse/Services/Cloud/CloudKitSyncService.swift): `Primuse/Services/Cloud/CloudKitSyncService.swift`
- [Apple Music](https://github.com/chenqi92/primuse/blob/main/Primuse/Services/AppleMusic/AppleMusicService.swift): `Primuse/Services/AppleMusic/AppleMusicService.swift`

### Playback and audio

- [Audio engine](https://github.com/chenqi92/primuse/blob/main/Primuse/Services/Audio/AudioEngine.swift): `Primuse/Services/Audio/AudioEngine.swift`
- [TV audio engine](https://github.com/chenqi92/primuse/blob/main/PrimuseTV/Audio/TVAudioEngine.swift): `PrimuseTV/Audio/TVAudioEngine.swift`
- [TV format fallback](https://github.com/chenqi92/primuse/blob/main/PrimuseTV/Audio/TVSFBEngine.swift): `PrimuseTV/Audio/TVSFBEngine.swift`
- [Format support](https://github.com/chenqi92/primuse/blob/main/PrimuseKit/Sources/PrimuseKit/Models/AudioFormat.swift): `PrimuseKit/Sources/PrimuseKit/Models/AudioFormat.swift`
- [Radio playback](https://github.com/chenqi92/primuse/blob/main/Primuse/Services/Radio/RadioPlaybackController.swift): `Primuse/Services/Radio/RadioPlaybackController.swift`

### Discovery and lyrics

- [Smart playlists](https://github.com/chenqi92/primuse/blob/main/Primuse/Services/Library/SmartPlaylistEngine.swift): `Primuse/Services/Library/SmartPlaylistEngine.swift`
- [Music intelligence](https://github.com/chenqi92/primuse/blob/main/Primuse/Services/AI/MusicIntelligenceService.swift): `Primuse/Services/AI/MusicIntelligenceService.swift`
- [Metadata scraping](https://github.com/chenqi92/primuse/blob/main/Primuse/Services/Metadata/ScraperManager.swift): `Primuse/Services/Metadata/ScraperManager.swift`
- [Lyrics model](https://github.com/chenqi92/primuse/blob/main/PrimuseKit/Sources/PrimuseKit/Models/LyricLine.swift): `PrimuseKit/Sources/PrimuseKit/Models/LyricLine.swift`
- [Lyrics translation](https://github.com/chenqi92/primuse/blob/main/Primuse/Services/Lyrics/LocalLyricsTranslationEngine.swift): `Primuse/Services/Lyrics/LocalLyricsTranslationEngine.swift`

### Apple experiences

- [Primuse apps](https://github.com/chenqi92/primuse/blob/main/PrimuseTV/App.swift): `PrimuseTV/App.swift`
- [Watch controls](https://github.com/chenqi92/primuse/blob/main/PrimuseWatch/Stores/WatchPlayerStore.swift): `PrimuseWatch/Stores/WatchPlayerStore.swift`
- [Now playing widgets](https://github.com/chenqi92/primuse/blob/main/PrimuseWidgetExtension/NowPlayingWidget.swift): `PrimuseWidgetExtension/NowPlayingWidget.swift`
- [Mac desktop tools](https://github.com/chenqi92/primuse/blob/main/Primuse/App/MacMenuBarController.swift): `Primuse/App/MacMenuBarController.swift`
- [Share relay](https://github.com/chenqi92/primuse/blob/main/ShareRelay/main.go): `ShareRelay/main.go`

### Other components

- **Listener**

## Connections

- Listener → Primuse apps: uses (evidence: `README.md`)
- Primuse apps → Music sources: connects sources (evidence: `README.md`)
- Music sources → Music library: feeds catalog (evidence: `README.md`)
- Music library → Song model: stores songs (evidence: `README.md`)
- Music library → Stream resolution: resolves streams (evidence: `README.md`)
- Stream resolution → Credential storage: uses credentials (evidence: `README.md`)
- Music library → Cloud sync: syncs library (evidence: `README.md`)
- Primuse apps → Audio engine: plays audio (evidence: `README.md`)
- Primuse apps → TV audio engine: plays on TV (evidence: `README.md`)
- TV audio engine → TV format fallback: decodes fallback (evidence: `PrimuseTV/Audio/TVAudioEngine.swift`)
- TV audio engine → Format support: selects formats
- Primuse apps → Radio playback: plays radio (evidence: `README.md`)
- Music library → Smart playlists: builds playlists (evidence: `Primuse/Services/Library/SmartPlaylistEngine.swift`)
- Primuse apps → Music intelligence: offers recommendations (evidence: `README.md`)
- Primuse apps → Metadata scraping: scrapes metadata (evidence: `README.md`)
- Primuse apps → Lyrics model: displays lyrics (evidence: `README.md`)
- Lyrics model → Lyrics translation: translates lyrics (evidence: `README.md`)
- Music sources → Apple Music: includes source (evidence: `README.md`)
- Primuse apps → Watch controls: supports remote control (evidence: `README.md`)
- Primuse apps → Now playing widgets: provides widgets (evidence: `README.md`)
- Primuse apps → Mac desktop tools: offers desktop tools (evidence: `README.md`)
- Primuse apps → Share relay: supports transfer relay
