# kagerun/predub architecture

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

- Interactive diagram: https://gitdiagram.com/kagerun/predub
- Repository: https://github.com/kagerun/predub

## Overview

predub is a local video dubbing application: a CLI or browser player requests a target-language dub, the service fetches/decodes media and runs speech recognition, optional speaker attribution, translation and voice synthesis, then buffers timed audio for playback or writes dubbed output. The graph preserves the documented browser-extension, language/voice and vocal-separation capabilities. Some wiring is omitted because the supplied source excerpts are partial; paths for documented but unsampled subsystems use their exact tree entries.

Main entry points: [`predub/stream.py`](https://github.com/kagerun/predub/blob/main/predub/stream.py) (Lookahead scheduler), [`predub/cli.py`](https://github.com/kagerun/predub/blob/main/predub/cli.py) (CLI workflows), [`extension/content.js`](https://github.com/kagerun/predub/blob/main/extension/content.js) (Extension controls), [`predub/server.py`](https://github.com/kagerun/predub/blob/main/predub/server.py) (Player HTTP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_cli["CLI workflows<br/>[cli.py]"]
  node_extension["Extension controls<br/>[content.js]"]
  node_popup["Language settings<br/>[popup.js]"]
end

subgraph group_media["Media acquisition"]
  node_fetch["Media fetching<br/>[fetch.py]"]
  node_mediaio["Media decode encode<br/>[env.py]"]
end

subgraph group_pipeline["Dub pipeline"]
  node_scheduler["Lookahead scheduler<br/>[stream.py]"]
  node_asr["Speech recognition<br/>[asr.py]"]
  node_separation["Vocal separation<br/>[separate.py]"]
  node_diarize["Speaker diarisation<br/>[diarize.py]"]
  node_translate["Text translation<br/>[translate.py]"]
  node_dubber["Timed dub rendering<br/>[dub.py]"]
  node_tts["Speech synthesis<br/>[tts.py]"]
  node_clone["Voice cloning<br/>[xtts.py]"]
end

subgraph group_delivery["Playback and output"]
  node_player_server["Player HTTP server<br/>[server.py]"]
  node_player["Buffered web player<br/>[player.html]"]
end

subgraph group_support["Local runtime services"]
  node_daemon["Session daemon<br/>[daemon.py]"]
  node_settings[("Live settings<br/>[settings.py]")]
  node_languages["Language catalog<br/>[langs.py]"]
end

node_viewer(("Viewer"))
node_browser(("Browser video page"))
node_voice_models[("Neural voice models")]
node_video_source(("Video source"))

node_viewer -->|"runs workflow"| node_cli
node_cli -->|"decodes media"| node_mediaio
node_cli -->|"starts pipeline"| node_scheduler
node_cli -->|"starts player"| node_player_server
node_video_source -->|"provides URL media"| node_fetch
node_daemon -->|"fetches source"| node_fetch
node_fetch -->|"provides media"| node_mediaio
node_scheduler -->|"reads audio"| node_mediaio
node_scheduler -->|"transcribes audio"| node_asr
node_scheduler -.->|"separates vocals"| node_separation
node_scheduler -.->|"assigns speakers"| node_diarize
node_scheduler -->|"translates text"| node_translate
node_scheduler -->|"renders timed lines"| node_dubber
node_dubber -->|"synthesizes speech"| node_tts
node_dubber -.->|"clones speaker voice"| node_clone
node_tts -->|"loads voice"| node_voice_models
node_scheduler -->|"reads live options"| node_settings
node_cli -->|"lists languages"| node_languages
node_viewer -->|"opens video"| node_browser
node_browser -->|"hosts controls"| node_extension
node_popup -->|"stores preferences"| node_settings
node_extension -->|"creates session"| node_daemon
node_daemon -->|"starts session pipeline"| node_scheduler
node_extension -->|"polls session"| node_daemon
node_extension -->|"schedules audio"| node_player
node_player_server -->|"reads chunks"| node_scheduler
node_player_server -->|"serves player"| node_player
node_scheduler -->|"publishes chunks"| node_player_server
node_cli -->|"writes dubbed output"| node_mediaio

click node_cli "https://github.com/kagerun/predub/blob/main/predub/cli.py"
click node_extension "https://github.com/kagerun/predub/blob/main/extension/content.js"
click node_popup "https://github.com/kagerun/predub/blob/main/extension/popup.js"
click node_daemon "https://github.com/kagerun/predub/blob/main/predub/daemon.py"
click node_fetch "https://github.com/kagerun/predub/blob/main/predub/fetch.py"
click node_mediaio "https://github.com/kagerun/predub/blob/main/predub/env.py"
click node_scheduler "https://github.com/kagerun/predub/blob/main/predub/stream.py"
click node_asr "https://github.com/kagerun/predub/blob/main/predub/asr.py"
click node_separation "https://github.com/kagerun/predub/blob/main/predub/separate.py"
click node_diarize "https://github.com/kagerun/predub/blob/main/predub/diarize.py"
click node_translate "https://github.com/kagerun/predub/blob/main/predub/translate.py"
click node_dubber "https://github.com/kagerun/predub/blob/main/predub/dub.py"
click node_tts "https://github.com/kagerun/predub/blob/main/predub/tts.py"
click node_clone "https://github.com/kagerun/predub/blob/main/predub/xtts.py"
click node_player_server "https://github.com/kagerun/predub/blob/main/predub/server.py"
click node_player "https://github.com/kagerun/predub/blob/main/predub/web/player.html"
click node_settings "https://github.com/kagerun/predub/blob/main/predub/settings.py"
click node_languages "https://github.com/kagerun/predub/blob/main/predub/langs.py"

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_cli,node_extension,node_popup,node_viewer,node_browser toneBlue
class node_fetch,node_mediaio,node_voice_models toneAmber
class node_scheduler,node_asr,node_separation,node_diarize,node_translate,node_dubber,node_tts,node_clone toneMint
class node_player_server,node_player toneRose
class node_daemon,node_settings,node_languages,node_video_source toneIndigo
```

## Components

### User entry points

- [CLI workflows](https://github.com/kagerun/predub/blob/main/predub/cli.py): `predub/cli.py`
- [Extension controls](https://github.com/kagerun/predub/blob/main/extension/content.js): `extension/content.js`
- [Language settings](https://github.com/kagerun/predub/blob/main/extension/popup.js): `extension/popup.js`

### Media acquisition

- [Media fetching](https://github.com/kagerun/predub/blob/main/predub/fetch.py): `predub/fetch.py`
- [Media decode encode](https://github.com/kagerun/predub/blob/main/predub/env.py): `predub/env.py`

### Dub pipeline

- [Lookahead scheduler](https://github.com/kagerun/predub/blob/main/predub/stream.py): `predub/stream.py`
- [Speech recognition](https://github.com/kagerun/predub/blob/main/predub/asr.py): `predub/asr.py`
- [Vocal separation](https://github.com/kagerun/predub/blob/main/predub/separate.py): `predub/separate.py`
- [Speaker diarisation](https://github.com/kagerun/predub/blob/main/predub/diarize.py): `predub/diarize.py`
- [Text translation](https://github.com/kagerun/predub/blob/main/predub/translate.py): `predub/translate.py`
- [Timed dub rendering](https://github.com/kagerun/predub/blob/main/predub/dub.py): `predub/dub.py`
- [Speech synthesis](https://github.com/kagerun/predub/blob/main/predub/tts.py): `predub/tts.py`
- [Voice cloning](https://github.com/kagerun/predub/blob/main/predub/xtts.py): `predub/xtts.py`

### Playback and output

- [Player HTTP server](https://github.com/kagerun/predub/blob/main/predub/server.py): `predub/server.py`
- [Buffered web player](https://github.com/kagerun/predub/blob/main/predub/web/player.html): `predub/web/player.html`

### Local runtime services

- [Session daemon](https://github.com/kagerun/predub/blob/main/predub/daemon.py): `predub/daemon.py`
- [Live settings](https://github.com/kagerun/predub/blob/main/predub/settings.py): `predub/settings.py`
- [Language catalog](https://github.com/kagerun/predub/blob/main/predub/langs.py): `predub/langs.py`

### Other components

- **Viewer**
- **Browser video page**
- **Neural voice models**
- **Video source**

## Connections

- Viewer → CLI workflows: runs workflow
- CLI workflows → Media decode encode: decodes media
- CLI workflows → Lookahead scheduler: starts pipeline
- CLI workflows → Player HTTP server: starts player
- Video source → Media fetching: provides URL media
- Session daemon → Media fetching: fetches source
- Media fetching → Media decode encode: provides media
- Lookahead scheduler → Media decode encode: reads audio
- Lookahead scheduler → Speech recognition: transcribes audio
- Lookahead scheduler → Vocal separation: separates vocals
- Lookahead scheduler → Speaker diarisation: assigns speakers
- Lookahead scheduler → Text translation: translates text
- Lookahead scheduler → Timed dub rendering: renders timed lines
- Timed dub rendering → Speech synthesis: synthesizes speech
- Timed dub rendering → Voice cloning: clones speaker voice
- Speech synthesis → Neural voice models: loads voice
- Lookahead scheduler → Live settings: reads live options
- CLI workflows → Language catalog: lists languages
- Viewer → Browser video page: opens video
- Browser video page → Extension controls: hosts controls
- Language settings → Live settings: stores preferences
- Extension controls → Session daemon: creates session
- Session daemon → Lookahead scheduler: starts session pipeline
- Extension controls → Session daemon: polls session
- Extension controls → Buffered web player: schedules audio
- Player HTTP server → Lookahead scheduler: reads chunks
- Player HTTP server → Buffered web player: serves player
- Lookahead scheduler → Player HTTP server: publishes chunks
- CLI workflows → Media decode encode: writes dubbed output