# jamesdun2866/music-assistant-display architecture

> Architecture diagram of the GitHub repository jamesdun2866/music-assistant-display, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jamesdun2866/music-assistant-display
- Repository: https://github.com/jamesdun2866/music-assistant-display

## Overview

Music Assistant Display is a local TV kiosk for artwork, lyrics, ambient photos, and optional line-in features; it does not play or control audio. The main path is Music Assistant queue/player state into the server, then a browser snapshot and synchronized display. Separate branches provide ambient photo management, line-in album recognition and correction, the listening journal, source tools, and optional CEC remote navigation. The README documents several capabilities whose implementation was not sampled; those links are cited as documented behavior rather than inspected call paths.

Main entry points: [`src/web/App.tsx`](https://github.com/jamesdun2866/music-assistant-display/blob/main/src/web/App.tsx) (Display app), [`src/server/index.ts`](https://github.com/jamesdun2866/music-assistant-display/blob/main/src/server/index.ts) (HTTP server), [`src/server/line-in-album.ts`](https://github.com/jamesdun2866/music-assistant-display/blob/main/src/server/line-in-album.ts) (Line-in album service), [`src/web/usePlayback.ts`](https://github.com/jamesdun2866/music-assistant-display/blob/main/src/web/usePlayback.ts) (Playback updates)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_display["Kiosk display"]
  node_app["Display app<br/>[App.tsx]"]
  node_playback_hook["Playback updates<br/>[usePlayback.ts]"]
  node_protocol["Display protocol<br/>[protocol.ts]"]
  node_ambient_view["Ambient view<br/>[Ambient.tsx]"]
  node_album_view["Line-in view<br/>[LineInAlbum.tsx]"]
  node_journal_view["Journal view"]
  node_tools_view["Tools panel<br/>[ToolsPanel.tsx]"]
end

subgraph group_playback["Playback services"]
  node_server["HTTP server<br/>[index.ts]"]
  node_http["HTTP routes<br/>[http.ts]"]
  node_bridge["Playback bridge<br/>[bridge.ts]"]
  node_ma_client["MA connection<br/>[ma-client.ts]"]
  node_ma_provider["MA provider<br/>[ma-provider.ts]"]
  node_lyrics_cache[("Lyrics cache<br/>[cache.ts]")]
end

subgraph group_linein["Line-in albums"]
  node_album_service["Line-in album service<br/>[line-in-album.ts]"]
  node_album_catalog["Album catalog<br/>[album-catalog.ts]"]
  node_editions[("Edition correction<br/>[album-editions.ts]")]
end

subgraph group_local["Local features"]
  node_ambient[("Ambient library<br/>[ambient.ts]")]
  node_journal[("Listening journal")]
  node_tools["Source tools<br/>[source-tools.ts]"]
  node_cec["CEC navigation<br/>[cec-native.ts]"]
end

subgraph group_source["Input source"]
  node_linein_source["Line-in source<br/>[audio.py]"]
  node_recognition["Album recognition<br/>[recognition.py]"]
  node_recording[("Recording library")]
  node_health["Source health<br/>[source_health.py]"]
end

node_viewer(("Viewer"))

node_viewer -->|"uses"| node_app
node_app -->|"subscribes"| node_playback_hook
node_playback_hook -.->|"requests state"| node_http
node_http -.->|"streams snapshots"| node_playback_hook
node_server -->|"configures"| node_http
node_server -->|"creates"| node_bridge
node_bridge -.->|"uses"| node_ma_provider
node_ma_provider -->|"uses"| node_ma_client
node_ma_client -.->|"requests lyrics"| node_lyrics_cache
node_http -.->|"serves snapshots"| node_protocol
node_playback_hook -->|"validates snapshots"| node_protocol
node_app -->|"renders"| node_ambient_view
node_server -->|"initializes"| node_ambient
node_app -.->|"manages photos"| node_ambient
node_linein_source -->|"provides audio"| node_recognition
node_recognition -.->|"publishes album"| node_album_service
node_server -->|"initializes"| node_album_service
node_album_service -->|"loads tracklist"| node_album_catalog
node_server -->|"initializes"| node_editions
node_album_service -->|"sets correction service"| node_editions
node_app -->|"renders"| node_album_view
node_album_view -.->|"displays album"| node_album_service
node_server -->|"configures"| node_journal
node_app -.->|"offers history"| node_journal_view
node_server -->|"configures"| node_tools
node_tools -->|"uses library"| node_recording
node_tools -->|"uses diagnostics"| node_health
node_app -.->|"offers tools"| node_tools_view
node_cec -->|"uses remote types"| node_protocol
node_app -.->|"remote navigation"| node_cec

click node_app "https://github.com/jamesdun2866/music-assistant-display/blob/main/src/web/App.tsx"
click node_playback_hook "https://github.com/jamesdun2866/music-assistant-display/blob/main/src/web/usePlayback.ts"
click node_protocol "https://github.com/jamesdun2866/music-assistant-display/blob/main/src/shared/protocol.ts"
click node_server "https://github.com/jamesdun2866/music-assistant-display/blob/main/src/server/index.ts"
click node_http "https://github.com/jamesdun2866/music-assistant-display/blob/main/src/server/http.ts"
click node_bridge "https://github.com/jamesdun2866/music-assistant-display/blob/main/src/server/bridge.ts"
click node_ma_client "https://github.com/jamesdun2866/music-assistant-display/blob/main/src/server/ma-client.ts"
click node_ma_provider "https://github.com/jamesdun2866/music-assistant-display/blob/main/src/server/ma-provider.ts"
click node_lyrics_cache "https://github.com/jamesdun2866/music-assistant-display/blob/main/src/server/cache.ts"
click node_ambient "https://github.com/jamesdun2866/music-assistant-display/blob/main/src/server/ambient.ts"
click node_ambient_view "https://github.com/jamesdun2866/music-assistant-display/blob/main/src/web/Ambient.tsx"
click node_linein_source "https://github.com/jamesdun2866/music-assistant-display/blob/main/source/sendspin_karaoke_source/audio.py"
click node_recognition "https://github.com/jamesdun2866/music-assistant-display/blob/main/source/sendspin_karaoke_source/recognition.py"
click node_album_service "https://github.com/jamesdun2866/music-assistant-display/blob/main/src/server/line-in-album.ts"
click node_album_catalog "https://github.com/jamesdun2866/music-assistant-display/blob/main/src/server/album-catalog.ts"
click node_editions "https://github.com/jamesdun2866/music-assistant-display/blob/main/src/server/album-editions.ts"
click node_album_view "https://github.com/jamesdun2866/music-assistant-display/blob/main/src/web/LineInAlbum.tsx"
click node_journal "https://github.com/jamesdun2866/music-assistant-display/blob/main/src/server/listening-journal.ts"
click node_journal_view "https://github.com/jamesdun2866/music-assistant-display/blob/main/src/web/ListeningJournal.tsx"
click node_tools "https://github.com/jamesdun2866/music-assistant-display/blob/main/src/server/source-tools.ts"
click node_tools_view "https://github.com/jamesdun2866/music-assistant-display/blob/main/src/web/ToolsPanel.tsx"
click node_recording "https://github.com/jamesdun2866/music-assistant-display/blob/main/source/sendspin_karaoke_source/recording_library.py"
click node_health "https://github.com/jamesdun2866/music-assistant-display/blob/main/source/sendspin_karaoke_source/source_health.py"
click node_cec "https://github.com/jamesdun2866/music-assistant-display/blob/main/src/server/cec-native.ts"

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_playback_hook,node_protocol,node_ambient_view,node_album_view,node_journal_view,node_tools_view,node_viewer toneBlue
class node_server,node_http,node_bridge,node_ma_client,node_ma_provider,node_lyrics_cache toneAmber
class node_album_service,node_album_catalog,node_editions toneMint
class node_ambient,node_journal,node_tools,node_cec toneRose
class node_linein_source,node_recognition,node_recording,node_health toneIndigo
```

## Components

### Kiosk display

- [Display app](https://github.com/jamesdun2866/music-assistant-display/blob/main/src/web/App.tsx): `src/web/App.tsx`
- [Playback updates](https://github.com/jamesdun2866/music-assistant-display/blob/main/src/web/usePlayback.ts): `src/web/usePlayback.ts`
- [Display protocol](https://github.com/jamesdun2866/music-assistant-display/blob/main/src/shared/protocol.ts): `src/shared/protocol.ts`
- [Ambient view](https://github.com/jamesdun2866/music-assistant-display/blob/main/src/web/Ambient.tsx): `src/web/Ambient.tsx`
- [Line-in view](https://github.com/jamesdun2866/music-assistant-display/blob/main/src/web/LineInAlbum.tsx): `src/web/LineInAlbum.tsx`
- [Journal view](https://github.com/jamesdun2866/music-assistant-display/blob/main/src/web/ListeningJournal.tsx): `src/web/ListeningJournal.tsx`
- [Tools panel](https://github.com/jamesdun2866/music-assistant-display/blob/main/src/web/ToolsPanel.tsx): `src/web/ToolsPanel.tsx`

### Playback services

- [HTTP server](https://github.com/jamesdun2866/music-assistant-display/blob/main/src/server/index.ts): `src/server/index.ts`
- [HTTP routes](https://github.com/jamesdun2866/music-assistant-display/blob/main/src/server/http.ts): `src/server/http.ts`
- [Playback bridge](https://github.com/jamesdun2866/music-assistant-display/blob/main/src/server/bridge.ts): `src/server/bridge.ts`
- [MA connection](https://github.com/jamesdun2866/music-assistant-display/blob/main/src/server/ma-client.ts): `src/server/ma-client.ts`
- [MA provider](https://github.com/jamesdun2866/music-assistant-display/blob/main/src/server/ma-provider.ts): `src/server/ma-provider.ts`
- [Lyrics cache](https://github.com/jamesdun2866/music-assistant-display/blob/main/src/server/cache.ts): `src/server/cache.ts`

### Line-in albums

- [Line-in album service](https://github.com/jamesdun2866/music-assistant-display/blob/main/src/server/line-in-album.ts): `src/server/line-in-album.ts`
- [Album catalog](https://github.com/jamesdun2866/music-assistant-display/blob/main/src/server/album-catalog.ts): `src/server/album-catalog.ts`
- [Edition correction](https://github.com/jamesdun2866/music-assistant-display/blob/main/src/server/album-editions.ts): `src/server/album-editions.ts`

### Local features

- [Ambient library](https://github.com/jamesdun2866/music-assistant-display/blob/main/src/server/ambient.ts): `src/server/ambient.ts`
- [Listening journal](https://github.com/jamesdun2866/music-assistant-display/blob/main/src/server/listening-journal.ts): `src/server/listening-journal.ts`
- [Source tools](https://github.com/jamesdun2866/music-assistant-display/blob/main/src/server/source-tools.ts): `src/server/source-tools.ts`
- [CEC navigation](https://github.com/jamesdun2866/music-assistant-display/blob/main/src/server/cec-native.ts): `src/server/cec-native.ts`

### Input source

- [Line-in source](https://github.com/jamesdun2866/music-assistant-display/blob/main/source/sendspin_karaoke_source/audio.py): `source/sendspin_karaoke_source/audio.py`
- [Album recognition](https://github.com/jamesdun2866/music-assistant-display/blob/main/source/sendspin_karaoke_source/recognition.py): `source/sendspin_karaoke_source/recognition.py`
- [Recording library](https://github.com/jamesdun2866/music-assistant-display/blob/main/source/sendspin_karaoke_source/recording_library.py): `source/sendspin_karaoke_source/recording_library.py`
- [Source health](https://github.com/jamesdun2866/music-assistant-display/blob/main/source/sendspin_karaoke_source/source_health.py): `source/sendspin_karaoke_source/source_health.py`

### Other components

- **Viewer**

## Connections

- Viewer → Display app: uses
- Display app → Playback updates: subscribes (evidence: `src/web/App.tsx`)
- Playback updates → HTTP routes: requests state
- HTTP routes → Playback updates: streams snapshots
- HTTP server → HTTP routes: configures (evidence: `src/server/index.ts`)
- HTTP server → Playback bridge: creates (evidence: `src/server/index.ts`)
- Playback bridge → MA provider: uses
- MA provider → MA connection: uses
- MA connection → Lyrics cache: requests lyrics
- HTTP routes → Display protocol: serves snapshots
- Playback updates → Display protocol: validates snapshots (evidence: `src/web/usePlayback.ts`)
- Display app → Ambient view: renders (evidence: `src/web/App.tsx`)
- HTTP server → Ambient library: initializes (evidence: `src/server/index.ts`)
- Display app → Ambient library: manages photos
- Line-in source → Album recognition: provides audio (evidence: `source/sendspin_karaoke_source/recognition.py`)
- Album recognition → Line-in album service: publishes album
- HTTP server → Line-in album service: initializes (evidence: `src/server/index.ts`)
- Line-in album service → Album catalog: loads tracklist (evidence: `src/server/line-in-album.ts`)
- HTTP server → Edition correction: initializes (evidence: `src/server/index.ts`)
- Line-in album service → Edition correction: sets correction service (evidence: `src/server/index.ts`)
- Display app → Line-in view: renders (evidence: `src/web/App.tsx`)
- Line-in view → Line-in album service: displays album
- HTTP server → Listening journal: configures (evidence: `src/server/index.ts`)
- Display app → Journal view: offers history
- HTTP server → Source tools: configures (evidence: `src/server/index.ts`)
- Source tools → Recording library: uses library (evidence: `src/server/source-tools.ts`)
- Source tools → Source health: uses diagnostics (evidence: `src/server/source-tools.ts`)
- Display app → Tools panel: offers tools
- CEC navigation → Display protocol: uses remote types (evidence: `src/server/cec-native.ts`)
- Display app → CEC navigation: remote navigation
