# mikk0git/youtube-auto-dubbing architecture

> Architecture diagram of the GitHub repository mikk0git/youtube-auto-dubbing, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mikk0git/youtube-auto-dubbing
- Repository: https://github.com/mikk0git/youtube-auto-dubbing

## Overview

##### Project type and purpose
- This is a small command-line tool (“Youtube Auto Dubbing”) that takes a YouTube URL, downloads the video, extracts or uses provided subtitles, translates them into a target language, generates AI voice via TTS, re-syncs audio to match lip movements, and outputs a dubbed video.

##### File structure
- At the top level you have:
- main.py – the single entry point and orchestrator
- requirements.txt – Python dependencies
- rubberband.exe / rubberband-r3.exe – native audio time-stretching utilities
- README.md, LICENSE, .gitignore – supporting documentation
- No separate frontend/backend—this is a monolithic CLI app
- External dependencies: Python packages, FFmpeg, Rubberband

##### Key insights from the README
- Usage flags for language, subtitle folder, and “audio only” mode
- Depends on FFmpeg for media handling, uses pure-Python TTS/translation (no cloud APIs)
- Future plans: GUI, add 11Labs voice support

##### Components & relationships
a. Main Components
1. CLI Parser (main.py)
2. YouTube Downloader (e.g., pytube or yt-dl)
3. Media Extractor (FFmpeg)
4. Subtitle Loader / Parser (built-in or from file)
5. Translator Service (local translation library)
6. TTS Engine (local AI voice generator)
7. Audio Sync Module (Rubberband)
8. Media Merger (FFmpeg)
9. Output Writer (final video/audio file)
10. External Dependencies (FFmpeg, rubberband.exe)

b. Data flows & interactions
- User types “python main.py <URL> -l de” → CLI Parser
- CLI Parser calls YouTube Downloader → raw video + source subtitles
- Media Extractor splits video into audio track and frames/subtitles
- Subtitle Loader reads custom or extracted subtitles
- Translator turns source lines into target‐language lines
- TTS Engine converts translated lines into speech audio clips
- Audio Sync Module (rubberband) adjusts timing/duration of speech to match original pacing
- Media Merger uses FFmpeg to combine original video frames with dubbed audio
- Output Writer saves final dubbed video (or audio only)

c. Architectural patterns & design principles
- Single orchestrator script following a pipeline pattern—each step takes input, transforms it, passes it onward
- Clear separation between download, transform (translate/TTS), sync, and output stages
- External tools (FFmpeg, rubberband) invoked as subprocesses

d. Key technologies / libraries
- Python (main.py)
- FFmpeg (command-line)
- Rubberband (audio time-stretch)
- pytube or youtube-dl (video download)
- translation & TTS Python packages

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User invocation
    A["User invokes CLI\npython main.py <URL> -l <lang>"]:::orchestration

    %% Orchestration
    subgraph "Orchestrator (main.py)"
        direction TB
        CLI["CLI Parser"]:::orchestration
        Downloader["YouTube Downloader"]:::orchestration
        SubLoader["Subtitle Loader / Parser"]:::orchestration
        Translator["Translator Service"]:::transform
        TTS["TTS Engine"]:::transform
        Merger["Media Merger"]:::orchestration
        OutputWriter["Output Writer"]:::orchestration
    end

    %% External services/tools
    subgraph "External Tools & Services"
        direction TB
        YT["YouTube Service"]:::external
        FFmpeg1["FFmpeg (extract)"]:::external
        FFmpeg2["FFmpeg (merge)"]:::external
        RB["Rubberband"]:::external
    end

    %% Data artifacts
    RawVideo["Raw Video"]:::data
    SrcSubs["Source Subtitles"]:::data
    AudioTrack["Audio Track"]:::data
    VideoFrames["Video Frames"]:::data
    TransText["Translated Text"]:::data
    SpeechAudio["Speech Audio"]:::data
    SyncedAudio["Synced Speech Audio"]:::data
    FinalVideo["Final Dubbed Video"]:::data

    %% Process flow
    A --> CLI
    CLI -->|"calls"| Downloader
    Downloader -->|"raw video.mp4"| RawVideo
    Downloader -->|".srt"| SrcSubs
    RawVideo --> FFmpeg1
    FFmpeg1 -->|"audio.wav"| AudioTrack
    FFmpeg1 -->|"frames/*"| VideoFrames
    SrcSubs --> SubLoader
    SubLoader -->|"subtitle lines"| SubLoaderOut[subtitle lines]
    SubLoaderOut --> Translator
    Translator -->|"translated text"| TransText
    TransText --> TTS
    TTS -->|"speech.wav"| SpeechAudio
    SpeechAudio --> RB
    RB -->|"synced.wav"| SyncedAudio
    VideoFrames --> Merger
    SyncedAudio --> Merger
    Merger --> FFmpeg2
    FFmpeg2 --> FinalVideo
    FinalVideo --> OutputWriter

    %% Documentation & dependencies
    Doc["Docs & Metadata"]:::documentation
    Req["requirements.txt"]:::documentation
    Doc --> Req

    %% Click events
    click CLI "https://github.com/mikk0git/youtube-auto-dubbing/blob/main/main.py"
    click Downloader "https://github.com/mikk0git/youtube-auto-dubbing/blob/main/main.py"
    click SubLoader "https://github.com/mikk0git/youtube-auto-dubbing/blob/main/main.py"
    click Translator "https://github.com/mikk0git/youtube-auto-dubbing/blob/main/main.py"
    click TTS "https://github.com/mikk0git/youtube-auto-dubbing/blob/main/main.py"
    click Merger "https://github.com/mikk0git/youtube-auto-dubbing/blob/main/main.py"
    click OutputWriter "https://github.com/mikk0git/youtube-auto-dubbing/blob/main/main.py"
    click RB "https://github.com/mikk0git/youtube-auto-dubbing/blob/main/rubberband.exe"
    click RB "https://github.com/mikk0git/youtube-auto-dubbing/blob/main/rubberband-r3.exe"
    click Req "https://github.com/mikk0git/youtube-auto-dubbing/blob/main/requirements.txt"
    click Doc "https://github.com/mikk0git/youtube-auto-dubbing/blob/main/README.md"
    click Doc "https://github.com/mikk0git/youtube-auto-dubbing/tree/main/LICENSE"
    click Doc "https://github.com/mikk0git/youtube-auto-dubbing/blob/main/.gitignore"

    %% Styles
    classDef orchestration fill:#cce5ff,stroke:#4da3ff,color:#004085
    classDef external fill:#d4edda,stroke:#28a745,color:#155724
    classDef transform fill:#fff3cd,stroke:#ffc107,color:#856404
    classDef data fill:#e2e3e5,stroke:#6c757d,color:#383d41
    classDef documentation fill:#f8d7da,stroke:#dc3545,color:#721c24
```
