# bjarneo/cliamp architecture

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

- Interactive diagram: https://gitdiagram.com/bjarneo/cliamp
- Repository: https://github.com/bjarneo/cliamp

## Overview

cliamp is a retro terminal music player for local media, streams, podcasts, radio, and many remote music services. The principal workflow begins with CLI startup and track or URL resolution, then presents and controls a queue in the terminal UI while the player decodes and outputs audio. Provider integrations supply browsable/searchable media, and the product also offers remote control, Lua plugins, and OS media-key integration. Main startup imports establish several runtime links; broader provider and radio workflows are documented in the README, so unsampled internals are represented at subsystem level.

Main entry points: [`provider/interfaces.go`](https://github.com/bjarneo/cliamp/blob/main/provider/interfaces.go) (Provider Contracts), [`main.go`](https://github.com/bjarneo/cliamp/blob/main/main.go) (CLI Startup), [`cmd/setup.go`](https://github.com/bjarneo/cliamp/blob/main/cmd/setup.go) (Provider Setup), [`ui/model`](https://github.com/bjarneo/cliamp/tree/main/ui/model) (Terminal UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Application Runtime"]
  node_main["CLI Startup<br/>[main.go]"]
  node_ui["Terminal UI"]
end

subgraph group_media["Media Playback"]
  node_resolve["Input Resolver<br/>[resolve.go]"]
  node_playlist["Playlist Model<br/>[playlist.go]"]
  node_player["Audio Player<br/>[player.go]"]
end

subgraph group_sources["Media Sources"]
  node_local["Local Library<br/>[provider.go]"]
  node_radio["Radio Directory<br/>[provider.go]"]
  node_podcasts["Podcast Provider<br/>[provider.go]"]
  node_provider["Provider Contracts<br/>[interfaces.go]"]
end

subgraph group_services["Remote Services"]
  node_lyrion["Lyrion Client<br/>[client.go]"]
  node_navidrome["Navidrome Client<br/>[client.go]"]
  node_plex["Plex Client<br/>[client.go]"]
  node_emby["Emby/Jellyfin API<br/>[client.go]"]
  node_spotify["Spotify Session<br/>[session.go]"]
  node_qobuz["Qobuz Client<br/>[client.go]"]
  node_tidal["Tidal Client<br/>[client.go]"]
  node_yandex["Yandex Client<br/>[client.go]"]
  node_setup["Provider Setup<br/>[setup.go]"]
end

subgraph group_extensions["Control Extensions"]
  node_ipc["IPC Server<br/>[server.go]"]
  node_plugins["Lua Plugins<br/>[luaplugin.go]"]
  node_mediactl["OS Media Controls<br/>[service_darwin.go]"]
end

node_user(("Listener"))

node_user -->|"starts player"| node_main
node_main -->|"resolves inputs"| node_resolve
node_main -->|"creates player"| node_player
node_main -->|"configures UI"| node_ui
node_main -->|"starts control"| node_ipc
node_main -->|"loads plugins"| node_plugins
node_main -->|"uses radio"| node_radio
node_resolve -->|"builds tracks"| node_playlist
node_ui -->|"searches providers"| node_playlist
node_player -.->|"plays audio"| node_user
node_user -->|"configures services"| node_setup
node_setup -->|"validates connection"| node_lyrion
node_setup -->|"validates connection"| node_navidrome
node_setup -->|"validates connection"| node_plex
node_setup -->|"validates connection"| node_emby
node_provider -->|"defines interface"| node_playlist
node_lyrion -->|"implements provider"| node_provider
node_navidrome -->|"implements provider"| node_provider
node_plex -->|"implements provider"| node_provider
node_emby -->|"implements provider"| node_provider
node_local -->|"implements provider"| node_provider
node_user -->|"browses stations"| node_radio
node_user -->|"discovers shows"| node_podcasts
node_user -->|"sends commands"| node_ipc
node_ipc -->|"dispatches requests"| node_ui
node_plugins -.->|"controls playback"| node_player
node_mediactl -->|"sends controls"| node_ui
node_user -->|"uses media keys"| node_mediactl
node_spotify -.->|"supplies service media"| node_provider
node_qobuz -.->|"supplies service media"| node_provider
node_tidal -.->|"supplies service media"| node_provider
node_yandex -.->|"supplies service media"| node_provider

click node_main "https://github.com/bjarneo/cliamp/blob/main/main.go"
click node_ui "https://github.com/bjarneo/cliamp/tree/main/ui/model"
click node_resolve "https://github.com/bjarneo/cliamp/blob/main/resolve/resolve.go"
click node_playlist "https://github.com/bjarneo/cliamp/blob/main/playlist/playlist.go"
click node_player "https://github.com/bjarneo/cliamp/blob/main/player/player.go"
click node_local "https://github.com/bjarneo/cliamp/blob/main/external/local/provider.go"
click node_radio "https://github.com/bjarneo/cliamp/blob/main/external/radio/provider.go"
click node_podcasts "https://github.com/bjarneo/cliamp/blob/main/external/podcast/provider.go"
click node_provider "https://github.com/bjarneo/cliamp/blob/main/provider/interfaces.go"
click node_lyrion "https://github.com/bjarneo/cliamp/blob/main/external/lyrion/client.go"
click node_navidrome "https://github.com/bjarneo/cliamp/blob/main/external/navidrome/client.go"
click node_plex "https://github.com/bjarneo/cliamp/blob/main/external/plex/client.go"
click node_emby "https://github.com/bjarneo/cliamp/blob/main/internal/embyapi/client.go"
click node_spotify "https://github.com/bjarneo/cliamp/blob/main/external/spotify/session.go"
click node_qobuz "https://github.com/bjarneo/cliamp/blob/main/external/qobuz/client.go"
click node_tidal "https://github.com/bjarneo/cliamp/blob/main/external/tidal/client.go"
click node_yandex "https://github.com/bjarneo/cliamp/blob/main/external/yandex/client.go"
click node_setup "https://github.com/bjarneo/cliamp/blob/main/cmd/setup.go"
click node_ipc "https://github.com/bjarneo/cliamp/blob/main/ipc/server.go"
click node_plugins "https://github.com/bjarneo/cliamp/blob/main/luaplugin/luaplugin.go"
click node_mediactl "https://github.com/bjarneo/cliamp/blob/main/mediactl/service_darwin.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_main,node_ui toneBlue
class node_resolve,node_playlist,node_player toneAmber
class node_local,node_radio,node_podcasts,node_provider toneMint
class node_lyrion,node_navidrome,node_plex,node_emby,node_spotify,node_qobuz,node_tidal,node_yandex,node_setup toneRose
class node_ipc,node_plugins,node_mediactl,node_user toneIndigo
```

## Components

### Application Runtime

- [CLI Startup](https://github.com/bjarneo/cliamp/blob/main/main.go): `main.go`
- [Terminal UI](https://github.com/bjarneo/cliamp/tree/main/ui/model): `ui/model`

### Media Playback

- [Input Resolver](https://github.com/bjarneo/cliamp/blob/main/resolve/resolve.go): `resolve/resolve.go`
- [Playlist Model](https://github.com/bjarneo/cliamp/blob/main/playlist/playlist.go): `playlist/playlist.go`
- [Audio Player](https://github.com/bjarneo/cliamp/blob/main/player/player.go): `player/player.go`

### Media Sources

- [Local Library](https://github.com/bjarneo/cliamp/blob/main/external/local/provider.go): `external/local/provider.go`
- [Radio Directory](https://github.com/bjarneo/cliamp/blob/main/external/radio/provider.go): `external/radio/provider.go`
- [Podcast Provider](https://github.com/bjarneo/cliamp/blob/main/external/podcast/provider.go): `external/podcast/provider.go`
- [Provider Contracts](https://github.com/bjarneo/cliamp/blob/main/provider/interfaces.go): `provider/interfaces.go`

### Remote Services

- [Lyrion Client](https://github.com/bjarneo/cliamp/blob/main/external/lyrion/client.go): `external/lyrion/client.go`
- [Navidrome Client](https://github.com/bjarneo/cliamp/blob/main/external/navidrome/client.go): `external/navidrome/client.go`
- [Plex Client](https://github.com/bjarneo/cliamp/blob/main/external/plex/client.go): `external/plex/client.go`
- [Emby/Jellyfin API](https://github.com/bjarneo/cliamp/blob/main/internal/embyapi/client.go): `internal/embyapi/client.go`
- [Spotify Session](https://github.com/bjarneo/cliamp/blob/main/external/spotify/session.go): `external/spotify/session.go`
- [Qobuz Client](https://github.com/bjarneo/cliamp/blob/main/external/qobuz/client.go): `external/qobuz/client.go`
- [Tidal Client](https://github.com/bjarneo/cliamp/blob/main/external/tidal/client.go): `external/tidal/client.go`
- [Yandex Client](https://github.com/bjarneo/cliamp/blob/main/external/yandex/client.go): `external/yandex/client.go`
- [Provider Setup](https://github.com/bjarneo/cliamp/blob/main/cmd/setup.go): `cmd/setup.go`

### Control Extensions

- [IPC Server](https://github.com/bjarneo/cliamp/blob/main/ipc/server.go): `ipc/server.go`
- [Lua Plugins](https://github.com/bjarneo/cliamp/blob/main/luaplugin/luaplugin.go): `luaplugin/luaplugin.go`
- [OS Media Controls](https://github.com/bjarneo/cliamp/blob/main/mediactl/service_darwin.go): `mediactl/service_darwin.go`

### Other components

- **Listener**

## Connections

- Listener → CLI Startup: starts player
- CLI Startup → Input Resolver: resolves inputs (evidence: `main.go`)
- CLI Startup → Audio Player: creates player (evidence: `main.go`)
- CLI Startup → Terminal UI: configures UI (evidence: `main.go`)
- CLI Startup → IPC Server: starts control (evidence: `main.go`)
- CLI Startup → Lua Plugins: loads plugins (evidence: `main.go`)
- CLI Startup → Radio Directory: uses radio (evidence: `main.go`)
- Input Resolver → Playlist Model: builds tracks (evidence: `resolve/resolve.go`)
- Terminal UI → Playlist Model: searches providers (evidence: `ui/model/keys_search.go`)
- Audio Player → Listener: plays audio
- Listener → Provider Setup: configures services
- Provider Setup → Lyrion Client: validates connection (evidence: `cmd/setup.go`)
- Provider Setup → Navidrome Client: validates connection (evidence: `cmd/setup.go`)
- Provider Setup → Plex Client: validates connection (evidence: `cmd/setup.go`)
- Provider Setup → Emby/Jellyfin API: validates connection (evidence: `cmd/setup.go`)
- Provider Contracts → Playlist Model: defines interface (evidence: `provider/interfaces.go`)
- Lyrion Client → Provider Contracts: implements provider (evidence: `external/lyrion/client.go`)
- Navidrome Client → Provider Contracts: implements provider (evidence: `external/navidrome/client.go`)
- Plex Client → Provider Contracts: implements provider (evidence: `external/plex/client.go`)
- Emby/Jellyfin API → Provider Contracts: implements provider (evidence: `internal/embyapi/client.go`)
- Local Library → Provider Contracts: implements provider (evidence: `external/local/provider.go`)
- Listener → Radio Directory: browses stations
- Listener → Podcast Provider: discovers shows
- Listener → IPC Server: sends commands
- IPC Server → Terminal UI: dispatches requests
- Lua Plugins → Audio Player: controls playback
- OS Media Controls → Terminal UI: sends controls (evidence: `mediactl/service_darwin.go`)
- Listener → OS Media Controls: uses media keys
- Spotify Session → Provider Contracts: supplies service media
- Qobuz Client → Provider Contracts: supplies service media
- Tidal Client → Provider Contracts: supplies service media
- Yandex Client → Provider Contracts: supplies service media
