How vincrichard/vobsub-ml-ocr works
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)