# rishabhjain2003/autosubai architecture

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

- Interactive diagram: https://gitdiagram.com/rishabhjain2003/autosubai
- Repository: https://github.com/rishabhjain2003/autosubai

## Overview

1. **What this repo is**
   - A small Python CLI package for generating subtitle files from YouTube URLs.
   - It is not a service or web app; the whole architecture is a local command-line pipeline.

2. **Top-level structure**
   - `setup.py` packages and exposes the tool for installation.
   - `requirements.txt` captures runtime dependencies.
   - `yt_whisper/` contains the actual application code.
   - `README.md` documents the user-facing flow and supported options.

3. **Primary entry point**
   - `yt_whisper/cli.py` is the main boundary between the user and the system.
   - This layer is responsible for parsing command-line arguments such as the video URL, Whisper model size, and translation task.

4. **Core processing layer**
   - `yt_whisper/utils.py` appears to hold the operational logic for the pipeline.
   - This is where the repo likely separates media download, audio preparation, Whisper inference, and subtitle file generation.

5. **End-to-end data flow**
   - Input: a YouTube video URL from the CLI.
   - Step 1: the tool downloads audio from YouTube using `yt-dlp`.
   - Step 2: the audio is processed by Whisper locally.
   - Step 3: subtitle segments are converted into `.vtt`.
   - Output: a subtitle file written to the local filesystem.

6. **External dependencies that shape the architecture**
   - `yt-dlp` is the ingestion layer for pulling media from YouTube.
   - `ffmpeg` is an external system dependency for audio extraction/transcoding.
   - Whisper models are selected locally (`tiny` through `large`), affecting compute cost and transcription quality.

7. **Feature boundary: transcription vs translation**
   - The `--task translate` option changes the Whisper job from transcription to English translation.
   - This is a pipeline-level mode switch rather than a separate subsystem.

8. **Output contract**
   - The system’s final artifact is a standard WebVTT subtitle file.
   - That makes the output interoperable with media players and subtitle tooling.

9. **Packaging/runtime boundary**
   - The project is distributed as a Python package installed via `pip`.
   - Runtime requirements include Python 3.7+ plus system-level `ffmpeg`, so the architecture depends on both Python libraries and an OS-installed binary.

10. **Likely architectural diagram shape**
   - One user-facing CLI box feeding into a small internal processing box.
   - From there, arrows go to YouTube/`yt-dlp` for download, to local Whisper for inference, and to local filesystem for `.vtt` output.
   - There are no evident internal microservices, databases, or remote application servers.

11. **Important repo characteristic**
   - The codebase is intentionally minimal: a thin CLI wrapper around a single local media-processing pipeline.
   - Most architectural complexity comes from the external tools it orchestrates, not from many internal modules.

Main entry points: [`yt_whisper/cli.py`](https://github.com/rishabhjain2003/autosubai/blob/main/yt_whisper/cli.py) (CLI), [`yt_whisper/utils.py`](https://github.com/rishabhjain2003/autosubai/blob/main/yt_whisper/utils.py) (Pipeline), [`setup.py`](https://github.com/rishabhjain2003/autosubai/blob/main/setup.py) (Setup), [`requirements.txt`](https://github.com/rishabhjain2003/autosubai/blob/main/requirements.txt) (Requirements)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["Repository"]
  node_readme["README<br/>docs<br/>[README.md]"]
  node_setup["Setup<br/>packaging<br/>[setup.py]"]
  node_requirements["Requirements<br/>deps<br/>[requirements.txt]"]
  node_package_init["Package<br/>pkg marker<br/>[__init__.py]"]
  node_cli["CLI<br/>entrypoint<br/>[cli.py]"]
  node_pipeline["Pipeline<br/>orchestrator<br/>[utils.py]"]
  node_download_step["Download audio<br/>ingestion"]
  node_prep_step["Prep audio<br/>media prep"]
  node_transcribe_step["Whisper run<br/>inference"]
  node_subtitle_step["VTT writer<br/>output"]
end

subgraph group_external["External"]
  node_youtube(("YouTube<br/>input source"))
  node_ytdlp["yt-dlp<br/>external tool"]
  node_ffmpeg["ffmpeg<br/>system binary"]
  node_whisper{{"Whisper<br/>model runtime"}}
  node_filesystem[("Filesystem<br/>local sink")]
end

node_readme -->|"documents"| node_cli
node_setup -->|"exposes"| node_cli
node_setup -.->|"depends on"| node_requirements
node_cli -->|"invokes"| node_pipeline
node_cli -->|"starts"| node_download_step
node_cli -.->|"selects mode"| node_transcribe_step
node_download_step -->|"uses"| node_ytdlp
node_ytdlp -->|"reads from"| node_youtube
node_pipeline -->|"coordinates"| node_prep_step
node_prep_step -->|"uses"| node_ffmpeg
node_pipeline -->|"coordinates"| node_transcribe_step
node_transcribe_step -->|"uses"| node_whisper
node_transcribe_step -->|"emits"| node_subtitle_step
node_subtitle_step -->|"writes"| node_filesystem
node_requirements -.->|"depends on"| node_ffmpeg
node_package_init -.->|"namespaces"| node_cli

click node_readme "https://github.com/rishabhjain2003/autosubai/blob/main/README.md"
click node_setup "https://github.com/rishabhjain2003/autosubai/blob/main/setup.py"
click node_requirements "https://github.com/rishabhjain2003/autosubai/blob/main/requirements.txt"
click node_package_init "https://github.com/rishabhjain2003/autosubai/blob/main/yt_whisper/__init__.py"
click node_cli "https://github.com/rishabhjain2003/autosubai/blob/main/yt_whisper/cli.py"
click node_pipeline "https://github.com/rishabhjain2003/autosubai/blob/main/yt_whisper/utils.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_readme,node_setup,node_requirements,node_package_init,node_cli,node_pipeline,node_download_step,node_prep_step,node_transcribe_step,node_subtitle_step toneBlue
class node_youtube,node_ytdlp,node_ffmpeg,node_whisper,node_filesystem toneAmber
```

## Components

### Repository

Python package, CLI entrypoint, and core pipeline code.

- [README](https://github.com/rishabhjain2003/autosubai/blob/main/README.md): docs · User-facing usage and option overview. · `README.md`
- [Setup](https://github.com/rishabhjain2003/autosubai/blob/main/setup.py): packaging · Package metadata and console-script exposure. · `setup.py`
- [Requirements](https://github.com/rishabhjain2003/autosubai/blob/main/requirements.txt): deps · Runtime Python dependency list. · `requirements.txt`
- [Package](https://github.com/rishabhjain2003/autosubai/blob/main/yt_whisper/__init__.py): pkg marker · Python package namespace marker. · `yt_whisper/__init__.py`
- [CLI](https://github.com/rishabhjain2003/autosubai/blob/main/yt_whisper/cli.py): entrypoint · Parses URL, model choice, and task mode. · `yt_whisper/cli.py`
- [Pipeline](https://github.com/rishabhjain2003/autosubai/blob/main/yt_whisper/utils.py): orchestrator · Coordinates download, inference, and output generation. · `yt_whisper/utils.py`
- **Download audio**: ingestion · Fetches media from YouTube via yt-dlp.
- **Prep audio**: media prep · Uses ffmpeg-backed processing before inference.
- **Whisper run**: inference · Runs local Whisper transcription or translation.
- **VTT writer**: output · Converts segments into a WebVTT subtitle file.

### External

Runtime tools and inputs the CLI orchestrates.

- **YouTube**: input source · Source video addressed by the CLI URL.
- **yt-dlp**: external tool · Downloads audio from YouTube.
- **ffmpeg**: system binary · System-level audio extraction/transcoding dependency.
- **Whisper**: model runtime · Local speech-to-text model selected by size and task.
- **Filesystem**: local sink · Writes the final .vtt artifact locally.

## Connections

- README → CLI: documents · Describes the command-line flow and options.
- Setup → CLI: exposes · Installs the CLI entrypoint for pip-based use.
- Setup → Requirements: depends on · Package/runtime dependency specification.
- CLI → Pipeline: invokes · Hands parsed arguments to the processing pipeline.
- CLI → Download audio: starts · Begins the media acquisition stage.
- CLI → Whisper run: selects mode · Chooses transcription or translation task.
- Download audio → yt-dlp: uses · Delegates YouTube media fetching to yt-dlp.
- yt-dlp → YouTube: reads from · Pulls the source video/audio from YouTube.
- Pipeline → Prep audio: coordinates · Stages audio before model inference.
- Prep audio → ffmpeg: uses · Relies on ffmpeg for extraction/transcoding.
- Pipeline → Whisper run: coordinates · Runs the Whisper job after preparation.
- Whisper run → Whisper: uses · Executes the selected Whisper model locally.
- Whisper run → VTT writer: emits · Produces timestamped subtitle segments.
- VTT writer → Filesystem: writes · Saves the final WebVTT file locally.
- Requirements → ffmpeg: depends on · Python requirements complement the OS binary dependency.
- Package → CLI: namespaces · Marks the installable package boundary.