# cavalia88/hardsubextract architecture

> Architecture diagram of the GitHub repository cavalia88/hardsubextract, 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/cavalia88/hardsubextract
- Repository: https://github.com/cavalia88/hardsubextract

## Overview

HardSubExtract is a command-line utility that samples video frames, recognizes hardcoded subtitles, merges similar detections, and writes an SRT file. Its principal workflow includes a six-frame region preview and user confirmation before OCR; a separate frame-scroller GUI helps users determine region percentages, which they enter into the CLI. The source excerpts show these runtime stages and calls. The documented handoff of region values is user-mediated, not an automatic data transfer.

Main entry points: [`HardSubExtract.py`](https://github.com/cavalia88/hardsubextract/blob/main/HardSubExtract.py) (CLI workflow), [`Video_Frame_Scroller.py`](https://github.com/cavalia88/hardsubextract/blob/main/Video_Frame_Scroller.py) (Frame navigation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_extract["Subtitle extraction"]
  node_cli["CLI workflow<br/>[HardSubExtract.py]"]
  node_preview["Sample frames<br/>[HardSubExtract.py]"]
  node_preview_display["Preview display<br/>[HardSubExtract.py]"]
  node_extractor["Frame OCR<br/>[HardSubExtract.py]"]
  node_ocr["PaddleOCR"]
  node_merger["Subtitle merging<br/>[HardSubExtract.py]"]
  node_srt["SRT writer<br/>[HardSubExtract.py]"]
end

subgraph group_scroller["Region scroller"]
  node_scroller_ui["Scroller GUI"]
  node_video_open["Video selection"]
  node_frame_nav["Frame navigation"]
  node_roi["Region selection"]
end

subgraph group_io["Video and output"]
  node_video["Video file"]
  node_output["SRT file"]
end

node_user(("User"))

node_user -->|"runs with options"| node_cli
node_cli -->|"samples frames"| node_preview
node_preview -->|"reads frames"| node_video
node_cli -->|"displays samples"| node_preview_display
node_cli -->|"requests confirmation"| node_user
node_cli -->|"starts extraction"| node_extractor
node_extractor -->|"reads frames"| node_video
node_extractor -->|"recognizes cropped frames"| node_ocr
node_extractor -->|"merges detections"| node_merger
node_extractor -->|"writes subtitles"| node_srt
node_srt -->|"creates file"| node_output
node_user -->|"opens scroller"| node_scroller_ui
node_scroller_ui -->|"opens video"| node_video_open
node_video_open -->|"reads video"| node_video
node_video_open -->|"shows first frame"| node_frame_nav
node_scroller_ui -->|"navigates frames"| node_frame_nav
node_frame_nav -->|"seeks and reads"| node_video
node_frame_nav -->|"renders region"| node_roi
node_user -->|"draws boundaries"| node_roi
node_roi -->|"shows percentages"| node_user
node_user -->|"enters region values"| node_cli

click node_cli "https://github.com/cavalia88/hardsubextract/blob/main/HardSubExtract.py"
click node_preview "https://github.com/cavalia88/hardsubextract/blob/main/HardSubExtract.py"
click node_preview_display "https://github.com/cavalia88/hardsubextract/blob/main/HardSubExtract.py"
click node_extractor "https://github.com/cavalia88/hardsubextract/blob/main/HardSubExtract.py"
click node_merger "https://github.com/cavalia88/hardsubextract/blob/main/HardSubExtract.py"
click node_srt "https://github.com/cavalia88/hardsubextract/blob/main/HardSubExtract.py"
click node_scroller_ui "https://github.com/cavalia88/hardsubextract/blob/main/Video_Frame_Scroller.py"
click node_video_open "https://github.com/cavalia88/hardsubextract/blob/main/Video_Frame_Scroller.py"
click node_frame_nav "https://github.com/cavalia88/hardsubextract/blob/main/Video_Frame_Scroller.py"
click node_roi "https://github.com/cavalia88/hardsubextract/blob/main/Video_Frame_Scroller.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_preview,node_preview_display,node_extractor,node_ocr,node_merger,node_srt,node_user toneBlue
class node_scroller_ui,node_video_open,node_frame_nav,node_roi toneAmber
class node_video,node_output toneMint
```

## Components

### Subtitle extraction

- [CLI workflow](https://github.com/cavalia88/hardsubextract/blob/main/HardSubExtract.py): `HardSubExtract.py`
- [Sample frames](https://github.com/cavalia88/hardsubextract/blob/main/HardSubExtract.py): `HardSubExtract.py`
- [Preview display](https://github.com/cavalia88/hardsubextract/blob/main/HardSubExtract.py): `HardSubExtract.py`
- [Frame OCR](https://github.com/cavalia88/hardsubextract/blob/main/HardSubExtract.py): `HardSubExtract.py`
- **PaddleOCR**
- [Subtitle merging](https://github.com/cavalia88/hardsubextract/blob/main/HardSubExtract.py): `HardSubExtract.py`
- [SRT writer](https://github.com/cavalia88/hardsubextract/blob/main/HardSubExtract.py): `HardSubExtract.py`

### Region scroller

- [Scroller GUI](https://github.com/cavalia88/hardsubextract/blob/main/Video_Frame_Scroller.py): `Video_Frame_Scroller.py`
- [Video selection](https://github.com/cavalia88/hardsubextract/blob/main/Video_Frame_Scroller.py): `Video_Frame_Scroller.py`
- [Frame navigation](https://github.com/cavalia88/hardsubextract/blob/main/Video_Frame_Scroller.py): `Video_Frame_Scroller.py`
- [Region selection](https://github.com/cavalia88/hardsubextract/blob/main/Video_Frame_Scroller.py): `Video_Frame_Scroller.py`

### Video and output

- **Video file**
- **SRT file**

### Other components

- **User**

## Connections

- User → CLI workflow: runs with options (evidence: `README.md`)
- CLI workflow → Sample frames: samples frames (evidence: `HardSubExtract.py`)
- Sample frames → Video file: reads frames (evidence: `HardSubExtract.py`)
- CLI workflow → Preview display: displays samples (evidence: `HardSubExtract.py`)
- CLI workflow → User: requests confirmation (evidence: `HardSubExtract.py`)
- CLI workflow → Frame OCR: starts extraction (evidence: `HardSubExtract.py`)
- Frame OCR → Video file: reads frames (evidence: `HardSubExtract.py`)
- Frame OCR → PaddleOCR: recognizes cropped frames (evidence: `HardSubExtract.py`)
- Frame OCR → Subtitle merging: merges detections (evidence: `HardSubExtract.py`)
- Frame OCR → SRT writer: writes subtitles (evidence: `HardSubExtract.py`)
- SRT writer → SRT file: creates file (evidence: `HardSubExtract.py`)
- User → Scroller GUI: opens scroller (evidence: `README.md`)
- Scroller GUI → Video selection: opens video (evidence: `Video_Frame_Scroller.py`)
- Video selection → Video file: reads video (evidence: `Video_Frame_Scroller.py`)
- Video selection → Frame navigation: shows first frame (evidence: `Video_Frame_Scroller.py`)
- Scroller GUI → Frame navigation: navigates frames (evidence: `Video_Frame_Scroller.py`)
- Frame navigation → Video file: seeks and reads (evidence: `Video_Frame_Scroller.py`)
- Frame navigation → Region selection: renders region (evidence: `Video_Frame_Scroller.py`)
- User → Region selection: draws boundaries (evidence: `Video_Frame_Scroller.py`)
- Region selection → User: shows percentages (evidence: `Video_Frame_Scroller.py`)
- User → CLI workflow: enters region values (evidence: `README.md`)
