yt-tools-cli 0.24.2__tar.gz → 0.25.0__tar.gz

{yt_tools_cli-0.24.2 → yt_tools_cli-0.25.0}/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "yt-tools",
   "displayName": "yt-tools",
-  "version": "0.24.2",
+  "version": "0.25.0",
   "description": "Iterative YouTube watching for agents: clean-markdown transcripts with [mm:ss] anchors, targeted frame extraction, FFT audio analysis (BPM, key, chord progression, spectral features), full-metadata extraction (description, chapters, most-replayed, counts, tags), comment scraping, and OCR over cached frames (RapidOCR PP-OCRv5) for silent-with-text videos. Light core (transcript / metadata / comments / search) with heavy stacks in [frames] and [audio] extras. Bundles the using-yt-tools skill and a SessionStart hook that auto-installs from the plugin's local clone via pipx (default [full] extras, fallback to [frames,audio]) and probes ffmpeg.",
   "author": {
     "name": "Victor Kuznetsov",

{yt_tools_cli-0.24.2 → yt_tools_cli-0.25.0}/.github/workflows/ci.yml

@@ -31,6 +31,38 @@ jobs:
       - name: Unit + CLI smoke tests
         run: pytest -q
 
+  ocr-engine-matrix:
+    name: ocr engine (rapidocr ${{ matrix.rapidocr }})
+    runs-on: ubuntu-latest
+    strategy:
+      # Both legs are the point: `[ocr]` is a pin on a third-party params API,
+      # and release 0.24.0/0.24.1 shipped broken because the *newer* minor was
+      # never exercised — the engine factory was mocked in every test, so the
+      # suite was green while a clean install could not construct the engine at
+      # all ([[issue:77]], [[task:2831]]). 0.25.0 names every model version and
+      # model type explicitly ([[task:2833]]); the verified minors live here and
+      # in the `[ocr]` bound, and tests/test_packaging.py asserts the two agree.
+      fail-fast: false
+      matrix:
+        rapidocr: ["3.8.4", "3.9.2"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      # `[ocr]` alone is enough: the engine tests need rapidocr, onnxruntime and
+      # cv2 (a rapidocr dependency) — nothing from [full] or [audio]. The second
+      # install pins the leg, since the extra's bound spans both.
+      - name: Install ([ocr] at ${{ matrix.rapidocr }})
+        run: |
+          python -m pip install -e ".[ocr,test]"
+          python -m pip install "rapidocr==${{ matrix.rapidocr }}"
+      # First construction downloads the ~8 MB model, so this leg needs network —
+      # the same prerequisite the `tests` job already carries for the model calls
+      # it makes.
+      - name: Engine tests
+        run: pytest -q tests/test_ocr_engine.py tests/test_ocr.py
+
   build:
     name: build (sdist + wheel, publishable metadata)
     runs-on: ubuntu-latest

{yt_tools_cli-0.24.2 → yt_tools_cli-0.25.0}/CHANGELOG.md

@@ -11,6 +11,36 @@ Releases before 0.8.0 are summarized only in the git log.
 
 _(nothing yet)_
 
+## [0.25.0] — 2026-09-13
+
+### Added
+
+- **`yt-ocr` works on rapidocr 3.9** ([[task:2833]]). The 0.24.2 cap (`<3.9`) is
+  gone: `yt_tools/ocr.py` now names the model type alongside the model version
+  for Det/Cls/Rec, so the params dict means the same thing on every 3.x release
+  instead of inheriting a version-dependent default (3.8 → PP-OCRv4+`mobile`,
+  3.9 → PP-OCRv6+`small`, and PP-OCRv5 has no `small` — that inheritance was
+  [[issue:77]]). The bound is now `>=3.8,<4`: a major is where a params-API
+  change would land.
+- **A CI matrix over the verified minors** (`ocr-engine-matrix`: rapidocr 3.8.4
+  and 3.9.2, engine tests only). The old pin asked users on the *newer* minor to
+  be the acceptance test; now both legs run on every push.
+- **A per-language engine test.** Every `--language` value the CLI advertises is
+  built against the real model registry — the guard for the bug below.
+
+### Fixed
+
+- **`--language ja` never worked.** PP-OCRv5 ships twelve recognizers and
+  Japanese is not one of them: asking for `PP-OCRv5 + japan` resolved to nothing,
+  and the engine raised `error: Invalid OCR configuration` — on 3.8.4 as much as
+  3.9.2, i.e. in every release that ever offered the flag. It used to "work" only
+  because the library's lenient fallback picked the PP-OCRv4 Japanese model, and
+  once the model type was pinned explicitly (above) that fallback was skipped.
+  Japanese now pins the v4 recognizer on purpose, and `ocr.md`'s header says so
+  instead of claiming PP-OCRv5: `RapidOCR (PP-OCRv5 det/cls + PP-OCRv4 ja rec)`.
+  Found by running the language matrix while adapting to 3.9 — the same mocked
+  seam that hid [[issue:77]].
+
 ## [0.24.2] — 2026-09-13
 
 ### Fixed

{yt_tools_cli-0.24.2 → yt_tools_cli-0.25.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: yt-tools-cli
-Version: 0.24.2
+Version: 0.25.0
 Summary: CLI suite for iterative YouTube watching by LLM agents: transcript with [mm:ss] anchors, targeted frame extraction, FFT audio analysis (BPM, key, chord progression, spectral features), and OCR over cached frames for silent-with-text videos.
 Project-URL: Homepage, https://github.com/kzntsv-dev/yt-tools
 Project-URL: Repository, https://github.com/kzntsv-dev/yt-tools
@@ -35,7 +35,7 @@ Requires-Dist: matplotlib>=3.8; extra == 'full'
 Requires-Dist: scenedetect[opencv]>=0.6.4; extra == 'full'
 Provides-Extra: ocr
 Requires-Dist: onnxruntime>=1.18; extra == 'ocr'
-Requires-Dist: rapidocr<3.9,>=3.8; extra == 'ocr'
+Requires-Dist: rapidocr<4,>=3.8; extra == 'ocr'
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == 'test'
 Description-Content-Type: text/markdown
@@ -155,7 +155,7 @@ pipx install "yt-tools-cli[full,ocr]"
 # redirections in bash, cmd.exe and PowerShell. `rapidocr` is capped below 3.9
 # because 3.9 moved the bundled defaults to PP-OCRv6, where the PP-OCRv5 params
 # yt-ocr builds no longer resolve (see the OCR section).
-pipx inject yt-tools-cli "rapidocr>=3.8,<3.9" "onnxruntime>=1.18"
+pipx inject yt-tools-cli "rapidocr>=3.8,<4" "onnxruntime>=1.18"
 ```
 
 `uv` users: `uv tool install "yt-tools-cli[full]"`, or for a one-off run
@@ -192,7 +192,7 @@ matplotlib. Heavier stacks are opt-in, per flow.
 | core (no extras) | `youtube-transcript-api`, `yt-dlp` | `yt-transcript`, `yt-meta`, `yt-comments`, `yt-search`, `yt-tools cache`; `yt-frames --timestamps` / `--mode interval` (without near-duplicate dedup) |
 | `[frames]` | `scenedetect[opencv]` (OpenCV) | `yt-frames --mode scene`, `yt-watch`, and dedup in the other frame modes |
 | `[audio]` | `librosa`, `matplotlib` | `yt-listen` (spectral features, spectrogram, BPM/key) |
-| `[ocr]` | `rapidocr>=3.8,<3.9`, `onnxruntime` | `yt-ocr` (PP-OCRv5; ONNX model downloaded on first run) |
+| `[ocr]` | `rapidocr>=3.8,<4`, `onnxruntime` | `yt-ocr` (PP-OCRv5; ONNX model downloaded on first run) |
 | `[full]` | core + `[frames]` + `[audio]` | the plugin default: every flow above **except `yt-ocr`** |
 
 `[full]` is a *flow* default, not "everything". Two things stay outside it on
@@ -462,8 +462,9 @@ When `yt-transcript` returns 0 bytes (or near-nothing) and the content
 lives entirely in burned-in overlay text — tutorial channels with
 schematic labels, chord matrices over dimmed B-roll, parameter
 walkthroughs without voice-over — fall back to OCR over cached frames.
-Engine is [RapidOCR](https://github.com/RapidAI/RapidOCR) (PP-OCRv5
-models via `onnxruntime`).
+Engine is [RapidOCR](https://github.com/RapidAI/RapidOCR) (PP-OCRv5 models via
+`onnxruntime`; Japanese is read by the PP-OCRv4 recognizer, the only one that
+ships for it — the header line of `ocr.md` names whichever ran).
 
 ```bash
 # 1) extract frames first (lower scene threshold catches overlay fades
@@ -487,7 +488,7 @@ yt-ocr URL --timestamps 1:30,2:45,5:10
 
 # Non-English overlays:
 yt-ocr URL --language ru        # Cyrillic
-yt-ocr URL --language ja        # Japanese
+yt-ocr URL --language ja        # Japanese (PP-OCRv4 recognizer — no v5 model exists)
 yt-ocr URL --language zh        # Chinese (simplified)
 yt-ocr URL --language multi     # PP-OCR multilingual (Chinese+English)
 ```
@@ -501,7 +502,7 @@ was checked vs. silently omitted).
 > core install — and **not** in `[full]` either. If `yt-ocr` exits with the
 > missing-extra hint, run:
 > ```bash
-> pipx inject yt-tools-cli "rapidocr>=3.8,<3.9" "onnxruntime>=1.18"
+> pipx inject yt-tools-cli "rapidocr>=3.8,<4" "onnxruntime>=1.18"
 > # or for non-pipx setups:
 > pip install 'yt-tools-cli[ocr]'
 > ```
@@ -510,13 +511,14 @@ was checked vs. silently omitted).
 > they land in the installed package's own `rapidocr/models/` directory, not in
 > `~/.cache/` — verified on a clean venv.
 >
-> The `rapidocr` bound is not decoration: 3.9 moved the bundled defaults to
-> PP-OCRv6 with `model_type=small`, and PP-OCRv5 ships `mobile`/`server` only —
-> the v5 detector the CLI asks for resolves to nothing there, so a 3.9 install
-> fails at engine construction with `error: Invalid OCR configuration`. The
-> `[ocr]` extra carries the bound, and so does the `pipx inject` line above: an
-> inject resolves from PyPI directly and would otherwise install the version the
-> extra exists to exclude.
+> The `rapidocr` bound is `>=3.8,<4`: the CLI names every model version *and*
+> model type explicitly, so the config means the same on each 3.x release — but a
+> major could change the params API, which is what bit 0.24.x (3.9 defaulted to
+> PP-OCRv6 + `small`, where the PP-OCRv5 detector the CLI asks for does not
+> exist). Both verified minors (3.8.4, 3.9.2) are exercised by the engine test in
+> CI. The `[ocr]` extra carries the bound, and so does the `pipx inject` line
+> above: an inject resolves from PyPI directly and never inherits the extra's
+> metadata.
 
 ### Cache hygiene
 

{yt_tools_cli-0.24.2 → yt_tools_cli-0.25.0}/README.md

@@ -113,7 +113,7 @@ pipx install "yt-tools-cli[full,ocr]"
 # redirections in bash, cmd.exe and PowerShell. `rapidocr` is capped below 3.9
 # because 3.9 moved the bundled defaults to PP-OCRv6, where the PP-OCRv5 params
 # yt-ocr builds no longer resolve (see the OCR section).
-pipx inject yt-tools-cli "rapidocr>=3.8,<3.9" "onnxruntime>=1.18"
+pipx inject yt-tools-cli "rapidocr>=3.8,<4" "onnxruntime>=1.18"
 ```
 
 `uv` users: `uv tool install "yt-tools-cli[full]"`, or for a one-off run
@@ -150,7 +150,7 @@ matplotlib. Heavier stacks are opt-in, per flow.
 | core (no extras) | `youtube-transcript-api`, `yt-dlp` | `yt-transcript`, `yt-meta`, `yt-comments`, `yt-search`, `yt-tools cache`; `yt-frames --timestamps` / `--mode interval` (without near-duplicate dedup) |
 | `[frames]` | `scenedetect[opencv]` (OpenCV) | `yt-frames --mode scene`, `yt-watch`, and dedup in the other frame modes |
 | `[audio]` | `librosa`, `matplotlib` | `yt-listen` (spectral features, spectrogram, BPM/key) |
-| `[ocr]` | `rapidocr>=3.8,<3.9`, `onnxruntime` | `yt-ocr` (PP-OCRv5; ONNX model downloaded on first run) |
+| `[ocr]` | `rapidocr>=3.8,<4`, `onnxruntime` | `yt-ocr` (PP-OCRv5; ONNX model downloaded on first run) |
 | `[full]` | core + `[frames]` + `[audio]` | the plugin default: every flow above **except `yt-ocr`** |
 
 `[full]` is a *flow* default, not "everything". Two things stay outside it on
@@ -420,8 +420,9 @@ When `yt-transcript` returns 0 bytes (or near-nothing) and the content
 lives entirely in burned-in overlay text — tutorial channels with
 schematic labels, chord matrices over dimmed B-roll, parameter
 walkthroughs without voice-over — fall back to OCR over cached frames.
-Engine is [RapidOCR](https://github.com/RapidAI/RapidOCR) (PP-OCRv5
-models via `onnxruntime`).
+Engine is [RapidOCR](https://github.com/RapidAI/RapidOCR) (PP-OCRv5 models via
+`onnxruntime`; Japanese is read by the PP-OCRv4 recognizer, the only one that
+ships for it — the header line of `ocr.md` names whichever ran).
 
 ```bash
 # 1) extract frames first (lower scene threshold catches overlay fades
@@ -445,7 +446,7 @@ yt-ocr URL --timestamps 1:30,2:45,5:10
 
 # Non-English overlays:
 yt-ocr URL --language ru        # Cyrillic
-yt-ocr URL --language ja        # Japanese
+yt-ocr URL --language ja        # Japanese (PP-OCRv4 recognizer — no v5 model exists)
 yt-ocr URL --language zh        # Chinese (simplified)
 yt-ocr URL --language multi     # PP-OCR multilingual (Chinese+English)
 ```
@@ -459,7 +460,7 @@ was checked vs. silently omitted).
 > core install — and **not** in `[full]` either. If `yt-ocr` exits with the
 > missing-extra hint, run:
 > ```bash
-> pipx inject yt-tools-cli "rapidocr>=3.8,<3.9" "onnxruntime>=1.18"
+> pipx inject yt-tools-cli "rapidocr>=3.8,<4" "onnxruntime>=1.18"
 > # or for non-pipx setups:
 > pip install 'yt-tools-cli[ocr]'
 > ```
@@ -468,13 +469,14 @@ was checked vs. silently omitted).
 > they land in the installed package's own `rapidocr/models/` directory, not in
 > `~/.cache/` — verified on a clean venv.
 >
-> The `rapidocr` bound is not decoration: 3.9 moved the bundled defaults to
-> PP-OCRv6 with `model_type=small`, and PP-OCRv5 ships `mobile`/`server` only —
-> the v5 detector the CLI asks for resolves to nothing there, so a 3.9 install
-> fails at engine construction with `error: Invalid OCR configuration`. The
-> `[ocr]` extra carries the bound, and so does the `pipx inject` line above: an
-> inject resolves from PyPI directly and would otherwise install the version the
-> extra exists to exclude.
+> The `rapidocr` bound is `>=3.8,<4`: the CLI names every model version *and*
+> model type explicitly, so the config means the same on each 3.x release — but a
+> major could change the params API, which is what bit 0.24.x (3.9 defaulted to
+> PP-OCRv6 + `small`, where the PP-OCRv5 detector the CLI asks for does not
+> exist). Both verified minors (3.8.4, 3.9.2) are exercised by the engine test in
+> CI. The `[ocr]` extra carries the bound, and so does the `pipx inject` line
+> above: an inject resolves from PyPI directly and never inherits the extra's
+> metadata.
 
 ### Cache hygiene
 

{yt_tools_cli-0.24.2 → yt_tools_cli-0.25.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "yt-tools-cli"
-version = "0.24.2"
+version = "0.25.0"
 description = "CLI suite for iterative YouTube watching by LLM agents: transcript with [mm:ss] anchors, targeted frame extraction, FFT audio analysis (BPM, key, chord progression, spectral features), and OCR over cached frames for silent-with-text videos."
 readme = "README.md"
 requires-python = ">=3.10,<3.13"
@@ -79,18 +79,17 @@ full = [
     "matplotlib>=3.8",
 ]
 ocr = [
-    # Capped below 3.9 on purpose ([[task:2831]], [[issue:77]]). 3.9 moved the
-    # bundled defaults to ``ocr_version=PP-OCRv6, model_type=small``; ocr.py
-    # overrides the ocr_version to PP-OCRv5 but leaves model_type at that
-    # default, and PP-OCRv5 ships ``mobile``/``server`` only — so "PP-OCRv5 small"
-    # resolves to nothing (the lenient prefix fallback finds no candidate either)
-    # and RapidOCR raises ``error: Invalid OCR configuration`` at construction.
-    # A clean ``pipx install "yt-tools-cli[ocr]"`` therefore installed 3.9.2 and
-    # every ``yt-ocr`` run died. Lift the cap only in the change that teaches
-    # ocr.py the 3.9 model matrix (pin ``model_type`` explicitly, then re-check
-    # every ``--language``) — tests/test_ocr_engine.py drives the real engine and
-    # fails if the pin comes off alone.
-    "rapidocr>=3.8,<3.9",
+    # Pinned to the 3.x params API ([[task:2833]]). Within it, `ocr.py` names
+    # *everything* explicitly — `Det/Cls/Rec.ocr_version` and the matching
+    # `model_type`, plus the recognizer version per language — so the config no
+    # longer depends on whatever defaults the installed release ships. That was
+    # the 0.24.2 bug ([[issue:77]]): 3.8 defaulted to PP-OCRv4+mobile, 3.9 moved
+    # Det/Rec to PP-OCRv6+small, and PP-OCRv5 has no `small`, so a version-only
+    # pin asked for a model that does not exist and construction raised
+    # `error: Invalid OCR configuration`. Verified against 3.8.4 and 3.9.2 for
+    # every `--language` (CI matrix: .github/workflows/ci.yml); the major bound
+    # is what a params-API change would break, so it stays.
+    "rapidocr>=3.8,<4",
     "onnxruntime>=1.18",
 ]
 test = ["pytest>=7.0"]

{yt_tools_cli-0.24.2 → yt_tools_cli-0.25.0}/skills/using-yt-tools/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: using-yt-tools
-version: 0.24.2
+version: 0.25.0
 description: Seven YouTube flows, one skill. Discovery `yt-search` ("find a video about X", «найди видео про X», «поищи туториал»). Summary / exploration `yt-transcript` — [mm:ss] anchors, then pick moments and run `yt-frames` ("what's in this video", «о чём видео»). Targeted frames directly by timestamp ("show frame at N", «покажи кадр на N»). Audio FFT `yt-listen` — BPM, key, chords, structure ("what's the BPM", «спектрограмма», «тональность видео»). Metadata `yt-meta` — description, chapters, most-replayed ("video description", «что в описании», «покажи главы»). Comments `yt-comments` ("top comments", «комменты под роликом»). OCR over cached frames `yt-ocr` — silent-with-text fallback ("read text from frames", "captions burned in", «прочти текст с кадров»). Any youtube.com URL. Install once per machine with pipx (`pipx install 'yt-tools-cli[full]'`); `yt-tools doctor` is the read-only preflight that names what is missing. YouTube-only — Vimeo / Twitch / local files need other tools.
 ---
 
@@ -108,7 +108,7 @@ Seven distinct flows, picked by user intent:
   interesting timestamps if you need the original frames.
 - **Requires the `[ocr]` extra** — `rapidocr` + `onnxruntime`, **not** part of
   `[full]`. If missing on the running yt-tools install, `yt-ocr` exits nonzero
-  with both install hints (`pipx inject yt-tools-cli "rapidocr>=3.8,<3.9"
+  with both install hints (`pipx inject yt-tools-cli "rapidocr>=3.8,<4"
   "onnxruntime>=1.18"` / `pip install 'yt-tools-cli[ocr]'`). The plugin's
   SessionStart hook installs `[full]` (core + `[frames]` + `[audio]`, plus a
   best-effort `bpm-detector` inject) only, **not** `[ocr]` — first run of Flow F
@@ -152,10 +152,10 @@ pipx install "yt-tools-cli[full]==0.24.2"
 # OCR (explicit extra, ~10 MB model fetched on first run). Naming it in the
 # install lets pip resolve it from the metadata, bounds included:
 pipx install "yt-tools-cli[full,ocr]"
-# already installed? widen in place — `rapidocr` is capped below 3.9, where the
-# PP-OCRv5 params yt-ocr builds no longer resolve (quote the specs: `>`/`<` are
-# redirections in bash, cmd.exe and PowerShell):
-pipx inject yt-tools-cli "rapidocr>=3.8,<3.9" "onnxruntime>=1.18"
+# already installed? widen in place — the bound is `>=3.8,<4` (a major is where a
+# params-API change would land; quote the specs — `>`/`<` are redirections in
+# bash, cmd.exe and PowerShell):
+pipx inject yt-tools-cli "rapidocr>=3.8,<4" "onnxruntime>=1.18"
 ```
 
 From a checkout instead of PyPI (the plugin path, or tracking `master`):
@@ -305,7 +305,7 @@ prepend is needed — invoke normally.
 | C — audio-analysis | YouTube URL + timestamps (same formats as B) | `--duration 30s` (default 30s — the lower bound for beat-tracking); `--mode interval --interval 60s` (bulk sampling); `--no-wav` / `--no-spectrogram` (both default ON); `--linear` (STFT instead of mel); `--chroma` (bonus chromagram PNG); `--sample-rate 22050`; `--no-cache-source`; `--out DIR` |
 | D — metadata | YouTube URL or bare 11-char video id | `--out PATH` |
 | E — comments | YouTube URL or bare 11-char video id | `--max N` (default 50; higher = slower); `--sort {top,new}` (default top); `--out PATH` |
-| F — OCR | YouTube URL or bare 11-char video id (frames in cache, or pass `--timestamps`) | `--timestamps T1,T2,…` (extract via internal yt-frames then OCR); `--language {en,ru,ja,zh,multi}` (default `en`); `--out PATH` |
+| F — OCR | YouTube URL or bare 11-char video id (frames in cache, or pass `--timestamps`) | `--timestamps T1,T2,…` (extract via internal yt-frames then OCR); `--language {en,ru,ja,zh,multi}` (default `en`; `ja` is read by the PP-OCRv4 recognizer — no PP-OCRv5 Japanese model exists); `--out PATH` |
 
 **Frame budget.** Auto-selected frames (`--mode scene`, `--mode interval`, and
 `yt-watch`) are capped at **100 per call** and evenly thinned with the first and
@@ -532,7 +532,7 @@ All failures abort cleanly; never leave a half-finished state.
 | `Subtitles disabled` / `no captions in the requested language(s)` / `the transcript API returned nothing usable (ParseError: …)` from `yt-transcript` | Captions are absent (channel-disabled, wrong `--lang`, or YouTube answered with an empty body — the last one used to surface as a bare `no element found: line 1, column 0`). The message names the reason and both fallbacks. | Fatal for Flow A — tell the user the reason, and switch: Flow C (`yt-listen`) for audio, Flow F (`yt-ocr`) for text burned into the frames. Try another `--lang` first only when the reason says the *requested language* is missing. `yt-watch` on the same video does **not** fail — it writes a frames-only `watch.md` with the reason in its header, so read the frames and say that the text layer is absent. |
 | Flow B/D — `yt-frames --mode scene requires the [frames] extra` / `yt-watch requires the [frames] extra` | `scenedetect` / `opencv-python` not in the active pipx venv | Exit code 1, nothing was downloaded. Tell the user the command the CLI printed (`pipx inject yt-tools-cli scenedetect opencv-python` or `pip install 'yt-tools-cli[frames]'`). Fallbacks that need no install: Flow D with an explicit `--timestamps` list, or `--mode interval` (which still runs and announces on stderr that near-duplicate dedup was skipped). |
 | Flow C — `yt-listen requires the [audio] extra` | `librosa` / `matplotlib` not in the active pipx venv | Exit code 1. Same shape: print the command the CLI named. Until it is installed, Flow A (transcript) and Flow F (`yt-ocr`) are the alternatives for this video. |
-| Flow F — `yt-ocr requires the [ocr] extra` | `rapidocr` / `onnxruntime` not in the active pipx venv | Run the inject command the CLI printed: `pipx inject yt-tools-cli "rapidocr>=3.8,<3.9" "onnxruntime>=1.18"` (or `pip install 'yt-tools-cli[ocr]'` in non-pipx setups). The bound is load-bearing: an inject resolves from PyPI directly, and 3.9 fails at engine construction. The plugin's SessionStart hook installs `[full]`, not `[ocr]`, so first run typically needs this. |
+| Flow F — `yt-ocr requires the [ocr] extra` | `rapidocr` / `onnxruntime` not in the active pipx venv | Run the inject command the CLI printed: `pipx inject yt-tools-cli "rapidocr>=3.8,<4" "onnxruntime>=1.18"` (or `pip install 'yt-tools-cli[ocr]'` in non-pipx setups). The bound is load-bearing: an inject resolves from PyPI directly and never inherits the extra's metadata (`>`/`<` need the quotes). The plugin's SessionStart hook installs `[full]`, not `[ocr]`, so first run typically needs this. |
 | Flow F — `no cached frames in …/frames` | Batch-on-cache mode but `yt-frames` wasn't run yet (or wrote elsewhere) | Either run `yt-frames URL --mode scene --scene-threshold 12` (or `--mode interval --interval 15s`) first, or re-invoke `yt-ocr URL --timestamps T1,T2,…` to let it do extraction inline. |
 | Flow F — RapidOCR model download fails (offline / firewall) | First-run lazy-download of PP-OCRv5 ONNX weights blocked | Print the captured error; let the user re-run with network access. Don't retry. |
 | User passed a non-YouTube URL (Vimeo / Twitch / local mp4) | Out of scope | Stop; say the skill is YouTube-only. |
@@ -647,7 +647,9 @@ instead of printing a traceback.
   `zh` / `multi`. If the user doesn't name a language, default to `en`;
   if they say "русский / Japanese / Chinese", pass the matching code
   explicitly. (`multi` is the PP-OCR multilingual model — slower, wider
-  CJK + Latin coverage; use it when the video mixes scripts.)
+  CJK + Latin coverage; use it when the video mixes scripts. `en`/`ru`/
+  `zh`/`multi` read with a PP-OCRv5 recognizer and `ja` with the v4 one —
+  the header line of `ocr.md` names whichever ran.)
 - **Don't try to OCR arbitrary `.jpg` files with `yt-ocr`.** This skill
   and CLI live in the YouTube domain: `yt-ocr` only accepts a YouTube
   URL / video-id and reads frames from `./yt-cache/<vid>/frames/`. For

{yt_tools_cli-0.24.2 → yt_tools_cli-0.25.0}/tests/test_missing_extra.py

@@ -82,7 +82,7 @@ def test_audio_refusal_wording_is_exact():
 def test_ocr_refusal_wording_is_exact():
     assert extras.format_missing_extra("yt-ocr", "ocr") == (
         "yt-ocr requires the [ocr] extra:\n"
-        '  pipx inject yt-tools-cli "rapidocr>=3.8,<3.9" "onnxruntime>=1.18"\n'
+        '  pipx inject yt-tools-cli "rapidocr>=3.8,<4" "onnxruntime>=1.18"\n'
         "  # or\n"
         "  pip install 'yt-tools-cli[ocr]'"
     )

{yt_tools_cli-0.24.2 → yt_tools_cli-0.25.0}/tests/test_ocr.py

@@ -88,6 +88,11 @@ class _FakeLangRec:
 
 class _FakeOCRVersion:
     PPOCRV5 = "ocrver::v5"
+    PPOCRV4 = "ocrver::v4"
+
+
+class _FakeModelType:
+    MOBILE = "model::mobile"
 
 
 def test_build_params_en_maps_to_LangRec_EN():
@@ -133,6 +138,68 @@ def test_build_params_multi_still_forces_v5():
     assert "Rec.lang_type" not in p
 
 
+# task:2833 — the model_type half of the PP-OCRv5 pin. Pinning only the version
+# left model_type at rapidocr's default, which is a *version-dependent* value:
+# 3.8 defaults every component to PP-OCRv4 + "mobile" (valid for v5), 3.9 moved
+# Det/Rec to PP-OCRv6 + "small" — and PP-OCRv5 ships mobile/server only, so
+# "PP-OCRv5 … small" resolves to nothing and construction raises
+# "error: Invalid OCR configuration" ([[issue:77]]). Naming the model type makes
+# the config independent of whatever default the installed release ships.
+def test_build_params_pins_the_model_type_alongside_the_version():
+    p = _build_params("en", _FakeLangRec, _FakeOCRVersion, _FakeModelType)
+    assert p["Det.model_type"] == "model::mobile"
+    assert p["Cls.model_type"] == "model::mobile"
+    assert p["Rec.model_type"] == "model::mobile"
+
+
+def test_build_params_multi_also_pins_the_model_type():
+    p = _build_params("multi", _FakeLangRec, _FakeOCRVersion, _FakeModelType)
+    assert p["Rec.model_type"] == "model::mobile"
+    assert "Rec.lang_type" not in p
+
+
+def test_build_params_without_a_modeltype_enum_stays_silent_about_it():
+    """The version/model pins travel together: no enum, no keys.
+
+    ``_build_params`` is called with the rapidocr enums only from
+    ``_load_engine``; the older signature (no ``ModelType``) must not
+    silently emit a half pin — a config with ``model_type`` but no
+    ``ocr_version`` (or the reverse) is exactly the drift this pins against.
+    """
+    p = _build_params("en", _FakeLangRec, _FakeOCRVersion)
+    assert not [k for k in p if "model_type" in k] or p["Det.ocr_version"] == "ocrver::v5"
+
+
+# task:2833 — PP-OCRv5 ships twelve recognizers and Japanese is not one of them
+# (its registry entry is v4-only, identically in 3.8.x and 3.9.x). Asking for
+# v5 + japan resolves to nothing; before this pin the v4 model was found by the
+# library's lenient fallback, and once model_type is named — as it must be, so
+# the config stops depending on the installed release's defaults — that fallback
+# is skipped and construction raises. Pinning the recognizer per language makes
+# `--language ja` work by design rather than by luck.
+def test_build_params_ja_uses_the_v4_recognizer():
+    p = _build_params("ja", _FakeLangRec, _FakeOCRVersion, _FakeModelType)
+    assert p["Rec.lang_type"] == "lang::japan"
+    assert p["Rec.ocr_version"] == "ocrver::v4"
+    # ...while detection and classification stay on v5: they are
+    # language-agnostic (one `ch` model each) in the v5 family.
+    assert p["Det.ocr_version"] == "ocrver::v5"
+    assert p["Cls.ocr_version"] == "ocrver::v5"
+
+
+def test_build_params_languages_with_a_v5_recognizer_stay_on_v5():
+    for lang in ("en", "ru", "zh"):
+        p = _build_params(lang, _FakeLangRec, _FakeOCRVersion, _FakeModelType)
+        assert p["Rec.ocr_version"] == "ocrver::v5", lang
+
+
+def test_build_params_multi_keeps_the_v5_ch_recognizer():
+    """`multi` means RapidOCR's default recognizer — which for v5 is `ch`."""
+    p = _build_params("multi", _FakeLangRec, _FakeOCRVersion, _FakeModelType)
+    assert p["Rec.ocr_version"] == "ocrver::v5"
+    assert "Rec.lang_type" not in p
+
+
 # --- ocr_to_markdown ---------------------------------------------------------
 
 
@@ -180,6 +247,21 @@ def test_render_zero_frames_still_emits_header():
     assert "frames: 0" in md
 
 
+# task:2833 — the header line is the only trace of *what* read the frames, so it
+# must not claim PP-OCRv5 for a language that has no v5 recognizer (Japanese is
+# read by the v4 recognizer, see _LANGUAGE_REC_VERSION).
+def test_render_names_the_v4_recognizer_for_japanese():
+    md = ocr_to_markdown(_VID, [(23, ["こんにちは"])], language="ja")
+    assert "PP-OCRv4" in md, "the ja header must name the recognizer that actually ran"
+    assert "language: ja" in md
+
+
+def test_render_keeps_the_plain_v5_label_for_languages_that_have_one():
+    md = ocr_to_markdown(_VID, [(23, ["hello"])], language="en")
+    assert "engine: RapidOCR (PP-OCRv5)" in md
+    assert "PP-OCRv4" not in md
+
+
 # --- _load_engine: friendly missing-extra hint -------------------------------
 
 
@@ -195,7 +277,7 @@ def test_load_engine_friendly_hint_when_rapidocr_missing(monkeypatch):
     with pytest.raises(OcrError) as exc_info:
         ocr_mod._load_engine("en")
     msg = str(exc_info.value)
-    assert 'pipx inject yt-tools-cli "rapidocr>=3.8,<3.9" "onnxruntime>=1.18"' in msg
+    assert 'pipx inject yt-tools-cli "rapidocr>=3.8,<4" "onnxruntime>=1.18"' in msg
     assert "pip install 'yt-tools-cli[ocr]'" in msg
 
 
@@ -294,7 +376,7 @@ def test_cli_missing_extra_prints_friendly_hint(tmp_path, monkeypatch, capsys):
     def _raise(_lang):
         raise OcrError(
             "yt-ocr requires the [ocr] extra:\n"
-            '  pipx inject yt-tools-cli "rapidocr>=3.8,<3.9" "onnxruntime>=1.18"\n'
+            '  pipx inject yt-tools-cli "rapidocr>=3.8,<4" "onnxruntime>=1.18"\n'
             "  # or\n"
             "  pip install 'yt-tools-cli[ocr]'"
         )
@@ -304,7 +386,7 @@ def test_cli_missing_extra_prints_friendly_hint(tmp_path, monkeypatch, capsys):
 
     assert rc == 1
     err = capsys.readouterr().err
-    assert 'pipx inject yt-tools-cli "rapidocr>=3.8,<3.9" "onnxruntime>=1.18"' in err
+    assert 'pipx inject yt-tools-cli "rapidocr>=3.8,<4" "onnxruntime>=1.18"' in err
     assert "pip install 'yt-tools-cli[ocr]'" in err
 
 

{yt_tools_cli-0.24.2 → yt_tools_cli-0.25.0}/tests/test_ocr_engine.py

@@ -85,6 +85,25 @@ def engine():
     return ocr_mod._load_engine("en")
 
 
+@pytest.mark.parametrize("language", ocr_mod.SUPPORTED_LANGUAGES)
+def test_every_supported_language_constructs_an_engine(language):
+    """Every `--language` value must resolve to a model that exists (task:2833).
+
+    Language → model is not a free mapping: the recognizer is per language, and
+    PP-OCRv5 ships twelve of them with **no Japanese** among them — `--language
+    ja` asked for a model that does not exist and died at construction, on 3.8.4
+    as well as 3.9.2, while every test here (and the whole suite) stayed green
+    because only `en` was ever built. This is the guard for that class: it
+    exercises the real registry for every value the CLI advertises.
+
+    Construction, not OCR: what breaks is model resolution, and a Japanese
+    recognizer reading Latin text proves nothing. It does download a recognizer
+    per language (~8-16 MB, once per runner) — the same lazy fetch the first real
+    run pays, which is why this module already needs the network.
+    """
+    assert ocr_mod._load_engine(language) is not None
+
+
 def test_load_engine_constructs_the_declared_params(engine):
     """The 3.9.x failure mode: RapidOCR refuses the 3.8.x-shaped ``params`` dict."""
     assert engine is not None

{yt_tools_cli-0.24.2 → yt_tools_cli-0.25.0}/tests/test_packaging.py

@@ -214,31 +214,32 @@ def test_ocr_extra_is_unchanged():
     assert ocr == {"rapidocr", "onnxruntime"}
 
 
-def test_ocr_extra_pins_rapidocr_below_3_9():
-    """`yt_tools/ocr.py` builds the RapidOCR **3.8.x** params schema (task:2831).
-
-    ``params["Det.ocr_version"] = OCRVersion.PPOCRV5`` (+ Cls/Rec) and the
-    ``LangRec`` overrides are 3.8.x-shaped. 3.9.x changed the schema and rejects
-    the dict at construction — ``error: Invalid OCR configuration`` — which is
-    what a clean ``pipx install "yt-tools-cli[ocr]"`` hit: 0.24.0/0.24.1 declared
-    ``rapidocr>=3.8``, the resolver picked 3.9.2, and every ``yt-ocr`` run died
-    on a machine that had installed exactly what the metadata asked for.
-
-    Same shape as the librosa cap above: an upper bound that encodes a
-    compatibility fact, removed only together with the code that depends on it.
-    The behavioural half is ``tests/test_ocr_engine.py``, which drives the real
-    engine — this one keeps the boundary from drifting back out of the metadata
-    where nothing local would notice.
+def test_ocr_extra_keeps_the_rapidocr_3x_params_bound():
+    """The bound encodes a params-API boundary, not a version grudge (task:2833).
+
+    0.24.2 capped `rapidocr<3.9`: `ocr.py` pinned `ocr_version=PP-OCRv5` but left
+    `model_type` at the library default, and 3.9 moved that default to
+    `PP-OCRv6 + small` where the v5 family has no `small` — so a clean install
+    died with `error: Invalid OCR configuration` ([[issue:77]]). The fix names
+    every component's version *and* model type, which makes the config
+    release-independent and lets 3.9.x back in; the remaining cap is the major
+    version, because that is the boundary a params-API change would cross.
+
+    Both halves are cheap to assert and hard to notice by hand: the verified
+    minors must stay installable (CI installs exactly them — see the matrix job)
+    and the next major must not slide in unannounced.
     """
     specs = _pyproject()["project"]["optional-dependencies"]["ocr"]
     req = Requirement(next(spec for spec in specs if _dist_name(spec) == "rapidocr"))
 
-    assert req.specifier.contains("3.8.4"), (
-        "the RapidOCR release yt-ocr is written against must stay installable"
-    )
-    assert not req.specifier.contains("3.9.0"), (
-        "rapidocr 3.9 changed the params schema yt_tools/ocr.py builds — lift this "
-        "cap only in the same change that adapts the code"
+    for verified in ("3.8.4", "3.9.2"):
+        assert req.specifier.contains(verified), (
+            f"rapidocr {verified} is verified by tests/test_ocr_engine.py in CI and "
+            "must stay installable"
+        )
+    assert not req.specifier.contains("4.0.0"), (
+        "a rapidocr major could change the params API again — widen only with a "
+        "green engine test against that version"
     )
 
 
@@ -246,11 +247,12 @@ def test_ocr_inject_hint_carries_the_same_bound_as_the_extra():
     """Two install routes, one bound — the `pipx inject` hint has no metadata to inherit.
 
     ``yt-ocr`` refusing with `pipx inject yt-tools-cli rapidocr onnxruntime` told
-    the user to install exactly the pair the extra caps below 3.9 — an inject
-    resolves from PyPI directly, so the refusal message would have reproduced
-    [[issue:77]] on a machine that followed it to the letter. ``doctor``'s
-    ``next_step`` and the README print the same line, so the assertion is on the
-    constant all three read from, not on one caller's wording.
+    the user to install the pair by name — an inject resolves from PyPI directly,
+    so the refusal message never inherited the extra's bound and, in the 0.24.x
+    window, would have reproduced [[issue:77]] on a machine that followed it to
+    the letter. ``doctor``'s ``next_step`` and the README print the same line, so
+    the assertion is on the constant all three read from, not on one caller's
+    wording.
     """
     from yt_tools import extras  # noqa: PLC0415 — local import keeps the packaging tests import-light
 
@@ -268,7 +270,7 @@ def test_ocr_inject_hint_carries_the_same_bound_as_the_extra():
         "the [ocr] extra and the inject hint must name the same requirements — "
         "the hint is what a user pastes when the extra is missing"
     )
-    assert '"rapidocr>=3.8,<3.9"' in extras.inject_command("ocr"), (
+    assert '"rapidocr>=3.8,<4"' in extras.inject_command("ocr"), (
         "a bounded spec must be quoted: `>` and `<` are redirections in bash, cmd.exe and PowerShell"
     )
 
@@ -286,6 +288,13 @@ def test_ci_installs_the_ocr_extra_so_the_engine_test_actually_runs():
     assert 'pip install -e ".[full,ocr,test]"' in workflow, (
         "the pytest job must install [ocr], or tests/test_ocr_engine.py skips there too"
     )
+    # ...and the matrix legs are where the *unselected* minor gets exercised: the
+    # pytest job resolves whichever rapidocr the bound allows today.
+    for verified in ("3.8.4", "3.9.2"):
+        assert f'"{verified}"' in workflow, (
+            f"the ocr-engine-matrix job must cover rapidocr {verified} — a bound "
+            "claiming a version nothing runs against is how issue:77 shipped"
+        )
 
 
 @pytest.mark.parametrize("extra", ["audio", "full"])

{yt_tools_cli-0.24.2 → yt_tools_cli-0.25.0}/yt_tools/extras.py

@@ -44,7 +44,7 @@ EXTRA_MODULES: dict[str, tuple[str, ...]] = {
 EXTRA_PACKAGES: dict[str, tuple[str, ...]] = {
     "frames": ("scenedetect", "opencv-python"),
     "audio": ("librosa", "matplotlib"),
-    "ocr": ("rapidocr>=3.8,<3.9", "onnxruntime>=1.18"),
+    "ocr": ("rapidocr>=3.8,<4", "onnxruntime>=1.18"),
 }
 
 #: The enrichment that cannot be a package extra. ``bpm-detector`` gives
@@ -105,7 +105,7 @@ def inject_command_for(extra_names: list[str] | tuple[str, ...]) -> str:
     """One command adding several extras — what ``doctor``'s ``next_step`` prints.
 
     Every spec is double-quoted: an injected spec can carry version bounds
-    (``rapidocr>=3.8,<3.9``), and an unquoted ``>``/``<`` is a redirection in
+    (``rapidocr>=3.8,<4``), and an unquoted ``>``/``<`` is a redirection in
     bash, cmd.exe and PowerShell alike — the printed command has to be
     pasteable, since being pasteable is the whole point of it.
     """

{yt_tools_cli-0.24.2 → yt_tools_cli-0.25.0}/yt_tools/ocr.py

@@ -30,12 +30,35 @@ from yt_tools.core import (
 from yt_tools.extras import format_missing_extra
 
 ENGINE_LABEL = "RapidOCR (PP-OCRv5)"
+#: Languages whose recognizer is not PP-OCRv5 — the label has to name what ran.
+_ENGINE_LABEL_JA = "RapidOCR (PP-OCRv5 det/cls + PP-OCRv4 ja rec)"
 DEFAULT_LANGUAGE = "en"
 SUPPORTED_LANGUAGES = ("en", "ru", "ja", "zh", "multi")
 
 _FRAME_RE = re.compile(r"^frame_(\d+)(?:_(\d+))?\.jpg$")
 _NO_TEXT_MARKER = "_(no text detected)_"
 
+#: Language → (``LangRec`` member name, recognizer ``OCRVersion`` member name).
+#:
+#: Detection and classification are language-agnostic in the v5 family (one `ch`
+#: model each), but the recognizer is per language — and PP-OCRv5 ships twelve of
+#: them (arabic, ch, cyrillic, devanagari, el, en, eslav, korean, latin, ta, te,
+#: th), **Japanese not among them**: `japan_PP-OCRv4_rec_mobile` is the only
+#: Japanese recognizer in both 3.8.x and 3.9.x registries. So the version is
+#: named per language instead of forced globally. Two failure modes meet here, and
+#: both shipped: with `Rec.ocr_version=PP-OCRv5` + `japan` the library's lenient
+#: fallback used to pick the v4 model (working by luck), and once `model_type` is
+#: named — which it must be, or the config depends on the installed release's
+#: defaults ([[issue:77]]) — the fallback is skipped and construction raises
+#: `Invalid OCR configuration`. Verified by building the engine for every
+#: ``SUPPORTED_LANGUAGES`` entry on rapidocr 3.8.4 and 3.9.2 ([[task:2833]]).
+_LANGUAGE_REC_VERSION: dict[str, tuple[str, str]] = {
+    "en": ("EN", "PPOCRV5"),
+    "ru": ("CYRILLIC", "PPOCRV5"),
+    "ja": ("JAPAN", "PPOCRV4"),
+    "zh": ("CH", "PPOCRV5"),
+}
+
 
 class OcrError(RuntimeError):
     """Any OCR-side failure: missing extra, missing cache, model issues, etc."""
@@ -82,36 +105,58 @@ def discover_frames(frames_dir: Path) -> list[tuple[int, Path]]:
 # --- engine factory (lazy import) -------------------------------------------
 
 
-def _build_params(language: str, langrec_enum, ocrversion_enum=None) -> dict:
+def _build_params(
+    language: str,
+    langrec_enum,
+    ocrversion_enum=None,
+    modeltype_enum=None,
+) -> dict:
     """Map user-facing language → RapidOCR params dict.
 
     Forces ``PP-OCRv5`` across Det / Cls / Rec when ``ocrversion_enum`` is
     supplied (RapidOCR 3.8.x defaults the bundled-model dance to v4 — we want
-    v5 per design spec). For ``multi``, returns params **without** a
-    ``Rec.lang_type`` override so RapidOCR picks its default multilingual
-    model (Chinese+English).
+    v5 per design spec) **and names the model type** (``mobile``) alongside it,
+    when ``modeltype_enum`` is supplied.
+
+    Both halves are needed, and that is the whole lesson of [[issue:77]]: the
+    model type is a *version-dependent default*, not a constant. 3.8.x defaults
+    every component to ``PP-OCRv4 + mobile`` — which happens to be valid for v5
+    too; 3.9.x moved Det/Rec to ``PP-OCRv6 + small``, and the v5 family ships
+    ``mobile``/``server`` only, so a version-only pin asked for "PP-OCRv5 … small"
+    and RapidOCR refused the config at construction. Pinning the pair makes the
+    params mean the same thing on every supported release.
+
+    For ``multi``, returns params **without** a ``Rec.lang_type`` override so
+    RapidOCR picks its default multilingual model (Chinese+English).
     """
     params: dict = {}
     if ocrversion_enum is not None:
         v5 = ocrversion_enum.PPOCRV5
         params["Det.ocr_version"] = v5
         params["Cls.ocr_version"] = v5
+        # Overridden per language below: not every supported language has a v5
+        # recognizer (see _LANGUAGE_REC_VERSION).
         params["Rec.ocr_version"] = v5
+    if modeltype_enum is not None:
+        # `mobile` (not `server`): the small/fast bundle, matching the CPU-only
+        # onnxruntime install the extra brings, and the one key the v5 family
+        # has for every supported language/component.
+        mobile = modeltype_enum.MOBILE
+        params["Det.model_type"] = mobile
+        params["Cls.model_type"] = mobile
+        params["Rec.model_type"] = mobile
     if language == "multi":
         return params
-    mapping = {
-        "en": getattr(langrec_enum, "EN", None),
-        "ru": getattr(langrec_enum, "CYRILLIC", None),
-        "ja": getattr(langrec_enum, "JAPAN", None),
-        "zh": getattr(langrec_enum, "CH", None),
-    }
-    lang_type = mapping.get(language)
+    member, rec_version = _LANGUAGE_REC_VERSION.get(language, (None, None))
+    lang_type = getattr(langrec_enum, member, None) if member else None
     if lang_type is None:
         raise OcrError(
             f"unknown language: {language!r} "
             f"(supported: {', '.join(SUPPORTED_LANGUAGES)})"
         )
     params["Rec.lang_type"] = lang_type
+    if ocrversion_enum is not None:
+        params["Rec.ocr_version"] = getattr(ocrversion_enum, rec_version)
     return params
 
 
@@ -123,12 +168,12 @@ def _load_engine(language: str):
     without it.
     """
     try:
-        from rapidocr import LangRec, OCRVersion, RapidOCR  # noqa: PLC0415
+        from rapidocr import LangRec, ModelType, OCRVersion, RapidOCR  # noqa: PLC0415
         import onnxruntime  # noqa: F401, PLC0415 — the [ocr] extra ships both; a half-installed pair must refuse here, not crash later
     except ImportError as e:
         # Same wording as every other CLI (D4) — the message lives in one place.
         raise OcrError(format_missing_extra("yt-ocr", "ocr")) from e
-    params = _build_params(language, LangRec, OCRVersion)
+    params = _build_params(language, LangRec, OCRVersion, ModelType)
     return RapidOCR(params=params)
 
 
@@ -153,6 +198,18 @@ def _ocr_one(engine, image_path: Path) -> list[str]:
 # --- pure render -------------------------------------------------------------
 
 
+def engine_label(language: str) -> str:
+    """Header label naming the recognizer that actually runs for ``language``.
+
+    Japanese is the one supported language with no PP-OCRv5 recognizer, so a
+    blanket "PP-OCRv5" line would be a claim the artefact cannot back — and the
+    header is the only place a reader (or an agent comparing two runs) can see
+    which models produced the text.
+    """
+    _, rec_version = _LANGUAGE_REC_VERSION.get(language, (None, "PPOCRV5"))
+    return _ENGINE_LABEL_JA if rec_version == "PPOCRV4" else ENGINE_LABEL
+
+
 def ocr_to_markdown(
     video_id: str,
     frames: list[tuple[int, list[str]]],
@@ -166,7 +223,7 @@ def ocr_to_markdown(
         f"# OCR — {video_id}",
         "",
         (
-            f"generated: {generated} · engine: {ENGINE_LABEL}"
+            f"generated: {generated} · engine: {engine_label(language)}"
             f" · language: {language} · frames: {len(frames)}"
         ),
         "",
@@ -259,7 +316,8 @@ def main(argv: list[str] | None = None) -> int:
         default=DEFAULT_LANGUAGE,
         help=(
             f"OCR language (default: {DEFAULT_LANGUAGE}). "
-            "multi = PP-OCR multilingual (Chinese+English)."
+            "multi = PP-OCR multilingual (Chinese+English). "
+            "ja uses the PP-OCRv4 recognizer: no PP-OCRv5 Japanese model exists."
         ),
     )
     args = parser.parse_args(argv)