# timminator/videocr architecture

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

- Interactive diagram: https://gitdiagram.com/timminator/videocr
- Repository: https://github.com/timminator/videocr

## Overview

VideOCR is a desktop and command-line application for extracting burned-in subtitles. The main workflow selects a video and subtitle region, samples and filters frames, runs local or hybrid OCR, consolidates recognized text into timed subtitle entries, and writes an SRT file. The GUI also supports batch processing and configurable extraction; the CLI exposes the same processing API. The GUI excerpt is partial and the README documents capabilities whose internal wiring is not fully shown, so uncertain subsystem links are omitted.

Main entry points: [`CLI/videocr/video.py`](https://github.com/timminator/videocr/blob/master/CLI/videocr/video.py) (Frame Pipeline), [`CLI/videocr/api.py`](https://github.com/timminator/videocr/blob/master/CLI/videocr/api.py) (Extraction API), [`CLI/videocr_cli.py`](https://github.com/timminator/videocr/blob/master/CLI/videocr_cli.py) (CLI Arguments), [`VideOCR.py`](https://github.com/timminator/videocr/blob/master/VideOCR.py) (Desktop GUI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_gui["Desktop GUI<br/>[VideOCR.py]"]
  node_cli["CLI Arguments<br/>[videocr_cli.py]"]
  node_api["Extraction API<br/>[api.py]"]
end

subgraph group_processing["Video Processing"]
  node_video["Frame Pipeline<br/>[video.py]"]
  node_video_io["Video Decoder<br/>[pyav_adapter.py]"]
  node_frame_utils["Frame Utilities<br/>[utils.py]"]
end

subgraph group_recognition["OCR Recognition"]
  node_paddle["PaddleOCR"]
  node_lens["Google Lens"]
  node_lang_config["OCR Languages"]
  node_predictions["Text Predictions<br/>[models.py]"]
end

subgraph group_output["Subtitle Output"]
  node_subtitle_model["Subtitle Consolidation<br/>[models.py]"]
  node_srt["SRT File"]
end

node_desktop_user(("Desktop User"))
node_cli_user(("CLI User"))

node_desktop_user -->|"selects and runs"| node_gui
node_cli_user -->|"provides options"| node_cli
node_cli -->|"calls extraction"| node_api
node_gui -->|"launches process"| node_cli
node_api -->|"checks hardware and models"| node_frame_utils
node_api -->|"configures and runs"| node_video
node_video -->|"decodes frames"| node_video_io
node_video -->|"filters and processes frames"| node_frame_utils
node_video -->|"detects and recognizes"| node_paddle
node_video -.->|"recognizes text"| node_lens
node_video -->|"creates predictions"| node_predictions
node_predictions -->|"consolidates text"| node_subtitle_model
node_api -->|"requests subtitles"| node_subtitle_model
node_api -->|"writes SRT"| node_srt

click node_gui "https://github.com/timminator/videocr/blob/master/VideOCR.py"
click node_cli "https://github.com/timminator/videocr/blob/master/CLI/videocr_cli.py"
click node_api "https://github.com/timminator/videocr/blob/master/CLI/videocr/api.py"
click node_video "https://github.com/timminator/videocr/blob/master/CLI/videocr/video.py"
click node_video_io "https://github.com/timminator/videocr/blob/master/CLI/videocr/pyav_adapter.py"
click node_frame_utils "https://github.com/timminator/videocr/blob/master/CLI/videocr/utils.py"
click node_lang_config "https://github.com/timminator/videocr/blob/master/CLI/videocr/lang_dictionaries.py"
click node_predictions "https://github.com/timminator/videocr/blob/master/CLI/videocr/models.py"
click node_subtitle_model "https://github.com/timminator/videocr/blob/master/CLI/videocr/models.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_gui,node_cli,node_api,node_desktop_user,node_cli_user toneBlue
class node_video,node_video_io,node_frame_utils toneAmber
class node_paddle,node_lens,node_lang_config,node_predictions toneMint
class node_subtitle_model,node_srt toneRose
```

## Components

### User Interfaces

- [Desktop GUI](https://github.com/timminator/videocr/blob/master/VideOCR.py): `VideOCR.py`
- [CLI Arguments](https://github.com/timminator/videocr/blob/master/CLI/videocr_cli.py): `CLI/videocr_cli.py`
- [Extraction API](https://github.com/timminator/videocr/blob/master/CLI/videocr/api.py): `CLI/videocr/api.py`

### Video Processing

- [Frame Pipeline](https://github.com/timminator/videocr/blob/master/CLI/videocr/video.py): `CLI/videocr/video.py`
- [Video Decoder](https://github.com/timminator/videocr/blob/master/CLI/videocr/pyav_adapter.py): `CLI/videocr/pyav_adapter.py`
- [Frame Utilities](https://github.com/timminator/videocr/blob/master/CLI/videocr/utils.py): `CLI/videocr/utils.py`

### OCR Recognition

- **PaddleOCR**
- **Google Lens**
- [OCR Languages](https://github.com/timminator/videocr/blob/master/CLI/videocr/lang_dictionaries.py): `CLI/videocr/lang_dictionaries.py`
- [Text Predictions](https://github.com/timminator/videocr/blob/master/CLI/videocr/models.py): `CLI/videocr/models.py`

### Subtitle Output

- [Subtitle Consolidation](https://github.com/timminator/videocr/blob/master/CLI/videocr/models.py): `CLI/videocr/models.py`
- **SRT File**

### Other components

- **Desktop User**
- **CLI User**

## Connections

- Desktop User → Desktop GUI: selects and runs
- CLI User → CLI Arguments: provides options
- CLI Arguments → Extraction API: calls extraction
- Desktop GUI → CLI Arguments: launches process
- Extraction API → Frame Utilities: checks hardware and models
- Extraction API → Frame Pipeline: configures and runs
- Frame Pipeline → Video Decoder: decodes frames
- Frame Pipeline → Frame Utilities: filters and processes frames
- Frame Pipeline → PaddleOCR: detects and recognizes
- Frame Pipeline → Google Lens: recognizes text
- Frame Pipeline → Text Predictions: creates predictions
- Text Predictions → Subtitle Consolidation: consolidates text
- Extraction API → Subtitle Consolidation: requests subtitles
- Extraction API → SRT File: writes SRT