# finanf/subtitle-generator architecture

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

- Interactive diagram: https://gitdiagram.com/finanf/subtitle-generator
- Repository: https://github.com/finanf/subtitle-generator

## Overview

Subtitle Generator accepts short MP4 uploads through a React interface, processes them through a FastAPI endpoint, and offers the burned-in video for download. The API owns duration validation, temporary-file handling, and calls each documented processing stage; the UI also checks video metadata before upload. The README documents the pipeline and CLI capabilities. Edges follow shown calls and documented relationships; the deployment configuration and unsampled source are not mapped.

Main entry points: [`api/api.py`](https://github.com/finanf/subtitle-generator/blob/main/api/api.py) (Transcription API), [`frontend/src/App.js`](https://github.com/finanf/subtitle-generator/blob/main/frontend/src/App.js) (Upload interface), [`frontend/src/index.js`](https://github.com/finanf/subtitle-generator/blob/main/frontend/src/index.js) (React bootstrap), [`proscessing/audio_extraction.py`](https://github.com/finanf/subtitle-generator/blob/main/proscessing/audio_extraction.py) (Audio extraction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Upload interface"]
  node_react["React bootstrap<br/>[index.js]"]
  node_upload_ui["Upload interface<br/>[App.js]"]
  node_vitals["Web vitals<br/>[reportWebVitals.js]"]
end

subgraph group_api["API workflow"]
  node_transcribe_api["Transcription API<br/>[api.py]"]
  node_temp_files[("Temporary video files<br/>[api.py]")]
  node_duration_check["Duration validation<br/>[api.py]"]
end

subgraph group_processing["Subtitle processing"]
  node_audio["Audio extraction"]
  node_transcription["Speech transcription"]
  node_srt["SRT generation<br/>[generate_srt.py]"]
  node_merge["Subtitle burning"]
end

node_user(("Video user"))
node_ffmpeg["FFmpeg tools"]
node_whisper["Distil-Whisper model"]

node_user -->|"selects video"| node_upload_ui
node_react -->|"renders"| node_upload_ui
node_react -->|"invokes"| node_vitals
node_upload_ui -->|"uploads video"| node_transcribe_api
node_transcribe_api -->|"returns download URL"| node_upload_ui
node_upload_ui -->|"requests download"| node_transcribe_api
node_transcribe_api -->|"writes and cleans"| node_temp_files
node_transcribe_api -->|"checks duration"| node_duration_check
node_transcribe_api -->|"extracts audio"| node_audio
node_transcribe_api -->|"transcribes audio"| node_transcription
node_transcribe_api -->|"generates SRT"| node_srt
node_transcribe_api -->|"burns subtitles"| node_merge
node_audio -->|"extracts audio"| node_ffmpeg
node_transcription -->|"runs model"| node_whisper
node_merge -->|"burns subtitles"| node_ffmpeg

click node_react "https://github.com/finanf/subtitle-generator/blob/main/frontend/src/index.js"
click node_upload_ui "https://github.com/finanf/subtitle-generator/blob/main/frontend/src/App.js"
click node_vitals "https://github.com/finanf/subtitle-generator/blob/main/frontend/src/reportWebVitals.js"
click node_transcribe_api "https://github.com/finanf/subtitle-generator/blob/main/api/api.py"
click node_temp_files "https://github.com/finanf/subtitle-generator/blob/main/api/api.py"
click node_duration_check "https://github.com/finanf/subtitle-generator/blob/main/api/api.py"
click node_audio "https://github.com/finanf/subtitle-generator/blob/main/proscessing/audio_extraction.py"
click node_transcription "https://github.com/finanf/subtitle-generator/blob/main/proscessing/generate_transcription.py"
click node_srt "https://github.com/finanf/subtitle-generator/blob/main/proscessing/generate_srt.py"
click node_merge "https://github.com/finanf/subtitle-generator/blob/main/proscessing/merge_srt_to_mp4.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_react,node_upload_ui,node_vitals,node_user toneBlue
class node_transcribe_api,node_temp_files,node_duration_check toneAmber
class node_audio,node_transcription,node_srt,node_merge toneMint
class node_ffmpeg,node_whisper toneIndigo
```

## Components

### Upload interface

- [React bootstrap](https://github.com/finanf/subtitle-generator/blob/main/frontend/src/index.js): `frontend/src/index.js`
- [Upload interface](https://github.com/finanf/subtitle-generator/blob/main/frontend/src/App.js): `frontend/src/App.js`
- [Web vitals](https://github.com/finanf/subtitle-generator/blob/main/frontend/src/reportWebVitals.js): `frontend/src/reportWebVitals.js`

### API workflow

- [Transcription API](https://github.com/finanf/subtitle-generator/blob/main/api/api.py): `api/api.py`
- [Temporary video files](https://github.com/finanf/subtitle-generator/blob/main/api/api.py): `api/api.py`
- [Duration validation](https://github.com/finanf/subtitle-generator/blob/main/api/api.py): `api/api.py`

### Subtitle processing

- [Audio extraction](https://github.com/finanf/subtitle-generator/blob/main/proscessing/audio_extraction.py): `proscessing/audio_extraction.py`
- [Speech transcription](https://github.com/finanf/subtitle-generator/blob/main/proscessing/generate_transcription.py): `proscessing/generate_transcription.py`
- [SRT generation](https://github.com/finanf/subtitle-generator/blob/main/proscessing/generate_srt.py): `proscessing/generate_srt.py`
- [Subtitle burning](https://github.com/finanf/subtitle-generator/blob/main/proscessing/merge_srt_to_mp4.py): `proscessing/merge_srt_to_mp4.py`

### Other components

- **Video user**
- **FFmpeg tools**
- **Distil-Whisper model**

## Connections

- Video user → Upload interface: selects video (evidence: `frontend/src/App.js`)
- React bootstrap → Upload interface: renders (evidence: `frontend/src/index.js`)
- React bootstrap → Web vitals: invokes (evidence: `frontend/src/index.js`)
- Upload interface → Transcription API: uploads video (evidence: `frontend/src/App.js`)
- Transcription API → Upload interface: returns download URL (evidence: `api/api.py`)
- Upload interface → Transcription API: requests download (evidence: `frontend/src/App.js`)
- Transcription API → Temporary video files: writes and cleans (evidence: `api/api.py`)
- Transcription API → Duration validation: checks duration (evidence: `api/api.py`)
- Transcription API → Audio extraction: extracts audio (evidence: `api/api.py`)
- Transcription API → Speech transcription: transcribes audio (evidence: `api/api.py`)
- Transcription API → SRT generation: generates SRT (evidence: `api/api.py`)
- Transcription API → Subtitle burning: burns subtitles (evidence: `api/api.py`)
- Audio extraction → FFmpeg tools: extracts audio (evidence: `proscessing/audio_extraction.py`)
- Speech transcription → Distil-Whisper model: runs model (evidence: `proscessing/generate_transcription.py`)
- Subtitle burning → FFmpeg tools: burns subtitles (evidence: `proscessing/merge_srt_to_mp4.py`)
