# ysn-b13/sub2voice architecture

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

- Interactive diagram: https://gitdiagram.com/ysn-b13/sub2voice
- Repository: https://github.com/ysn-b13/sub2voice

## Overview

1. **Overall shape**
   - This is a small Flask application with a thin web layer and most of the work done in a local Python package, `Sub2Voice/`.
   - The architecture is request-driven: a user submits a YouTube URL, the server fetches subtitles, parses them, optionally translates them, and renders the result back in HTML.

2. **Entry point and orchestration**
   - `main.py` is the application entry point and likely owns Flask setup, route registration, environment loading, and request flow coordination.
   - It acts as the boundary between the browser-facing UI and the subtitle/translation logic.

3. **Presentation layer**
   - `templates/` contains the server-rendered pages: landing page, “get started” form, English subtitle view, and Arabic subtitle view.
   - `static/css/` and `static/js/` provide styling and client-side behavior, but the app is primarily server-rendered rather than a SPA.

4. **Subtitle acquisition subsystem**
   - `Sub2Voice/Subtitle.py` is responsible for pulling subtitles from YouTube using `yt-dlp`.
   - This subsystem is the first external integration point and transforms a YouTube URL into a local subtitle artifact, usually an SRT file.

5. **Subtitle parsing subsystem**
   - `Sub2Voice/SRT_file.py` and `Sub2Voice/SRT_timestamp.py` parse SRT structure and timestamps into usable subtitle segments.
   - The parser preserves the core SRT fields: sequence number, start time, end time, and text, which are then used for display and translation.

6. **Translation subsystem**
   - `Sub2Voice/Translate.py` handles translation into Arabic using the Google Gemini API.
   - The README indicates chunking is used, which suggests the translation layer groups subtitle text to fit API limits while preserving segment boundaries as much as possible.

7. **Formatting and view helpers**
   - `Sub2Voice/format_time.py` is a Jinja2-oriented helper/filter for formatting timestamps in the templates.
   - This is a small but important boundary: raw parsed times are converted into presentation-friendly strings at render time.

8. **Data flow through the app**
   - The main flow is: YouTube URL → subtitle download via `yt-dlp` → SRT parsing → English subtitle rendering → optional Arabic translation via Gemini → Arabic rendering.
   - The English and Arabic views are separate outputs from the same underlying subtitle dataset rather than independent pipelines.

9. **Runtime and external services**
   - The app depends on Flask for request handling and templating, `yt-dlp` for subtitle extraction, and `google-generativeai` for translation.
   - `python-dotenv` and environment variables supply secrets such as `FLASK_SECRET_KEY` and `GOOGLE_API_KEY`, so configuration is externalized from code.

10. **Temporary file boundary**
   - The README references a `temp_subtitles/` working area for generated `.srt` files.
   - This indicates the app uses ephemeral filesystem storage during processing rather than a database or persistent content store.

11. **State and persistence**
   - There is no sign of a database, message queue, or user account system.
   - The app appears stateless across requests except for temporary subtitle files and whatever in-memory data is used during one request/translation cycle.

12. **What to show in an architecture diagram**
   - A clean diagram would center on `main.py` as the orchestrator, with three internal boxes beneath it: subtitle download, SRT parsing, and translation.
   - Surround those with the external dependencies: browser/UI on one side, YouTube/yt-dlp and Gemini API on the other, plus a temporary filesystem boundary for generated subtitle files.

Main entry points: [`main.py`](https://github.com/ysn-b13/sub2voice/blob/main/main.py) (main.py), [`Sub2Voice/Subtitle.py`](https://github.com/ysn-b13/sub2voice/blob/main/Sub2Voice/Subtitle.py) (Subtitle fetch), [`templates/base.html`](https://github.com/ysn-b13/sub2voice/blob/main/templates/base.html) (Base layout), [`Sub2Voice/SRT_file.py`](https://github.com/ysn-b13/sub2voice/blob/main/Sub2Voice/SRT_file.py) (SRT parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_home_template["Home page<br/>Jinja template<br/>[homepage.html]"]
  node_start_template["Get started<br/>Jinja template<br/>[get_started.html]"]
  node_show_sub_template["English view<br/>Jinja template<br/>[show_sub.html]"]
  node_show_sub_ar_template["Arabic view<br/>Jinja template<br/>[show_sub_ar.html]"]
  node_base_template["Base layout<br/>Jinja layout<br/>[base.html]"]
  node_css_assets["Stylesheets<br/>CSS assets"]
  node_js_assets["Client scripts<br/>JavaScript assets"]
end

subgraph group_core["Core App"]
  node_main["main.py<br/>Flask entrypoint<br/>[main.py]"]
  node_subtitle_fetch["Subtitle fetch<br/>yt-dlp adapter<br/>[Subtitle.py]"]
  node_srt_parse["SRT parser<br/>subtitle parser<br/>[SRT_file.py]"]
  node_timestamp_parse["Time parser<br/>timestamp helper<br/>[SRT_timestamp.py]"]
  node_translate["Translator<br/>Gemini client<br/>[Translate.py]"]
  node_format_time["Format time<br/>template helper<br/>[format_time.py]"]
end

subgraph group_external["External Systems"]
  node_browser(("Browser<br/>user interface"))
  node_youtube(("YouTube<br/>content source"))
  node_yt_dlp(("yt-dlp<br/>extraction library"))
  node_gemini_api(("Gemini API<br/>translation service"))
  node_env(("Env vars<br/>config source"))
  node_flask(("Flask<br/>web framework"))
end

subgraph group_storage["Working Files"]
  node_temp_files[("Temp subtitles<br/>working files")]
end

node_browser -->|"submit URL"| node_main
node_main -->|"serve"| node_flask
node_main -->|"load config"| node_env
node_main -->|"render"| node_home_template
node_main -->|"render"| node_start_template
node_main -->|"download"| node_subtitle_fetch
node_subtitle_fetch -->|"source"| node_youtube
node_subtitle_fetch -->|"uses"| node_yt_dlp
node_subtitle_fetch -->|"write SRT"| node_temp_files
node_main -->|"parse"| node_srt_parse
node_srt_parse -->|"uses"| node_timestamp_parse
node_srt_parse -->|"feed view"| node_show_sub_template
node_show_sub_template -->|"format"| node_format_time
node_main -->|"translate"| node_translate
node_translate -->|"call"| node_gemini_api
node_main -->|"render"| node_show_sub_ar_template
node_show_sub_ar_template -->|"format"| node_format_time
node_main -->|"compose"| node_base_template
node_base_template -->|"style"| node_css_assets
node_base_template -->|"script"| node_js_assets

click node_main "https://github.com/ysn-b13/sub2voice/blob/main/main.py"
click node_home_template "https://github.com/ysn-b13/sub2voice/blob/main/templates/homepage.html"
click node_start_template "https://github.com/ysn-b13/sub2voice/blob/main/templates/get_started.html"
click node_show_sub_template "https://github.com/ysn-b13/sub2voice/blob/main/templates/show_sub.html"
click node_show_sub_ar_template "https://github.com/ysn-b13/sub2voice/blob/main/templates/show_sub_ar.html"
click node_base_template "https://github.com/ysn-b13/sub2voice/blob/main/templates/base.html"
click node_css_assets "https://github.com/ysn-b13/sub2voice/tree/main/static/css"
click node_js_assets "https://github.com/ysn-b13/sub2voice/tree/main/static/js"
click node_subtitle_fetch "https://github.com/ysn-b13/sub2voice/blob/main/Sub2Voice/Subtitle.py"
click node_srt_parse "https://github.com/ysn-b13/sub2voice/blob/main/Sub2Voice/SRT_file.py"
click node_timestamp_parse "https://github.com/ysn-b13/sub2voice/blob/main/Sub2Voice/SRT_timestamp.py"
click node_translate "https://github.com/ysn-b13/sub2voice/blob/main/Sub2Voice/Translate.py"
click node_format_time "https://github.com/ysn-b13/sub2voice/blob/main/Sub2Voice/format_time.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_home_template,node_start_template,node_show_sub_template,node_show_sub_ar_template,node_base_template,node_css_assets,node_js_assets toneBlue
class node_main,node_subtitle_fetch,node_srt_parse,node_timestamp_parse,node_translate,node_format_time toneAmber
class node_browser,node_youtube,node_yt_dlp,node_gemini_api,node_env,node_flask toneMint
class node_temp_files toneRose
```

## Components

### Presentation

Server-rendered pages and assets

- [Home page](https://github.com/ysn-b13/sub2voice/blob/main/templates/homepage.html): Jinja template · Landing page shown before a URL is submitted. · `templates/homepage.html`
- [Get started](https://github.com/ysn-b13/sub2voice/blob/main/templates/get_started.html): Jinja template · Form page for entering a YouTube URL. · `templates/get_started.html`
- [English view](https://github.com/ysn-b13/sub2voice/blob/main/templates/show_sub.html): Jinja template · Renders the parsed English subtitles. · `templates/show_sub.html`
- [Arabic view](https://github.com/ysn-b13/sub2voice/blob/main/templates/show_sub_ar.html): Jinja template · Renders translated Arabic subtitles. · `templates/show_sub_ar.html`
- [Base layout](https://github.com/ysn-b13/sub2voice/blob/main/templates/base.html): Jinja layout · Shared page structure used by the rendered views. · `templates/base.html`
- [Stylesheets](https://github.com/ysn-b13/sub2voice/tree/main/static/css): CSS assets · Page styling for the shared layout and subtitle views. · `static/css`
- [Client scripts](https://github.com/ysn-b13/sub2voice/tree/main/static/js): JavaScript assets · Browser behavior supporting the server-rendered pages. · `static/js`

### Core App

Request orchestration and subtitle pipeline

- [main.py](https://github.com/ysn-b13/sub2voice/blob/main/main.py): Flask entrypoint · Sets up the web app, routes, and request flow. · `main.py`
- [Subtitle fetch](https://github.com/ysn-b13/sub2voice/blob/main/Sub2Voice/Subtitle.py): yt-dlp adapter · Downloads subtitle tracks from a YouTube URL and produces local SRT output. · `Sub2Voice/Subtitle.py`
- [SRT parser](https://github.com/ysn-b13/sub2voice/blob/main/Sub2Voice/SRT_file.py): subtitle parser · Parses SRT structure into subtitle segments and timestamps. · `Sub2Voice/SRT_file.py`
- [Time parser](https://github.com/ysn-b13/sub2voice/blob/main/Sub2Voice/SRT_timestamp.py): timestamp helper · Handles SRT time parsing and conversion for subtitle segments. · `Sub2Voice/SRT_timestamp.py`
- [Translator](https://github.com/ysn-b13/sub2voice/blob/main/Sub2Voice/Translate.py): Gemini client · Translates subtitle text into Arabic, likely in chunks. · `Sub2Voice/Translate.py`
- [Format time](https://github.com/ysn-b13/sub2voice/blob/main/Sub2Voice/format_time.py): template helper · Formats raw timestamps for display in templates. · `Sub2Voice/format_time.py`

### External Systems

Outside services and runtime dependencies

- **Browser**: user interface · Human entry point for submitting URLs and viewing results.
- **YouTube**: content source · Source of subtitle tracks fetched by the app.
- **yt-dlp**: extraction library · Underlying downloader/extractor used to retrieve subtitles.
- **Gemini API**: translation service · External generative AI service used for Arabic translation.
- **Env vars**: config source · Provides secret keys and runtime configuration.
- **Flask**: web framework · Handles request routing, templating, and response rendering.

### Working Files

Ephemeral subtitle artifacts

- **Temp subtitles**: working files · Ephemeral .srt files used during processing.

## Connections

- Browser → main.py: submit URL · User submits a YouTube link through the web app.
- main.py → Flask: serve · Flask manages the request/response cycle.
- main.py → Env vars: load config · Reads secrets and runtime settings from the environment.
- main.py → Home page: render · Renders the landing page.
- main.py → Get started: render · Renders the submission form page.
- main.py → Subtitle fetch: download · Initiates subtitle retrieval for the submitted URL.
- Subtitle fetch → YouTube: source · Subtitle extraction begins from YouTube content.
- Subtitle fetch → yt-dlp: uses · Relies on yt-dlp to fetch subtitle tracks.
- Subtitle fetch → Temp subtitles: write SRT · Stores downloaded subtitles as temporary files.
- main.py → SRT parser: parse · Reads the subtitle artifact into structured segments.
- SRT parser → Time parser: uses · Delegates timestamp handling while parsing SRT entries.
- SRT parser → English view: feed view · Supplies parsed English subtitle data to the view.
- English view → Format time: format · Formats timestamps for display in the English page.
- main.py → Translator: translate · Translates subtitle text into Arabic when requested.
- Translator → Gemini API: call · Sends chunked subtitle text to Gemini.
- main.py → Arabic view: render · Renders the Arabic subtitle page.
- Arabic view → Format time: format · Formats timestamps for the Arabic view.
- main.py → Base layout: compose · Uses the shared layout to build all pages.
- Base layout → Stylesheets: style · Shared layout pulls in stylesheet assets.
- Base layout → Client scripts: script · Shared layout pulls in browser scripts.
