# vincrichard/vobsub-ml-ocr architecture

> Architecture diagram of the GitHub repository vincrichard/vobsub-ml-ocr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vincrichard/vobsub-ml-ocr
- Repository: https://github.com/vincrichard/vobsub-ml-ocr

## Overview

##### Project type and purpose
- This is a command-line Python tool (open-source utility) whose sole purpose is to extract bitmap images from VobSub subtitle files (`.sub`/`.idx`) and run OCR on them to produce text.

##### File structure
- **Root**
- `main.py` – CLI entry point that parses arguments (`mode`, `sub_file`, `dest_folder`, `language`, `jobs`).
- `requirements.txt` – lists Python dependencies (e.g., `easyocr`, `MangaOcr`).
- `fig` – contains static assets (logo).
- **Package: vob_sub/**
- `config.py` – global settings, default paths, constants.
- `idx.py` – handles `.idx` file metadata parsing.
- `packetized_elementary_strem.py` – reads packetized streams from VobSub binaries.
- `vob_sub_parser.py` – core routine combining `.sub` and `.idx` parsing into subtitle “packets.”
- `vob_sub_pack.py` & `vob_sub_merge_pack.py` – logic to rebuild or merge subtitle packets into extractable frames.
- `sub_picture.py` – converts raw packet data into image bitmaps.
- `main.py` – orchestrator for extract/predict/both flows inside the package.

##### README for further insight
- Modes supported: `extract`, `predict`, `both`.
- External dependencies:
- MKVToolNix (`mkvmerge`, `mkvextract`) for ripping VobSub streams out of MKV files.
- OCR libraries: `MangaOcr` for Japanese, `easyocr.Reader` for other languages.
- Parallel processing: configurable via `-j` flag.

a. **Main components**
1. **CLI Layer** (root `main.py`)
2. **Controller/Orchestration** (`vob_sub/main.py`)
3. **Parser Layer** (`idx.py`, `packetized_elementary_stream.py`, `vob_sub_parser.py`)
4. **Packaging Layer** (`vob_sub_pack.py`, `vob_sub_merge_pack.py`)
5. **Image Extraction** (`sub_picture.py`)
6. **OCR Layer** (`MangaOcr`, `easyocr.Reader`)
7. **Utilities** (`utils.py`, `custom_color.py`, `config.py`)
8. **External Services** (`mkvmerge`, `mkvextract`)

b. **Relationships & Data Flow**
1. **User CLI →** parses flags → calls **Controller**.
2. **Controller → Parser Layer** to read `.idx` & `.sub` using external MKV tools if needed.
3. **Parser Layer → Packaging Layer** to assemble packets into full subtitle frames.
4. **Packaging Layer → Image Extraction** to convert raw frame data into image files.
5. **Image files → OCR Layer** depending on language (routes to MangaOcr or easyocr).
6. **OCR Layer →** outputs text files/logs.

c. **Key architectural patterns**
- **Pipeline/Chain of Responsibility**: each stage (parse → pack → extract → OCR) hands off to the next.
- **Factory/Strategy** for selecting OCR engine by language.
- **Modular separation** of pure-parsing logic vs. packing vs. OCR vs. utilities.

d. **Relevant technologies**
- Python 3.x, `argparse` (CLI)
- `MangaOcr`, `easyocr`
- External CLI: `mkvmerge`, `mkvextract`
- Concurrent execution via Python’s `concurrent.futures` or similar (in `utils.py`)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers
    subgraph "CLI Layer"
        CLI["main.py"]:::core
    end

    subgraph "Controller / Orchestration"
        Controller["vob_sub/main.py"]:::core
    end

    subgraph "Parser Layer"
        IDX["vob_sub/idx.py"]:::core
        PES["vob_sub/packetized_elementary_stream.py"]:::core
        Parser["vob_sub_parser.py"]:::core
    end

    subgraph "Packaging Layer"
        Pack["vob_sub/vob_sub_pack.py"]:::core
        Merge["vob_sub/vob_sub_merge_pack.py"]:::core
    end

    subgraph "Image Extraction"
        SubPic["vob_sub/sub_picture.py"]:::core
    end

    %% OCR Decision
    OCRdecision{"Language?"}:::decision
    Manga["MangaOcr"]:::ocr
    Easy["easyocr.Reader"]:::ocr
    Output["Text Output"]:::core

    %% External Tools
    MKVMerge["mkvmerge"]:::external
    MKVExtract["mkvextract"]:::external

    %% Utilities
    Config["vob_sub/config.py"]:::util
    Utils["vob_sub/utils.py"]:::util
    Color["vob_sub/custom_color.py"]:::util

    %% Flow
    CLI -->|"invoke"| Controller
    Controller -->|"start pipeline"| IDX
    Controller -->|"start pipeline"| PES
    MKVMerge -->|"extract streams"| IDX
    MKVExtract -->|"extract streams"| PES
    IDX --> Parser
    PES --> Parser
    Parser --> Pack
    Pack --> Merge
    Merge --> SubPic
    SubPic -->|"images (N jobs)"| OCRdecision
    OCRdecision -->|"ja"| Manga
    OCRdecision -->|"other"| Easy
    Manga --> Output
    Easy --> Output

    %% Utilities injection
    Config -.-> Controller
    Config -.-> IDX
    Config -.-> Pack
    Config -.-> SubPic

    Utils -.-> Parser
    Utils -.-> Pack
    Utils -.-> SubPic

    Color -.-> Parser
    Color -.-> SubPic

    %% Click Events
    click CLI "https://github.com/vincrichard/vobsub-ml-ocr/blob/main/main.py"
    click Controller "https://github.com/vincrichard/vobsub-ml-ocr/blob/main/vob_sub/main.py"
    click IDX "https://github.com/vincrichard/vobsub-ml-ocr/blob/main/vob_sub/idx.py"
    click PES "https://github.com/vincrichard/vobsub-ml-ocr/blob/main/vob_sub/packetized_elementary_stream.py"
    click Parser "https://github.com/vincrichard/vobsub-ml-ocr/blob/main/vob_sub/vob_sub_parser.py"
    click Pack "https://github.com/vincrichard/vobsub-ml-ocr/blob/main/vob_sub/vob_sub_pack.py"
    click Merge "https://github.com/vincrichard/vobsub-ml-ocr/blob/main/vob_sub/vob_sub_merge_pack.py"
    click SubPic "https://github.com/vincrichard/vobsub-ml-ocr/blob/main/vob_sub/sub_picture.py"
    click Config "https://github.com/vincrichard/vobsub-ml-ocr/blob/main/vob_sub/config.py"
    click Utils "https://github.com/vincrichard/vobsub-ml-ocr/blob/main/vob_sub/utils.py"
    click Color "https://github.com/vincrichard/vobsub-ml-ocr/blob/main/vob_sub/custom_color.py"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0366D6,stroke-width:1px
    classDef external fill:#D4F7DC,stroke:#2E8B57,stroke-width:1px
    classDef ocr fill:#FFF4C1,stroke:#DAA520,stroke-width:1px
    classDef util fill:#F0F0F0,stroke:#A9A9A9,stroke-width:1px,stroke-dasharray: 5 5
    classDef decision fill:#FFEFEF,stroke:#FF6347,stroke-width:1px,stroke-dasharray: 2 2
```
