Open-source AI podcast clipper. Generate vertical clips with face tracking and burned-in captions. CLI, MCP server, web app.
Python ai-toolsauto-captionscaptionscliffmpegmcpmcp-serveropusclip-alternativepodcast-clipspodcastsshortform-videovertical-videowhisper
Give the clip selector speaker turns to read (#168)
Nika Siradzeb8a64b4d6fe6
diff --git a/.claude/commands/auto.md b/.claude/commands/auto.mdindex 73e9ebd..87aa8f5 100644--- a/.claude/commands/auto.md+++ b/.claude/commands/auto.md@@ -23,6 +23,7 @@ This command orchestrates the existing MCP tools on top of the compact packed tr2. **Strategy first, render after.** Propose the cut list and WAIT for user confirmation before calling `batch_create_clips`.3. **Knowledge base is context, not template.** If `` exists, read it for brand voice and format preferences. If not, infer from the content itself.4. **Never silently render.** Every clip that ships must appear in the proposal the user approved.+5. **Every clip carries its own context.** A stranger who never heard the episode has to follow it from the first second. If the moment is an answer, the question comes with it.---@@ -48,12 +49,67 @@ This command orchestrates the existing MCP tools on top of the compact packed tr- Loop: call `transcribe_status(job_id, wait_seconds: 30)`. Between calls, emit ONE terse line to the user like `"Progress: 47% — pyannote diarization"`. Keep it to one line per poll — no repeat prose. Exit the loop when `done: true`.- If `status: "error"`, stop and report the error.3. Read the packed transcript: `get_ui_state(include_transcript: true)`. This returns a compact phrase-grouped view with speakers, silence gaps, and energy peaks.+ - **If the header says speakers: 0**, stop and tell the user before going further. Without speaker labels you cannot tell a question from an answer, so the whole question-with-the-answer rule below is inert and the picks will be worse. Offer to re-transcribe with `transcribe_start(file_path, enable_diarization: true)`. Only continue without it if the user says to.4. If `` exists, read `01-brand-identity.md`, `02-voice-and-tone.md`, and `04-shorts-creation-guide.md` for show context. Skip silently if missing — `/auto` works on any content.5. Call `clip_history` to see what's already been shipped for this episode. Avoid duplicates in the proposal.**Fallback**: if `transcribe_start` returns an error about the Web UI not running, tell the user and offer either (a) run `npm run ui` in another terminal then retry, or (b) fall back to the synchronous `transcribe_podcast` (no live progress, works silently).-### Phase 2 — Strategy Proposal (GATE)+### Phase 2 — Topic Map (silent)++Before picking a single clip, map the whole episode. Clips get cut out of topics, never out of loose lines.++1. Sweep the packed transcript end to end and mark every topic change.+2. Emit 2-5 topics per 30 minutes of runtime, 6-12 for a full hour. Each topic covers 3-12 minutes.+3. Cover the whole runtime. The first 10 minutes and the last 5 get skipped most often, and they hold the setup and the summary. Anything that fits nowhere goes into a "loose ends" topic rather than being dropped.+4. Merge adjacent topics that both run under 2 minutes and cover the same ground.++Per topic, hold:++| Field | Value |+|-------|-------|+| `span` | `[hh:mm:ss-hh:mm:ss]` |+| `title` | what the topic is about, not a headline |+| `beats` | 2-5 sub-points actually said |+| `speakers` | who drives it |++Keep the map internal. It feeds Phase 3 and is only shown if the user asks for it.++### Phase 3 — Cut Planning (silent)++Work inside one topic at a time. Set boundaries by meaning, not by the clock.++**start_second**++- Land on the first sentence of the core statement. Drop the throat-clearing in front of it.+- If the moment is an answer, move the start back to include the question. Otherwise the clip opens on a reply to nothing and the viewer bounces.+- The question has to be inside the clip. `context_line` is a note for the editor, not a fix: nothing burns it into the video yet, so a clip that relies on it still ships with no setup.+- If the question rambles past roughly 8 seconds, use `segments` to keep the asked part and cut the rambling, or drop the moment.+- Never open on a word pointing back before the cut: "that", "it", "they", "yeah", "so", "exactly", "right", "which is why". Widen the start until the reference is inside the clip.++**end_second**++- Land on the end of the last sentence of the argument, never on the end of the topic block.+- Cut before trailing summaries, transitions, and "anyway, so" tails.+- If the thought is unfinished at the boundary, extend until it closes or drop the moment. Never ship half an argument.++**Never cut** mid-sentence, mid-list, or between a claim and the evidence for it.++**Write the payoff before the title.** One sentence, second person, on what the viewer walks away with. The title is then derived from the payoff, not from transcript wording. A moment with no payoff you can state in one sentence is not a clip. Drop it.++**Check the moment against its own type**, not against one generic bar:++| Type | Carries the clip | Fails when |+|------|------------------|-----------|+| Guest story | A turn: what they expected, what happened instead | It summarizes the story instead of telling it |+| Technical insight | One mechanism explained in plain words | It needs a diagram, or terms the viewer does not have |+| Market / landscape | A specific read on where things are going, with a reason | It lists players without taking a position |+| Business / strategy | A number, a trade-off, or a decision with a cost | The advice would fit any company in any year |+| Hot take | A claim a reasonable person would argue with, plus the reason | It is only a strong tone with no claim under it |++**Run the standalone check.** Name what the viewer must already know. If that is anything other than "nothing", the start moves back until the clip covers it. If it cannot, drop the moment.++### Phase 4 — Strategy Proposal (GATE)Emit a numbered strategy table. Do NOT render yet.@@ -65,33 +121,37 @@ Inferred tone: <from voice fingerprint or 02-voice-and-tone.md>Target count: <N> clips (from arg, or inferred from content density)#1 [00:04:22-00:05:01] 39s S0 "<hook>"- Why: <one line — the angle, the stakes, or the moment>- Title: <suggested, ≤60 chars>- Style: <hormozi | karaoke | subtle | branded>+ Payoff: <what the viewer walks away with, one sentence, second person>+ Needs: <nothing | what the viewer must know, and how this clip covers it>+ Why: <the angle, the stakes, or the moment>+ Title: <derived from the payoff, ≤60 chars>+ Style: <hormozi | karaoke | subtle | branded>#2 ...Unused peaks / skipped moments:-- [00:18:45] — high energy but no standalone hook-- [00:34:10] — great quote, but needs 40s of setup+- [00:18:45] high energy, no payoff you can state in one sentence+- [00:34:10] great quote, needs 40s of setup that will not fit+- [00:41:02] answer with no question in reach, and the setup is too long to cardConfirm? (yes / redirect / change specific clips)```**Stop here. Wait for the user's response.** Do not call `batch_create_clips` on implicit approval — require an explicit "yes", "go", "ship it", or similar.-### Phase 3 — Render (with live progress)+### Phase 5 — Render (with live progress)Once the user confirms:-1. Call `batch_create_clips(clip_numbers=[1,2,...], async_mode: true)` → returns `{job_id, clip_count}` immediately.-2. Emit to the user: _"Rendering {clip_count} clips — I'll report progress per clip."_-3. Loop: `job_status(job_id, wait_seconds: 30)` → emit ONE terse line per poll, e.g. `"Rendering 3/7 — clip #3 (speaker crop)"`. Exit when `done: true`.-4. When done, print the output paths and a one-line-per-clip summary (from the result field).+1. Call `suggest_clips` with the approved list. Every entry carries `payoff`, `standalone`, `context_line`, and `preview_text` (the real opening line, verbatim) alongside the timings. The tool rejects a clip whose context is missing and tells you which one; fix it and resubmit the full list rather than dropping it.+2. Call `batch_create_clips(clip_numbers=[1,2,...], async_mode: true)` → returns `{job_id, clip_count}` immediately.+3. Emit to the user: _"Rendering {clip_count} clips — I'll report progress per clip."_+4. Loop: `job_status(job_id, wait_seconds: 30)` → emit ONE terse line per poll, e.g. `"Rendering 3/7 — clip #3 (speaker crop)"`. Exit when `done: true`.+5. When done, print the output paths and a one-line-per-clip summary (from the result field).**Fallback**: if `async_mode` fails (Web UI down), fall back to sync `batch_create_clips(clip_numbers=[...])` — renders silently but still works.-### Phase 4 — Persist+### Phase 6 — PersistWrite a compact session log to `.podcli/sessions/<episode-slug>.md` (create the dir if missing):diff --git a/.claude/commands/process-transcript.md b/.claude/commands/process-transcript.mdindex a5bbc96..bf609fb 100644--- a/.claude/commands/process-transcript.md+++ b/.claude/commands/process-transcript.md@@ -73,20 +73,43 @@ Scan the entire transcript for:Flag 15-20 potential moments.-### Phase 3: Score Each Moment+### Phase 3: Anchor Each Moment (Silent)++Before scoring, fix each flagged moment's edges and state its payoff.++**Start**++- Open on the first sentence of the core statement. Drop the throat-clearing in front of it.+- If the moment is an answer, pull the start back to include the question. A clip that opens on a reply to nothing loses the viewer in two seconds.+- The question has to be inside the clip. A setup line is a note for the editor, not a fix: nothing renders it into the video yet. If the question rambles past roughly 8 seconds, cut the rambling out of the middle or drop the moment.+- Never open on a word pointing back before the cut: "that", "it", "they", "yeah", "so", "exactly", "right", "which is why".++**End**++- Close on the last sentence of the argument, not on the last sentence in the topic.+- Cut before trailing summaries, transitions, and "anyway, so" tails.+- If the thought is unfinished at the edge, extend until it closes or drop the moment. Never ship half an argument.++**Never cut** mid-sentence, mid-list, or between a claim and the evidence for it.++**Then write the payoff, before any title.** One sentence, second person, on what the viewer walks away with. The title is derived from the payoff, never from transcript wording. A moment with no payoff you can state in one sentence is not a short. Drop it.++**Then run the standalone check.** Name what the viewer must already know. If it is anything other than nothing, the start moves back until the clip covers it. If it cannot, drop the moment.++### Phase 4: Score Each MomentFor every flagged moment, score on four dimensions (1-5 each):| Dimension | What It Measures ||-----------|-----------------|-| **Standalone value** | Makes complete sense without episode context? |+| **Standalone value** | Makes complete sense with no episode context, including the question it answers? || **Hook strength** | Grabs attention in first 3 seconds of the clip? || **Relevance** | Matters to the show's target audience? || **Quotability** | Contains memorable, shareable phrasing? |**Total score = sum of 4 dimensions (max 20).**-### Phase 4: Select & Classify+### Phase 5: Select & Classify1. Rank all moments by total score2. Select the top moments (per target count)@@ -100,11 +123,23 @@ For every flagged moment, score on four dimensions (1-5 each):| **Business / Strategy** | Revenue, fundraising, pricing, go-to-market || **Hot Take / Opinion** | Challenges widely held belief |-### Phase 5: Check for Duplicates+Then check each moment against its own type, not against one generic bar:++| Type | Carries the clip | Fails when |+|------|------------------|-----------|+| **Founder/Guest Story** | A turn: what they expected, what happened instead | It summarizes the story instead of telling it |+| **Product/Technical Insight** | One mechanism explained in plain words | It needs a diagram, or three terms the viewer does not have |+| **Market / Landscape** | A specific read on where things are going, with a reason | It lists players without taking a position |+| **Business / Strategy** | A number, a trade-off, or a decision with a cost attached | The advice would fit any company in any year |+| **Hot Take / Opinion** | A claim a reasonable person would argue with, plus the reason | It is only a strong tone with no actual claim under it |++A moment that fails its type's bar drops, however well it scored.++### Phase 6: Check for DuplicatesRead `03-episodes-database.md` and verify no selected moments overlap with existing shorts.-### Phase 6: Extract Keywords+### Phase 7: Extract KeywordsFrom the full transcript, extract:- Main topics discussed@@ -144,6 +179,10 @@ Format: comma-separated, under 500 characters.> "[Exact quote from transcript — the hook sentence]"+**Payoff:** [What the viewer walks away with. One sentence, second person.]+**Needs:** [nothing | what the viewer must already know]+**Setup line:** [The question this answers, in one line, or omit when the clip carries its own setup]+**Why it works:** [One sentence explaining the appeal]**Suggested titles:**@@ -169,6 +208,8 @@ Format: comma-separated, under 500 characters.For every moment included:- [ ] Makes sense without the full episode+- [ ] Payoff states what the viewer gets, and is not a restatement of the title+- [ ] Does not open on a word pointing back before the cut- [ ] Has a clear start and satisfying end- [ ] Hook lands in first 3 seconds- [ ] Single focused idea, fully delivered@@ -182,7 +223,7 @@ For every moment included:## Self-Correction Rules1. If output feels generic → add specificity from the transcript-2. If a moment needs context → it's not a good short, skip it+2. If a moment needs context → pull the start back to include it, or carry it in the setup line. If neither fits, skip the moment3. If you can't find enough strong moments → flag it honestly, don't pad with weak ones4. Always prioritize variety across content typesdiff --git a/.claude/commands/produce-shorts.md b/.claude/commands/produce-shorts.mdindex 6c96d15..cb1f1aa 100644--- a/.claude/commands/produce-shorts.md+++ b/.claude/commands/produce-shorts.md@@ -50,12 +50,12 @@ Each phase calls the corresponding skill's logic. Each phase reports its own Com### Phase 1: Transcript Processing*Runs `/process-transcript` logic*-Extract guest info, flag 15-20 moments, score them, select top moments, classify by content type, check for duplicates.+Extract guest info, flag 15-20 moments, anchor each one (boundaries by meaning, question pulled in or carried as a setup line, payoff written before any title), score them, select top moments, classify by content type, check for duplicates.### Phase 2: Title Development*Runs `/generate-titles` logic per moment*-For each moment: extract anchor, classify, generate 8 options, verify, flag top 2. Narrow to 2-3 best per moment.+For each moment: extract anchor, classify, generate 8 options, verify, flag top 2. Narrow to 2-3 best per moment. Every option is derived from the moment's payoff, not from transcript wording.### Phase 3: Description Writing*Runs `/generate-descriptions` logic*@@ -100,7 +100,7 @@ Each phase consumes upstream output and passes structured state downstream. Phas| Phase | Consumes | Produces ||-------|----------|----------|-| 1 | Transcript | Moment list with scores, categories, quotes, timestamps |+| 1 | Transcript | Moment list with scores, categories, quotes, timestamps, payoff + needs + setup line || 2 | Moment list | 2-3 titles per moment + top picks || 3 | Moments + titles | Per-short + long-form descriptions with hashtags || 4 | Moments | Podcast + shorts thumbnail briefs |diff --git a/.claude/commands/review-content.md b/.claude/commands/review-content.mdindex eb13c42..9647b9c 100644--- a/.claude/commands/review-content.md+++ b/.claude/commands/review-content.md@@ -49,7 +49,7 @@ Dispatch subagents in parallel, each owning one dimension. Each returns a findin| **Voice Check** | Coffee Test, tone fingerprint match | Yes || **Banned Words** | Exact scan against `02-voice-and-tone.md` | Yes || **Title Review** | Length, keyword-first, shape, anchor presence, no tension-without-payoff | If titles in package |-| **Standalone Check** | Each short makes sense without the episode | If shorts in package |+| **Standalone Check** | Each short makes sense without the episode: payoff is stated and is not the title again, nothing is required going in that the clip range itself does not cover, and the first line does not point back before the cut. A setup line is not coverage, since nothing renders it | If shorts in package || **Clickbait Detector** | Title promises something the clip can't deliver | If titles + clips both in package || **SEO / Hashtags** | Description hashtags count, show hashtag present, keyword coverage | If descriptions in package || **Duplication Check** | Cross-reference `03-episodes-database.md` | If moments/shorts in package |diff --git a/backend/cli.py b/backend/cli.pyindex 2f99034..e028aea 100644--- a/backend/cli.py+++ b/backend/cli.py@@ -135,7 +135,8 @@ def _selection_signature(config: dict) -> str:]if ai_select:try:- from services.claude_suggest import kb_signature+ from services.claude_suggest import PROMPT_VERSION, kb_signature+ parts.append(PROMPT_VERSION)parts.append(kb_signature())except Exception:# Unique per call, so a run that could not read the knowledge basediff --git a/backend/services/claude_suggest.py b/backend/services/claude_suggest.pyindex 0d26dbb..6585658 100644--- a/backend/services/claude_suggest.py+++ b/backend/services/claude_suggest.py@@ -123,6 +123,12 @@ KB_FILES = []+# Bump when the selection rules in _build_prompt change. Folded into the+# suggestion cache key for the same reason the knowledge base is: replaying old+# picks under new rules teaches people the rules do nothing.+PROMPT_VERSION = 5++def kb_signature() -> str:"""Fingerprint of exactly what the knowledge base contributes to the prompt.@@ -314,6 +320,9 @@ DURATION RULES (CRITICAL):CUTTING RULES (CRITICAL):- Cut TIGHT. Every second must earn its place.- Start at the exact moment the hook hits — no preamble, no "so", no "well"+- ONE EXCEPTION: if the moment is an ANSWER, start on the QUESTION that prompted it.+ A question is not preamble, it is the setup the viewer needs. Only leave it out when+ it rambles past ~8 seconds, and then cut the rambling with "segments" or skip the moment.- End the MOMENT the point lands with a complete thought — don't trail off- NEVER cut mid-sentence or mid-thought. The viewer must feel closure.- The last sentence must feel like a natural ending, a punchline, or a mic-drop@@ -324,6 +333,8 @@ MOMENT SELECTION ({b.lens}):- Would YOU stop scrolling for this? If no, skip it.- First 3 seconds must HOOK — a bold claim, shocking number, or provocative question- Must make complete sense standalone — no "as I mentioned" or "going back to"+- Must not OPEN on a word pointing back before the cut: "that", "it", "they", "yeah",+ "so", "exactly", "right", "which is why". Widen the start until it is inside the clip.- Must end on a COMPLETE THOUGHT — sentence boundary, natural pause, or mic-drop moment- Single focused idea — one concept, fully delivered, no loose threads- Prioritize: controversial takes, surprising numbers, founder war stories, "wait what?" moments, emotional peaks@@ -335,6 +346,19 @@ MOMENT SELECTION ({b.lens}):{f"ALREADY PUBLISHED (do NOT suggest these moments again):{chr(10)}{chr(10).join('- ' + s for s in existing_shorts)}" if existing_shorts else ""}{excluded_ranges}{_format_reaction_anchors(reaction_times)}+CONTEXT RULES (CRITICAL):+- State the PAYOFF first: one sentence, second person, on what the viewer walks away with.+ If you cannot state it in one sentence, the moment is not a clip. Skip it.+- WRITE the title from the payoff. Never copy the first sentence of the moment into+ it. A transcript fragment is not a title: "Is it having a big?" and "Was not working+ so well" are what copying produces, and they promise the viewer nothing.+- The title must be a complete thought that reads on its own, under 60 characters.+- In "needs", name what the viewer must already know. Write "nothing" when the clip+ carries its own setup.+- If "needs" is anything other than "nothing", move start_second back until the clip+ covers it on camera. "context_line" is a note for the editor, not a fix: nothing burns+ it into the video, so a clip that leans on it still ships with no setup.+Score each moment on 4 dimensions (1-5 each):- standalone: Makes sense without episode context?- hook: Grabs attention in first 3 seconds?@@ -347,7 +371,7 @@ Return this exact JSON structure:{{"clips": [{{- "title": "First strong sentence from the moment",+ "title": "Written from the payoff, never copied from the transcript","start_second": 123.4,"end_second": 168.4,"segments": [@@ -359,7 +383,10 @@ Return this exact JSON structure:"scores": {{"standalone": 4, "hook": 5, "relevance": 4, "quotability": 3}},"total_score": 16,"quote": "The key quote from this moment",- "why": "One sentence on why this works as a short"+ "payoff": "What the viewer walks away with, one sentence, second person",+ "needs": "nothing",+ "context_line": "",+ "why": "One sentence on why this earns 30 seconds of a stranger's attention"}}]}}@@ -542,12 +569,19 @@ RULES:- Duration target: {bounds.target_min}-{bounds.target_max} seconds, max {bounds.dur_max} seconds- Cut tight: start at the hook, end when the point lands- Use segments to cut filler if needed+- If the moment is an ANSWER, start on the QUESTION that prompted it. A question is+ not preamble. If it rambles past ~8 seconds, cut the rambling with "segments".+- State the PAYOFF: one sentence, second person, on what the viewer walks away with.+ Write the title from it. Never copy the first sentence of the moment into the title.+- In "needs", name what the viewer must already know, or "nothing". If it is anything+ else, move start_second back until the clip covers it. "context_line" is a note for+ the editor, not a fix: nothing burns it into the video.Return this JSON:{{"clips": [{{- "title": "First sentence of the moment",+ "title": "Written for the viewer, never copied from the transcript","start_second": 123.4,"end_second": 158.4,"segments": [{{"start": 123.4, "end": 158.4}}],@@ -556,6 +590,9 @@ Return this JSON:"scores": {{"standalone": 4, "hook": 5, "relevance": 4, "quotability": 3}},"total_score": 16,"quote": "The key quote",+ "payoff": "What the viewer walks away with, one sentence, second person",+ "needs": "nothing",+ "context_line": "","why": "Why this matches what the user asked for"}}]@@ -605,6 +642,9 @@ Transcript:"score": total,"content_type": c.get("content_type", "unknown"),"reasoning": c.get("why", ""),+ "payoff": c.get("payoff", ""),+ "standalone": c.get("needs", ""),+ "context_line": c.get("context_line", ""),"preview_text": c.get("quote", "")[:120],"suggested_caption_style": caption_style,"quote": c.get("quote", ""),@@ -808,6 +848,9 @@ def suggest_with_claude("score": total,"content_type": c.get("content_type", "unknown"),"reasoning": c.get("why", ""),+ "payoff": c.get("payoff", ""),+ "standalone": c.get("needs", ""),+ "context_line": c.get("context_line", ""),"preview_text": c.get("quote", "")[:120],"suggested_caption_style": caption_style,"quote": c.get("quote", ""),diff --git a/backend/services/clip_generator.py b/backend/services/clip_generator.pyindex de3f739..a928b0a 100644--- a/backend/services/clip_generator.py+++ b/backend/services/clip_generator.py@@ -837,6 +837,10 @@ def generate_clip(duration = end_second - start_secondlength_warning = None+ # A clip that asks for captions and renders without them used to be+ # indistinguishable from a clip that never wanted them. Two shipped clips+ # went out silent that way.+ caption_warning = Noneif duration > spec.dur_max:length_warning = f"{duration:.0f}s, over the {spec.dur_max}s {spec.name} target"print(f" {length_warning}", file=sys.stderr, flush=True)@@ -936,6 +940,13 @@ def generate_clip()# Step 3: Render captions (Remotion-first; ASS fallback optional)+ if not transcript_words:+ caption_warning = (+ f"rendered without captions: no transcript words were passed, so the "+ f"{caption_style} style had nothing to draw"+ )+ print(f" {caption_warning}", file=sys.stderr, flush=True)+if transcript_words:if progress_callback:progress_callback(50, f"Adding {caption_style} captions (3/{total_steps})")@@ -948,10 +959,24 @@ def generate_clip(if w["end"] > start_second and w["start"] < end_second]+ words_in_range = len(clip_words)+# Clean filler wordsif clean_fillers:clip_words = _clean_transcript_words(clip_words)+ if not clip_words:+ caption_warning = (+ "rendered without captions: filler cleaning removed every one of "+ f"the {words_in_range} words in range"+ if words_in_range+ else (+ "rendered without captions: no transcript words fall between "+ f"{start_second:.1f}s and {end_second:.1f}s"+ )+ )+ print(f" {caption_warning}", file=sys.stderr, flush=True)+if clip_words:if progress_callback:progress_callback(65, f"Rendering captions into video (3/{total_steps})")@@ -1097,8 +1122,9 @@ def generate_clip("crop_strategy": crop_strategy,"format": spec.name,}- if length_warning:- out["warning"] = length_warning+ warnings = [w for w in (caption_warning, length_warning) if w]+ if warnings:+ out["warning"] = "; ".join(warnings)if keep_caption_overlay and caption_overlay_path and os.path.exists(caption_overlay_path):# Copy out of work_dir before cleanup so the returned paths survive.base, _ = os.path.splitext(final_path)diff --git a/backend/services/speaker_detection.py b/backend/services/speaker_detection.pyindex 5022d62..c6c225c 100644--- a/backend/services/speaker_detection.py+++ b/backend/services/speaker_detection.py@@ -47,6 +47,44 @@ def extract_audio_wav(video_path: str, output_path: str) -> str:return output_path+def _load_wav_waveform(audio_path: str):+ """Read a PCM WAV into the {waveform, sample_rate} dict pyannote accepts.++ pyannote 4 loads a file path through torchcodec, which needs FFmpeg's+ shared libraries on the system and raises "Could not load libtorchcodec"+ on machines that only have the ffmpeg binary. extract_audio_wav always+ writes 16 kHz mono PCM, so read it with the stdlib instead and hand the+ pipeline a tensor. Returns None when the file is not plain PCM, in which+ case the caller falls back to passing the path.+ """+ import wave++ try:+ import numpy as np+ import torch++ with wave.open(audio_path, "rb") as wf:+ sample_rate = wf.getframerate()+ channels = wf.getnchannels()+ width = wf.getsampwidth()+ raw = wf.readframes(wf.getnframes())+ except Exception:+ return None++ dtype = {1: "uint8", 2: "int16", 4: "int32"}.get(width)+ if dtype is None or not raw:+ return None++ data = np.frombuffer(raw, dtype=dtype).astype("float32")+ if width == 1:+ data = (data - 128.0) / 128.0+ else:+ data /= float(1 << (8 * width - 1))++ data = data.reshape(-1, channels).T if channels > 1 else data.reshape(1, -1)+ return {"waveform": torch.from_numpy(data.copy()), "sample_rate": sample_rate}++def run_diarization(audio_path: str,num_speakers: Optional[int] = None,@@ -165,7 +203,7 @@ def run_diarization(diarization_params["min_speakers"] = min_speakersdiarization_params["max_speakers"] = max_speakers- diarization = pipeline(audio_path, **diarization_params)+ diarization = pipeline(_load_wav_waveform(audio_path) or audio_path, **diarization_params)if progress_callback:progress_callback(90, "Processing speaker segments...")diff --git a/backend/services/transcript_packer.py b/backend/services/transcript_packer.pyindex 82777c5..726704c 100644--- a/backend/services/transcript_packer.py+++ b/backend/services/transcript_packer.py@@ -38,6 +38,9 @@ SILENCE_SPLIT_SEC = 0.5 # split a phrase on word gap >= thisSILENCE_GAP_REPORT_SEC = 0.6 # list gaps >= this in the silence sectionPHRASE_MAX_SEC = 12.0PHRASE_MAX_CHARS = 160+# Below this a "." is more likely an abbreviation than a sentence end, so only+# longer phrases get split on one. Question marks always split.+SENTENCE_SPLIT_MIN_CHARS = 25ENERGY_PEAKS_TO_REPORT = 20REACTIONS_TO_REPORT = 20REACTION_REPORT_THRESHOLD = 0.15@@ -204,6 +207,12 @@ def _speaker_at(speaker_segments: list[dict], t: float, last_known: Optional[strreturn last_known+def _ends_sentence(text: str, mark_only: bool = False) -> bool:+ """True when a word closes a sentence, ignoring trailing quotes/brackets."""+ stripped = text.rstrip().rstrip("\"')]}\u2019\u201d")+ return stripped.endswith("?") if mark_only else stripped.endswith(("?", ".", "!"))++def _build_phrases(words: list[dict],short: dict[str, str],@@ -214,6 +223,12 @@ def _build_phrases(Uses speaker_segments as authoritative for speaker attribution — per-wordspeaker fields are often noisy at segment boundaries, causing single-wordfragments that make the transcript unreadable.++ Sentence ends close a phrase once it is long enough to not be an+ abbreviation. Boundaries the selector can cut on have to be boundaries a+ listener hears, and a phrase that runs "...in the Amazon. Why did you want+ to" gives it nowhere clean to start. Diarization drifts a word or two at a+ turn, so this matters most exactly where speaker labels exist."""phrases: list[dict] = []current: Optional[dict] = None@@ -232,9 +247,15 @@ def _build_phrases(last_known = raw_spkspk = short.get(raw_spk, "S?")+ broke_sentence = current is not None and _ends_sentence(+ current["text"],+ mark_only=len(current["text"]) < SENTENCE_SPLIT_MIN_CHARS,+ )+should_split = (current is Noneor current["speaker"] != spk+ or broke_sentenceor (start - current["end"]) >= SILENCE_SPLIT_SECor (end - current["start"]) >= PHRASE_MAX_SECor (len(current["text"]) + len(text) + 1) >= PHRASE_MAX_CHARS@@ -298,6 +319,10 @@ def pack_transcript(short = _speaker_short_map(speakers_block)speaker_segments = transcript.get("speaker_segments", []) or []phrases = _build_phrases(words, short, speaker_segments)+ # Derived from what was emitted, not from num_speakers: a summary can claim+ # two speakers while the segments and per-word labels are both missing, and+ # then every line still reads "S?" with no warning to say so.+ no_speaker_labels = bool(phrases) and all(p["speaker"] == "S?" for p in phrases)gaps = _find_silence_gaps(words, SILENCE_GAP_REPORT_SEC)lines: list[str] = []@@ -326,6 +351,14 @@ def pack_transcript(# Transcript phraseslines.append("## Transcript")+ if no_speaker_labels:+ lines.append(+ "> No speaker labels for this transcript, so every line reads S? and lines "+ "break at sentence ends rather than at speaker turns. You cannot tell who "+ "is asking from who is answering here: do not guess. Re-run transcription "+ "with speaker detection on before selecting clips that depend on it."+ )+ lines.append("")for p in phrases:lines.append(f"[{_fmt_ts(p['start'])}-{_fmt_ts(p['end'])}] {p['speaker']} {p['text']}"diff --git a/backend/services/video_processor.py b/backend/services/video_processor.pyindex 65be64b..79bd37e 100644--- a/backend/services/video_processor.py+++ b/backend/services/video_processor.py@@ -77,6 +77,35 @@ def _manual_crop_x_expr(keyframes: list, crop_w: int, width: int) -> str:return expr+def _sane_speaker_mappings(face_map: Optional[dict]) -> Optional[dict]:+ """Drop speaker to cluster entries that do not point at a real cluster.++ A stale or partial face map can carry an index past the end of clusters, or+ a -1 that would quietly select clusters[-1]. isinstance(True, int) is True+ in Python, so a bool has to be excluded by type identity rather than by+ isinstance. Every consumer downstream reads speaker_mappings directly, so+ this runs once at the entry point instead of at each of them.+ """+ if not face_map:+ return face_map+ clusters = face_map.get("clusters") or []+ mappings = face_map.get("speaker_mappings") or {}+ clean = {+ sp: ci+ for sp, ci in mappings.items()+ if type(ci) is int and 0 <= ci < len(clusters)+ }+ if clean == mappings:+ return face_map+ log_event(+ "crop", "speaker_mappings_sanitized",+ dropped=len(mappings) - len(clean), kept=len(clean),+ )+ out = dict(face_map)+ out["speaker_mappings"] = clean+ return out++def crop_to_vertical(input_path: str,output_path: str,@@ -103,6 +132,7 @@ def crop_to_vertical(clip_start: The start time of this clip in the original video (for timestamp alignment)."""width, height = get_dimensions(input_path)+ face_map = _sane_speaker_mappings(face_map)target_w, target_h = target_dimstarget_ratio = target_w / target_h # 0.5625 for the vertical default@@ -2103,6 +2133,25 @@ def _use_face_map(if transcript_words:speakers_in_clip = set(w.get("speaker") for w in transcript_words if w.get("speaker"))+ # No speaker labels at all is not the same as one speaker, and a labelled+ # speaker with no cluster behind it is just as unusable. With two faces on+ # screen and nothing that resolves who is talking, any single cluster is a+ # guess, and clusters[0] is a guess by list order. Returning None drops the+ # caller through to per-frame tracking, which at least follows whoever the+ # source is actually showing.+ unmapped = {+ sp for sp in speakers_in_clip+ if type(speaker_mappings.get(sp)) is not int+ or not 0 <= speaker_mappings[sp] < len(clusters)+ }+ if len(clusters) >= 2 and (not speakers_in_clip or unmapped):+ log_event(+ "crop", "face_map_declined",+ reason="no_speaker_labels" if not speakers_in_clip else "unmapped_speakers",+ clusters=len(clusters), unmapped=len(unmapped),+ )+ return None+if len(speakers_in_clip) < 2 or len(clusters) < 2:# Single speaker — use their cluster or the dominant onefor sp in speakers_in_clip:diff --git a/src/config/paths.ts b/src/config/paths.tsindex dc2cf1e..4c46f7a 100644--- a/src/config/paths.ts+++ b/src/config/paths.ts@@ -84,6 +84,10 @@ export const paths = {corrections: join(home, "corrections.json"),thumbnailConfig: join(home, "thumbnail-config.json"),integrations: join(home, "integrations.json"),+ // Mirrors PODCLI_ENV_FILE from the Go launcher and backend/services/env_settings.py.+ // Reading it from process.cwd() instead is how HF_TOKEN went missing and speaker+ // detection silently stayed off.+ envFile: process.env.PODCLI_ENV_FILE || join(home, ".env"),pythonBackend: join(backendDir, "main.py"),pythonPath: detectPython(),ffmpegPath: process.env.FFMPEG_PATH || "ffmpeg",diff --git a/src/handlers/suggest-clips.handler.ts b/src/handlers/suggest-clips.handler.tsindex 772c34d..f028160 100644--- a/src/handlers/suggest-clips.handler.ts+++ b/src/handlers/suggest-clips.handler.ts@@ -6,7 +6,83 @@*/import { randomUUID } from "crypto";-import { validateSuggestionRange } from "../utils/clip-validation.js";+import { z } from "zod";+import {+ validateSuggestionContext,+ validateSuggestionRange,+} from "../utils/clip-validation.js";++const suggestionSchema = z.object({+ title: z.string().describe("Short catchy title for the clip"),+ start_second: z+ .number()+ .describe(+ "Start timestamp in seconds. If the moment is an answer, move this back " ++ "to include the question that prompted it.",+ ),+ end_second: z.number().describe("End timestamp in seconds"),+ segments: z+ .array(z.object({ start: z.number(), end: z.number() }))+ .optional()+ .describe(+ "Multi-cut keep-ranges within the clip. Use to cut out filler/tangents " ++ "in the middle. Omit for a single continuous clip.",+ ),+ payoff: z+ .string()+ .describe(+ "What the viewer walks away with. One sentence, second person, e.g. " ++ '"You learn why raising a seed round early cost them control of pricing." ' ++ "Not a description of the clip and not a restatement of the title.",+ ),+ standalone: z+ .string()+ .describe(+ "What a viewer who never heard this episode must already know to follow " ++ 'the clip. Write "nothing" when the clip carries its own setup.',+ ),+ context_line: z+ .string()+ .optional()+ .describe(+ "The question or setup that makes the clip land, in one line, for an editor " ++ "to place. Nothing renders it yet, so it does NOT satisfy the standalone " ++ "check: the clip range itself must still contain the setup.",+ ),+ reasoning: z+ .string()+ .describe("Why this earns 30 seconds of a stranger's attention"),+ preview_text: z+ .string()+ .describe(+ "The first sentence or two the viewer actually hears, verbatim from " ++ "start_second. This is what the standalone check reads, so it has to be " ++ "the real opening line, not a paraphrase.",+ ),+ content_type: z+ .string()+ .optional()+ .describe(+ "Content classification: guest_story, technical_insight, market_landscape, business_strategy, hot_take",+ ),+ score: z+ .number()+ .optional()+ .describe(+ "Virality score (0-20). Sum of standalone + hook + relevance + quotability (each 1-5).",+ ),+ suggested_caption_style: z+ .enum(["hormozi", "karaoke", "subtle", "branded"])+ .optional()+ .describe("Recommended caption style for this clip"),+});++/** Single source of truth for the tool's arguments; server.ts registers this. */+export const suggestClipsInputShape = {+ suggestions: z+ .array(suggestionSchema)+ .describe("Array of suggested clip moments"),+};export const suggestClipsToolDef = {name: "suggest_clips",@@ -14,87 +90,16 @@ export const suggestClipsToolDef = {"STEP 2 — Submit your clip suggestions after analyzing the transcript.\n\n" +"Before calling this: read the transcript via get_ui_state(include_transcript: true) " +"and identify the best viral moments.\n\n" ++ "Every suggestion must carry its own context. A clip that opens on an answer " ++ "whose question stayed behind the cut is rejected: widen start_second so the " ++ "question is inside the clip.\n\n" +"What it does: Stores your suggestions, assigns clip numbers (#1, #2, etc.), " +"and pushes them to the Web UI for the user to review.\n\n" +"After this: the user reviews in the UI. Then export with " +"batch_create_clips(export_selected: true) or create_clip(clip_number: N).",- inputSchema: {- type: "object" as const,- properties: {- suggestions: {- type: "array",- description: "Array of suggested clip moments",- items: {- type: "object",- properties: {- title: {- type: "string",- description: "Short catchy title for the clip",- },- start_second: {- type: "number",- description: "Start timestamp in seconds",- },- end_second: {- type: "number",- description: "End timestamp in seconds",- },- segments: {- type: "array",- description:- "Multi-cut keep-ranges within the clip. Use to cut out filler/tangents " +- "in the middle. If omitted, the full start→end range is used.",- items: {- type: "object",- properties: {- start: { type: "number" },- end: { type: "number" },- },- required: ["start", "end"],- },- },- reasoning: {- type: "string",- description: "Why this moment is viral-worthy",- },- preview_text: {- type: "string",- description: "Brief text preview of what's said",- },- content_type: {- type: "string",- description:- "Content classification: guest_story, technical_insight, market_landscape, business_strategy, hot_take",- },- score: {- type: "number",- description: "Virality score (0-20). Sum of standalone + hook + relevance + quotability (each 1-5).",- },- suggested_caption_style: {- type: "string",- enum: ["hormozi", "karaoke", "subtle", "branded"],- description: "Recommended caption style for this clip",- },- },- required: ["title", "start_second", "end_second", "reasoning"],- },- },- },- required: ["suggestions"],- },};-export interface RawSuggestion {- title: string;- start_second: number;- end_second: number;- segments?: Array<{ start: number; end: number }>;- reasoning: string;- preview_text?: string;- content_type?: string;- score?: number;- suggested_caption_style?: string;-}+export type RawSuggestion = z.infer<typeof suggestionSchema>;export interface SuggestClipsInput {suggestions: RawSuggestion[];@@ -103,13 +108,23 @@ export interface SuggestClipsInput {export async function handleSuggestClips(input: SuggestClipsInput): Promise<string> {const suggestions = input.suggestions;+ const problems: string[] = [];for (let i = 0; i < suggestions.length; i++) {const s = suggestions[i];- const rangeError = validateSuggestionRange(s.start_second, s.end_second);- if (rangeError) {- throw new Error(`Suggestion ${i + 1} ("${s.title}"): ${rangeError}`);+ const errors = [+ validateSuggestionRange(s.start_second, s.end_second),+ validateSuggestionContext(s),+ ].filter((e): e is string => e !== null);+ for (const error of errors) {+ problems.push(`Suggestion ${i + 1} ("${s.title}"): ${error}`);}}+ if (problems.length > 0) {+ throw new Error(+ `${problems.length} of ${suggestions.length} suggestions need work. ` ++ `Fix them and call suggest_clips again with the full list.\n\n${problems.join("\n")}`,+ );+ }// Validate and enrich suggestionsconst enriched = suggestions.map((s, i) => {@@ -127,6 +142,9 @@ export async function handleSuggestClips(input: SuggestClipsInput): Promise<striend_second: s.end_second,segments: segments.length > 0 ? segments : [{ start: s.start_second, end: s.end_second }],duration: Math.round(keptDuration * 10) / 10,+ payoff: s.payoff,+ standalone: s.standalone,+ context_line: s.context_line || "",reasoning: s.reasoning,preview_text: s.preview_text || "",content_type: s.content_type || "unknown",diff --git a/src/handlers/transcribe.handler.ts b/src/handlers/transcribe.handler.tsindex 8f1f57a..4ec89d2 100644--- a/src/handlers/transcribe.handler.ts+++ b/src/handlers/transcribe.handler.ts@@ -1,6 +1,6 @@import { basename } from "path";import { PythonExecutor } from "../services/python-executor.js";-import { TranscriptCache } from "../services/transcript-cache.js";+import { TranscriptCache, hasSpeakerLabels } from "../services/transcript-cache.js";import { webServerUrl } from "../config/server.js";import type { TranscriptResult } from "../models/index.js";@@ -20,8 +20,9 @@ export const transcribeToolDef = {name: "transcribe_podcast",description:"STEP 1 — Transcribe a podcast video/audio file. This is typically the first tool you call.\n\n" +- "What it does: Uses Whisper AI for word-level timestamps. Speaker detection (who said what) is off by " +- "default; pass enable_diarization=true to add speaker labels where torch/pyannote is available (whisper-py engine).\n" ++ "What it does: Uses Whisper AI for word-level timestamps, with speaker detection (who said what) on by " ++ "default. Speaker labels are what let a clip tell a question from an answer, so leave them on for any " ++ "interview. Pass enable_diarization=false to skip them and save time on a single-speaker recording.\n" +"Returns: Lightweight metadata only — duration, language, word/segment counts, speaker summary, and " +"packed_ready flag. The actual transcript body is NOT returned here (it would be 500KB+ for a typical " +"episode). Read the content via get_ui_state(include_transcript: true) which returns a compact " +@@ -56,9 +57,10 @@ export const transcribeToolDef = {enable_diarization: {type: "boolean",description:- "Set true for speaker labels (who is speaking). Works where torch/pyannote.audio is available " +- "(whisper-py engine); slower. Default: false",- default: false,+ "Speaker labels (who is speaking). On by default, and required for any clip logic that needs " ++ "to tell a question from an answer. Set false only for a single-speaker recording. " ++ "Falls back to no labels with a warning where torch/pyannote.audio is unavailable.",+ default: true,},num_speakers: {type: "number",@@ -76,11 +78,14 @@ export async function handleTranscribe(input: TranscribeInput): Promise<string>const modelSize = input.model_size ?? "base";const engine = input.engine;const language = input.language;- const enableDiarization = input.enable_diarization === true;+ const enableDiarization = input.enable_diarization !== false;const numSpeakers = input.num_speakers;- // Check cache first- const cached = await cache.get(filePath, engine);+ // Check cache first. A cached transcript without speakers cannot answer a+ // request for them, so serving it makes re-transcribing look like a no-op.+ const cachedRaw = await cache.get(filePath, engine);+ const cached =+ cachedRaw && enableDiarization && !hasSpeakerLabels(cachedRaw) ? null : cachedRaw;if (cached) {const packedEngine = cached.engine ?? engine;// Backfill packed view if this cache predates auto-packing.@@ -170,7 +175,7 @@ export const transcribeStartToolDef = {type: "string",enum: ["whisper-py", "whispercpp", "assemblyai"],},- enable_diarization: { type: "boolean", default: false },+ enable_diarization: { type: "boolean", default: true },num_speakers: { type: "number" },},required: ["file_path"],@@ -187,7 +192,7 @@ export async function handleTranscribeStart(input: TranscribeInput): Promise<strmodel_size: input.model_size ?? "base",engine: input.engine,language: input.language,- enable_diarization: input.enable_diarization === true,+ enable_diarization: input.enable_diarization !== false,num_speakers: input.num_speakers,}),});diff --git a/src/models/index.ts b/src/models/index.tsindex 8c9aa6f..2148b48 100644--- a/src/models/index.ts+++ b/src/models/index.ts@@ -99,6 +99,9 @@ export interface SuggestedClip {start_second: number;end_second: number;duration: number;+ payoff?: string;+ standalone?: string;+ context_line?: string;reasoning: string;preview_text: string;segments?: Array<{ start: number; end: number }>;diff --git a/src/server.ts b/src/server.tsindex 6c11eda..eb45117 100644--- a/src/server.ts+++ b/src/server.ts@@ -12,6 +12,7 @@ import {} from "./handlers/transcribe.handler.js";import {suggestClipsToolDef,+ suggestClipsInputShape,handleSuggestClips,} from "./handlers/suggest-clips.handler.js";import {@@ -186,7 +187,8 @@ async function getWorkflowGuidance(): Promise<string> {"1. Set the video: use set_video or transcribe_podcast with a file path\n" +"2. Get a transcript: use transcribe_podcast (auto) or import_transcript / parse_transcript\n" +"3. Read the transcript: use get_ui_state(include_transcript: true)\n" +- "4. Suggest clips: analyze the transcript yourself, then call suggest_clips with your picks\n" ++ "4. Suggest clips: analyze the transcript yourself, then call suggest_clips with your picks.\n" ++ " Each pick needs a payoff and a standalone check, and an answer needs its question.\n" +"5. Export: use batch_create_clips(export_selected: true) or create_clip(clip_number: N)\n\n" +"Note: The Web UI is not running. Start it with: npm run ui");@@ -228,7 +230,8 @@ async function getWorkflowGuidance(): Promise<string> {`NEXT: Transcript is ready (${wordCount} words). Time to find viral moments!\n` +" → Use get_ui_state(include_transcript: true) to read the full transcript\n" +" → Analyze it for the most engaging, viral-worthy moments\n" +- " → Then call suggest_clips with your suggestions (title, start_second, end_second, reasoning)",+ " → For each one: pull the question in if it is an answer, then state the payoff before the title\n" ++ " → Then call suggest_clips with your suggestions (title, start_second, end_second, payoff, standalone, reasoning)",);} else if (phase === "review" && selectedCount > 0) {lines.push(@@ -277,9 +280,11 @@ export function createServer(): McpServer {enable_diarization: z.boolean().optional()- .default(false)+ .default(true).describe(- "Set true for speaker labels (who is speaking). Works where torch is available (whisper-py engine); slower. Default: false",+ "Speaker labels (who is speaking). On by default: without them a clip cannot tell a question " ++ "from an answer. Set false only for a single-speaker recording. Falls back to no labels with " ++ "a warning where torch is unavailable.",),num_speakers: z.number()@@ -351,7 +356,7 @@ export function createServer(): McpServer {.default("base"),language: z.string().optional(),engine: z.enum(["whisper-py", "whispercpp", "assemblyai"]).optional(),- enable_diarization: z.boolean().optional().default(false),+ enable_diarization: z.boolean().optional().default(true),num_speakers: z.number().optional(),},async (input) => {@@ -390,30 +395,7 @@ export function createServer(): McpServer {server.tool(suggestClipsToolDef.name,suggestClipsToolDef.description,- {- suggestions: z- .array(- z.object({- title: z.string(),- start_second: z.number(),- end_second: z.number(),- segments: z- .array(z.object({ start: z.number(), end: z.number() }))- .optional()- .describe(- "Multi-cut keep-ranges. Omit for a single continuous clip.",- ),- reasoning: z.string(),- preview_text: z.string().optional(),- content_type: z.string().optional(),- score: z.number().optional(),- suggested_caption_style: z- .enum(["hormozi", "karaoke", "subtle", "branded"])- .optional(),- }),- )- .describe("Array of suggested clip moments"),- },+ suggestClipsInputShape,async ({ suggestions }) => {try {const result = await handleSuggestClips({ suggestions });@@ -1521,6 +1503,9 @@ export function createServer(): McpServer {title: z.string().optional(),start_second: z.number().optional(),end_second: z.number().optional(),+ payoff: z.string().optional(),+ standalone: z.string().optional(),+ context_line: z.string().optional(),reasoning: z.string().optional(),preview_text: z.string().optional(),suggested_caption_style: z@@ -1539,7 +1524,7 @@ export function createServer(): McpServer {content: [{type: "text" as const,- text: "No updates provided. Specify at least one field: title, start_second, end_second, reasoning, preview_text, or suggested_caption_style.",+ text: "No updates provided. Specify at least one field: title, start_second, end_second, payoff, standalone, context_line, reasoning, preview_text, or suggested_caption_style.",},],};@@ -2529,7 +2514,8 @@ export function createServer(): McpServer {"- Questions that hook the viewer","","For each moment, note the start/end timestamps and craft a catchy title.",- "Aim for 15-45 second clips (target 20-35s). Then call suggest_clips with your picks.",+ "Aim for 15-45 second clips (target 20-35s). If a moment is an answer, start on the question. "+ + "Then call suggest_clips with your picks, each carrying a payoff and a standalone check.","","## Step 5: Export","Call batch_create_clips(export_selected: true) to render all clips.",diff --git a/src/services/transcript-cache.test.ts b/src/services/transcript-cache.test.tsindex 2ad11b8..990983b 100644--- a/src/services/transcript-cache.test.ts+++ b/src/services/transcript-cache.test.ts@@ -8,7 +8,7 @@ const tmp = mkdtempSync(join(tmpdir(), "podcli-cache-test-"));process.env.PODCLI_HOME = tmp;process.env.PODCLI_DATA = tmp;-const { TranscriptCache } = await import("./transcript-cache.js");+const { TranscriptCache, hasSpeakerLabels } = await import("./transcript-cache.js");function makeFakeVideo(name: string, content: string): string {const p = join(tmp, name);@@ -85,3 +85,37 @@ describe("TranscriptCache", () => {expect(await cache.get(file)).toBeNull();});});+++describe("hasSpeakerLabels", () => {+ it("accepts a transcript with speaker segments", () => {+ expect(hasSpeakerLabels({ speaker_segments: [{ speaker: "S0", start: 0, end: 1 }] })).toBe(true);+ });++ it("accepts a transcript whose words carry speakers", () => {+ expect(hasSpeakerLabels({ words: [{ word: "hi", speaker: "SPEAKER_00" }] })).toBe(true);+ });++ it("rejects a count with no labels behind it", () => {+ // The packer emits "S?" on every line for this shape, so serving it back+ // to a request for speakers would make re-transcribing a no-op.+ expect(+ hasSpeakerLabels({ speakers: { num_speakers: 2 }, speaker_segments: [], words: [] }),+ ).toBe(false);+ });++ it("rejects the shape a whisper.cpp run leaves behind", () => {+ expect(+ hasSpeakerLabels({+ speakers: { num_speakers: 0 },+ speaker_segments: [],+ words: [{ word: "hi", speaker: null }],+ }),+ ).toBe(false);+ });++ it("rejects missing and empty input", () => {+ expect(hasSpeakerLabels(null)).toBe(false);+ expect(hasSpeakerLabels({})).toBe(false);+ });+});diff --git a/src/services/transcript-cache.ts b/src/services/transcript-cache.tsindex 345a06e..c963798 100644--- a/src/services/transcript-cache.ts+++ b/src/services/transcript-cache.ts@@ -9,6 +9,28 @@ import type { TranscriptResult } from "../models/index.js";* Caches transcripts by file hash so we don't re-transcribe* the same podcast when creating multiple clips.*/+/** Whether a cached transcript actually carries speaker labels.+ *+ * The cache is keyed by file hash and engine, not by diarization, so a request+ * that asks for speaker labels is otherwise answered with the speaker-less+ * transcript that is already on disk. Re-transcribing then looks like a no-op.+ */+export function hasSpeakerLabels(transcript: unknown): boolean {+ const t = transcript as {+ speaker_segments?: Array<{ speaker?: unknown }>;+ words?: Array<{ speaker?: unknown }>;+ } | null;+ if (!t) return false;+ // Read the labels, not the count. A summary can report two speakers while+ // the segments and per-word fields are both empty, and the packer then emits+ // "S?" on every line. Trusting the count would serve that cache back to a+ // request that asked for speakers.+ const labelled = (items?: Array<{ speaker?: unknown }>) =>+ items?.some((i) => typeof i.speaker === "string" && i.speaker.trim().length > 0) ??+ false;+ return labelled(t.speaker_segments) || labelled(t.words);+}+export class TranscriptCache {private cacheDir: string;diff --git a/src/ui/client/EpisodeWorkspace.jsx b/src/ui/client/EpisodeWorkspace.jsxindex 4c76b87..474f9b8 100644--- a/src/ui/client/EpisodeWorkspace.jsx+++ b/src/ui/client/EpisodeWorkspace.jsx@@ -812,7 +812,7 @@ const onKeyActivate = (fn) => (e) => {// Clip editingconst [editingClip, setEditingClip] = useState(null); // index- const [editForm, setEditForm] = useState({ title: '', start: 0, end: 0 });+ const [editForm, setEditForm] = useState({ title: '', start: 0, end: 0, payoff: '', contextLine: '' });const [editDuration, setEditDuration] = useState(0);const editDialogRef = useDialog(editingClip !== null, () => setEditingClip(null));const previewDialogRef = useDialog(!!previewFile, () => setPreviewFile(null));@@ -925,7 +925,13 @@ const onKeyActivate = (fn) => (e) => {const clip = suggestions[idx];if (!clip) return;setEditingClip(idx);- setEditForm({ title: clip.title, start: clip.start_second, end: clip.end_second });+ setEditForm({+ title: clip.title,+ start: clip.start_second,+ end: clip.end_second,+ payoff: clip.payoff || '',+ contextLine: clip.context_line || '',+ });};const clampEditTime = (v) => {@@ -939,7 +945,16 @@ const onKeyActivate = (fn) => (e) => {const reTimed = edited && (edited.start_second !== editForm.start || edited.end_second !== editForm.end);setSuggestions(prev => {const next = [...prev];- next[editingClip] = { ...next[editingClip], title: editForm.title, start_second: editForm.start, end_second: editForm.end, duration: Math.round(editForm.end - editForm.start), segments: undefined };+ next[editingClip] = {+ ...next[editingClip],+ title: editForm.title,+ start_second: editForm.start,+ end_second: editForm.end,+ payoff: editForm.payoff,+ context_line: editForm.contextLine,+ duration: Math.round(editForm.end - editForm.start),+ segments: undefined,+ };return next;});// The score was measured over the old range, so it no longer describes this clip.@@ -993,7 +1008,7 @@ const onKeyActivate = (fn) => (e) => {model_size: whisperModel,engine,assemblyai_api_key: transcriptionEngine === 'assemblyai' ? assemblyAiKey.trim() : undefined,- enable_diarization: transcriptionEngine === 'assemblyai' || (speakerStatus?.configured || false),+ enable_diarization: transcriptionEngine === 'assemblyai' || speakerStatus?.configured !== false,}) });if (data.error) {setError(data.error);@@ -1759,6 +1774,10 @@ const onKeyActivate = (fn) => (e) => {start_second: c.start_second,end_second: c.end_second,reasoning: c.reasoning || c.content_type || '',+ payoff: c.payoff || '',+ standalone: c.standalone || '',+ context_line: c.context_line || '',+ preview_text: c.preview_text || '',segments: c.segments,duration: c.duration ?? Math.round((c.end_second || 0) - (c.start_second || 0)),}));@@ -2616,6 +2635,12 @@ const onKeyActivate = (fn) => (e) => {<div className="clip-info"><div className="clip-title">{clip.title}</div>+ {clip.payoff && <div className="clip-payoff">{clip.payoff}</div>}+ {clip.context_line && (+ <div className="clip-context" title={clip.context_line}>+ <span>Setup</span> {clip.context_line}+ </div>+ )}<div className="clip-meta">{fmt(clip.start_second)} {'\u2192'} {fmt(clip.end_second)} {'\u00B7'} {clip.duration}s{energy && (@@ -2855,6 +2880,19 @@ const onKeyActivate = (fn) => (e) => {<input type="text" value={editForm.title} onChange={e => setEditForm(f => ({ ...f, title: e.target.value }))}onKeyDown={e => { if (e.key === 'Enter') saveClipEdit(); }} autoFocus /></div>+ <div className="edit-field">+ <label htmlFor="clip-edit-payoff">Payoff</label>+ <textarea id="clip-edit-payoff" rows={2} value={editForm.payoff}+ placeholder="What the viewer walks away with, in one sentence"+ onChange={e => setEditForm(f => ({ ...f, payoff: e.target.value }))} />+ </div>+ <div className="edit-field">+ <label htmlFor="clip-edit-context">Setup line</label>+ <input id="clip-edit-context" type="text" value={editForm.contextLine}+ placeholder="The question this answers, if it is not in the clip"+ onChange={e => setEditForm(f => ({ ...f, contextLine: e.target.value }))}+ onKeyDown={e => { if (e.key === 'Enter') saveClipEdit(); }} />+ </div>{videoPath && !sourceIsUrl && (<div className="edit-field"><label>Trim</label>diff --git a/src/ui/public/css/styles.css b/src/ui/public/css/styles.cssindex 8015fb7..5917cef 100644--- a/src/ui/public/css/styles.css+++ b/src/ui/public/css/styles.css@@ -843,6 +843,16 @@ select {.clip-meta { font-size: 12px; color: var(--text2); margin-top: 2px; }.clip-meta .err { color: var(--red); }.clip-meta .warn { color: var(--amber); }+.clip-payoff {+ font-size: 12px; color: var(--text2); line-height: 1.45; margin-top: 3px;+ overflow-wrap: anywhere;+ display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden;+}+.clip-context {+ font-size: 11px; color: var(--text3); line-height: 1.45; margin-top: 5px;+ padding-left: 8px; border-left: 2px solid var(--border); overflow-wrap: anywhere;+}+.clip-context span { color: var(--accent-2); font-weight: 600; margin-right: 4px; }.clip-actions { display: flex; gap: 4px; flex-shrink: 0; }.clip-status { width: 22px; height: 22px; border-radius: 50%; display: flex; align-items: center; justify-content: center; flex-shrink: 0; font-size: 11px; font-weight: 700; }.clip-status.pending { border: 1.5px dashed var(--border); }@@ -1317,8 +1327,8 @@ input[type="range"]::-webkit-slider-thumb {margin-bottom: 12px;}.clip-edit-panel .edit-field label {- font-size: 11px; color: var(--text2); font-weight: 600;- display: block; margin-bottom: 4px; text-transform: uppercase; letter-spacing: 0.5px;+ font-size: 12px; color: var(--text2); font-weight: 600;+ display: block; margin-bottom: 4px;}.clip-edit-panel .edit-field input,.clip-edit-panel .edit-field textarea {diff --git a/src/ui/web-server.ts b/src/ui/web-server.tsindex 83f1191..cb5ada1 100644--- a/src/ui/web-server.ts+++ b/src/ui/web-server.ts@@ -31,7 +31,7 @@ import { fileURLToPath } from "url";import { v4 as uuidv4 } from "uuid";import { PythonExecutor, terminateProcessTree } from "../services/python-executor.js";-import { TranscriptCache } from "../services/transcript-cache.js";+import { hasSpeakerLabels, TranscriptCache } from "../services/transcript-cache.js";import { FileManager } from "../services/file-manager.js";import { AssetManager, inferType, safeName } from "../services/asset-manager.js";import { ClipsHistory } from "../services/clips-history.js";@@ -1002,7 +1002,7 @@ app.post("/api/transcribe", async (req, res) => {engine,assemblyai_api_key,language,- enable_diarization = false,+ enable_diarization = true,num_speakers,} = req.body;@@ -1010,8 +1010,11 @@ app.post("/api/transcribe", async (req, res) => {res.status(400).json({ error: "File not found" });return;}- // Check cache first- const cached = await cache.get(file_path, engine);+ // Check cache first. A cached transcript without speakers cannot answer a+ // request for them, so serving it makes re-transcribing look like a no-op.+ const cachedRaw = await cache.get(file_path, engine);+ const cached =+ cachedRaw && enable_diarization && !hasSpeakerLabels(cachedRaw) ? null : cachedRaw;if (cached) {const jobId = uuidv4();sessionTranscripts.set(file_path, cached as unknown as ServerTranscript);@@ -1089,6 +1092,16 @@ app.post("/api/transcribe", async (req, res) => {});});+/** The session transcript, for callers that render without passing words.+ *+ * A caller that omits transcript_words used to get a silently uncaptioned+ * clip. /api/export already falls back this way; these two did not, so a+ * studio session whose client state had dropped the transcript shipped clips+ * with no captions and no error. */+function sessionWords(): unknown[] {+ return Array.isArray(uiState.transcript?.words) ? uiState.transcript.words : [];+}+/*** POST /api/create-clip — Start clip creation job*/@@ -1100,7 +1113,7 @@ app.post("/api/create-clip", async (req, res) => {caption_style = "hormozi",crop_strategy = "speaker",format = "vertical",- transcript_words = [],+ transcript_words = sessionWords(),title = "clip",clean_fillers = false,allow_ass_fallback = false,@@ -1288,7 +1301,7 @@ app.post("/api/batch-clips", async (req, res) => {const {video_path,clips,- transcript_words = [],+ transcript_words = sessionWords(),clean_fillers = false,keep_caption_overlay = false,format = "vertical",@@ -2201,11 +2214,11 @@ app.get("/api/encoder-info", async (_req, res) => {// --- Speaker Detection Status ---app.get("/api/speaker-status", (_req, res) => {if (DEMO) { res.json({ configured: true, setup_url: "", token_url: "" }); return; }- const envPath = join(process.cwd(), ".env");let token = process.env.HF_TOKEN || "";- if (!token && existsSync(envPath)) {- const envContent = readFileSync(envPath, "utf-8");- const match = envContent.match(/^HF_TOKEN=(.+)$/m);+ for (const envPath of [paths.envFile, join(process.cwd(), ".env")]) {+ if (token) break;+ if (!existsSync(envPath)) continue;+ const match = readFileSync(envPath, "utf-8").match(/^HF_TOKEN=(.+)$/m);if (match) token = match[1].trim();}res.json({@@ -3497,6 +3510,9 @@ app.post("/api/claude-suggest", async (req, res) => {duration: c.duration ?? c.end_second - c.start_second,segments: c.segments,reasoning: c.reasoning ?? "",+ payoff: c.payoff ?? "",+ standalone: c.standalone ?? "",+ context_line: c.context_line ?? "",preview_text: c.preview_text ?? "",content_type: c.content_type,score: c.score,@@ -3571,6 +3587,9 @@ app.post("/api/find-moment", async (req, res) => {duration: c.duration ?? c.end_second - c.start_second,segments: c.segments,reasoning: c.reasoning ?? "",+ payoff: c.payoff ?? "",+ standalone: c.standalone ?? "",+ context_line: c.context_line ?? "",preview_text: c.preview_text ?? "",content_type: c.content_type,score: c.score,@@ -4006,6 +4025,9 @@ app.post("/api/suggestions/modify", (req, res) => {if (typeof upd.title === "string") clip.title = upd.title;clip.start_second = nextStart;clip.end_second = nextEnd;+ if (typeof upd.payoff === "string") clip.payoff = upd.payoff;+ if (typeof upd.standalone === "string") clip.standalone = upd.standalone;+ if (typeof upd.context_line === "string") clip.context_line = upd.context_line;if (typeof upd.reasoning === "string") clip.reasoning = upd.reasoning;if (typeof upd.preview_text === "string") clip.preview_text = upd.preview_text;if (typeof upd.suggested_caption_style === "string") {diff --git a/src/utils/clip-validation.test.ts b/src/utils/clip-validation.test.tsindex e1ef765..22db136 100644--- a/src/utils/clip-validation.test.ts+++ b/src/utils/clip-validation.test.ts@@ -1,5 +1,12 @@import { describe, it, expect } from "vitest";-import { validateClipRange, validateSuggestionRange, maxClipSeconds } from "./clip-validation.js";+import {+ validateClipRange,+ validateSuggestionRange,+ validateSuggestionContext,+ findOrphanOpener,+ isSelfContained,+ maxClipSeconds,+} from "./clip-validation.js";describe("validateClipRange", () => {it("accepts a normal vertical clip", () => {@@ -52,3 +59,101 @@ describe("validateSuggestionRange", () => {expect(validateSuggestionRange(null, 10)).toMatch(/must be numbers/);});});++describe("findOrphanOpener", () => {+ it("flags replies that point back before the cut", () => {+ expect(findOrphanOpener("Yeah, and that's exactly why it failed.")).toBe("yeah");+ expect(findOrphanOpener("That was the moment we knew.")).toBe("that");+ expect(findOrphanOpener("Because nobody wanted to pay for it.")).toBe("because");+ expect(findOrphanOpener("I mean, we were broke.")).toBe("i mean");+ });++ it("lets self-contained openers through", () => {+ expect(findOrphanOpener("Most founders raise too early.")).toBeNull();+ expect(findOrphanOpener("So many founders quit at month six.")).toBeNull();+ expect(findOrphanOpener("It takes ten years to build a brand.")).toBeNull();+ });++ it("ignores leading punctuation and empty input", () => {+ expect(findOrphanOpener('"Exactly what I told them."')).toBe("exactly");+ expect(findOrphanOpener("")).toBeNull();+ expect(findOrphanOpener(undefined)).toBeNull();+ });+});++describe("validateSuggestionContext", () => {+ const good = {+ title: "Raising too early cost them pricing power",+ payoff: "You learn why an early seed round took their pricing control away.",+ standalone: "nothing",+ preview_text: "Most founders raise before they have pricing power.",+ };++ it("accepts a clip that carries its own context", () => {+ expect(validateSuggestionContext(good)).toBeNull();+ });++ it("requires a payoff", () => {+ expect(validateSuggestionContext({ ...good, payoff: "" })).toMatch(/payoff is required/);+ expect(validateSuggestionContext({ ...good, payoff: "Good story" })).toMatch(/too thin/);+ });++ it("rejects a payoff that only restates the title", () => {+ expect(+ validateSuggestionContext({ ...good, payoff: "Raising too early cost them pricing power!" }),+ ).toMatch(/restates the title/);+ });++ it("requires standalone", () => {+ expect(validateSuggestionContext({ ...good, standalone: "" })).toMatch(+ /standalone is required/,+ );+ });++ it("rejects a clip whose viewer needs prior knowledge", () => {+ const needsSetup = { ...good, standalone: "that the company had just been acquired" };+ expect(validateSuggestionContext(needsSetup)).toMatch(/Move start_second back/);+ });++ it("catches an orphaned answer even when standalone claims nothing", () => {+ const orphan = { ...good, preview_text: "Yeah, and that's exactly why we shut it down." };+ expect(validateSuggestionContext(orphan)).toMatch(/points at something said before the cut/);+ });++ it("does not let a context_line stand in for setup nothing renders", () => {+ // The renderer does not draw context_line, so accepting it here would pass+ // a clip whose viewer still has no idea what the question was.+ const needsSetup = {+ ...good,+ standalone: "that the company had just been acquired",+ context_line: "Right after the acquisition:",+ };+ expect(validateSuggestionContext(needsSetup)).toMatch(/nothing renders it yet/);++ const orphan = {+ ...good,+ preview_text: "Yeah, and that's exactly why we shut it down.",+ context_line: "Why did you kill the product?",+ };+ expect(validateSuggestionContext(orphan)).toMatch(/Move start_second back/);+ });++ it("accepts a payoff in a language that does not use the Latin alphabet", () => {+ expect(+ validateSuggestionContext({+ ...good,+ title: "რატომ დაიხურა პროდუქტი",+ payoff: "გაიგებ, რა სიგნალმა აიძულა ისინი პროდუქტი დაეხურათ.",+ }),+ ).toBeNull();+ expect(+ validateSuggestionContext({ ...good, title: "なぜ畳んだのか", payoff: "撤退を決めた合図が分かります。" }),+ ).toBeNull();+ });++ it("isSelfContained treats the empty and 'none' forms as no context needed", () => {+ expect(isSelfContained("nothing")).toBe(true);+ expect(isSelfContained("None.")).toBe(true);+ expect(isSelfContained("who the guest is")).toBe(false);+ });+});diff --git a/src/utils/clip-validation.ts b/src/utils/clip-validation.tsindex 82e0810..6c8e373 100644--- a/src/utils/clip-validation.ts+++ b/src/utils/clip-validation.ts@@ -45,3 +45,135 @@ export function validateSuggestionRange(start: unknown, end: unknown): string |}return null;}++// ---------------------------------------------------------------------------+// Context checks: does this clip make sense to someone who never heard the+// episode? A moment can be perfectly cut and still be unwatchable because it+// opens on an answer whose question stayed behind the cut.+// ---------------------------------------------------------------------------++const MIN_PAYOFF_WORDS = 5;+// Japanese and Chinese do not space-delimit, so every payoff in them counts as+// one "word" however long it runs. A character floor stands in there.+const MIN_PAYOFF_CHARS = 12;++/** Values that mean "the viewer needs to know nothing going in". */+const SELF_CONTAINED = new Set([+ "",+ "-",+ "n/a",+ "na",+ "none",+ "no context",+ "no context needed",+ "nothing",+ "nothing needed",+]);++/**+ * First words that point backwards at something said before the cut. This is a+ * backstop, not the primary gate: the model declares `standalone` itself, and+ * this list only catches the case where it declared "nothing" but cut into the+ * middle of an exchange anyway.+ */+const ORPHAN_OPENERS = new Set([+ "absolutely", "also", "and", "anyway", "because", "but", "cause", "exactly",+ "he", "her", "his", "it", "no", "nope", "ok", "okay", "plus", "right", "she",+ "so", "sure", "that", "their", "them", "they", "those", "totally", "well",+ "which", "yeah", "yep", "yes",+]);++/**+ * Two-word starts that read as self-contained despite a flagged first word,+ * e.g. "So many founders quit" or "It takes ten years".+ */+const SELF_CONTAINED_STARTS = new Set([+ "it costs", "it takes", "it turns", "no idea", "no matter", "no one",+ "so few", "so long", "so many", "so much",+]);++/** Lowercase, punctuation-stripped, single-spaced. Unicode-aware: a Georgian+ * or Japanese payoff has to survive this, not normalize down to nothing. */+function normalize(text: string): string {+ return text+ .toLowerCase()+ .replace(/[^\p{L}\p{N}'\s]/gu, " ")+ .replace(/\s+/gu, " ")+ .trim();+}++function wordCount(text: string): number {+ const n = normalize(text);+ return n ? n.split(" ").length : 0;+}++function isTooThin(payoff: string): boolean {+ const normalized = normalize(payoff);+ return normalized.includes(" ")+ ? wordCount(payoff) < MIN_PAYOFF_WORDS+ : normalized.length < MIN_PAYOFF_CHARS;+}++export function isSelfContained(standalone: string): boolean {+ return SELF_CONTAINED.has(normalize(standalone));+}++/** Returns the backward-pointing opener, or null when the clip starts clean. */+export function findOrphanOpener(previewText: unknown): string | null {+ if (typeof previewText !== "string") return null;+ const words = normalize(previewText).split(" ").filter(Boolean);+ if (!words.length) return null;+ if (SELF_CONTAINED_STARTS.has(words.slice(0, 2).join(" "))) return null;+ // "I mean" is only a stall when the sentence leads with it.+ if (words[0] === "i" && words[1] === "mean") return "i mean";+ return ORPHAN_OPENERS.has(words[0]) ? words[0] : null;+}++export interface SuggestionContext {+ title?: unknown;+ payoff?: unknown;+ standalone?: unknown;+ context_line?: unknown;+ preview_text?: unknown;+}++/** Returns an error message, or null when the clip carries its own context. */+export function validateSuggestionContext(s: SuggestionContext): string | null {+ const payoff = typeof s.payoff === "string" ? s.payoff.trim() : "";+ if (!payoff) {+ return "payoff is required: one sentence, second person, on what the viewer walks away with.";+ }+ if (isTooThin(payoff)) {+ return `payoff is too thin ("${payoff}"). Write a full sentence on what the viewer walks away with.`;+ }+ if (typeof s.title === "string" && normalize(s.title) === normalize(payoff)) {+ return "payoff just restates the title. Say what the viewer gets, not what the clip is called.";+ }++ const standalone = typeof s.standalone === "string" ? s.standalone.trim() : "";+ if (!standalone) {+ return 'standalone is required: what the viewer must already know to follow this clip, or "nothing".';+ }++ // context_line is not consulted here on purpose. Nothing burns it into the+ // video yet, so treating it as coverage would pass clips whose viewer still+ // has no setup, which is the exact failure these checks exist to catch. It+ // stays on the suggestion as editor metadata until the renderer draws it.+ if (!isSelfContained(standalone)) {+ return (+ `standalone says the viewer needs to know "${standalone}". Move start_second back ` ++ "so the clip itself contains that setup on camera. A context_line does not cover it: " ++ "nothing renders it yet."+ );+ }++ const orphan = findOrphanOpener(s.preview_text);+ if (orphan) {+ return (+ `preview_text opens on "${orphan}", which points at something said before the cut. ` ++ "Move start_second back so the question is inside the clip."+ );+ }++ return null;+}diff --git a/tests/test_crop_path_golden.py b/tests/test_crop_path_golden.pyindex 7472f2b..2897fb5 100644--- a/tests/test_crop_path_golden.py+++ b/tests/test_crop_path_golden.py@@ -260,3 +260,97 @@ class DumpCropPathTests(unittest.TestCase):if __name__ == "__main__":unittest.main()+++class UseFaceMapSpeakerGuardTests(unittest.TestCase):+ """A face map without speaker labels must not pick a face by list order.++ Two clusters and no diarization is the state whisper.cpp leaves behind. The+ old code read that as "single speaker" and pinned the whole clip to+ clusters[0], so the camera watched one person while the other talked.+ """++ def _face_map(self, **over):+ fm = {+ "clusters": [+ {"center_x": 1006, "crop_x": 399, "count": 262},+ {"center_x": 2964, "crop_x": 2357, "count": 236},+ ],+ "speaker_mappings": {},+ "dominant_speaker": None,+ "is_split_screen": True,+ "video_width": 3840,+ }+ fm.update(over)+ return fm++ def _call(self, face_map, words):+ return vp._use_face_map(+ face_map=face_map,+ transcript_words=words,+ clip_start=0.0,+ width=3840,+ height=2160,+ target_ratio=1080 / 1920,+ )++ def test_two_clusters_without_speakers_declines(self):+ words = [{"word": "hi", "start": 0.0, "end": 0.4, "speaker": None}]+ self.assertIsNone(self._call(self._face_map(), words))++ def test_no_words_at_all_declines(self):+ self.assertIsNone(self._call(self._face_map(), []))++ def test_one_cluster_without_speakers_still_crops(self):+ fm = self._face_map(+ clusters=[{"center_x": 1006, "crop_x": 399, "count": 262}],+ is_split_screen=False,+ )+ words = [{"word": "hi", "start": 0.0, "end": 0.4, "speaker": None}]+ self.assertIsNotNone(self._call(fm, words))++ def test_labelled_but_unmapped_speaker_declines(self):+ # Exactly the state a diarized transcript is in before the face map is+ # rebuilt: words carry speakers, speaker_mappings is still empty.+ words = [{"word": "hi", "start": 0.0, "end": 0.4, "speaker": "SPEAKER_01"}]+ self.assertIsNone(self._call(self._face_map(), words))++ def test_partially_mapped_speakers_decline(self):+ fm = self._face_map(speaker_mappings={"SPEAKER_00": 0})+ words = [+ {"word": "hi", "start": 0.0, "end": 0.4, "speaker": "SPEAKER_00"},+ {"word": "yes", "start": 1.0, "end": 1.4, "speaker": "SPEAKER_01"},+ ]+ self.assertIsNone(self._call(fm, words))++ def test_out_of_range_cluster_index_declines(self):+ fm = self._face_map(speaker_mappings={"SPEAKER_01": 7})+ words = [{"word": "hi", "start": 0.0, "end": 0.4, "speaker": "SPEAKER_01"}]+ self.assertIsNone(self._call(fm, words))++ def test_single_labelled_speaker_uses_their_cluster(self):+ fm = self._face_map(speaker_mappings={"SPEAKER_01": 1})+ words = [{"word": "hi", "start": 0.0, "end": 0.4, "speaker": "SPEAKER_01"}]+ self.assertEqual(self._call(fm, words), "2357")+++class SaneSpeakerMappingsTests(unittest.TestCase):+ """A stale face map must not hand a bad cluster index to the tracker."""++ def _fm(self, mappings):+ return {"clusters": [{"center_x": 100}, {"center_x": 900}], "speaker_mappings": mappings}++ def test_drops_out_of_range_and_negative_indices(self):+ out = vp._sane_speaker_mappings(self._fm({"A": 0, "B": 7, "C": -1}))+ self.assertEqual(out["speaker_mappings"], {"A": 0})++ def test_drops_booleans_which_python_counts_as_ints(self):+ out = vp._sane_speaker_mappings(self._fm({"A": True, "B": 1}))+ self.assertEqual(out["speaker_mappings"], {"B": 1})++ def test_returns_the_same_object_when_nothing_is_wrong(self):+ fm = self._fm({"A": 0, "B": 1})+ self.assertIs(vp._sane_speaker_mappings(fm), fm)++ def test_passes_none_through(self):+ self.assertIsNone(vp._sane_speaker_mappings(None))diff --git a/tests/test_transcript_packer.py b/tests/test_transcript_packer.pynew file mode 100644index 0000000..bfb5ce6--- /dev/null+++ b/tests/test_transcript_packer.py@@ -0,0 +1,130 @@+"""Tests for backend.services.transcript_packer phrase boundaries.++The packed markdown is the only view the clip selector reads, so a phrase that+swallows a question plus the answer around it is the difference between a clip+that makes sense and one that opens on a reply to nothing.+"""++import os+import sys+import unittest++ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))+BACKEND_ROOT = os.path.join(ROOT, "backend")+if BACKEND_ROOT not in sys.path:+ sys.path.insert(0, BACKEND_ROOT)++from services.transcript_packer import pack_transcript+++def _words(text: str, start: float = 0.0, speaker=None, step: float = 0.3):+ """One word per token, back to back so no silence gap ever splits."""+ out = []+ t = start+ for token in text.split(" "):+ out.append({"word": token, "start": round(t, 3), "end": round(t + step, 3), "speaker": speaker})+ t += step+ return out+++def _transcript(words, speaker_segments=None, num_speakers=0):+ speakers = {"num_speakers": num_speakers, "speakers": {}}+ if num_speakers:+ speakers["speakers"] = {+ f"SPEAKER_0{i}": {"label": f"Speaker {i}", "total_time": 10.0}+ for i in range(num_speakers)+ }+ return {+ "words": words,+ "duration": words[-1]["end"] if words else 0.0,+ "language": "en",+ "speakers": speakers,+ "speaker_segments": speaker_segments or [],+ }+++def _phrase_lines(md: str):+ return [ln for ln in md.split("\n") if ln.startswith("[") and "]" in ln and " S" in ln]+++class NoSpeakerLabelsTests(unittest.TestCase):+ """With diarization off every line is S?, so the speaker split never fires."""++ def setUp(self):+ text = (+ "But I went to Peru and that is where we stayed. "+ "Why did you want to go there? "+ "Well I am a big nature person and I wanted to see it."+ )+ self.md = pack_transcript(_transcript(_words(text)), "test.mp4")+ self.lines = _phrase_lines(self.md)++ def test_question_becomes_its_own_line(self):+ questions = [ln for ln in self.lines if ln.rstrip().endswith("?")]+ self.assertEqual(len(questions), 1)+ self.assertIn("Why did you want to go there?", questions[0])+ # and it carries its own timestamps, so a clip can start on it+ self.assertNotIn("stayed", questions[0])+ self.assertNotIn("Well I am", questions[0])++ def test_full_stops_also_split(self):+ self.assertGreaterEqual(len(self.lines), 3)++ def test_header_warns_the_reader_not_to_guess_turns(self):+ self.assertIn("No speaker labels", self.md)+ self.assertIn("do not guess", self.md)++ def test_short_fragment_before_a_stop_does_not_split(self):+ # "No." is under the abbreviation floor, so it stays glued.+ md = pack_transcript(_transcript(_words("No. that never happened to us at all")), "t.mp4")+ self.assertEqual(len(_phrase_lines(md)), 1)+++class ClaimedButUnlabelledTests(unittest.TestCase):+ """A summary can claim speakers the phrases do not actually carry."""++ def test_warns_when_the_count_is_two_but_every_line_is_unlabelled(self):+ md = pack_transcript(+ _transcript(_words("We shipped it in a week and it broke by Friday."), num_speakers=2),+ "test.mp4",+ )+ self.assertIn("No speaker labels", md)+ self.assertTrue(all(" S? " in ln for ln in _phrase_lines(md)))+++class WithSpeakerLabelsTests(unittest.TestCase):+ """Diarized transcripts keep speaker splits and gain the sentence split."""++ def setUp(self):+ words = _words(+ "I stayed deep in the Amazon jungle. It was great.", start=0.0, speaker="SPEAKER_00"+ )+ words += _words("Why did you go there?", start=20.0, speaker="SPEAKER_01")+ segments = [+ {"speaker": "SPEAKER_00", "start": 0.0, "end": 10.0},+ {"speaker": "SPEAKER_01", "start": 20.0, "end": 26.0},+ ]+ self.md = pack_transcript(_transcript(words, segments, num_speakers=2), "test.mp4")+ self.lines = _phrase_lines(self.md)++ def test_no_warning_when_speakers_are_known(self):+ self.assertNotIn("No speaker labels", self.md)++ def test_speakers_are_distinguished(self):+ speakers = {ln.split("] ")[1].split(" ")[0] for ln in self.lines}+ self.assertEqual(len(speakers), 2)+ self.assertNotIn("S?", speakers)++ def test_question_still_splits(self):+ self.assertTrue(any(ln.rstrip().endswith("?") for ln in self.lines))++ def test_full_stops_split_diarized_lines_too(self):+ # Diarization drifts a word or two at a turn, so a phrase that runs past+ # a sentence end leaves the selector nowhere clean to start a clip.+ first = [ln for ln in self.lines if "Amazon" in ln][0]+ self.assertNotIn("It was great.", first)+ self.assertTrue(any("It was great." in ln for ln in self.lines))+++if __name__ == "__main__":+ unittest.main()