How ysn-b13/sub2voice works
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 main.py · Subtitle.py Subtitle fetch · base.html Base layout · SRT_file.py SRT parser
Components 20
Presentation
Server-rendered pages and assets
- Home page · Landing page shown before a URL is submitted.
templates/homepage.html - Get started · Form page for entering a YouTube URL.
templates/get_started.html - English view · Renders the parsed English subtitles.
templates/show_sub.html - Arabic view · Renders translated Arabic subtitles.
templates/show_sub_ar.html - Base layout · Shared page structure used by the rendered views.
templates/base.html - Stylesheets · Page styling for the shared layout and subtitle views.
static/css - Client scripts · Browser behavior supporting the server-rendered pages.
static/js
Core App
Request orchestration and subtitle pipeline
- main.py · Sets up the web app, routes, and request flow.
main.py - Subtitle fetch · Downloads subtitle tracks from a YouTube URL and produces local SRT output.
Sub2Voice/Subtitle.py - SRT parser · Parses SRT structure into subtitle segments and timestamps.
Sub2Voice/SRT_file.py - Time parser · Handles SRT time parsing and conversion for subtitle segments.
Sub2Voice/SRT_timestamp.py - Translator · Translates subtitle text into Arabic, likely in chunks.
Sub2Voice/Translate.py - Format time · Formats raw timestamps for display in templates.
Sub2Voice/format_time.py
External Systems
Outside services and runtime dependencies
- Browser · Human entry point for submitting URLs and viewing results.
- YouTube · Source of subtitle tracks fetched by the app.
- yt-dlp · Underlying downloader/extractor used to retrieve subtitles.
- Gemini API · External generative AI service used for Arabic translation.
- Env vars · Provides secret keys and runtime configuration.
- Flask · Handles request routing, templating, and response rendering.
Working Files
Ephemeral subtitle artifacts
- Temp subtitles · Ephemeral .srt files used during processing.
Connections 20
- 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.