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

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

@@ -1,7 +1,7 @@
 {
   "name": "yt-tools",
   "displayName": "yt-tools",
-  "version": "0.24.1",
+  "version": "0.24.2",
   "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.1 → yt_tools_cli-0.24.2}/.github/workflows/ci.yml

@@ -20,10 +20,14 @@ jobs:
           python-version: "3.12"
       # The heavy stacks are installed on purpose: a handful of tests exercise the
       # real audio pipeline rather than a mock, and a suite that is red on a clean
-      # machine teaches everyone to ignore it. The light-core contract is covered
-      # by the gate job below, which runs without any extra.
+      # machine teaches everyone to ignore it. `[ocr]` is in the list for the same
+      # reason as the rest: the whole suite mocked the engine factory while the
+      # published extra resolved to a rapidocr whose params schema yt-ocr does not
+      # speak, so a clean `pipx install "yt-tools-cli[ocr]"` broke with the suite
+      # green ([[task:2831]]). tests/test_ocr_engine.py drives the real engine and
+      # needs the network once, for the ~10 MB PP-OCRv5 model.
       - name: Install
-        run: pip install -e ".[full,test]"
+        run: pip install -e ".[full,ocr,test]"
       - name: Unit + CLI smoke tests
         run: pytest -q
 

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

@@ -11,6 +11,60 @@ Releases before 0.8.0 are summarized only in the git log.
 
 _(nothing yet)_
 
+## [0.24.2] — 2026-09-13
+
+### Fixed
+
+- **`yt-ocr` on a clean `[ocr]` install** ([[issue:77]], [[task:2831]]). The extra
+  declared `rapidocr>=3.8`, so the resolver picked 3.9.2 — where the bundled
+  defaults moved to PP-OCRv6 with `model_type=small`, while PP-OCRv5 (which
+  `yt_tools/ocr.py` pins) ships `mobile`/`server` only. Engine construction died
+  with `error: Invalid OCR configuration`, i.e. the install did exactly what the
+  metadata asked and the first `yt-ocr` run failed. `[ocr]` now reads
+  `rapidocr>=3.8,<3.9`, with the reason in the metadata, and the bound is lifted
+  only in the change that teaches `ocr.py` the 3.9 model matrix.
+- **The `pipx inject` hint installed the version the extra excludes.** The
+  refusal, `doctor`'s `next_step` and the README all printed
+  `pipx inject yt-tools-cli rapidocr onnxruntime` — an inject resolves from PyPI
+  directly, so following the message reproduced the bug above. The hint now
+  carries the same bound as the extra (one constant, pinned equal by test) and
+  double-quotes every spec, because `>` and `<` are redirections in bash,
+  cmd.exe and PowerShell alike; `doctor` formats its multi-extra command through
+  the same helper instead of re-joining the list.
+
+### Added
+
+- **A real-engine test for the `[ocr]` extra** (`tests/test_ocr_engine.py`).
+  Every yt-ocr integration test mocked `_load_engine`, so the whole suite stayed
+  green while the published extra was broken — the mocked seam was the broken
+  seam. The new test builds the engine through `_load_engine` and OCRs a frame
+  it renders itself (OpenCV's built-in Hershey font, no binary fixture), and the
+  CI `pytest` job installs `[full,ocr,test]` so it cannot pass by being skipped.
+  Verified against both ends: rapidocr 3.9.2 → the `Invalid OCR configuration`
+  failure above, 3.8.4 → text read back and a non-empty `ocr.md`.
+- **A guard on the skill description length.** `using-yt-tools`'s description was
+  2511 characters as the YAML scalar (2261 as the host measured it) against a
+  1024 cap — the part the host matches triggers on, so a harness reported the
+  skill as conflicted. Trimmed to 987 with prose cut and every flow name and
+  trigger phrase kept; the new test fails on growth and on a trim that drops a
+  flow's command name.
+
+### Changed
+
+- **Docs corrected against a real machine install** ([[wiki:3595]]): `[full]` is
+  a flow default, **not** "everything" — it excludes `[ocr]` and carries no
+  `bpm-detector` VCS dependency, so chord progression / structural segments need
+  the inject and read `n/a` without it; the OCR section names the `rapidocr`
+  bound; the standalone install block offers
+  `pipx install "yt-tools-cli[full,ocr]"` (metadata-resolved) alongside the
+  bounded inject, and pins `0.24.2`; `yt-frames` is documented as requiring
+  `--timestamps` or `--mode {interval|scene}`, and `yt-ocr` as reading
+  `./yt-cache/<vid>/frames/` unless given `--timestamps`.
+- **The OCR model path.** The README and skill claimed the PP-OCRv5 weights land
+  in `~/.cache/rapidocr/`. In RapidOCR 3.8.x they land in the installed package's
+  own `rapidocr/models/` directory — found while running the clean-venv
+  acceptance, so the claim is replaced by the measured one.
+
 ## [0.24.1] — 2026-09-13
 
 ### Fixed

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: yt-tools-cli
-Version: 0.24.1
+Version: 0.24.2
 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.8; extra == 'ocr'
+Requires-Dist: rapidocr<3.9,>=3.8; extra == 'ocr'
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == 'test'
 Description-Content-Type: text/markdown
@@ -69,7 +69,9 @@ has to guess where the artefact landed:
   text (schematic labels, chord matrices, parameter walkthroughs). Needs
   the `[ocr]` extra.
 - `yt-listen` — FFT audio analysis: per-timestamp clip + mel-spectrogram PNG +
-  features `.md` with BPM, key, chord progression, and spectral statistics.
+  features `.md` with BPM, key, and spectral statistics (chord progression and
+  structural segments come from the optional `bpm-detector` enrichment —
+  [see below](#installing-bpm-detector); without it those rows read `n/a`).
 - `yt-watch` — combined transcript + scene-frames in one `.md` with
   `![](frames/...)` sidecar embeds.
 - `yt-tools cache list | prune` — manage the source-mp4 cache.
@@ -77,8 +79,8 @@ has to guess where the artefact landed:
 ## Installation
 
 `yt-tools` v1 ships **via a Claude Code plugin** (recommended for agent
-workflows) or **directly from this Git repository** (for standalone CLI
-use in any environment). PyPI distribution is deferred to a future release.
+workflows), **from PyPI** as the distribution `yt-tools-cli`, or **directly from
+this Git repository** (a checkout, or anyone tracking `master`).
 
 ### As a Claude Code plugin (recommended for agent workflows)
 
@@ -137,14 +139,23 @@ every console command stay `yt-tools`, and the import name stays `yt_tools`.
 python -m pip install --user pipx
 python -m pipx ensurepath          # adds ~/.local/bin to PATH; restart shell after
 
-# 2. install from PyPI — core + [frames] + [audio], i.e. every flow except OCR
+# 2. install from PyPI — [full] = core + [frames] + [audio]
+#    NOTE: [full] does NOT include OCR (see the next command)
 pipx install "yt-tools-cli[full]"
 
 # reproducible: pin the exact version
-pipx install "yt-tools-cli[full]==0.23.1"
-
-# [ocr] is always separate and explicit (its ONNX model is ~10 MB, fetched lazily)
-pipx inject yt-tools-cli rapidocr onnxruntime
+pipx install "yt-tools-cli[full]==0.24.2"
+
+# OCR is always an explicit extra (its ONNX model is ~10 MB, fetched lazily).
+# Preferred: name it at install time, so pip resolves it from the metadata —
+# bounds included — instead of from PyPI's "latest":
+pipx install "yt-tools-cli[full,ocr]"
+
+# Already installed? Widen the venv in place. Quote the specs: `>` and `<` are
+# 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"
 ```
 
 `uv` users: `uv tool install "yt-tools-cli[full]"`, or for a one-off run
@@ -157,6 +168,11 @@ pipx inject yt-tools-cli rapidocr onnxruntime
 pipx install 'git+https://github.com/kzntsv-dev/yt-tools.git#egg=yt-tools-cli[full]'
 ```
 
+> **Which Python.** The ceiling is real: `requires-python` is `>=3.10,<3.13`, so
+> on a machine whose only interpreter is 3.13 the install is refused by
+> `pip`/`pipx` (`librosa` 3.13 friction holds the ceiling — see Requirements).
+> Install a 3.12 interpreter, or point pipx at one: `pipx install --python 3.12 …`.
+
 > **Changing the extras of an existing install.** `pipx uninstall yt-tools-cli`
 > first, then install the new extras set. `pipx install --force` on an existing
 > venv can leave the new extras half-installed and resolve against the old pin
@@ -176,12 +192,20 @@ 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`, `onnxruntime` | `yt-ocr` (PP-OCRv5; ONNX model downloaded on first run) |
-| `[full]` | core + `[frames]` + `[audio]` | everything above except `yt-ocr` — this is what the plugin hook installs |
+| `[ocr]` | `rapidocr>=3.8,<3.9`, `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
+purpose: `[ocr]` (the ~10 MB ONNX model is always an explicit opt-in) and
+`bpm-detector` (not on PyPI — see below). If you want one install that runs every
+CLI in this README, name both: `pipx install "yt-tools-cli[full,ocr]"` plus the
+inject below.
 
 #### Installing bpm-detector
 
-`[full]` deliberately stops at `[frames]` + `[audio]`. The optional
+`[full]` deliberately stops at `[frames]` + `[audio]`: it carries **no VCS
+dependency**, so nothing a user installs from PyPI hits a Git remote (the plugin
+hook injects this one separately, best-effort). The optional
 [`bpm-detector`](https://github.com/libraz/bpm-detector) enrichment (chord
 progression, structural segments, refined BPM, a confidence-scored key per
 timestamp) is not on PyPI, so it can only be a PEP 508 *direct reference* — and
@@ -444,11 +468,17 @@ models via `onnxruntime`).
 ```bash
 # 1) extract frames first (lower scene threshold catches overlay fades
 #    within the same shot; or use --mode interval for a denser sample)
+#    yt-frames needs a mode: it will not guess between interval and scene.
+#    (--mode scene needs the [frames] extra; --mode interval does not.)
 yt-frames URL --mode scene --scene-threshold 12
 # or:
 yt-frames URL --mode interval --interval 15s
+# or, for named moments — no mode flag, no [frames] extra:
+yt-frames URL --timestamps 1:30,2:45
 
 # 2) OCR every cached frame → markdown with [mm:ss] anchors
+#    yt-ocr reads ./yt-cache/<vid>/frames/ — it extracts nothing on its own
+#    unless you give it --timestamps (which calls the yt-frames helper for you).
 yt-ocr URL
 # → ./yt-cache/<vid>/ocr.md
 
@@ -467,16 +497,26 @@ per detected text region, an explicit `_(no text detected)_` marker for
 frames where the engine returned nothing (so an agent can tell the frame
 was checked vs. silently omitted).
 
-> **Install the `[ocr]` extra.** RapidOCR and `onnxruntime` are **not**
-> in the core install. If `yt-ocr` exits with the missing-extra hint,
-> run:
+> **Install the `[ocr]` extra.** RapidOCR and `onnxruntime` are **not** in the
+> core install — and **not** in `[full]` either. If `yt-ocr` exits with the
+> missing-extra hint, run:
 > ```bash
-> pipx inject yt-tools-cli rapidocr onnxruntime
+> pipx inject yt-tools-cli "rapidocr>=3.8,<3.9" "onnxruntime>=1.18"
 > # or for non-pipx setups:
 > pip install 'yt-tools-cli[ocr]'
 > ```
-> First run with a given `--language` lazy-downloads a ~10 MB PP-OCRv5
-> ONNX model into `~/.cache/rapidocr/`.
+> First run with a given `--language` lazy-downloads the PP-OCRv5 ONNX models
+> (~8 MB for the english recognizer, plus the shared detector). In RapidOCR 3.8.x
+> 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.
 
 ### Cache hygiene
 
@@ -552,8 +592,10 @@ scripts trivial.
 - **Scene threshold:** 27 (PySceneDetect `ContentDetector` default; lower =
   more sensitive).
 - **`yt-listen` defaults:** 8-second clip per timestamp, mel-spectrogram at
-  default `librosa` settings, full feature set when `[full]` extra is
-  installed.
+  default `librosa` settings; BPM/key/spectral features when the `[audio]` extra
+  is installed, chord progression and structural segments only when
+  `bpm-detector` has been injected as well — on a plain `[full]` install those
+  rows are `n/a`, not silently absent.
 
 ## Requirements
 

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

@@ -27,7 +27,9 @@ has to guess where the artefact landed:
   text (schematic labels, chord matrices, parameter walkthroughs). Needs
   the `[ocr]` extra.
 - `yt-listen` — FFT audio analysis: per-timestamp clip + mel-spectrogram PNG +
-  features `.md` with BPM, key, chord progression, and spectral statistics.
+  features `.md` with BPM, key, and spectral statistics (chord progression and
+  structural segments come from the optional `bpm-detector` enrichment —
+  [see below](#installing-bpm-detector); without it those rows read `n/a`).
 - `yt-watch` — combined transcript + scene-frames in one `.md` with
   `![](frames/...)` sidecar embeds.
 - `yt-tools cache list | prune` — manage the source-mp4 cache.
@@ -35,8 +37,8 @@ has to guess where the artefact landed:
 ## Installation
 
 `yt-tools` v1 ships **via a Claude Code plugin** (recommended for agent
-workflows) or **directly from this Git repository** (for standalone CLI
-use in any environment). PyPI distribution is deferred to a future release.
+workflows), **from PyPI** as the distribution `yt-tools-cli`, or **directly from
+this Git repository** (a checkout, or anyone tracking `master`).
 
 ### As a Claude Code plugin (recommended for agent workflows)
 
@@ -95,14 +97,23 @@ every console command stay `yt-tools`, and the import name stays `yt_tools`.
 python -m pip install --user pipx
 python -m pipx ensurepath          # adds ~/.local/bin to PATH; restart shell after
 
-# 2. install from PyPI — core + [frames] + [audio], i.e. every flow except OCR
+# 2. install from PyPI — [full] = core + [frames] + [audio]
+#    NOTE: [full] does NOT include OCR (see the next command)
 pipx install "yt-tools-cli[full]"
 
 # reproducible: pin the exact version
-pipx install "yt-tools-cli[full]==0.23.1"
-
-# [ocr] is always separate and explicit (its ONNX model is ~10 MB, fetched lazily)
-pipx inject yt-tools-cli rapidocr onnxruntime
+pipx install "yt-tools-cli[full]==0.24.2"
+
+# OCR is always an explicit extra (its ONNX model is ~10 MB, fetched lazily).
+# Preferred: name it at install time, so pip resolves it from the metadata —
+# bounds included — instead of from PyPI's "latest":
+pipx install "yt-tools-cli[full,ocr]"
+
+# Already installed? Widen the venv in place. Quote the specs: `>` and `<` are
+# 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"
 ```
 
 `uv` users: `uv tool install "yt-tools-cli[full]"`, or for a one-off run
@@ -115,6 +126,11 @@ pipx inject yt-tools-cli rapidocr onnxruntime
 pipx install 'git+https://github.com/kzntsv-dev/yt-tools.git#egg=yt-tools-cli[full]'
 ```
 
+> **Which Python.** The ceiling is real: `requires-python` is `>=3.10,<3.13`, so
+> on a machine whose only interpreter is 3.13 the install is refused by
+> `pip`/`pipx` (`librosa` 3.13 friction holds the ceiling — see Requirements).
+> Install a 3.12 interpreter, or point pipx at one: `pipx install --python 3.12 …`.
+
 > **Changing the extras of an existing install.** `pipx uninstall yt-tools-cli`
 > first, then install the new extras set. `pipx install --force` on an existing
 > venv can leave the new extras half-installed and resolve against the old pin
@@ -134,12 +150,20 @@ 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`, `onnxruntime` | `yt-ocr` (PP-OCRv5; ONNX model downloaded on first run) |
-| `[full]` | core + `[frames]` + `[audio]` | everything above except `yt-ocr` — this is what the plugin hook installs |
+| `[ocr]` | `rapidocr>=3.8,<3.9`, `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
+purpose: `[ocr]` (the ~10 MB ONNX model is always an explicit opt-in) and
+`bpm-detector` (not on PyPI — see below). If you want one install that runs every
+CLI in this README, name both: `pipx install "yt-tools-cli[full,ocr]"` plus the
+inject below.
 
 #### Installing bpm-detector
 
-`[full]` deliberately stops at `[frames]` + `[audio]`. The optional
+`[full]` deliberately stops at `[frames]` + `[audio]`: it carries **no VCS
+dependency**, so nothing a user installs from PyPI hits a Git remote (the plugin
+hook injects this one separately, best-effort). The optional
 [`bpm-detector`](https://github.com/libraz/bpm-detector) enrichment (chord
 progression, structural segments, refined BPM, a confidence-scored key per
 timestamp) is not on PyPI, so it can only be a PEP 508 *direct reference* — and
@@ -402,11 +426,17 @@ models via `onnxruntime`).
 ```bash
 # 1) extract frames first (lower scene threshold catches overlay fades
 #    within the same shot; or use --mode interval for a denser sample)
+#    yt-frames needs a mode: it will not guess between interval and scene.
+#    (--mode scene needs the [frames] extra; --mode interval does not.)
 yt-frames URL --mode scene --scene-threshold 12
 # or:
 yt-frames URL --mode interval --interval 15s
+# or, for named moments — no mode flag, no [frames] extra:
+yt-frames URL --timestamps 1:30,2:45
 
 # 2) OCR every cached frame → markdown with [mm:ss] anchors
+#    yt-ocr reads ./yt-cache/<vid>/frames/ — it extracts nothing on its own
+#    unless you give it --timestamps (which calls the yt-frames helper for you).
 yt-ocr URL
 # → ./yt-cache/<vid>/ocr.md
 
@@ -425,16 +455,26 @@ per detected text region, an explicit `_(no text detected)_` marker for
 frames where the engine returned nothing (so an agent can tell the frame
 was checked vs. silently omitted).
 
-> **Install the `[ocr]` extra.** RapidOCR and `onnxruntime` are **not**
-> in the core install. If `yt-ocr` exits with the missing-extra hint,
-> run:
+> **Install the `[ocr]` extra.** RapidOCR and `onnxruntime` are **not** in the
+> core install — and **not** in `[full]` either. If `yt-ocr` exits with the
+> missing-extra hint, run:
 > ```bash
-> pipx inject yt-tools-cli rapidocr onnxruntime
+> pipx inject yt-tools-cli "rapidocr>=3.8,<3.9" "onnxruntime>=1.18"
 > # or for non-pipx setups:
 > pip install 'yt-tools-cli[ocr]'
 > ```
-> First run with a given `--language` lazy-downloads a ~10 MB PP-OCRv5
-> ONNX model into `~/.cache/rapidocr/`.
+> First run with a given `--language` lazy-downloads the PP-OCRv5 ONNX models
+> (~8 MB for the english recognizer, plus the shared detector). In RapidOCR 3.8.x
+> 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.
 
 ### Cache hygiene
 
@@ -510,8 +550,10 @@ scripts trivial.
 - **Scene threshold:** 27 (PySceneDetect `ContentDetector` default; lower =
   more sensitive).
 - **`yt-listen` defaults:** 8-second clip per timestamp, mel-spectrogram at
-  default `librosa` settings, full feature set when `[full]` extra is
-  installed.
+  default `librosa` settings; BPM/key/spectral features when the `[audio]` extra
+  is installed, chord progression and structural segments only when
+  `bpm-detector` has been injected as well — on a plain `[full]` install those
+  rows are `n/a`, not silently absent.
 
 ## Requirements
 

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "yt-tools-cli"
-version = "0.24.1"
+version = "0.24.2"
 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,7 +79,18 @@ full = [
     "matplotlib>=3.8",
 ]
 ocr = [
-    "rapidocr>=3.8",
+    # 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",
     "onnxruntime>=1.18",
 ]
 test = ["pytest>=7.0"]

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

@@ -1,7 +1,7 @@
 ---
 name: using-yt-tools
-version: 0.24.1
-description: Seven flows for YouTube content. **Discovery-search** (`yt-search`) — query → markdown list of candidate videos via yt-dlp's native ytsearch extractor; the entry point when the user hasn't named a URL yet. **Iterative-watch** (summary / exploration) — transcript with [mm:ss] anchors → pick moments → extract frames. **Targeted-frames** (specific timestamps) — extract frames directly, no transcript. **Audio-analysis** (music FFT) — per timestamp spectrogram + numeric digest (BPM, key, chord progression, harmonic content) via `yt-listen`. **Metadata** (`yt-meta`, free — rides the same yt-dlp call) — description, chapters, most-replayed heatmap, view/like/comment counts, tags, subtitle languages as markdown. **Comments** (`yt-comments`, separate paginated scrape) — top comments + nested replies; capped top-50 by default, costly on viral videos, only on explicit request. **OCR** (`yt-ocr`, silent-with-text fallback) — RapidOCR PP-OCRv5 over cached frames → `[mm:ss]` blocks as a transcript substitute when `yt-transcript` is empty or the video is silent-instructional (burned-in captions, schematic labels, chord matrices). Triggers (mixed RU/EN — same skill serves both audiences) — "find a video about X", "search youtube for X", "find tutorial about X", "найди видео про X", "поищи туториал", "обзор на X youtube", "what's in this video", "video summary", "youtube transcript", "что в ролике", "о чём видео", "show frame at N", "покажи кадр на N", "listen to fragment at N", "послушай момент N", "what's the BPM", "BPM/тональность видео", "analyze audio", "спектрограмма", "video description", "show chapters", "most replayed", "video stats", "что в описании", "покажи главы", "самые пересматриваемые", "top comments", "what are people saying", "комменты под роликом", "топ комментариев", "read text from frames", "OCR this video", "what does the caption say", "extract overlay text", "captions burned in", "прочти текст с кадров", "OCR этого видео", "silent video с текстом", or any youtube.com URL. CLI installed once per machine with pipx (`pipx install 'yt-tools-cli[full]'` adds the audio/chord stack); `yt-tools doctor` is the read-only preflight that names whatever is missing. YouTube-only — for Vimeo / Twitch / local files use other tools.
+version: 0.24.2
+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.
 ---
 
 # using-yt-tools
@@ -106,13 +106,15 @@ Seven distinct flows, picked by user intent:
   → Read `<vid>/ocr.md` as a transcript substitute (per-timestamp
   `[mm:ss]` blocks, same paradigm) → continue into Flow B at the
   interesting timestamps if you need the original frames.
-- **Requires the `[ocr]` extra** — `rapidocr` + `onnxruntime`. If
-  missing on the running yt-tools install, `yt-ocr` exits nonzero with
-  both install hints (`pipx inject yt-tools-cli rapidocr onnxruntime` /
-  `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 on a machine may need the inject step.
+- **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"
+  "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
+  on a machine may need the inject step. `yt-ocr` reads
+  `./yt-cache/<vid>/frames/`, so either run `yt-frames` first or pass
+  `--timestamps` (which extracts for you).
 - Trigger phrases: "read text from frames", "OCR this video", "what
   does the caption say", "extract overlay text", "captions burned in",
   "silent video with text on screen", «прочти текст с кадров», «OCR
@@ -138,14 +140,22 @@ Install once per machine — one command, the same in every harness. The
 commands stay `yt-tools`; the import name is `yt_tools`):
 
 ```bash
-# from PyPI — core + [frames] + [audio], i.e. every flow except OCR
+# from PyPI — [full] = core + [frames] + [audio]. NOT OCR (see below).
 pipx install "yt-tools-cli[full]"
 
 # core only (transcript / meta / comments / search / cache)
 pipx install yt-tools-cli
 
 # reproducible: pin the exact version
-pipx install "yt-tools-cli[full]==0.23.1"
+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"
 ```
 
 From a checkout instead of PyPI (the plugin path, or tracking `master`):
@@ -154,7 +164,8 @@ From a checkout instead of PyPI (the plugin path, or tracking `master`):
 pipx install 'git+https://github.com/kzntsv-dev/yt-tools.git#egg=yt-tools-cli[full]'
 ```
 
-The `[full]` extra is core + `[frames]` + `[audio]`. Chord progression,
+The `[full]` extra is core + `[frames]` + `[audio]` — a flow default, not
+"everything": OCR and `bpm-detector` are both outside it. Chord progression,
 structural segments and the refined BPM/key in `yt-listen` come from
 `bpm-detector`, which is **not on PyPI** and therefore cannot live in the
 published metadata — the Python package index rejects direct VCS references.
@@ -165,8 +176,7 @@ pipx inject yt-tools-cli "bpm-detector @ git+https://github.com/libraz/bpm-detec
 ```
 
 Without it `yt-listen` still runs (librosa-only BPM/key, unfilled sections marked
-`n/a`). `[ocr]` is always an explicit extra: `pipx inject yt-tools-cli rapidocr
-onnxruntime`.
+`n/a`).
 
 Some harnesses do this for you: if your host ships the bundled yt-tools plugin
 (Claude Code does), its `SessionStart` hook pipx-installs the `[full]` set from
@@ -522,9 +532,9 @@ 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 onnxruntime` (or `pip install 'yt-tools-cli[ocr]'` in non-pipx setups). 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,<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 — `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 to `~/.cache/rapidocr/` blocked | Print the captured error; let the user re-run with network access. Don't retry. |
+| 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. |
 
 ## Side effects
@@ -538,9 +548,11 @@ All failures abort cleanly; never leave a half-finished state.
   - `<video-id>/source.mp4` (≤ 720p; produced by Flows A/B/C unless `--no-cache-source`; **not** by 0/D/E; produced by Flow F **only** when `--timestamps` triggers extraction)
   - `<video-id>/frames/frame_<mmss>.jpg` per extracted frame (also re-read by Flow F); a sub-second moment carries its milliseconds (`frame_0130_250.jpg` = 90.25 s), so two frames in one second never overwrite each other and stdout's `Wrote:` count equals the files on disk
   - `<video-id>/audio/{clip,spectrum,features}_<mmss>.{wav,png,md}` (Flow C)
-- Flow F also lazy-downloads RapidOCR PP-OCRv5 ONNX weights to
-  `~/.cache/rapidocr/` on first invocation with a given `--language`
-  (~10 MB per language model).
+- Flow F also lazy-downloads RapidOCR PP-OCRv5 ONNX weights on first
+  invocation with a given `--language` (~8 MB for the english recognizer plus the
+  shared detector). In RapidOCR 3.8.x they land in the installed package's own
+  `rapidocr/models/` directory — not in `~/.cache/`, which is where this line
+  claimed they went until a clean-venv check (2026-09-13).
 - Network: `yt-dlp` pulls metadata + optionally `source.mp4`;
   `youtube-transcript-api` pulls subs; Flow E additionally paginates the
   comment feed (the one heavy network path — minutes on viral videos).

{yt_tools_cli-0.24.1 → yt_tools_cli-0.24.2}/tests/test_doctor.py

@@ -85,11 +85,17 @@ def test_extras_that_are_installed_are_ok(monkeypatch, tmp_path):
     assert report.can_proceed is True
 
 
+# [test-modify: test_extra_check_reuses_the_shared_install_command: was
+#  `assert fix == "pipx inject yt-tools-cli scenedetect opencv-python"`; is the
+#  same via `extras.inject_command_for`; reason: task:2831 — doctor's one command
+#  is now formatted by the shared helper (specs double-quoted, bounded specs like
+#  the OCR pin safe to paste), so the literal here must move with it.]
 def test_extra_check_reuses_the_shared_install_command(monkeypatch, tmp_path):
     _only_importable(monkeypatch)
     fix = _by_name(doctor.collect(tmp_path, which=_which(BOTH_BINS)))["extra:frames"].fix
     assert fix == extras.inject_command("frames")
-    assert fix == "pipx inject yt-tools-cli scenedetect opencv-python"
+    assert fix == extras.inject_command_for(["frames"])
+    assert fix == 'pipx inject yt-tools-cli "scenedetect" "opencv-python"'
 
 
 # ---- AC4: a missing binary is the blocker -----------------------------------

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

@@ -49,10 +49,16 @@ def _explode(*args, **kwargs):
 # ---- one wording, one source of truth ---------------------------------------
 
 
+# [test-modify: test_frames_refusal_wording_is_exact: was
+#  '  pipx inject yt-tools-cli scenedetect opencv-python'; is the same line with
+#  each spec double-quoted; reason: task:2831 — the hint now formats specs
+#  through one helper (extras.inject_command_for) so a bounded spec like the OCR
+#  pin cannot be re-joined unquoted by a caller; `"` is required for those
+#  bounds, and mixed quoting per extra would be worse than quoting all.]
 def test_frames_refusal_wording_is_exact():
     assert extras.format_missing_extra("yt-frames --mode scene", "frames") == (
         "yt-frames --mode scene requires the [frames] extra:\n"
-        "  pipx inject yt-tools-cli scenedetect opencv-python\n"
+        '  pipx inject yt-tools-cli "scenedetect" "opencv-python"\n'
         "  # or\n"
         "  pip install 'yt-tools-cli[frames]'"
     )
@@ -61,16 +67,22 @@ def test_frames_refusal_wording_is_exact():
 def test_audio_refusal_wording_is_exact():
     assert extras.format_missing_extra("yt-listen", "audio") == (
         "yt-listen requires the [audio] extra:\n"
-        "  pipx inject yt-tools-cli librosa matplotlib\n"
+        '  pipx inject yt-tools-cli "librosa" "matplotlib"\n'
         "  # or\n"
         "  pip install 'yt-tools-cli[audio]'"
     )
 
 
+# [test-modify: test_ocr_refusal_wording_is_exact: was
+#  '  pipx inject yt-tools-cli rapidocr onnxruntime'; is the same line with the
+#  bound specs, each double-quoted; reason: task:2831 — the injected spec now
+#  carries the `>=3.8,<3.9` pin (an inject bypasses the extra's metadata, so an
+#  unbounded `rapidocr` there installed the broken 3.9.x), and quotes are
+#  required because `>`/`<` are redirections in bash, cmd.exe and PowerShell.]
 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 onnxruntime\n"
+        '  pipx inject yt-tools-cli "rapidocr>=3.8,<3.9" "onnxruntime>=1.18"\n'
         "  # or\n"
         "  pip install 'yt-tools-cli[ocr]'"
     )
@@ -91,9 +103,19 @@ def test_ocr_error_message_comes_from_the_shared_formatter(monkeypatch):
     assert str(exc_info.value) == extras.format_missing_extra("yt-ocr", "ocr")
 
 
+# [test-modify: test_ocr_refuses_when_only_onnxruntime_is_missing: was
+#  `_only_importable(monkeypatch, "rapidocr")`; is `_poison(monkeypatch,
+#  "onnxruntime")`; reason: task:2831 — `_only_importable` patches
+#  `extras.import_module`, which `_load_engine` never calls, so the old form only
+#  passed because rapidocr itself was absent from the venv and the *first*
+#  import raised. With `[ocr]` installed (now the case in CI, and the only way
+#  tests/test_ocr_engine.py can run) the real engine got built here — a model
+#  download inside a unit test, and on rapidocr 3.9 a ValueError instead of the
+#  named refusal. Poisoning the second half of the pair tests what the test
+#  says it tests.]
 def test_ocr_refuses_when_only_onnxruntime_is_missing(monkeypatch):
     """The [ocr] extra is a pair: a half-installed one must not fail later, unnamed."""
-    _only_importable(monkeypatch, "rapidocr")
+    _poison(monkeypatch, "onnxruntime")
     with pytest.raises(ocr_mod.OcrError) as exc_info:
         ocr_mod._load_engine("en")
     assert str(exc_info.value) == extras.format_missing_extra("yt-ocr", "ocr")
@@ -159,7 +181,7 @@ def test_degradation_note_for_audio_keeps_the_shared_wording(monkeypatch, capsys
     err = capsys.readouterr().err
     assert err.startswith("note: harmonic analysis skipped - the [audio] extra is not installed")
     assert "(continuing without it)." in err
-    assert "pipx inject yt-tools-cli librosa matplotlib" in err
+    assert 'pipx inject yt-tools-cli "librosa" "matplotlib"' in err
     assert "pip install 'yt-tools-cli[audio]'" in err
     assert "requires the [audio] extra" not in err, "a degradation must not read as a blocker"
 
@@ -187,7 +209,7 @@ def test_yt_frames_scene_refuses_without_frames_extra(tmp_path, monkeypatch, cap
     err = capsys.readouterr().err
     assert rc != 0, "a missing extra must be a non-zero exit"
     assert "requires the [frames] extra" in err
-    assert "pipx inject yt-tools-cli scenedetect opencv-python" in err
+    assert 'pipx inject yt-tools-cli "scenedetect" "opencv-python"' in err
     assert "pip install 'yt-tools-cli[frames]'" in err
     assert "Traceback" not in err
 
@@ -229,7 +251,7 @@ def test_yt_listen_refuses_without_audio_extra(tmp_path, monkeypatch, capsys):
     err = capsys.readouterr().err
     assert rc != 0
     assert "requires the [audio] extra" in err
-    assert "pipx inject yt-tools-cli librosa matplotlib" in err
+    assert 'pipx inject yt-tools-cli "librosa" "matplotlib"' in err
     assert "pip install 'yt-tools-cli[audio]'" in err
     assert "Traceback" not in err
 

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

@@ -183,6 +183,11 @@ def test_render_zero_frames_still_emits_header():
 # --- _load_engine: friendly missing-extra hint -------------------------------
 
 
+# [test-modify: test_load_engine_friendly_hint_when_rapidocr_missing: was
+#  `assert "pipx inject yt-tools-cli rapidocr onnxruntime" in msg`; is the same
+#  with the quoted, bounded specs; reason: task:2831 — the hint carries the
+#  rapidocr pin (an inject bypasses the extra metadata) and quotes every spec so
+#  the pasted command is safe in bash/cmd/PowerShell.]
 def test_load_engine_friendly_hint_when_rapidocr_missing(monkeypatch):
     """Stick None into sys.modules['rapidocr'] so `from rapidocr import ...`
     raises ImportError; verify the friendly hint is built into the error."""
@@ -190,7 +195,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 onnxruntime" in msg
+    assert 'pipx inject yt-tools-cli "rapidocr>=3.8,<3.9" "onnxruntime>=1.18"' in msg
     assert "pip install 'yt-tools-cli[ocr]'" in msg
 
 
@@ -289,7 +294,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 onnxruntime\n"
+            '  pipx inject yt-tools-cli "rapidocr>=3.8,<3.9" "onnxruntime>=1.18"\n'
             "  # or\n"
             "  pip install 'yt-tools-cli[ocr]'"
         )
@@ -299,7 +304,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 onnxruntime" in err
+    assert 'pipx inject yt-tools-cli "rapidocr>=3.8,<3.9" "onnxruntime>=1.18"' in err
     assert "pip install 'yt-tools-cli[ocr]'" in err
 
 

yt_tools_cli-0.24.2/tests/test_ocr_engine.py

@@ -0,0 +1,121 @@
+"""Real RapidOCR engine guard — the seam every other yt-ocr test mocks (task:2831).
+
+``tests/test_ocr.py`` patches ``_load_engine`` in every integration case, so the
+whole suite stayed green while the *published* ``[ocr]`` extra resolved to
+rapidocr 3.9.x, whose ``params`` schema ``yt_tools/ocr.py`` does not speak. On a
+clean ``pipx install "yt-tools-cli[ocr]"`` (0.24.0/0.24.1) the first
+``yt-ocr`` run died with::
+
+    error: Invalid OCR configuration.
+    Example valid usage:
+      from rapidocr import LangRec, OCRVersion, RapidOCR
+      engine = RapidOCR(params={'Rec.ocr_version': OCRVersion.PPOCRV5, ...})
+
+The mocked seam is exactly the seam that broke, so this module drives it for
+real: build the engine through ``_load_engine``, OCR a frame the test renders
+itself, and require text back. Detection is what makes it the guard it is —
+``_load_engine`` is where rapidocr 3.9 rejects the config, so the failure lands
+here as an ``OcrError``/``rapidocr`` error rather than in a consumer session.
+
+Skipped — never failed — when rapidocr is absent: the light-core jobs install no
+extras, and the ``pytest (full extras)`` CI job installs ``[ocr]`` (see
+``.github/workflows/ci.yml``), which is where this contract is enforced. The
+first construction downloads the ~10 MB PP-OCRv5 ONNX model, so the network is a
+prerequisite of that job, not of a plain ``pytest`` run.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from yt_tools import ocr as ocr_mod
+
+pytest.importorskip(
+    "rapidocr",
+    reason="[ocr] extra not installed (run: pip install 'yt-tools-cli[ocr]')",
+)
+
+_VID = "abcDEF12345"
+_URL = f"https://youtu.be/{_VID}"
+
+# Rendered big and blocky on purpose: the guard must fail on a *configuration*
+# mismatch, never because a serif glyph was misread at 12 px.
+_RENDERED_TEXT = "OCR TEST"
+_COLS = 720
+_ROWS = 220
+
+
+def _render_text_frame(path: Path, text: str = _RENDERED_TEXT) -> Path:
+    """Draw ``text`` on a white canvas — a frame real OCR can read.
+
+    ``cv2`` is not an optional nicety here: rapidocr depends on it (PP-OCRv5
+    preprocessing), so using it adds no dependency the extra does not already
+    carry. The Hershey font is built into OpenCV, so no font file is needed and
+    the fixture stays a file the test writes, not a binary in git.
+    """
+    import cv2  # noqa: PLC0415 — heavy import, only reachable behind the [ocr] skip
+    import numpy as np  # noqa: PLC0415
+
+    canvas = np.full((_ROWS, _COLS, 3), 255, dtype=np.uint8)
+    cv2.putText(
+        canvas,
+        text,
+        (40, 150),
+        cv2.FONT_HERSHEY_SIMPLEX,
+        3.0,
+        (0, 0, 0),
+        8,
+        cv2.LINE_AA,
+    )
+    path.parent.mkdir(parents=True, exist_ok=True)
+    assert cv2.imwrite(str(path), canvas), f"could not write the rendered frame to {path}"
+    return path
+
+
+@pytest.fixture(scope="module")
+def text_frame(tmp_path_factory: pytest.TempPathFactory) -> Path:
+    return _render_text_frame(tmp_path_factory.mktemp("frames") / "frame_0023.jpg")
+
+
+@pytest.fixture(scope="module")
+def engine():
+    """One engine per module: construction downloads the model, so it is not free."""
+    return ocr_mod._load_engine("en")
+
+
+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
+    # Not a mock assertion — `_load_engine` returns whatever RapidOCR built. If
+    # the params schema drifts again, construction raises before we get here.
+    assert hasattr(engine, "__call__"), "the engine handle must stay callable (engine(path))"
+
+
+def test_engine_reads_text_from_a_rendered_frame(engine, text_frame):
+    texts = ocr_mod._ocr_one(engine, text_frame)
+    assert texts, (
+        "a frame with rendered text produced no detections — the engine is not "
+        "actually OCR-ing (model missing, or params silently ignored)"
+    )
+    joined = " ".join(texts).upper()
+    assert "OCR" in joined, f"expected {_RENDERED_TEXT!r} to be read back, got {texts!r}"
+
+
+def test_cli_real_engine_writes_nonempty_markdown(tmp_path, monkeypatch, text_frame):
+    """The acceptance path end to end, minus YouTube: cached frame → ocr.md with text."""
+    monkeypatch.chdir(tmp_path)
+    cache_root = tmp_path / "yt-cache" / _VID
+    frames_dir = cache_root / "frames"
+    frames_dir.mkdir(parents=True)
+    (frames_dir / text_frame.name).write_bytes(text_frame.read_bytes())
+
+    out = tmp_path / "ocr.md"
+    rc = ocr_mod.main([_URL, "--out", str(out)])
+
+    assert rc == 0
+    body = out.read_text(encoding="utf-8")
+    assert body.strip(), "ocr.md must not be empty"
+    assert "## [0:23]" in body
+    assert "OCR" in body.upper()

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

@@ -214,6 +214,80 @@ 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.
+    """
+    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"
+    )
+
+
+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.
+    """
+    from yt_tools import extras  # noqa: PLC0415 — local import keeps the packaging tests import-light
+
+    specs = dict(
+        zip(
+            (Requirement(spec).name for spec in extras.EXTRA_PACKAGES["ocr"]),
+            extras.EXTRA_PACKAGES["ocr"],
+        )
+    )
+    declared = {
+        Requirement(spec).name: spec
+        for spec in _pyproject()["project"]["optional-dependencies"]["ocr"]
+    }
+    assert specs == declared, (
+        "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"), (
+        "a bounded spec must be quoted: `>` and `<` are redirections in bash, cmd.exe and PowerShell"
+    )
+
+
+def test_ci_installs_the_ocr_extra_so_the_engine_test_actually_runs():
+    """A guard test that is skipped in CI is worse than no guard.
+
+    ``tests/test_ocr_engine.py`` skips when rapidocr is absent (the light-core
+    jobs install nothing), which is the right shape for a local `pytest` run and
+    a silent hole in the pipeline: the suite would stay green while nothing
+    exercised the engine — the exact state that let [[issue:77]] ship. So the CI
+    install line is part of the contract.
+    """
+    workflow = (ROOT / ".github" / "workflows" / "ci.yml").read_text(encoding="utf-8")
+    assert 'pip install -e ".[full,ocr,test]"' in workflow, (
+        "the pytest job must install [ocr], or tests/test_ocr_engine.py skips there too"
+    )
+
+
 @pytest.mark.parametrize("extra", ["audio", "full"])
 def test_librosa_1x_is_excluded(extra):
     """`bpm-detector` 1.1.0 calls ``librosa.beat.tempo``, removed in librosa 1.0.

{yt_tools_cli-0.24.1 → yt_tools_cli-0.24.2}/tests/test_skill_portable.py

@@ -73,6 +73,37 @@ def test_frontmatter_description_is_install_neutral():
     assert "pipx install" in description, "the trigger text should name the neutral install path"
 
 
+#: The host's cap on a skill description. Measured, not chosen: a harness that
+#: loads this skill reported `description exceeds 1024 characters (2261)` — and
+#: nothing in this repo objected, because every other test here reads the
+#: frontmatter as free-form text. This test measures the raw YAML scalar, which
+#: reads a little longer (2511 before the trim); every measure of the old text
+#: was over the cap, which is the only part that matters.
+DESCRIPTION_MAX_CHARS = 1024
+
+
+def test_frontmatter_description_fits_the_host_limit():
+    """A description that does not fit is not installed — it is reported.
+
+    The description is the *only* part of the skill the host matches triggers
+    against, so overflowing it does not degrade the skill gracefully: the host
+    either refuses it or truncates the trigger list, and `yt-ocr` / `yt-listen`
+    become unreachable flows with a green suite ([[task:2831]] run, 2026-09-13).
+    Keep the trim honest by cutting prose, never trigger phrases — a shorter
+    description that no longer names a flow is a different bug.
+    """
+    description = re.search(r"^description:\s*(.+)$", _frontmatter(_text()), re.MULTILINE)
+    assert description, "the frontmatter has no description: line"
+    description = description.group(1).strip()
+    assert len(description) <= DESCRIPTION_MAX_CHARS, (
+        f"the description is {len(description)} chars, over the {DESCRIPTION_MAX_CHARS} "
+        "the host allows — trim prose, keep the trigger phrases"
+    )
+    # ...and the trim must not have traded triggers away for room.
+    for command in ("yt-search", "yt-transcript", "yt-frames", "yt-listen", "yt-meta", "yt-comments", "yt-ocr"):
+        assert command in description, f"the description stopped naming {command}"
+
+
 # ---- a named harness is always an option, never the flow --------------------
 
 

{yt_tools_cli-0.24.1 → yt_tools_cli-0.24.2}/yt_tools/doctor.py

@@ -127,11 +127,12 @@ class Report:
         if self.blockers:
             return None
         if self.missing_extras:
-            packages = " ".join(p for e in self.missing_extras for p in extras.EXTRA_PACKAGES[e])
             # Built from the same constant the refusals use: a rename that missed
             # this copy would make the report recommend a package that does not
-            # exist ([[wiki:3589]]).
-            return f"pipx inject {extras.DISTRIBUTION} {packages}"
+            # exist ([[wiki:3589]]). Bound specs (the OCR pin) mean the one
+            # command must be formatted by the same helper too, not re-joined
+            # here — an unquoted ``>=`` is a redirect ([[task:2831]]).
+            return extras.inject_command_for(self.missing_extras)
         for check in self.checks:
             if check.status == WARN and check.fix:
                 return check.fix

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

@@ -34,11 +34,17 @@ EXTRA_MODULES: dict[str, tuple[str, ...]] = {
     "ocr": ("rapidocr", "onnxruntime"),
 }
 
-# extra → distribution names for the ``pipx inject`` hint.
+# extra → install specs for the ``pipx inject`` hint. These are what the user
+# actually pastes, and an inject resolves them *outside* the extra's metadata —
+# so a bound that matters has to be repeated here or the hint contradicts the
+# extra it is advertising: `pipx inject yt-tools-cli rapidocr` used to resolve
+# 3.9.x while `[ocr]` said <3.9, i.e. the refusal message itself installed the
+# broken pair ([[task:2831]]). tests/test_packaging.py pins the OCR entries to
+# the requirement strings in pyproject.toml so the two routes cannot drift.
 EXTRA_PACKAGES: dict[str, tuple[str, ...]] = {
     "frames": ("scenedetect", "opencv-python"),
     "audio": ("librosa", "matplotlib"),
-    "ocr": ("rapidocr", "onnxruntime"),
+    "ocr": ("rapidocr>=3.8,<3.9", "onnxruntime>=1.18"),
 }
 
 #: The enrichment that cannot be a package extra. ``bpm-detector`` gives
@@ -92,8 +98,24 @@ def inject_command(extra: str) -> str:
     refusal and the recommendation must not drift apart.
     """
     _check_extra(extra)
-    packages = " ".join(EXTRA_PACKAGES[extra])
-    return f"pipx inject {DISTRIBUTION} {packages}"
+    return inject_command_for([extra])
+
+
+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
+    bash, cmd.exe and PowerShell alike — the printed command has to be
+    pasteable, since being pasteable is the whole point of it.
+    """
+    specs = [spec for name in extra_names for spec in _specs(name)]
+    return f"pipx inject {DISTRIBUTION} " + " ".join(f'"{spec}"' for spec in specs)
+
+
+def _specs(extra: str) -> tuple[str, ...]:
+    _check_extra(extra)
+    return EXTRA_PACKAGES[extra]
 
 
 def module_missing(name: str) -> bool: