# nake13/khuaplayer architecture

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

## Overview

Khua is a native macOS media player. The main workflow is opening a media file in the player, decoding and presenting it, with optional subtitle, enhancement, and damaged-file recovery features; Finder Quick Look is a separate playback entry point. The graph also preserves the documented release website and edge service. Some implementation paths are represented by their exact enclosing directories because their source was not sampled; dashed links mark unverified integration.

Main entry points: [`Apps/Mac/UI/PlayerViewController.swift`](https://github.com/nake13/khuaplayer/blob/main/Apps/Mac/UI/PlayerViewController.swift) (Player interface), [`Modules/Captions/CaptionEngine.swift`](https://github.com/nake13/khuaplayer/blob/main/Modules/Captions/CaptionEngine.swift) (Caption generation), [`Modules/MediaCore/Bridge/SPPlayerCore.h`](https://github.com/nake13/khuaplayer/blob/main/Modules/MediaCore/Bridge/SPPlayerCore.h) (Media playback core), [`Apps/Mac/UI/AppDelegate.swift`](https://github.com/nake13/khuaplayer/blob/main/Apps/Mac/UI/AppDelegate.swift) (App lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_macapp["Mac app"]
  node_app["App lifecycle<br/>[AppDelegate.swift]"]
  node_window["Player window"]
  node_playerui["Player interface"]
  node_welcome["Welcome and history<br/>[WelcomeView.swift]"]
  node_history[("Recent plays<br/>[RecentPlays.swift]")]
  node_quicklook["Quick Look playback"]
  node_sleep["Playback sleep control"]
end

subgraph group_media["Playback engine"]
  node_core["Media playback core<br/>[SPPlayerCore.h]"]
  node_demux["Demux and stream reads<br/>[Demuxer.cpp]"]
  node_recovery["Container recovery"]
  node_resilience["Bitstream resilience"]
  node_motion["Motion interpolation"]
end

subgraph group_captions["Caption tools"]
  node_captionui["Caption controls"]
  node_taskcenter["Caption task center"]
  node_engine["Caption generation"]
  node_transcriber["Speech transcription"]
  node_translator["Caption translation"]
  node_srt["SRT parsing and output<br/>[CaptionSRT.swift]"]
end

subgraph group_web["Release website"]
  node_site["Product and release site<br/>[App.jsx]"]
  node_releases["Release listings<br/>[Releases.jsx]"]
  node_edge["Release edge service<br/>[index.ts]"]
  node_catalog["Release catalog<br/>[catalog.ts]"]
end

node_user(("Mac user"))
node_finder(("Finder Quick Look"))

node_user -->|"opens app"| node_app
node_app -->|"creates windows"| node_window
node_window -->|"hosts"| node_playerui
node_playerui -.->|"controls playback"| node_core
node_app -->|"shows welcome"| node_welcome
node_welcome -->|"reads recent plays"| node_history
node_playerui -.->|"updates history"| node_history
node_finder -->|"previews media"| node_quicklook
node_quicklook -->|"creates preview core"| node_core
node_quicklook -->|"uses sleep control"| node_sleep
node_core -.->|"reads streams"| node_demux
node_demux -->|"uses recovery"| node_recovery
node_demux -->|"uses resilience"| node_resilience
node_core -.->|"routes interpolation"| node_motion
node_playerui -->|"hosts caption controls"| node_captionui
node_captionui -->|"submits tasks"| node_taskcenter
node_taskcenter -->|"runs generation"| node_engine
node_engine -->|"transcribes audio"| node_transcriber
node_engine -->|"translates cues"| node_translator
node_engine -->|"formats sidecars"| node_srt
node_user -.->|"visits site"| node_site
node_site -->|"shows releases"| node_releases
node_releases -->|"reads catalog"| node_catalog
node_edge -->|"parses catalog"| node_catalog

click node_app "https://github.com/nake13/khuaplayer/blob/main/Apps/Mac/UI/AppDelegate.swift"
click node_window "https://github.com/nake13/khuaplayer/blob/main/Apps/Mac/UI/PlayerWindowController.swift"
click node_playerui "https://github.com/nake13/khuaplayer/blob/main/Apps/Mac/UI/PlayerViewController.swift"
click node_welcome "https://github.com/nake13/khuaplayer/blob/main/Apps/Mac/UI/WelcomeView.swift"
click node_history "https://github.com/nake13/khuaplayer/blob/main/Apps/Mac/UI/RecentPlays.swift"
click node_quicklook "https://github.com/nake13/khuaplayer/blob/main/Apps/Mac/QuickLook/Preview/QuickLookPreviewViewController.swift"
click node_sleep "https://github.com/nake13/khuaplayer/blob/main/Apps/Mac/UI/SPPlaybackSleepController.swift"
click node_core "https://github.com/nake13/khuaplayer/blob/main/Modules/MediaCore/Bridge/SPPlayerCore.h"
click node_demux "https://github.com/nake13/khuaplayer/blob/main/Modules/MediaCore/Core/Demuxer.cpp"
click node_recovery "https://github.com/nake13/khuaplayer/tree/main/Modules/MediaCore/Core/Recovery"
click node_resilience "https://github.com/nake13/khuaplayer/tree/main/Modules/MediaCore/Core/Resilience"
click node_motion "https://github.com/nake13/khuaplayer/tree/main/Modules/VideoEnhancement"
click node_captionui "https://github.com/nake13/khuaplayer/blob/main/Apps/Mac/CaptionsHost/CaptionsController.swift"
click node_taskcenter "https://github.com/nake13/khuaplayer/blob/main/Apps/Mac/CaptionsHost/CaptionTaskCenter.swift"
click node_engine "https://github.com/nake13/khuaplayer/blob/main/Modules/Captions/CaptionEngine.swift"
click node_transcriber "https://github.com/nake13/khuaplayer/blob/main/Modules/Captions/CaptionTranscriber.swift"
click node_translator "https://github.com/nake13/khuaplayer/blob/main/Apps/Mac/CaptionsHost/CaptionTranslator.swift"
click node_srt "https://github.com/nake13/khuaplayer/blob/main/Modules/Captions/CaptionSRT.swift"
click node_site "https://github.com/nake13/khuaplayer/blob/main/Website/src/App.jsx"
click node_releases "https://github.com/nake13/khuaplayer/blob/main/Website/src/Releases.jsx"
click node_edge "https://github.com/nake13/khuaplayer/blob/main/Website/cloudflare/index.ts"
click node_catalog "https://github.com/nake13/khuaplayer/blob/main/Website/cloudflare/catalog.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_window,node_playerui,node_welcome,node_history,node_quicklook,node_sleep,node_user toneBlue
class node_core,node_demux,node_recovery,node_resilience,node_motion toneAmber
class node_captionui,node_taskcenter,node_engine,node_transcriber,node_translator,node_srt toneMint
class node_site,node_releases,node_edge,node_catalog toneRose
class node_finder toneIndigo
```

## Components

### Mac app

- [App lifecycle](https://github.com/nake13/khuaplayer/blob/main/Apps/Mac/UI/AppDelegate.swift): `Apps/Mac/UI/AppDelegate.swift`
- [Player window](https://github.com/nake13/khuaplayer/blob/main/Apps/Mac/UI/PlayerWindowController.swift): `Apps/Mac/UI/PlayerWindowController.swift`
- [Player interface](https://github.com/nake13/khuaplayer/blob/main/Apps/Mac/UI/PlayerViewController.swift): `Apps/Mac/UI/PlayerViewController.swift`
- [Welcome and history](https://github.com/nake13/khuaplayer/blob/main/Apps/Mac/UI/WelcomeView.swift): `Apps/Mac/UI/WelcomeView.swift`
- [Recent plays](https://github.com/nake13/khuaplayer/blob/main/Apps/Mac/UI/RecentPlays.swift): `Apps/Mac/UI/RecentPlays.swift`
- [Quick Look playback](https://github.com/nake13/khuaplayer/blob/main/Apps/Mac/QuickLook/Preview/QuickLookPreviewViewController.swift): `Apps/Mac/QuickLook/Preview/QuickLookPreviewViewController.swift`
- [Playback sleep control](https://github.com/nake13/khuaplayer/blob/main/Apps/Mac/UI/SPPlaybackSleepController.swift): `Apps/Mac/UI/SPPlaybackSleepController.swift`

### Playback engine

- [Media playback core](https://github.com/nake13/khuaplayer/blob/main/Modules/MediaCore/Bridge/SPPlayerCore.h): `Modules/MediaCore/Bridge/SPPlayerCore.h`
- [Demux and stream reads](https://github.com/nake13/khuaplayer/blob/main/Modules/MediaCore/Core/Demuxer.cpp): `Modules/MediaCore/Core/Demuxer.cpp`
- [Container recovery](https://github.com/nake13/khuaplayer/tree/main/Modules/MediaCore/Core/Recovery): `Modules/MediaCore/Core/Recovery`
- [Bitstream resilience](https://github.com/nake13/khuaplayer/tree/main/Modules/MediaCore/Core/Resilience): `Modules/MediaCore/Core/Resilience`
- [Motion interpolation](https://github.com/nake13/khuaplayer/tree/main/Modules/VideoEnhancement): `Modules/VideoEnhancement`

### Caption tools

- [Caption controls](https://github.com/nake13/khuaplayer/blob/main/Apps/Mac/CaptionsHost/CaptionsController.swift): `Apps/Mac/CaptionsHost/CaptionsController.swift`
- [Caption task center](https://github.com/nake13/khuaplayer/blob/main/Apps/Mac/CaptionsHost/CaptionTaskCenter.swift): `Apps/Mac/CaptionsHost/CaptionTaskCenter.swift`
- [Caption generation](https://github.com/nake13/khuaplayer/blob/main/Modules/Captions/CaptionEngine.swift): `Modules/Captions/CaptionEngine.swift`
- [Speech transcription](https://github.com/nake13/khuaplayer/blob/main/Modules/Captions/CaptionTranscriber.swift): `Modules/Captions/CaptionTranscriber.swift`
- [Caption translation](https://github.com/nake13/khuaplayer/blob/main/Apps/Mac/CaptionsHost/CaptionTranslator.swift): `Apps/Mac/CaptionsHost/CaptionTranslator.swift`
- [SRT parsing and output](https://github.com/nake13/khuaplayer/blob/main/Modules/Captions/CaptionSRT.swift): `Modules/Captions/CaptionSRT.swift`

### Release website

- [Product and release site](https://github.com/nake13/khuaplayer/blob/main/Website/src/App.jsx): `Website/src/App.jsx`
- [Release listings](https://github.com/nake13/khuaplayer/blob/main/Website/src/Releases.jsx): `Website/src/Releases.jsx`
- [Release edge service](https://github.com/nake13/khuaplayer/blob/main/Website/cloudflare/index.ts): `Website/cloudflare/index.ts`
- [Release catalog](https://github.com/nake13/khuaplayer/blob/main/Website/cloudflare/catalog.ts): `Website/cloudflare/catalog.ts`

### Other components

- **Mac user**
- **Finder Quick Look**

## Connections

- Mac user → App lifecycle: opens app (evidence: `Apps/Mac/UI/AppDelegate.swift`)
- App lifecycle → Player window: creates windows (evidence: `Apps/Mac/UI/AppDelegate.swift`)
- Player window → Player interface: hosts (evidence: `Apps/Mac/UI/PlayerWindowController.swift`)
- Player interface → Media playback core: controls playback
- App lifecycle → Welcome and history: shows welcome (evidence: `Apps/Mac/UI/AppDelegate.swift`)
- Welcome and history → Recent plays: reads recent plays (evidence: `Apps/Mac/UI/WelcomeView.swift`)
- Player interface → Recent plays: updates history (evidence: `Apps/Mac/UI/PlayerViewController.swift`)
- Finder Quick Look → Quick Look playback: previews media (evidence: `Apps/Mac/QuickLook/Preview/QuickLookPreviewViewController.swift`)
- Quick Look playback → Media playback core: creates preview core (evidence: `Apps/Mac/QuickLook/Preview/QuickLookPreviewViewController.swift`)
- Quick Look playback → Playback sleep control: uses sleep control (evidence: `Apps/Mac/QuickLook/Preview/QuickLookPreviewViewController.swift`)
- Media playback core → Demux and stream reads: reads streams
- Demux and stream reads → Container recovery: uses recovery (evidence: `Modules/MediaCore/Core/Demuxer.cpp`)
- Demux and stream reads → Bitstream resilience: uses resilience (evidence: `Modules/MediaCore/Core/Demuxer.cpp`)
- Media playback core → Motion interpolation: routes interpolation
- Player interface → Caption controls: hosts caption controls (evidence: `Apps/Mac/UI/PlayerViewController.swift`)
- Caption controls → Caption task center: submits tasks (evidence: `Apps/Mac/CaptionsHost/CaptionsController.swift`)
- Caption task center → Caption generation: runs generation (evidence: `Apps/Mac/CaptionsHost/CaptionTaskCenter.swift`)
- Caption generation → Speech transcription: transcribes audio (evidence: `Modules/Captions/CaptionEngine.swift`)
- Caption generation → Caption translation: translates cues (evidence: `Modules/Captions/CaptionEngine.swift`)
- Caption generation → SRT parsing and output: formats sidecars (evidence: `Modules/Captions/CaptionEngine.swift`)
- Mac user → Product and release site: visits site
- Product and release site → Release listings: shows releases (evidence: `Website/src/App.jsx`)
- Release listings → Release catalog: reads catalog (evidence: `Website/src/Releases.jsx`)
- Release edge service → Release catalog: parses catalog (evidence: `Website/cloudflare/index.ts`)