* fix: speaker detection — gated pyannote license surfaces a docs deeplink (closes#78)
Issue #78 ("Speaker detection fails — speakers blend together or aren't
detected correctly") was the user-visible symptom of the dub pipeline
silently falling back to the silence-gap heuristic in
`backend/api/routers/dub_core.py::_diarize`. The heuristic alternates
Speaker 1 ↔ Speaker 2 on >1.2s gaps only, so two real speakers with
similar pacing get merged or swapped — and once the auto-clone step
extracts a reference voice for the wrong label, downstream dubs make
"person A speak like person B" (the reporter's exact phrasing).
The structural cause is that pyannote-3.1 is gated on HuggingFace: a
valid HF_TOKEN by itself isn't enough — the user must also click
"Agree and access repository" on both pyannote/speaker-diarization-3.1
AND pyannote/segmentation-3.0. We can't fix that for the user, but we
CAN make the failure actionable instead of silent.
Changes:
- `backend/services/model_manager.py`: `get_diarization_pipeline()`
gains an opt-in `return_error=True` shape that returns
`(pipeline | None, error_sentinel)`. Sentinels distinguish
NO_TOKEN / PYANNOTE_LICENSE_REQUIRED / LOAD_FAILED. A new
`_classify_diarization_error()` sniffs the exception's class name +
message for 401/403/gated/"accept license" signals — kept as a
string heuristic so it survives huggingface_hub major-version
churn. Bare-`None` default return preserved for the legacy
`_transcribe` call site at dub_core.py:781.
- `backend/api/routers/dub_core.py::_diarize`: now emits a structured
SSE warning `{detail, source, error_class, docs_url}` instead of
plain `{detail, source}`. The new fields let the front-end render a
"See docs" button that deeplinks directly to the
`License acceptance flow` section of `docs/features/diarization.md`
(landed in PR #94) — the page with the click-by-click instructions
for fixing this exact failure mode.
- `backend/core/error_docs_map.py` + `frontend/src/utils/errorDocsMap.ts`:
add a 5th taxonomy class `PYANNOTE_LICENSE_REQUIRED` pointing at the
diarization docs section. Distinct from `HF_AUTH_FAILED` (which is
the more general "token missing or invalid" case). The TS
`classifyError` heuristic also picks up pyannote / gated /
"speaker diarization" keywords so a thrown error in the boundary
routes to the right deeplink too.
- `tests/backend/core/test_error_docs_map.py`: bump locked-keys set to
5 classes; add an explicit assertion that the new class points at
the `license-acceptance-flow` anchor.
- `frontend/src/utils/errorDocsMap.test.ts`: bump locked-keys set to
5 classes; add classifier tests for pyannote / gated / accept-license
keyword routing.
- `tests/test_diarization_error_class.py`: regression test (20 cases)
covering `_classify_diarization_error`, the new
`get_diarization_pipeline(return_error=True)` shape, backward-
compatible bare-`None` return for the legacy call site, and the
error_docs_map deeplink target. Uses sys.modules patching so
pyannote / torch are never actually imported.
HF token plumbing: unchanged. The new code continues to route through
`token_resolver.resolve()` per the AUTH-01 contract — no new bare
`os.environ.get("HF_TOKEN")` reads.
Cross-platform: identical behaviour on macOS / Windows / Linux —
the only platform-touching change is a docs URL string, which is
opened via the existing `openExternal()` helper that already abstracts
Tauri's `shell.open` on all three platforms.
Verification:
.venv/bin/python -m pytest tests/test_diarization_error_class.py \
tests/backend/core/test_error_docs_map.py -v
# 20 passed in 0.03s
bun run test src/utils/errorDocsMap.test.ts
# 13 passed (1 test file)
.venv/bin/python -m pytest tests/test_segmentation.py \
tests/test_dub_transcribe.py \
tests/backend/services/test_token_resolver.py \
tests/test_model_manager_preload.py
# 40 passed, 10 xfailed (pre-existing), 1 xpassed
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* test: add regression test for diarization error classification (issue #78)
Companion to the fix in d6e6586. 20 test cases covering:
- `_classify_diarization_error` — the string heuristic that buckets
pyannote/HF exceptions into NO_TOKEN / LICENSE / LOAD sentinels.
Pinned for 401/403/gated/accept-license/accept-user-conditions
signals so it survives huggingface_hub major-version churn.
- `get_diarization_pipeline(return_error=True)` — the new 2-tuple
return shape that lets the dub pipeline's SSE warning carry an
error_class.
- Backward compatibility — the bare-`None` return on the default
signature is preserved so dub_core.py:781's legacy `_transcribe`
call site doesn't break.
- The error_docs_map deeplink — the new PYANNOTE_LICENSE_REQUIRED
class points at `docs/features/diarization.md#license-acceptance-flow`.
Uses sys.modules patching for pyannote.audio.Pipeline + token_resolver
so the real torch + pyannote + HF API are never imported.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* test(diarization): dotted-path monkeypatch to survive Wave 1 sys.modules purge
The new `test_diarization_error_class.py` tests pass in isolation but fail
in the full suite — Wave 1's `fresh_resolver` fixture aggressively purges
all `services.*` and `core.*` modules from `sys.modules` mid-suite. When
this file's tests later did `from services import token_resolver` then
`monkeypatch.setattr(token_resolver, "resolve", ...)`, the local
`token_resolver` reference bound to a stale module identity. The function
under test does `from services import token_resolver` at call time, which
re-resolves through the (post-purge) `sys.modules['services.token_resolver']`
— a different object — so the monkeypatch was applied to one ID and the
function read from another.
Two fixes in this commit:
1. Don't pop `services.token_resolver` in this file's `model_manager`
fixture — the test body's import and the function's import must agree
on identity. Popping forces re-import that can create two distinct
modules.
2. Use the dotted-path form `monkeypatch.setattr("services.token_resolver.resolve", ...)`
instead of the object-attribute form. Pytest's dotted form re-resolves
the path through `sys.modules` at setattr time, so the binding is
always on the live module object regardless of which identity the test
imported earlier.
Verified: `pytest tests/ -q` → 442 passed, 0 failures (was 1 failed
before this commit on PR #110).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
