# encore-karaoke-labs/encore-karaoke architecture

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

- Interactive diagram: https://gitdiagram.com/encore-karaoke-labs/encore-karaoke
- Repository: https://github.com/encore-karaoke-labs/encore-karaoke

## Overview

Encore is an Electron karaoke player. The principal workflow is selecting a library track, starting playback, rendering synchronized lyrics, and scoring live microphone performance; users can also record, stream, and join remote sessions. The graph preserves the README’s major feature branches. Source-index references and excerpts support the implementation links shown; other capability links are documented in the README, and unsampled internals are not inferred beyond that evidence.

Main entry points: [`src/pkgs/services/modules/Playback.js`](https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/pkgs/services/modules/Playback.js) (Track Playback), [`src/pkgs/system/managers/PlaybackManager.js`](https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/pkgs/system/managers/PlaybackManager.js) (Playback Manager), [`src/pkgs/system/managers/UIManager.js`](https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/pkgs/system/managers/UIManager.js) (Player UI), [`src/pkgs/system/managers/SetupManager.js`](https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/pkgs/system/managers/SetupManager.js) (Setup Manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["App Runtime"]
  node_main["Desktop Shell<br/>[main.ts]"]
  node_boot["Boot Manager<br/>[BootManager.js]"]
  node_ui["Player UI<br/>[UIManager.js]"]
  node_input["Input Manager<br/>[InputManager.js]"]
  node_setup["Setup Manager<br/>[SetupManager.js]"]
  node_config[("Settings Config<br/>[config-manager.ts]")]
end

subgraph group_catalog["Library and Playback"]
  node_library["Library Manager<br/>[LibraryManager.js]"]
  node_playbackmgr["Playback Manager<br/>[PlaybackManager.js]"]
  node_playback["Track Playback<br/>[Playback.js]"]
  node_state[("Audio State<br/>[State.js]")]
  node_synth["MIDI Synthesizer<br/>[Synthesizer.js]"]
end

subgraph group_performance["Singing Experience"]
  node_lyrics["Lyrics Engine<br/>[LyricsEngine.js]"]
  node_romanizer["Romanizer<br/>[Romanizer.js]"]
  node_forte["Forte Audio Engine<br/>[Forte.js]"]
  node_scoring["Performance Scoring<br/>[Scoring.js]"]
end

subgraph group_social["Remote and Games"]
  node_sessions["Session Service<br/>[Sessions.js]"]
  node_sessionmgr["Session Manager<br/>[SessionManager.js]"]
  node_remote["Mobile Remote<br/>[script.js]"]
  node_games["Karaoke Dares<br/>[Dares.js]"]
end

subgraph group_creator["Creator Tools"]
  node_recorder["Recorder<br/>[Recorder.js]"]
  node_stream["Live Streaming<br/>[StreamManager.js]"]
end

node_user(("Singer"))
node_youtube(("YouTube"))
node_microphone(("Microphone"))
node_friends(("Remote Singers"))
node_obs(("OBS"))

node_user -->|"selects songs"| node_ui
node_ui -.->|"handles controls"| node_input
node_user -->|"configures devices"| node_setup
node_setup -.->|"sets preferences"| node_config
node_boot -.->|"starts desktop"| node_main
node_user -->|"imports library"| node_library
node_library -.->|"supplies tracks"| node_playbackmgr
node_playbackmgr -.->|"starts playback"| node_playback
node_playback -->|"reads state"| node_state
node_playback -->|"uses synthesizer"| node_synth
node_youtube -->|"provides tracks"| node_playbackmgr
node_playback -->|"synchronizes lyrics"| node_lyrics
node_lyrics -->|"romanizes text"| node_romanizer
node_microphone -->|"provides audio"| node_forte
node_forte -->|"tracks performance"| node_scoring
node_user -->|"records performance"| node_recorder
node_recorder -.->|"supplies broadcast"| node_stream
node_obs -->|"receives stream"| node_stream
node_friends -->|"joins sessions"| node_sessions
node_sessionmgr -->|"broadcasts performance"| node_sessions
node_friends -->|"controls karaoke"| node_remote
node_user -->|"plays dares"| node_games

click node_main "https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/main.ts"
click node_boot "https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/pkgs/system/BootManager.js"
click node_ui "https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/pkgs/system/managers/UIManager.js"
click node_input "https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/pkgs/system/managers/InputManager.js"
click node_setup "https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/pkgs/system/managers/SetupManager.js"
click node_config "https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/config-manager.ts"
click node_library "https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/pkgs/system/managers/LibraryManager.js"
click node_playbackmgr "https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/pkgs/system/managers/PlaybackManager.js"
click node_playback "https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/pkgs/services/modules/Playback.js"
click node_state "https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/pkgs/services/core/State.js"
click node_synth "https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/pkgs/services/modules/Synthesizer.js"
click node_lyrics "https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/pkgs/system/managers/LyricsEngine.js"
click node_romanizer "https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/modules/Romanizer.js"
click node_forte "https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/pkgs/services/Forte.js"
click node_scoring "https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/pkgs/services/modules/Scoring.js"
click node_recorder "https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/modules/Recorder.js"
click node_stream "https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/pkgs/system/managers/StreamManager.js"
click node_sessions "https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/pkgs/services/Sessions.js"
click node_sessionmgr "https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/pkgs/system/managers/SessionManager.js"
click node_remote "https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/remote/script.js"
click node_games "https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/games/Dares.js"

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_boot,node_ui,node_input,node_setup,node_config toneBlue
class node_library,node_playbackmgr,node_playback,node_state,node_synth toneAmber
class node_lyrics,node_romanizer,node_forte,node_scoring toneMint
class node_sessions,node_sessionmgr,node_remote,node_games toneRose
class node_recorder,node_stream,node_user,node_youtube,node_microphone,node_friends,node_obs toneIndigo
```

## Components

### App Runtime

- [Desktop Shell](https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/main.ts): `main.ts`
- [Boot Manager](https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/pkgs/system/BootManager.js): `src/pkgs/system/BootManager.js`
- [Player UI](https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/pkgs/system/managers/UIManager.js): `src/pkgs/system/managers/UIManager.js`
- [Input Manager](https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/pkgs/system/managers/InputManager.js): `src/pkgs/system/managers/InputManager.js`
- [Setup Manager](https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/pkgs/system/managers/SetupManager.js): `src/pkgs/system/managers/SetupManager.js`
- [Settings Config](https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/config-manager.ts): `config-manager.ts`

### Library and Playback

- [Library Manager](https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/pkgs/system/managers/LibraryManager.js): `src/pkgs/system/managers/LibraryManager.js`
- [Playback Manager](https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/pkgs/system/managers/PlaybackManager.js): `src/pkgs/system/managers/PlaybackManager.js`
- [Track Playback](https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/pkgs/services/modules/Playback.js): `src/pkgs/services/modules/Playback.js`
- [Audio State](https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/pkgs/services/core/State.js): `src/pkgs/services/core/State.js`
- [MIDI Synthesizer](https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/pkgs/services/modules/Synthesizer.js): `src/pkgs/services/modules/Synthesizer.js`

### Singing Experience

- [Lyrics Engine](https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/pkgs/system/managers/LyricsEngine.js): `src/pkgs/system/managers/LyricsEngine.js`
- [Romanizer](https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/modules/Romanizer.js): `src/modules/Romanizer.js`
- [Forte Audio Engine](https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/pkgs/services/Forte.js): `src/pkgs/services/Forte.js`
- [Performance Scoring](https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/pkgs/services/modules/Scoring.js): `src/pkgs/services/modules/Scoring.js`

### Remote and Games

- [Session Service](https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/pkgs/services/Sessions.js): `src/pkgs/services/Sessions.js`
- [Session Manager](https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/pkgs/system/managers/SessionManager.js): `src/pkgs/system/managers/SessionManager.js`
- [Mobile Remote](https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/remote/script.js): `src/remote/script.js`
- [Karaoke Dares](https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/games/Dares.js): `src/games/Dares.js`

### Creator Tools

- [Recorder](https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/modules/Recorder.js): `src/modules/Recorder.js`
- [Live Streaming](https://github.com/encore-karaoke-labs/encore-karaoke/blob/main/src/pkgs/system/managers/StreamManager.js): `src/pkgs/system/managers/StreamManager.js`

### Other components

- **Singer**
- **YouTube**
- **Microphone**
- **Remote Singers**
- **OBS**

## Connections

- Singer → Player UI: selects songs (evidence: `README.md`)
- Player UI → Input Manager: handles controls
- Singer → Setup Manager: configures devices (evidence: `README.md`)
- Setup Manager → Settings Config: sets preferences
- Boot Manager → Desktop Shell: starts desktop
- Singer → Library Manager: imports library (evidence: `README.md`)
- Library Manager → Playback Manager: supplies tracks
- Playback Manager → Track Playback: starts playback
- Track Playback → Audio State: reads state (evidence: `src/pkgs/services/modules/Playback.js`)
- Track Playback → MIDI Synthesizer: uses synthesizer (evidence: `src/pkgs/services/modules/Playback.js`)
- YouTube → Playback Manager: provides tracks (evidence: `README.md`)
- Track Playback → Lyrics Engine: synchronizes lyrics (evidence: `README.md`)
- Lyrics Engine → Romanizer: romanizes text (evidence: `src/pkgs/system/managers/LyricsEngine.js`)
- Microphone → Forte Audio Engine: provides audio (evidence: `README.md`)
- Forte Audio Engine → Performance Scoring: tracks performance (evidence: `README.md`)
- Singer → Recorder: records performance (evidence: `README.md`)
- Recorder → Live Streaming: supplies broadcast
- OBS → Live Streaming: receives stream (evidence: `README.md`)
- Remote Singers → Session Service: joins sessions (evidence: `README.md`)
- Session Manager → Session Service: broadcasts performance (evidence: `src/pkgs/system/managers/SessionManager.js`)
- Remote Singers → Mobile Remote: controls karaoke (evidence: `README.md`)
- Singer → Karaoke Dares: plays dares (evidence: `src/games/Dares.js`)