# go2sun/youtube-auto-dub-m4 architecture

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

- Interactive diagram: https://gitdiagram.com/go2sun/youtube-auto-dub-m4
- Repository: https://github.com/go2sun/youtube-auto-dub-m4

## Overview

youtube-auto-dub is a local YouTube video localization tool: a URL is downloaded, transcribed, segmented, translated, optionally dubbed, then rendered with subtitles and a replacement audio track. The graph follows the README’s documented stages and sampled module responsibilities; some orchestration details and unsampled implementations are documented rather than verified in the excerpts.

Main entry points: [`main.py`](https://github.com/go2sun/youtube-auto-dub-m4/blob/main/main.py) (Pipeline CLI), [`src/tts.py`](https://github.com/go2sun/youtube-auto-dub-m4/blob/main/src/tts.py) (Speech Synthesis), [`src/youtube.py`](https://github.com/go2sun/youtube-auto-dub-m4/blob/main/src/youtube.py) (Video Download), [`src/engines.py`](https://github.com/go2sun/youtube-auto-dub-m4/blob/main/src/engines.py) (Whisper ASR)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Workflow Control"]
  node_pipeline["Pipeline CLI<br/>[main.py]"]
  node_download["Video Download<br/>[youtube.py]"]
  node_output["Localized Video"]
end

subgraph group_speech["Speech and Translation"]
  node_transcribe["Whisper ASR<br/>[engines.py]"]
  node_translate["Batch Translation<br/>[googlev4.py]"]
  node_synthesis["Speech Synthesis<br/>[tts.py]"]
end

subgraph group_media["Media Processing"]
  node_chunk["Semantic Chunking<br/>[media.py]"]
  node_mix["Audio Mixing<br/>[media.py]"]
  node_subtitles["SRT Generation<br/>[media.py]"]
  node_render["Video Rendering<br/>[media.py]"]
end

subgraph group_support["Runtime Support"]
  node_project["Project Context<br/>[models.py]"]
  node_language["Language Map<br/>[language_map.json]"]
  node_ui["Terminal Feedback<br/>[ui.py]"]
end

node_user(("YouTube User"))
node_youtube(("YouTube"))
node_whisper(("Whisper Runtime"))
node_google(("Google Translate"))
node_edge(("Edge TTS"))
node_macos(("macOS Speech"))
node_ffmpeg(("FFmpeg"))

node_user -->|"submits URL"| node_pipeline
node_pipeline -->|"requests download"| node_download
node_download -->|"downloads streams"| node_youtube
node_download -->|"creates context"| node_project
node_project -->|"provides audio"| node_transcribe
node_pipeline -->|"runs recognition"| node_transcribe
node_transcribe -->|"runs locally"| node_whisper
node_pipeline -->|"segments transcript"| node_chunk
node_pipeline -->|"sends segments"| node_translate
node_translate -->|"requests translation"| node_google
node_pipeline -->|"generates captions"| node_subtitles
node_pipeline -->|"requests dubbing"| node_synthesis
node_synthesis -.->|"synthesizes speech"| node_edge
node_synthesis -.->|"fallback synthesis"| node_macos
node_language -->|"maps voice"| node_synthesis
node_pipeline -->|"mixes dubbed audio"| node_mix
node_pipeline -->|"renders video"| node_render
node_render -->|"encodes and muxes"| node_ffmpeg
node_pipeline -->|"produces result"| node_output
node_pipeline -->|"reports progress"| node_ui

click node_pipeline "https://github.com/go2sun/youtube-auto-dub-m4/blob/main/main.py"
click node_download "https://github.com/go2sun/youtube-auto-dub-m4/blob/main/src/youtube.py"
click node_project "https://github.com/go2sun/youtube-auto-dub-m4/blob/main/src/models.py"
click node_transcribe "https://github.com/go2sun/youtube-auto-dub-m4/blob/main/src/engines.py"
click node_chunk "https://github.com/go2sun/youtube-auto-dub-m4/blob/main/src/media.py"
click node_translate "https://github.com/go2sun/youtube-auto-dub-m4/blob/main/src/googlev4.py"
click node_language "https://github.com/go2sun/youtube-auto-dub-m4/blob/main/language_map.json"
click node_synthesis "https://github.com/go2sun/youtube-auto-dub-m4/blob/main/src/tts.py"
click node_mix "https://github.com/go2sun/youtube-auto-dub-m4/blob/main/src/media.py"
click node_subtitles "https://github.com/go2sun/youtube-auto-dub-m4/blob/main/src/media.py"
click node_render "https://github.com/go2sun/youtube-auto-dub-m4/blob/main/src/media.py"
click node_ui "https://github.com/go2sun/youtube-auto-dub-m4/blob/main/src/ui.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_pipeline,node_download,node_output,node_user toneBlue
class node_transcribe,node_translate,node_synthesis toneAmber
class node_chunk,node_mix,node_subtitles,node_render toneMint
class node_project,node_language,node_ui toneRose
class node_youtube,node_whisper,node_google,node_edge,node_macos,node_ffmpeg toneIndigo
```

## Components

### Workflow Control

- [Pipeline CLI](https://github.com/go2sun/youtube-auto-dub-m4/blob/main/main.py): `main.py`
- [Video Download](https://github.com/go2sun/youtube-auto-dub-m4/blob/main/src/youtube.py): `src/youtube.py`
- **Localized Video**

### Speech and Translation

- [Whisper ASR](https://github.com/go2sun/youtube-auto-dub-m4/blob/main/src/engines.py): `src/engines.py`
- [Batch Translation](https://github.com/go2sun/youtube-auto-dub-m4/blob/main/src/googlev4.py): `src/googlev4.py`
- [Speech Synthesis](https://github.com/go2sun/youtube-auto-dub-m4/blob/main/src/tts.py): `src/tts.py`

### Media Processing

- [Semantic Chunking](https://github.com/go2sun/youtube-auto-dub-m4/blob/main/src/media.py): `src/media.py`
- [Audio Mixing](https://github.com/go2sun/youtube-auto-dub-m4/blob/main/src/media.py): `src/media.py`
- [SRT Generation](https://github.com/go2sun/youtube-auto-dub-m4/blob/main/src/media.py): `src/media.py`
- [Video Rendering](https://github.com/go2sun/youtube-auto-dub-m4/blob/main/src/media.py): `src/media.py`

### Runtime Support

- [Project Context](https://github.com/go2sun/youtube-auto-dub-m4/blob/main/src/models.py): `src/models.py`
- [Language Map](https://github.com/go2sun/youtube-auto-dub-m4/blob/main/language_map.json): `language_map.json`
- [Terminal Feedback](https://github.com/go2sun/youtube-auto-dub-m4/blob/main/src/ui.py): `src/ui.py`

### Other components

- **YouTube User**
- **YouTube**
- **Whisper Runtime**
- **Google Translate**
- **Edge TTS**
- **macOS Speech**
- **FFmpeg**

## Connections

- YouTube User → Pipeline CLI: submits URL
- Pipeline CLI → Video Download: requests download
- Video Download → YouTube: downloads streams
- Video Download → Project Context: creates context
- Project Context → Whisper ASR: provides audio
- Pipeline CLI → Whisper ASR: runs recognition
- Whisper ASR → Whisper Runtime: runs locally
- Pipeline CLI → Semantic Chunking: segments transcript
- Pipeline CLI → Batch Translation: sends segments
- Batch Translation → Google Translate: requests translation
- Pipeline CLI → SRT Generation: generates captions
- Pipeline CLI → Speech Synthesis: requests dubbing
- Speech Synthesis → Edge TTS: synthesizes speech
- Speech Synthesis → macOS Speech: fallback synthesis
- Language Map → Speech Synthesis: maps voice
- Pipeline CLI → Audio Mixing: mixes dubbed audio
- Pipeline CLI → Video Rendering: renders video
- Video Rendering → FFmpeg: encodes and muxes
- Pipeline CLI → Localized Video: produces result
- Pipeline CLI → Terminal Feedback: reports progress