# Reported issues for talkthrough-mcp

Pod holds 14 of 14 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [talkthrough-mcp](/mcp/talkthrough-mcp).

## Most discussed

### Speaker diarization: sherpa-onnx backend — accepted for v0.2.0

Meetings with multiple speakers would benefit from 'who said it'. Constraints: local-only (privacy promise), CPU-friendly, pip-installable. Candidates to evaluate: pyannote (license/weights?), NeMo, whisperX-style alignment, sherpa-onnx diarization. Deliverable: a short comparison + recommendation in an issue comment; implementation is a separate PR. Explicitly out of v1 scope (README roadmap).

---

**Status 2026-07-14: ACCEPTED → v0.2.0, backend picked: sherpa-onnx.** Backend comparison is in 

[Read the thread](https://github.com/korovin-aa97/talkthrough-mcp/issues/4) · 2026-07-10 · closed · 3 comments

### Cache diarization embeddings so a num_speakers amend re-clusters in seconds

## Problem

Real-world report on a large multi-speaker meeting recording (v0.2.3):

1. `process_media(diarize=true)` without `num_speakers` → processing took ~12 min and unconstrained clustering over-split the audio into **123 "speakers"**.
2. Re-running with the correct `num_speakers=6` triggered the diarize amend path as designed — Whisper/frames/OCR were correctly reused — **but the call still took roughly as long as the first run**, because the amend re-runs the entire diarization engine.

#

[Read the thread](https://github.com/korovin-aa97/talkthrough-mcp/issues/33) · 2026-07-27 · open · 2 comments

### Semantic transcript search (local embeddings): tracking

Tracking issue for the semantic tier of transcript search (README Roadmap item, promoted to an issue after real-session evidence).

**Why.** `search` today is exact-substring — deliberate v1 scope (deterministic, zero deps, pointers-not-payloads). A real agent session hit its ceiling on *concept* queries: "where does he talk about the first phase" has no literal match against a transcript saying "the first one", "the first real phase", "the first step" (2026-07-14 tester feedback). Word-level ma

[Read the thread](https://github.com/korovin-aa97/talkthrough-mcp/issues/15) · 2026-07-14 · open · 2 comments

### ≤0.2.4 cannot start in freshly resolved environments: MCP SDK 2.0.0 removed mcp.server.fastmcp (fixed in 0.2.5)

**Symptom.** The server process dies on import before the MCP handshake. Claude Code shows:

```
/mcp  →  Failed to reconnect to plugin:talkthrough:talkthrough: -32000
```

Running the server command manually shows the real error:

```
File ".../talkthrough_mcp/server.py", line 20, in <module>
    from mcp.server.fastmcp import Context, FastMCP, Image
ModuleNotFoundError: No module named 'mcp.server.fastmcp'
```

**Cause.** The MCP Python SDK released 2.0.0 on 2026-07-28, which removes the `mcp.

[Read the thread](https://github.com/korovin-aa97/talkthrough-mcp/issues/40) · 2026-07-31 · closed · 1 comment

### search: multi-word queries should match by words, not exact phrase (+ Unicode/ё-е normalization)

**Problem** (2026-07-14 tester batch, agent-driven session): `search` is exact-substring, so a multi-word query silently means *exact phrase*. `search("first phase")` returns zero hits against a transcript that says "the first one", "the first real phase", "the first step" — the information is there, the agent concludes it isn't. Guidance already steers agents toward "a distinctive word", but the tool should survive natural usage instead of trapping it.

**Proposal — the dependency-free tier (de

[Read the thread](https://github.com/korovin-aa97/talkthrough-mcp/issues/16) · 2026-07-14 · closed · 1 comment

### get_frames / get_moment: explicit validity span (valid_from_ms / valid_to_ms) per served keyframe

**Insight from an early tester** (2026-07-14 batch, agent-driven session): perceptual dedup means a range query over a static minute returns a single keyframe — great for token budgets — and "what was on screen at time T" is answerable by reasoning over `duplicate_of` chains / nearest keyframes. But that's an *inference* the agent has to make every time. Return it as data instead.

**Proposal.** For every served unique keyframe, add an explicit validity span:

```json
"valid_from_ms": 47166,   /

[Read the thread](https://github.com/korovin-aa97/talkthrough-mcp/issues/14) · 2026-07-14 · closed · 1 comment

### extract_frame / get_frames: return the absolute file path in tool responses

**Problem.** `extract_frame` writes the extracted frame to `<TALKTHROUGH_HOME>/jobs/<job_id>/extracts/extract-t<ms>[-crop…].jpg`, but the JSON block in the response doesn't include that path. `get_frames` / `get_moment` similarly return only the basename (`"file": "t00047166.jpg"`) of served keyframes. An agent asked to "save this screenshot next to my project docs" has to reverse-engineer the store layout instead of copying a file it was just handed.

**Fix** (ships with v0.2.0, riding the diar

[Read the thread](https://github.com/korovin-aa97/talkthrough-mcp/issues/13) · 2026-07-14 · closed · 1 comment

### P6: macOS 26 (ReplayKit) screen recordings carry no com.apple.quicktime.creationdate — wall-clock rung 2 unreachable, docs overpromise

**Acceptance step:** 4.3 (wall-clock flagship), P6 manual acceptance 2026-07-10. Founder-approved filing.

**Expected:** per README (Wall-clock anchoring), docs/DESIGN.md (ladder table) and `core/wallclock.py` docstring, a macOS Cmd+Shift+5 recording carries `com.apple.quicktime.creationdate` (with tz offset) → `source=quicktime`, `confidence=high`.

**Got:** on macOS 26.4.1 all three ⌘⇧5 recordings on this machine are authored by ReplayKit and carry ONLY UTC `format.tags.creation_time` — no `cr

[Read the thread](https://github.com/korovin-aa97/talkthrough-mcp/issues/9) · 2026-07-10 · closed · 1 comment

## Most recent

### P6: OCR garbles Cyrillic UI text (default RapidOCR models) — document the limitation or expose a language option

**Acceptance step:** 4.5, P6 manual acceptance 2026-07-10 (founder-approved filing), job `ab4dcf3f5acf435c`.

**Got:** English/Spanish on-screen text OCRs well — `search("viajaste")` → 8 OCR hits; long English chat copy captured nearly verbatim. Large Cyrillic UI text at the same font size garbles: «Выберите поезд» → `Bepe noe3`, «Цена билета» → `Lea uneta`, RU chat bubbles → `,   ,   ?` placeholders. `search` over RU on-screen text therefore misses even though the words are clearly legible on t

[Read the thread](https://github.com/korovin-aa97/talkthrough-mcp/issues/11) · 2026-07-10 · closed · 0 comments

### P6: get_moment picks nearest unique frame by time — can cross a scene boundary when all in-range frames are duplicates

**Acceptance step:** 4.2, P6 manual acceptance 2026-07-10 (founder-approved filing), job `ab4dcf3f5acf435c` — real 2-min screencast, 8 unique / 119 frames, one long static stretch 47.2s→92.4s deduped to a single keyframe.

**Got:** `get_moment(start_ms=81810, end_ms=88950)` returned frame `t00092358.jpg` — 3.4 s AFTER the requested range and on the far side of a scene change (92.358 s starts a new scene). Every frame inside the range is `duplicate_of: 47166`, so the faithful representative of th

[Read the thread](https://github.com/korovin-aa97/talkthrough-mcp/issues/10) · 2026-07-10 · closed · 0 comments

### whisper.cpp backend as an alternative to faster-whisper

faster-whisper (CTranslate2) is the v1 backend. whisper.cpp with Metal/CoreML could be faster on Apple Silicon and removes the ctranslate2 wheel dependency. Port shape already exists conceptually (segments JSON with ms offsets). Needs: backend selection env (`TALKTHROUGH_STT_BACKEND`), binary resolution ladder like ffmpeg.py, and CI coverage decision.

[Read the thread](https://github.com/korovin-aa97/talkthrough-mcp/issues/6) · 2026-07-10 · open · 1 comment

### Expose RapidOCR language/config knobs

OCR currently runs RapidOCR defaults. Some recordings need language hints or det/rec model switches. Proposal: `TALKTHROUGH_OCR_LANG` (and maybe a generic pass-through env) wired into `core/ocr.py:create_engine`, documented in README Configuration.

[Read the thread](https://github.com/korovin-aa97/talkthrough-mcp/issues/3) · 2026-07-10 · closed · 1 comment

### Recipe: file approved findings as GitHub issues (gh CLI example)

The triage flow ends with findings JSON per `examples/output-contract.schema.json`. Add `examples/recipes/github-issues.md` (or a small script): for each approved finding, create one GitHub issue via `gh issue create` — title from `title`, body from quote/observed/expected/acceptance_criteria/verify_via + t_wall, attach the referenced frames from `~/.talkthrough/jobs/<job_id>/frames/`.

[Read the thread](https://github.com/korovin-aa97/talkthrough-mcp/issues/2) · 2026-07-10 · closed · 0 comments

### Windows: best-effort smoke run + docs notes

The codebase is OS-neutral by design (fcntl lock degrades to no-op, static-ffmpeg has win builds), but nobody has run it on Windows yet.

**Task**: run `uv run talkthrough-mcp process tests/fixtures/talkthrough-demo.mp4` on Windows, note what breaks (paths, locking, static-ffmpeg resolution), and PR a short 'Windows notes' README section. No CI needed — v1 keeps Windows best-effort.

[Read the thread](https://github.com/korovin-aa97/talkthrough-mcp/issues/1) · 2026-07-10 · closed · 0 comments

The remaining reports are on [the project's issue tracker](https://github.com/korovin-aa97/talkthrough-mcp/issues).