talkthrough-mcp: Skill for Claude Code

Analyzing narrated recordings with talkthrough

The talkthrough MCP server turns a local video/audio file into queryable structured data: timestamped transcript segments, scene keyframes, OCR'd on-screen text, and wall-clock anchoring. No LLM inside — you bring the reasoning; it brings the evidence. Everything is lazy and token-budgeted: never ask for more than the moment you are analyzing.

Prerequisite

The talkthrough MCP server must be connected (tools like process_media / get_transcript are visible). If not, tell the user to install it: claude mcp add -s user talkthrough -- uvx --python ">=3.11,<3.14" "talkthrough-mcp[diarization,url]" (see the repository README for other clients).

Core workflow

1. Ingest once: process_media(path) — idempotent by content hash; re-calls on the same file return instantly. Given a public video/audio URL instead of a file, call process_url(url): the source is downloaded once (the only network step; YouTube needs the [url] extra) and kept inside the job, then everything below is identical and local — never download twice; a repeat call serves the stored job. Long videos take minutes and stream progress. The summary gives you job_id, counts, wall-clock, and a transcript preview — do NOT dump anything else eagerly. Multi-person recording (meeting/interview)? Add diarize=true — even when the ask is just "summarize", speaker structure is part of meeting analysis — and — whenever the headcount is known — num_speakers=N (the main accuracy lever): segments get S1/S2/… labels and the summary a talk-time roster. On an already-processed job the amend re-runs ONLY diarization (no re-transcription) — still minutes on long recordings.
2. Orient: get_transcript(job_id) (paginate via next_start_ms when truncated) or search(job_id, "<distinctive word>") to jump straight to the relevant moments (searches speech AND on-screen OCR text). Multi-word search defaults to match_mode="all_words"; use "any_word" for broader lexical recall.
3. Evidence per remark: get_moment(job_id, t0-2000, t1+2000) — one call returns the transcript slice + up to 3 unique frames + their OCR text + the wall-clock range. This is the workhorse; describe observed from the returned pixels, never from imagination.
4. Precision when needed: get_frames(at_ms=...) for nearby keyframes; extract_frame(job_id, at_ms, crop={x,y,w,h}) for an exact instant at native resolution (keyframes capture scene changes + a 1 fps floor, so sub-second moments can fall between them).
5. Keep verified names: after proving an anonymous label's identity, call label_speakers(job_id, labels={"S1":"Name"}, evidence={"S1":"intro or frame proof"}). Saved names appear in later transcript, moment, and search calls while raw S1/S2 labels remain. If a diarization amend changes labels, those names move to speaker_names_pending_review and stop being identities. Use the stored old-roster context anchors to re-check them. A pending label still in the roster can be confirmed, replaced, or removed; a stale pending label can only be removed with labels={"Sx":null}. Never use a pending name in minutes or search as though it were active. A full force=true rebuild of a job with active or pending names must also use diarize=true; it rebuilds safely and moves every old identity to pending review, while omitting diarization is refused without changing the stored job.
6. Recall across sessions: list_jobs() — the store persists; a file processed yesterday (even via CLI) is queryable by job_id today.