# udayatk/video-translator architecture

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

- Interactive diagram: https://gitdiagram.com/udayatk/video-translator
- Repository: https://github.com/udayatk/video-translator

## Overview

##### Project type and purpose
- This is a small full-stack Python application built with Streamlit (single “app.py” entry point).
- Purpose: take an English video, extract its audio, transcribe speech to text, translate that text into Indian regional languages, generate synthetic voiceovers in the target language, replace the original audio track, then bundle the dubbed video plus transcripts into a downloadable ZIP.

##### File structure
- Top-level files
– app.py: contains both the Streamlit UI and the entire backend pipeline.
– requirements.txt: lists Python dependencies (e.g., ffmpeg-wrapper, OpenAI/Whisper, googletrans, gTTS or pyttsx3, moviepy).
– README.md: high-level description.
- .streamlit/config.toml
– Streamlit configuration (server settings, theming, etc.)

##### Extract key points from the README
- Workflow steps: audio extraction → transcription → translation → voiceover generation → audio replacement → packaging.
- Targets multiple Indian languages (Hindi, Telugu, Tamil, etc.).
- Outputs: dubbed video and original & translated transcripts in ZIP.

##### Main components
a. Streamlit Web UI
– Components: file uploader, language selector, “Translate” button, progress indicators, download link.
b. Backend Pipeline (Python functions/modules)
1. Video Ingestion & Audio Extraction (ffmpeg)
2. Speech-to-Text Transcription (e.g., OpenAI Whisper or other STT API)
3. Text Translation (googletrans or similar)
4. Text-to-Speech Synthesis (gTTS / pyttsx3)
5. Audio-Video Merging (moviepy or ffmpeg)
6. Packaging & ZIP Creation (built-in zipfile or shutil)
c. Storage / Temporary Files
– Local temp directory or in-memory streams for intermediate audio, text, and final video.
d. Client Download Endpoint (Streamlit file download component)

##### Relationships & data flow
- TTS to generate audio tracks per target language
- Packaging of original transcript

##### Architectural patterns & design principles
- Pipeline (staged processing) pattern – each transformation is a distinct module.
- Separation of concerns – UI logic vs. processing logic.
- Stateless, request-driven design – each upload triggers a fresh pipeline run.
- Extensibility point – add or swap out a translation or TTS engine by abstracting that stage.

##### Technologies & frameworks
- Streamlit: front-end UI server.
- ffmpeg (via subprocess or ffmpeg-python): audio extraction & merging.
- Whisper / other STT API: transcription.
- googletrans / DeepL API: translation.
- gTTS / pyttsx3: TTS.
- moviepy or direct ffmpeg: video editing.
- zipfile (Python stdlib): packaging.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "Frontend: Streamlit UI"
        direction TB
        UI(["Streamlit Web UI"]):::io
    end

    %% Configuration & Docs
    subgraph "Configuration & Documentation"
        direction TB
        Config[".streamlit/config.toml"]:::config
        Deps["requirements.txt"]:::config
        Readme["README.md"]:::config
    end

    %% External Services
    subgraph "External APIs"
        direction TB
        STTAPI[("Speech-to-Text API")]:::external
        TransAPI[("Translation API")]:::external
    end

    %% Storage
    Storage[(Temp Storage)]:::storage

    %% Backend Pipeline
    subgraph "Backend Pipeline"
        direction TB
        Extraction(("Video Ingestion & Audio Extraction")):::media
        Transcription(("Speech-to-Text Transcription")):::process
        Translation(("Text Translation")):::process
        TTS(("Text-to-Speech Synthesis")):::process
        Merging(("Audio-Video Merging")):::media
        Packaging(("Packaging & ZIP Creation")):::storage
    end

    %% Legend
    subgraph "Legend"
        direction TB
        L1(["Blue: I/O components"]):::io
        L2(["Green: Processing stages"]):::process
        L3(["Orange: Media handling"]):::media
        L4(["Gray: Packaging/Storage"]):::storage
        L5(["Dashed: External services"]):::external
    end

    %% Data Flow
    UI -->|".mp4 buffer"| Extraction
    Extraction -->|".wav audio"| Transcription
    Transcription -->|".txt transcript"| Translation
    Translation -->|".txt translated text"| TTS
    Translation -->|".txt transcript"| Packaging
    TTS -->|".mp3 voiceover"| Merging
    Extraction --> Storage
    Transcription --> Storage
    Translation --> Storage
    TTS --> Storage
    Merging -->|".mp4 dubbed video"| Packaging
    Packaging -->|".zip archive"| UI

    %% External Calls
    Transcription -->|calls| STTAPI
    Translation -->|calls| TransAPI

    %% Config & Docs Integration
    Config --> UI
    Deps --> UI
    Readme --> UI

    %% Click Events
    click UI "https://github.com/udayatk/video-translator/blob/main/app.py"
    click Extraction "https://github.com/udayatk/video-translator/blob/main/app.py"
    click Transcription "https://github.com/udayatk/video-translator/blob/main/app.py"
    click Translation "https://github.com/udayatk/video-translator/blob/main/app.py"
    click TTS "https://github.com/udayatk/video-translator/blob/main/app.py"
    click Merging "https://github.com/udayatk/video-translator/blob/main/app.py"
    click Packaging "https://github.com/udayatk/video-translator/blob/main/app.py"
    click Config "https://github.com/udayatk/video-translator/blob/main/.streamlit/config.toml"
    click Deps "https://github.com/udayatk/video-translator/blob/main/requirements.txt"
    click Readme "https://github.com/udayatk/video-translator/blob/main/README.md"

    %% Styles
    classDef io fill:#D0E8FF,stroke:#0366d6,color:#0366d6,stroke-width:1px;
    classDef process fill:#E6F4EA,stroke:#22863a,color:#22863a,stroke-width:1px;
    classDef media fill:#FFF5E5,stroke:#D29922,color:#D29922,stroke-width:1px;
    classDef storage fill:#F0F0F0,stroke:#6A737D,color:#6A737D,stroke-width:1px;
    classDef external stroke-dasharray: 5 5,stroke:#CCCCCC,color:#586069;
```
