docs(whisper-transcribe): add multi-language limitations reference (#14) #18

Closed

Mark wants to merge 0 commits from docs/multilang-limitations into main

Mark commented

2026-09-06 00:49:33 +00:00

Owner

Summary

Adds docs/multilang-limitations.md and a README link covering the four sections issue #14 asks for:

Mid-file language switch — single-alignment-model-per-file limitation (sourced to src/whisper_transcribe/cli.py:175, _load_align_model -> whisperx.load_align_model(language_code=...)); the file-split workaround with ffmpeg + two transcribe calls pinned per-chunk.
--language-hints behaviour — bias-not-force semantics, the MIN_HINT_CONFIDENCE = 0.50 floor in language_hints.py:35, the heavy-accent reverse-commit failure mode (e.g. Indian English scored as hi causing a wrong-language commit), and the --lang auto / --lang en fallbacks.
Batch processing — per-file independence, the canonical JSON shape (language, language_hints, forced_language, initial_prompt_used additive fields), and the explicit deferral of per-segment language to per-window detection.
Known-good / known-bad cases — table of the six scenarios from issue #14 (pure ES, pure EN, ES+EN mix, EN with jargon, Indian English, Australian English) mapped to shipped fixtures under tests/fixtures/multilang/, with one-line expected behaviour per row. Two rows cite the canonical smoke-test transcripts; four rows are explicitly marked "Not verified in CI" because the quality check requires a labelled reference transcript + GPU (see references/multi-language.md §Validation recipe).

Companion docs

references/multi-language.md — user-facing how-to (Quick start, --language-hints algorithm, mitigations). Already shipped.
tests/fixtures/multilang/SOURCES.md — fixture sources and licences. Shipped by parent kanban task t_7e982a14 (commit a189437).

Acceptance

docs/multilang-limitations.md created at the requested path.
Every claim traceable to a source on disk (file:line or tests/... fixture or references/... doc).
No Lorem Ipsum.
Linked from README.md (alongside the existing references/youtube-extraction-quirks.md link).
Six known-good / known-bad rows each cite a fixture path under tests/fixtures/multilang/.
Follow-up issue linked: #14.

Verification

python -m pytest tests/ --ignore=tests/test_benchmark_gpu_sizing.py → 115 passed, 16 skipped (network-conditional; same baseline as before this change).
ruff check src tests → 4 pre-existing findings (audio_stream.py UP007/UP037, cli.py:27 F401 unused import, cli.py:484 RUF100 unused noqa). None of these files are touched by this PR.
All in-doc relative links resolve (README.md, references/multi-language.md, tests/fixtures/multilang/..., src/..., .kilo/plans/...).

Tracking

Kanban: t_f2f1820e (this work), t_7e982a14 (parent — fixture ship).
Issue: Mark/whisper-transcribe#14.

## Summary Adds `docs/multilang-limitations.md` and a README link covering the four sections issue #14 asks for: 1. **Mid-file language switch** — single-alignment-model-per-file limitation (sourced to `src/whisper_transcribe/cli.py:175`, `_load_align_model` -> `whisperx.load_align_model(language_code=...)`); the file-split workaround with `ffmpeg` + two `transcribe` calls pinned per-chunk. 2. **`--language-hints` behaviour** — bias-not-force semantics, the `MIN_HINT_CONFIDENCE = 0.50` floor in `language_hints.py:35`, the heavy-accent reverse-commit failure mode (e.g. Indian English scored as `hi` causing a wrong-language commit), and the `--lang auto` / `--lang en` fallbacks. 3. **Batch processing** — per-file independence, the canonical JSON shape (`language`, `language_hints`, `forced_language`, `initial_prompt_used` additive fields), and the explicit deferral of per-segment `language` to per-window detection. 4. **Known-good / known-bad cases** — table of the six scenarios from issue #14 (pure ES, pure EN, ES+EN mix, EN with jargon, Indian English, Australian English) mapped to shipped fixtures under `tests/fixtures/multilang/`, with one-line expected behaviour per row. Two rows cite the canonical smoke-test transcripts; four rows are explicitly marked "Not verified in CI" because the quality check requires a labelled reference transcript + GPU (see `references/multi-language.md` §Validation recipe). ## Companion docs - `references/multi-language.md` — user-facing how-to (Quick start, `--language-hints` algorithm, mitigations). Already shipped. - `tests/fixtures/multilang/SOURCES.md` — fixture sources and licences. Shipped by parent kanban task t_7e982a14 (commit a189437). ## Acceptance - [x] `docs/multilang-limitations.md` created at the requested path. - [x] Every claim traceable to a source on disk (file:line or `tests/...` fixture or `references/...` doc). - [x] No Lorem Ipsum. - [x] Linked from `README.md` (alongside the existing `references/youtube-extraction-quirks.md` link). - [x] Six known-good / known-bad rows each cite a fixture path under `tests/fixtures/multilang/`. - [x] Follow-up issue linked: `#14`. ## Verification - `python -m pytest tests/ --ignore=tests/test_benchmark_gpu_sizing.py` → 115 passed, 16 skipped (network-conditional; same baseline as before this change). - `ruff check src tests` → 4 pre-existing findings (`audio_stream.py` UP007/UP037, `cli.py:27` F401 unused import, `cli.py:484` RUF100 unused noqa). None of these files are touched by this PR. - All in-doc relative links resolve (`README.md`, `references/multi-language.md`, `tests/fixtures/multilang/...`, `src/...`, `.kilo/plans/...`). ## Tracking - Kanban: `t_f2f1820e` (this work), `t_7e982a14` (parent — fixture ship). - Issue: [Mark/whisper-transcribe#14](https://forgejo.tail018ac4.ts.net/Mark/whisper-transcribe/issues/14).

Mark added 1 commit

2026-09-06 00:49:33 +00:00

docs(whisper-transcribe): add multi-language limitations reference 9a35b8cb2e

Adds docs/multilang-limitations.md (Mark/whisper-transcribe#14) and a
README link from the existing YouTube quirks paragraph.

The new doc covers the four sections the issue body asks for, with
every claim traceable to a source on disk:

  1. Mid-file language switch — single-alignment-model-per-file
     limitation sourced to src/whisper_transcribe/cli.py:175
     (_load_align_model -> whisperx.load_align_model(language_code=...)
     with no per-window alternative), plus the file-split workaround.
  2. --language-hints behaviour — bias-not-force semantics sourced to
     src/whisper_transcribe/language_hints.py:35 (MIN_HINT_CONFIDENCE
     = 0.50) and the cli.py:377-410 selection path; the heavy-accent
     reverse-commit failure mode and the --lang en fallback.
  3. Batch processing — per-file independence + canonical JSON schema
     (language_hints / forced_language / initial_prompt_used additive
     fields) sourced to README §Output formats and cli.py:449-462.
  4. Known-good and known-bad cases — table of the six scenarios from
     issue #14 (pure ES, pure EN, ES+EN mix, EN with jargon, Indian
     English, Australian English), each mapped to a shipped fixture
     under tests/fixtures/multilang/, with one-line expected
     behaviour. Two rows (pure EN) cite the canonical smoke-test
     transcripts in /tmp/whisperx-smoke/ lifted in the README; four
     rows are explicitly marked "Not verified in CI" because the
     quality check requires a labelled reference transcript + GPU
     (see references/multi-language.md §Validation recipe).

Companion:
  * references/multi-language.md — user-facing how-to (Quick start,
    --language-hints algorithm, mitigations). Already shipped in
    commit b839f39.
  * tests/fixtures/multilang/SOURCES.md — fixture sources and
    licences. Shipped in commit a189437 by the parent task (t_7e982a14
    on the fixit kanban).

No code changes. tests/test_language_hints.py (21) and
tests/test_multilang_fixtures.py (21) remain green; full suite
115 passed, 16 skipped (network-conditional). Pre-existing ruff
findings in audio_stream.py and cli.py:27,484 are untouched.

Tracking: kanban t_f2f1820e, parent t_7e982a14, issue #14.

Refs: forgejo.tail018ac4.ts.net/Mark/whisper-transcribe/issues/14

Mark added the

triage-approved

label

2026-09-06 17:36:51 +00:00

Mark commented

2026-09-08 21:52:57 +00:00

Author

Owner

Launcher-side notice: a kilo-gsd-runner card (t_ebf24bd5) was dispatched to work this issue, but the substrate cannot fly — the work is already complete on main. Concretely: commit 9a35b8c docs(whisper-transcribe): add multi-language limitations reference is reachable from main, docs/multilang-limitations.md exists at the requested path, README.md already links to it alongside references/youtube-extraction-quirks.md, and PR #18 itself is open with additions=0, deletions=0, changed_files=0 and merge_base == head.sha (418c100). No live kilo-gsd tmux session, no .gsd/in-progress/18.pid, no forgejo in-progress label, no salvage state for this issue. The kanban card is blocked with kind=capability so the dispatcher routes this to a human / the janitor instead of launching a no-op kilo-gsd run. The PR object should be closed (no diff to merge).

Launcher-side notice: a kilo-gsd-runner card (t_ebf24bd5) was dispatched to work this issue, but the substrate cannot fly — the work is already complete on `main`. Concretely: commit `9a35b8c docs(whisper-transcribe): add multi-language limitations reference` is reachable from `main`, `docs/multilang-limitations.md` exists at the requested path, `README.md` already links to it alongside `references/youtube-extraction-quirks.md`, and PR #18 itself is open with `additions=0, deletions=0, changed_files=0` and `merge_base == head.sha` (418c100). No live kilo-gsd tmux session, no `.gsd/in-progress/18.pid`, no forgejo `in-progress` label, no salvage state for this issue. The kanban card is blocked with `kind=capability` so the dispatcher routes this to a human / the janitor instead of launching a no-op kilo-gsd run. The PR object should be closed (no diff to merge).

Mark closed this pull request

2026-09-10 13:08:21 +00:00

Mark commented

2026-09-10 13:08:36 +00:00

Author

Owner

Closed: docs/multilang-limitations.md is already on main (commit 9a35b8cb). Branch and PR are no-op.

Closed: docs/multilang-limitations.md is already on main (commit 9a35b8cb). Branch and PR are no-op.