# daryllundy/whisper-video-to-text architecture

> Architecture diagram of the GitHub repository daryllundy/whisper-video-to-text, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/daryllundy/whisper-video-to-text
- Repository: https://github.com/daryllundy/whisper-video-to-text
- Video tour (about a minute): https://gitdiagram.com/daryllundy/whisper-video-to-text/video

## Overview

Whisper Video to Text is a local-first media transcription tool with CLI and web interfaces. Both feed a shared pipeline that optionally downloads media, normalizes it to WAV, transcribes locally with Whisper, and renders requested text or subtitle formats. The web interface additionally accepts uploads, tracks in-memory jobs, streams progress, and serves transcript downloads and history. Edges follow sampled calls or README statements; web wiring is only partially sampled, so undocumented details are omitted.

Main entry points: [`whisper_video_to_text/web/views.py`](https://github.com/daryllundy/whisper-video-to-text/blob/main/whisper_video_to_text/web/views.py) (Web routes), [`whisper_video_to_text/pipeline.py`](https://github.com/daryllundy/whisper-video-to-text/blob/main/whisper_video_to_text/pipeline.py) (Shared pipeline), [`whisper_video_to_text/web/static/app.js`](https://github.com/daryllundy/whisper-video-to-text/blob/main/whisper_video_to_text/web/static/app.js) (Web interface), [`whisper_video_to_text/convert.py`](https://github.com/daryllundy/whisper-video-to-text/blob/main/whisper_video_to_text/convert.py) (Media normalization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_web_ui["Web interface<br/>[app.js]"]
  node_web_app["Web app and page<br/>[main.py]"]
  node_web_routes["Web routes<br/>[views.py]"]
end

subgraph group_workflow["Transcription workflow"]
  node_pipeline["Shared pipeline<br/>[pipeline.py]"]
  node_download["URL download<br/>[download.py]"]
  node_convert["Media normalization<br/>[convert.py]"]
  node_transcribe["Transcription and rendering<br/>[transcribe.py]"]
end

subgraph group_webjobs["Web jobs and results"]
  node_progress["Job state and SSE<br/>[progress.py]"]
  node_web_files["Uploads and transcripts<br/>[views.py]"]
end

subgraph group_integrations["Local and external tools"]
  node_yt_dlp["yt-dlp"]
  node_ffmpeg["ffmpeg"]
  node_whisper_lib["Whisper library"]
  node_transcript_files["CLI output files"]
end

node_cli_user(("CLI user"))
node_web_user(("Web user"))

node_cli_user -->|"runs"| node_cli
node_cli -->|"submits request"| node_pipeline
node_web_user -.->|"uses"| node_web_ui
node_web_ui -->|"starts jobs"| node_web_routes
node_web_ui -->|"requests history"| node_web_routes
node_web_app -->|"registers routes"| node_web_routes
node_web_app -->|"gets media types"| node_convert
node_web_routes -->|"runs transcription"| node_pipeline
node_pipeline -->|"downloads optionally"| node_download
node_pipeline -->|"normalizes media"| node_convert
node_pipeline -->|"transcribes and renders"| node_transcribe
node_pipeline -->|"writes outputs"| node_transcript_files
node_download -->|"invokes"| node_yt_dlp
node_convert -->|"runs conversion"| node_ffmpeg
node_transcribe -->|"loads and runs model"| node_whisper_lib
node_web_routes -->|"saves uploads"| node_web_files
node_web_routes -->|"serves transcripts"| node_web_files
node_web_routes -->|"updates job state"| node_progress
node_web_routes -->|"streams job events"| node_progress
node_web_ui -.->|"opens progress stream"| node_web_routes

click node_cli "https://github.com/daryllundy/whisper-video-to-text/blob/main/whisper_video_to_text/cli.py"
click node_web_ui "https://github.com/daryllundy/whisper-video-to-text/blob/main/whisper_video_to_text/web/static/app.js"
click node_web_app "https://github.com/daryllundy/whisper-video-to-text/blob/main/whisper_video_to_text/web/main.py"
click node_web_routes "https://github.com/daryllundy/whisper-video-to-text/blob/main/whisper_video_to_text/web/views.py"
click node_pipeline "https://github.com/daryllundy/whisper-video-to-text/blob/main/whisper_video_to_text/pipeline.py"
click node_download "https://github.com/daryllundy/whisper-video-to-text/blob/main/whisper_video_to_text/download.py"
click node_convert "https://github.com/daryllundy/whisper-video-to-text/blob/main/whisper_video_to_text/convert.py"
click node_transcribe "https://github.com/daryllundy/whisper-video-to-text/blob/main/whisper_video_to_text/transcribe.py"
click node_progress "https://github.com/daryllundy/whisper-video-to-text/blob/main/whisper_video_to_text/web/progress.py"
click node_web_files "https://github.com/daryllundy/whisper-video-to-text/blob/main/whisper_video_to_text/web/views.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_cli,node_web_ui,node_web_app,node_web_routes,node_cli_user,node_web_user toneBlue
class node_pipeline,node_download,node_convert,node_transcribe toneAmber
class node_progress,node_web_files toneMint
class node_yt_dlp,node_ffmpeg,node_whisper_lib,node_transcript_files toneRose
```

## Components

### User interfaces

- [CLI](https://github.com/daryllundy/whisper-video-to-text/blob/main/whisper_video_to_text/cli.py): `whisper_video_to_text/cli.py`
- [Web interface](https://github.com/daryllundy/whisper-video-to-text/blob/main/whisper_video_to_text/web/static/app.js): `whisper_video_to_text/web/static/app.js`
- [Web app and page](https://github.com/daryllundy/whisper-video-to-text/blob/main/whisper_video_to_text/web/main.py): `whisper_video_to_text/web/main.py`
- [Web routes](https://github.com/daryllundy/whisper-video-to-text/blob/main/whisper_video_to_text/web/views.py): `whisper_video_to_text/web/views.py`

### Transcription workflow

- [Shared pipeline](https://github.com/daryllundy/whisper-video-to-text/blob/main/whisper_video_to_text/pipeline.py): `whisper_video_to_text/pipeline.py`
- [URL download](https://github.com/daryllundy/whisper-video-to-text/blob/main/whisper_video_to_text/download.py): `whisper_video_to_text/download.py`
- [Media normalization](https://github.com/daryllundy/whisper-video-to-text/blob/main/whisper_video_to_text/convert.py): `whisper_video_to_text/convert.py`
- [Transcription and rendering](https://github.com/daryllundy/whisper-video-to-text/blob/main/whisper_video_to_text/transcribe.py): `whisper_video_to_text/transcribe.py`

### Web jobs and results

- [Job state and SSE](https://github.com/daryllundy/whisper-video-to-text/blob/main/whisper_video_to_text/web/progress.py): `whisper_video_to_text/web/progress.py`
- [Uploads and transcripts](https://github.com/daryllundy/whisper-video-to-text/blob/main/whisper_video_to_text/web/views.py): `whisper_video_to_text/web/views.py`

### Local and external tools

- **yt-dlp**
- **ffmpeg**
- **Whisper library**
- **CLI output files**

### Other components

- **CLI user**
- **Web user**

## Connections

- CLI user → CLI: runs (evidence: `whisper_video_to_text/cli.py`)
- CLI → Shared pipeline: submits request (evidence: `whisper_video_to_text/cli.py`)
- Web user → Web interface: uses
- Web interface → Web routes: starts jobs (evidence: `whisper_video_to_text/web/static/app.js`)
- Web interface → Web routes: requests history (evidence: `whisper_video_to_text/web/static/app.js`)
- Web app and page → Web routes: registers routes (evidence: `whisper_video_to_text/web/main.py`)
- Web app and page → Media normalization: gets media types (evidence: `whisper_video_to_text/web/main.py`)
- Web routes → Shared pipeline: runs transcription (evidence: `README.md`)
- Shared pipeline → URL download: downloads optionally (evidence: `whisper_video_to_text/pipeline.py`)
- Shared pipeline → Media normalization: normalizes media (evidence: `whisper_video_to_text/pipeline.py`)
- Shared pipeline → Transcription and rendering: transcribes and renders (evidence: `whisper_video_to_text/pipeline.py`)
- Shared pipeline → CLI output files: writes outputs (evidence: `whisper_video_to_text/pipeline.py`)
- URL download → yt-dlp: invokes (evidence: `whisper_video_to_text/download.py`)
- Media normalization → ffmpeg: runs conversion (evidence: `whisper_video_to_text/convert.py`)
- Transcription and rendering → Whisper library: loads and runs model (evidence: `whisper_video_to_text/transcribe.py`)
- Web routes → Uploads and transcripts: saves uploads (evidence: `whisper_video_to_text/web/views.py`)
- Web routes → Uploads and transcripts: serves transcripts (evidence: `whisper_video_to_text/web/views.py`)
- Web routes → Job state and SSE: updates job state (evidence: `whisper_video_to_text/web/views.py`)
- Web routes → Job state and SSE: streams job events (evidence: `whisper_video_to_text/web/views.py`)
- Web interface → Web routes: opens progress stream (evidence: `README.md`)