# marouane53/transcribe architecture

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

- Interactive diagram: https://gitdiagram.com/marouane53/transcribe
- Repository: https://github.com/marouane53/transcribe

## Overview

##### Project type and purpose
- This is an open-source, single-script CLI tool for transcribing audio/video files (local or YouTube) via the Wit.ai API.
- It’s not a web or full-stack app but a standalone Python-based pipeline that orchestrates downloads, media conversion, API calls, and file output.

##### Main components
A. CLI / Entry Point (transcribe.py)
- Parses user input (YouTube URL vs. local file, language choice).
- Loads configuration (.env via python-dotenv).
B. Configuration Manager
- Reads environment variables (WIT_API_KEY_*).
- Feeds API keys into the transcription module.
C. Download Manager (yt-dlp)
- If a YouTube URL is provided, invokes yt-dlp to fetch audio/video.
- Stores downloaded media under `downloads/`.
D. Media Processor (ffmpeg, ffmpeg-python, pydub)
- Converts MP3→WAV, extracts audio from video containers (MP4/MKV/AVI).
- Ensures input to transcription is always WAV.
E. Transcription Core (tafrigh[wit] wrapper)
- Sends audio chunks to Wit.ai using the appropriate API key.
- Receives JSON/text responses.
F. Output Generator
- Transforms transcription results into .TXT and .SRT files.
- Writes them next to the source media.
G. External Services
- Wit.ai for speech-to-text.
- YouTube as an optional download source.

##### Relationships and data flow
1. User invokes transcribe.py via CLI.
2. Config Manager loads API keys.
3. CLI hands off to Download Manager (if needed) or directly to Media Processor.
4. Media Processor normalizes to WAV.
5. Normalized audio → Transcription Core → Wit.ai.
6. API returns text → Output Generator → TXT/SRT.

CLI → Config Manager
↓
Download Manager → Media Processor → Transcription Core → Output Generator

##### Architectural patterns & design principles
- Pipeline/Chain of Responsibility: each module performs one step and passes results downstream.
- Single-process, modular separation: each concern (download, convert, transcribe, output) is encapsulated.
- External-service integration: clearly delineate boundaries between local processing and remote API calls.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Docker image: transcribe-app"
        direction TB
        CLI["transcribe.py (CLI)"]:::cli
        Config["Config Manager (.env reader)"]:::config
        Download["Download Manager (yt-dlp)"]:::local
        Processor["Media Processor (ffmpeg/pydub)"]:::local
        Transcriber["Transcription Core (tafrigh+Wit.ai)"]:::externalCall
        Output["Output Generator (TXT/SRT writer)"]:::local
    end

    HostDownloads[(downloads/)]:::storage
    YouTubeCloud((YouTube)):::external
    WitCloud((Wit.ai API)):::external

    CLI -->|"parses input"| Config
    Config -->|"provides API keys"| Download
    CLI --> Download
    Download -->|"media file"| Processor
    Processor -->|"WAV audio"| Transcriber
    Transcriber -->|"JSON transcript"| Output
    Download --> HostDownloads
    Output --> HostDownloads

    Transcriber <-->|"speech-to-text request/response"| WitCloud
    YouTubeCloud -->|"video/audio"| Download
    HostDownloads -.-> Download

    click CLI "https://github.com/marouane53/transcribe/blob/main/transcribe.py"
    click Config "https://github.com/marouane53/transcribe/blob/main/.env.example"
    click Config "https://github.com/marouane53/transcribe/blob/main/transcribe.py"
    click Download "https://github.com/marouane53/transcribe/blob/main/transcribe.py"
    click Processor "https://github.com/marouane53/transcribe/blob/main/transcribe.py"
    click Transcriber "https://github.com/marouane53/transcribe/blob/main/transcribe.py"
    click Output "https://github.com/marouane53/transcribe/blob/main/transcribe.py"
    click Dockerfile "https://github.com/marouane53/transcribe/tree/main/Dockerfile"
    click Requirements "https://github.com/marouane53/transcribe/blob/main/requirements.txt"
    click README "https://github.com/marouane53/transcribe/blob/main/README.md"
    click EnvExample "https://github.com/marouane53/transcribe/blob/main/.env.example"
    click License "https://github.com/marouane53/transcribe/tree/main/LICENSE"
    click Gitignore "https://github.com/marouane53/transcribe/blob/main/.gitignore"

    classDef cli fill:#ddd,stroke:#333;
    classDef config fill:#ddd,stroke:#333;
    classDef local fill:#9f6,stroke:#333;
    classDef externalCall fill:#f96,stroke:#333;
    classDef external fill:#bbf,stroke:#333,stroke-dasharray:5 5;
    classDef storage fill:#ccf,stroke:#333,stroke-dasharray:2 2;
```
