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
Add `podcli ui` + backend hardening and audit fixes (#30)
Nika Siradze2396637ebf3b
diff --git a/CLAUDE.md b/CLAUDE.mdindex 33c5c5a..fa3ac3d 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -21,7 +21,7 @@ Both share the same knowledge base at `.podcli/knowledge/`.| `/generate-descriptions` | Copywriter | Creates descriptions + hashtags + SEO keywords || `/plan-thumbnails` | Art Director | Plans thumbnail text + layout briefs for both formats || `/review-content` | Brand Guardian | Reviews output against brand voice, quality gates, banned words |-| `/prep-episode` | Producer | Full pipeline: transcript → publish-ready package |+| `/produce-shorts` | Producer | Full pipeline: transcript → publish-ready package || `/publish-checklist` | Launch Manager | Pre/post-publish optimization checklist || `/retro-episode` | Analyst | Episode performance review + learnings |@@ -50,7 +50,7 @@ Both share the same knowledge base at `.podcli/knowledge/`.→ /plan-thumbnails → /review-content → /publish-checklist```-Or run everything at once: `/prep-episode`+Or run everything at once: `/produce-shorts`After publishing: `/retro-episode`@@ -99,7 +99,7 @@ When input is provided without a specific command:- **Asks for titles** → Run `/generate-titles`- **Asks for thumbnails** → Run `/plan-thumbnails`- **Asks for descriptions** → Run `/generate-descriptions`-- **Says "process episode"** → Run `/prep-episode`+- **Says "process episode"** → Run `/produce-shorts`- **Asks to review content** → Run `/review-content`---diff --git a/README.md b/README.mdindex 124efa9..7b21d0a 100644--- a/README.md+++ b/README.md@@ -84,7 +84,7 @@ Clips come out as **upload-ready Shorts**: 1080x1920, 9:16 vertical, with burnedOpen the project in **Claude Code** and run:```-/prep-episode+/produce-shorts```This runs the [PodStack](https://github.com/nmbrthirteen/podstack) pipeline — a gstack-style workflow that gives you:@@ -135,7 +135,7 @@ Both halves share the same **knowledge base** (`.podcli/knowledge/`) — your sh- **`/generate-descriptions`** — descriptions + hashtags + SEO keywords- **`/plan-thumbnails`** — thumbnail text + designer briefs for both formats- **`/review-content`** — paranoid brand check (banned words, voice, title rules)-- **`/prep-episode`** — full pipeline: transcript → publish-ready package+- **`/produce-shorts`** — full pipeline: transcript → publish-ready package- **`/publish-checklist`** — pre/post-publish optimization- **`/retro-episode`** — performance analysis after publishing@@ -240,7 +240,7 @@ Open the project in Claude Code, then use slash commands:```bash# Full pipeline — transcript to publish-ready package-/prep-episode+/produce-shorts# Individual steps/process-transcript # extract moments from a transcript@@ -356,7 +356,7 @@ podcli/│ ├── generate-descriptions.md│ ├── plan-thumbnails.md│ ├── review-content.md-│ ├── prep-episode.md+│ ├── produce-shorts.md│ ├── publish-checklist.md│ └── retro-episode.md│diff --git a/backend/cli.py b/backend/cli.pyindex bb93103..2ec78b1 100644--- a/backend/cli.py+++ b/backend/cli.py@@ -261,11 +261,18 @@ def _ensure_ssl_certs():except Exception:pass- # Method 4: Last resort — disable SSL verification for this session- # This is safe because we're only downloading Whisper models from known URLs- ssl._create_default_https_context = ssl._create_unverified_context- os.environ["PYTHONHTTPSVERIFY"] = "0"- print(" ⚠ SSL verification disabled for this session (model downloads only)")+ # Method 4: disable SSL verification only on explicit opt-in — silently+ # turning off TLS verification is a downgrade risk.+ if os.environ.get("PODCLI_INSECURE_SSL", "").strip().lower() in ("1", "true", "yes", "on"):+ ssl._create_default_https_context = ssl._create_unverified_context+ os.environ["PYTHONHTTPSVERIFY"] = "0"+ print(" ⚠ SSL verification DISABLED (PODCLI_INSECURE_SSL set) — model downloads only")+ else:+ print(+ " ✗ Could not configure SSL certificates. Install certifi "+ "(pip install certifi) or, to download models without verification, "+ "re-run with PODCLI_INSECURE_SSL=1."+ )def _sanitize_path_component(value: str) -> str:@@ -3299,6 +3306,9 @@ def main():studio.add_argument("--save-brand", action="store_true",help="Save handle/platforms/outro-title/accent/bg as the default brand and exit")+ # ── ui (Studio web dashboard) ──+ sub.add_parser("ui", aliases=["webui"], help="Open the Studio web UI (http://localhost:3847)")+# ── presets ──pre = sub.add_parser("presets", help="Manage presets")pre_sub = pre.add_subparsers(dest="presets_action")@@ -3562,10 +3572,66 @@ def main():cmd_info(args)elif args.command == "init-thumbnail":cmd_init_thumbnail(args)+ elif args.command in ("ui", "webui"):+ launch_webui()else:interactive_menu()+def launch_webui():+ """Launch the Studio web UI server (http://localhost:3847)."""+ import subprocess as sp+ import shutil as _shutil++ accent = "\033[38;2;212;135;74m"+ gray = "\033[38;5;245m"+ yellow = "\033[38;2;250;204;21m"+ dim = "\033[2m"+ reset = "\033[0m"++ backend_dir = os.path.dirname(os.path.abspath(__file__))+ port = os.environ.get("PORT", "3847")+ node = os.environ.get("PODCLI_NODE") or _shutil.which("node")+ studio = os.environ.get("PODCLI_STUDIO") or os.path.join(backend_dir, "..", "studio")+ server = os.path.join(studio, "web-server.mjs")+ repo = os.path.join(backend_dir, "..")++ if node and os.path.exists(server):+ # Bundled studio: hermetic Node serves it, rendering delegated to this+ # same Python backend + ffmpeg via the env below.+ env = {+ **os.environ,+ "PORT": str(port),+ "PODCLI_BACKEND": backend_dir,+ "PYTHON_PATH": sys.executable,+ "PODCLI_HOME": paths["home"],+ # data_dir is the cache's parent — output is now decoupled+ # (clips render to the working dir), so don't derive it from output.+ "PODCLI_DATA": os.path.dirname(paths["cache"]),+ "PODCLI_OUTPUT": paths["output"],+ "FFMPEG_PATH": os.environ.get("PODCLI_FFMPEG", "ffmpeg"),+ "FFPROBE_PATH": os.environ.get("PODCLI_FFPROBE", "ffprobe"),+ }+ print(f"\n {gray}Studio:{reset} {accent}http://localhost:{port}{reset} {dim}(Ctrl+C to stop){reset}\n")+ sp.run([node, server], env=env)+ elif os.path.exists(os.path.join(repo, "package.json")) and _shutil.which("npm"):+ # Source checkout (dev): build + serve via npm.+ _npm_shell = sys.platform == "win32"+ spa = os.path.join(repo, "dist", "ui", "public", "index.html")+ ok = True+ if not os.path.exists(spa):+ print(f"\n {gray}Building the studio (first run)…{reset}\n")+ ok = sp.run(["npm", "run", "build"], cwd=repo, shell=_npm_shell).returncode == 0+ if not ok:+ print(f"\n {yellow}Build failed — run 'npm install' then try again.{reset}\n")+ if ok:+ print(f"\n {gray}Studio:{reset} {accent}http://localhost:{port}{reset} {dim}(Ctrl+C to stop){reset}\n")+ sp.run(["npm", "run", "ui:prod"], cwd=repo, shell=_npm_shell)+ else:+ print(f"\n {yellow}Studio isn't provisioned yet.{reset}")+ print(f" {dim}Run{reset} {accent}podcli setup{reset} {dim}to fetch the bundled studio + Node.{reset}\n")++def interactive_menu():"""Interactive startup — show banner then let user pick what to do."""@@ -3631,48 +3697,7 @@ def interactive_menu():_interactive_process()returnelif choice == "webui":- import subprocess as sp- import shutil as _shutil- backend_dir = os.path.dirname(os.path.abspath(__file__))- port = os.environ.get("PORT", "3847")- node = os.environ.get("PODCLI_NODE") or _shutil.which("node")- studio = os.environ.get("PODCLI_STUDIO") or os.path.join(backend_dir, "..", "studio")- server = os.path.join(studio, "web-server.mjs")- repo = os.path.join(backend_dir, "..")- if node and os.path.exists(server):- # Bundled studio: hermetic Node serves it, rendering delegated to- # this same Python backend + ffmpeg via the env below.- env = {- **os.environ,- "PORT": str(port),- "PODCLI_BACKEND": backend_dir,- "PYTHON_PATH": sys.executable,- "PODCLI_HOME": paths["home"],- # data_dir is the cache's parent — output is now decoupled- # (clips render to the working dir), so don't derive it from output.- "PODCLI_DATA": os.path.dirname(paths["cache"]),- "PODCLI_OUTPUT": paths["output"],- "FFMPEG_PATH": os.environ.get("PODCLI_FFMPEG", "ffmpeg"),- "FFPROBE_PATH": os.environ.get("PODCLI_FFPROBE", "ffprobe"),- }- print(f"\n {gray}Studio:{reset} {accent}http://localhost:{port}{reset} {dim}(Ctrl+C to stop){reset}\n")- sp.run([node, server], env=env)- elif os.path.exists(os.path.join(repo, "package.json")) and _shutil.which("npm"):- # Source checkout (dev): build + serve via npm.- _npm_shell = sys.platform == "win32"- spa = os.path.join(repo, "dist", "ui", "public", "index.html")- ok = True- if not os.path.exists(spa):- print(f"\n {gray}Building the studio (first run)…{reset}\n")- ok = sp.run(["npm", "run", "build"], cwd=repo, shell=_npm_shell).returncode == 0- if not ok:- print(f"\n {yellow}Build failed — run 'npm install' then try again.{reset}\n")- if ok:- print(f"\n {gray}Studio:{reset} {accent}http://localhost:{port}{reset} {dim}(Ctrl+C to stop){reset}\n")- sp.run(["npm", "run", "ui:prod"], cwd=repo, shell=_npm_shell)- else:- print(f"\n {yellow}Studio isn't provisioned yet.{reset}")- print(f" {dim}Run{reset} {accent}podcli setup{reset} {dim}to fetch the bundled studio + Node.{reset}\n")+ launch_webui()elif choice == "assets":_interactive_assets()elif choice == "presets":diff --git a/backend/services/caption_renderer.py b/backend/services/caption_renderer.pyindex 940ed5a..1342971 100644--- a/backend/services/caption_renderer.py+++ b/backend/services/caption_renderer.py@@ -132,6 +132,21 @@ def render_captions(return output_path+CAPTION_GAP_FILL_MAX = 0.4 # seconds+++def _hold_through_gap(chunks: list[list[dict]], idx: int, end: float, offset: float) -> float:+ """Extend a chunk's end toward the next chunk's start so a pause on a chunk+ boundary doesn't blank the screen. Capped, and never overlaps the next chunk."""+ for j in range(idx + 1, len(chunks)):+ if chunks[j]:+ next_start = max(0, chunks[j][0]["start"] - offset)+ if next_start > end:+ return min(next_start, end + CAPTION_GAP_FILL_MAX)+ return end+ return end++def _render_hormozi(words: list[dict], style: dict, offset: float) -> str:"""Hormozi style: Show 2-3 words at a time, smooth karaoke-fill highlight.@@ -147,12 +162,12 @@ def _render_hormozi(words: list[dict], style: dict, offset: float) -> str:chunk = words[i : i + chunk_size]chunks.append(chunk)- for chunk in chunks:+ for idx, chunk in enumerate(chunks):if not chunk:continuechunk_start = max(0, chunk[0]["start"] - offset)- chunk_end = max(0, chunk[-1]["end"] - offset)+ chunk_end = _hold_through_gap(chunks, idx, max(0, chunk[-1]["end"] - offset), offset)# Build \kf karaoke-fill parts: each word fills progressivelyparts = []@@ -189,12 +204,12 @@ def _render_karaoke(words: list[dict], style: dict, offset: float) -> str:for i in range(0, len(words), sentence_size):sentences.append(words[i : i + sentence_size])- for sentence in sentences:+ for idx, sentence in enumerate(sentences):if not sentence:continuesent_start = max(0, sentence[0]["start"] - offset)- sent_end = max(0, sentence[-1]["end"] - offset)+ sent_end = _hold_through_gap(sentences, idx, max(0, sentence[-1]["end"] - offset), offset)parts = []for w in sentence:@@ -227,12 +242,12 @@ def _render_subtle(words: list[dict], style: dict, offset: float) -> str:for i in range(0, len(words), line_size):lines.append(words[i : i + line_size])- for line_words in lines:+ for idx, line_words in enumerate(lines):if not line_words:continueline_start = max(0, line_words[0]["start"] - offset)- line_end = max(0, line_words[-1]["end"] - offset)+ line_end = _hold_through_gap(lines, idx, max(0, line_words[-1]["end"] - offset), offset)line_text = " ".join(w["word"] for w in line_words)@@ -493,12 +508,12 @@ def _render_branded(words: list[dict], style: dict, offset: float) -> str:chunk = words[i : i + chunk_size]chunks.append(chunk)- for chunk in chunks:+ for chunk_idx, chunk in enumerate(chunks):if not chunk:continuechunk_start = max(0, chunk[0]["start"] - offset)- chunk_end = max(0, chunk[-1]["end"] - offset)+ chunk_end = _hold_through_gap(chunks, chunk_idx, max(0, chunk[-1]["end"] - offset), offset)# Normalize casingnormalized = []diff --git a/backend/services/claude_suggest.py b/backend/services/claude_suggest.pyindex e180477..e400efc 100644--- a/backend/services/claude_suggest.py+++ b/backend/services/claude_suggest.py@@ -360,19 +360,37 @@ def _should_bucket_initial_selection(segments: list[dict]) -> bool:def _dedupe_clips_by_range(clips: list[dict]) -> list[dict]:- """Drop duplicate clip suggestions that share the same rounded range."""- deduped = []- seen_ranges = set()- for clip in sorted(clips, key=lambda c: c.get("start_second", 0)):- key = (- round(float(clip.get("start_second", 0)), 1),- round(float(clip.get("end_second", 0)), 1),- )- if key in seen_ranges:- continue- seen_ranges.add(key)- deduped.append(clip)- return deduped+ """Collapse overlapping clip suggestions (>50% of the shorter clip), keeping+ the higher-scored one, sorted by start time. Exact-range matching would miss+ near-duplicates like 100.0-140.0 vs 102.5-141.5."""+ kept: list[dict] = []+ # Highest-scored first so the survivor of an overlap is the better clip.+ for clip in sorted(clips, key=lambda c: c.get("score", 0), reverse=True):+ start = float(clip.get("start_second", 0))+ end = float(clip.get("end_second", 0))+ dur = max(0.0, end - start)+ duplicate = False+ for k in kept:+ k_start = float(k.get("start_second", 0))+ k_end = float(k.get("end_second", 0))+ overlap = max(0.0, min(end, k_end) - max(start, k_start))+ shorter = min(dur, max(0.0, k_end - k_start)) or 1.0+ if overlap / shorter > 0.5:+ duplicate = True+ break+ if not duplicate:+ kept.append(clip)+ return sorted(kept, key=lambda c: c.get("start_second", 0))+++def _select_top_by_score(clips: list[dict], top_n: int) -> list[dict]:+ """Keep the highest-scored `top_n` clips, then order them by start time.+ Ranking by score must come before truncation — otherwise the earliest clips+ ship, not the best ones."""+ if len(clips) <= top_n:+ return sorted(clips, key=lambda c: c.get("start_second", 0))+ ranked = sorted(clips, key=lambda c: c.get("score", 0), reverse=True)[:top_n]+ return sorted(ranked, key=lambda c: c.get("start_second", 0))def find_moments_from_text(@@ -695,12 +713,12 @@ def suggest_with_claude("_ai_engine": engine,})- normalized.sort(key=lambda x: x["start_second"])+ selected = _select_top_by_score(normalized, top_n)- if normalized:+ if selected:if progress_callback:- progress_callback(100, f"{label} suggested {len(normalized)} clips")- return normalized+ progress_callback(100, f"{label} suggested {len(selected)} clips")+ return selectedif progress_callback:progress_callback(0, f"{label} returned no usable clips")@@ -798,7 +816,7 @@ def suggest_initial_with_claude(deduped = _dedupe_clips_by_range(aggregated)if len(deduped) >= top_n:- return deduped[:top_n]+ return _select_top_by_score(deduped, top_n)fallback_clips = suggest_with_claude(segments=segments,@@ -816,7 +834,7 @@ def suggest_initial_with_claude(if fallback_clips:deduped = _dedupe_clips_by_range(deduped + fallback_clips)- return deduped[:top_n] if deduped else None+ return _select_top_by_score(deduped, top_n) if deduped else Nonedef _bucket_coverage_seconds(existing_clips: list[dict], start: float, end: float) -> float:@@ -959,13 +977,5 @@ def suggest_more_with_claude(if fallback_clips:aggregated.extend(fallback_clips)- deduped = []- seen_ranges = set()- for clip in sorted(aggregated, key=lambda c: c.get("start_second", 0)):- key = (round(float(clip.get("start_second", 0)), 1), round(float(clip.get("end_second", 0)), 1))- if key in seen_ranges:- continue- seen_ranges.add(key)- deduped.append(clip)-- return deduped[:top_n] if deduped else None+ deduped = _dedupe_clips_by_range(aggregated)+ return _select_top_by_score(deduped, top_n) if deduped else Nonediff --git a/backend/services/face_analysis.py b/backend/services/face_analysis.pyindex 17fe762..f9501b5 100644--- a/backend/services/face_analysis.py+++ b/backend/services/face_analysis.py@@ -101,12 +101,27 @@ def analyze_faces(small = cv2.resize(roi, (16, 16))return cv2.cvtColor(small, cv2.COLOR_BGR2GRAY).astype(np.int16)- for i in range(sample_count):- t = i * duration / sample_count- cap.set(cv2.CAP_PROP_POS_MSEC, t * 1000)- ret, frame = cap.read()+ # Some containers under-report CAP_PROP_FRAME_COUNT, which would confine+ # sampling to the front of the video; fall back to duration*fps.+ reported_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT) or 0)+ est_frames = int(duration * fps) if duration and fps else 0+ total_frames = max(reported_frames, est_frames, 1)+ # grab() advances cheaply, retrieve() decodes only the sampled frames — far+ # cheaper than a cap.set() seek (keyframe re-decode) per sample.+ step = max(1, total_frames // sample_count)+ frame_idx = -1+ sampled = 0+ while sampled < sample_count:+ if not cap.grab():+ break+ frame_idx += 1+ if frame_idx % step != 0:+ continue+ ret, frame = cap.retrieve()if not ret:continue+ pos_ms = cap.get(cv2.CAP_PROP_POS_MSEC)+ t = pos_ms / 1000.0 if pos_ms and pos_ms > 0 else frame_idx / fpsfaces = detect_faces(detector, frame, width, height)current_mouth_gray: dict[int, "np.ndarray"] = {}@@ -139,9 +154,10 @@ def analyze_faces(prev_mouth_gray = current_mouth_grayfaces_per_frame.append(frame_faces)- if progress_callback and i % 20 == 0:- pct = 10 + int(60 * i / sample_count)- progress_callback(pct, f"Analyzing faces... {i}/{sample_count}")+ if progress_callback and sampled % 20 == 0:+ pct = 10 + int(60 * sampled / sample_count)+ progress_callback(pct, f"Analyzing faces... {sampled}/{sample_count}")+ sampled += 1cap.release()diff --git a/backend/services/transcription.py b/backend/services/transcription.pyindex 9ca581e..41cb9d0 100644--- a/backend/services/transcription.py+++ b/backend/services/transcription.py@@ -75,10 +75,120 @@ def _transcribe_with_whispercpp(file_path, model_size, language, progress_callbavad_model=os.environ.get("PODCLI_WHISPERCPP_VAD_MODEL") or None,)if progress_callback:- progress_callback(100, "Transcription complete")+ progress_callback(50, "Transcription complete")return result+def _attach_speakers_and_faces(+ file_path,+ base,+ enable_diarization,+ num_speakers,+ progress_callback,+):+ """Merge speaker diarization + face analysis into a transcribed result.+ Shared by both engines; face analysis (OpenCV) runs even when diarization+ is unavailable."""+ segments = base.get("segments") or []+ words = base.get("words") or []+ duration = base.get("duration") or (segments[-1]["end"] if segments else 0.0)++ speaker_segments = []+ speaker_summary = {"num_speakers": 0, "speakers": {}}+ diarization_warning = None++ if enable_diarization:+ try:+ from services.speaker_detection import (+ extract_audio_wav,+ run_diarization,+ assign_speakers_to_segments,+ assign_speakers_to_words,+ create_speaker_summary,+ )++ if progress_callback:+ progress_callback(55, "Extracting audio for speaker detection...")++ with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as tmp:+ wav_path = tmp.name++ try:+ extract_audio_wav(file_path, wav_path)++ if progress_callback:+ progress_callback(60, "Running speaker diarization...")++ speaker_segments = run_diarization(+ wav_path,+ num_speakers=num_speakers,+ progress_callback=lambda pct, msg: (+ progress_callback(60 + int(pct * 0.3), msg) if progress_callback else None+ ),+ )++ if speaker_segments:+ if progress_callback:+ progress_callback(92, "Assigning speakers to transcript...")++ segments = assign_speakers_to_segments(segments, speaker_segments)+ words = assign_speakers_to_words(words, speaker_segments)+ speaker_summary = create_speaker_summary(speaker_segments)++ if progress_callback:+ progress_callback(+ 95,+ f"Found {speaker_summary['num_speakers']} speakers",+ )++ finally:+ if os.path.exists(wav_path):+ os.unlink(wav_path)++ except ImportError as e:+ diarization_warning = f"Speaker detection unavailable: {e}"+ if progress_callback:+ progress_callback(90, diarization_warning)+ except PermissionError as e:+ diarization_warning = str(e)+ if progress_callback:+ progress_callback(90, diarization_warning)+ except Exception as e:+ diarization_warning = f"Speaker detection failed: {e}"+ if progress_callback:+ progress_callback(90, diarization_warning)+ else:+ diarization_warning = "Speaker detection disabled"++ face_map = None+ try:+ if progress_callback:+ progress_callback(95, "Analyzing face positions...")+ from services.face_analysis import analyze_faces++ face_map = analyze_faces(+ video_path=file_path,+ speaker_segments=speaker_segments,+ duration=duration,+ )+ except Exception as e:+ print(f"Warning: face analysis failed: {e}", file=sys.stderr)++ if progress_callback:+ progress_callback(100, "Complete")++ base["segments"] = segments+ base["words"] = words+ base["duration"] = round(duration, 3)+ base["speakers"] = speaker_summary+ base["speaker_segments"] = speaker_segments+ if face_map:+ base["face_map"] = face_map+ if diarization_warning:+ base["diarization_warning"] = diarization_warning+ return base++def transcribe_file(file_path: str,model_size: str = "base",@@ -106,30 +216,38 @@ def transcribe_file(requested = os.environ.get("PODCLI_ENGINE", "").strip().lower()engine = requested or "whisper-py"- if engine in ("whispercpp", "whisper-cpp", "whisper.cpp", "cpp"):- return _transcribe_with_whispercpp(file_path, model_size, language, progress_callback)-- # ================================================================- # Step 1: Whisper transcription- # ================================================================- if progress_callback:- progress_callback(5, "Loading Whisper model...")+ use_cpp = engine in ("whispercpp", "whisper-cpp", "whisper.cpp", "cpp")# Native installs ship whisper.cpp, not openai-whisper. Fall back to it# automatically — whether whisper is missing OR a broken install fails to# load/run — unless the user explicitly asked for the whisper-py engine.- try:- import whisper+ if not use_cpp:+ if progress_callback:+ progress_callback(5, "Loading Whisper model...")+ try:+ import whisper- model = whisper.load_model(model_size)- except Exception as e:- if not requested and _whispercpp_ready(model_size):- return _transcribe_with_whispercpp(file_path, model_size, language, progress_callback)- raise RuntimeError(- "The whisper-py engine needs the full source install (openai-whisper + torch). "- "This native install ships whisper.cpp — rerun with --engine whispercpp."- ) from e+ model = whisper.load_model(model_size)+ except Exception as e:+ if not requested and _whispercpp_ready(model_size):+ use_cpp = True+ else:+ raise RuntimeError(+ "The whisper-py engine needs the full source install (openai-whisper + torch). "+ "This native install ships whisper.cpp — rerun with --engine whispercpp."+ ) from e++ if use_cpp:+ base = _transcribe_with_whispercpp(file_path, model_size, language, progress_callback)+ # whisper.cpp is the no-torch path: importing torch for diarization can+ # hard-crash native runtimes. Skip diarization, keep face analysis (OpenCV).+ return _attach_speakers_and_faces(+ file_path, base, False, num_speakers, progress_callback+ )+ # ================================================================+ # Step 1: Whisper transcription+ # ================================================================if progress_callback:progress_callback(10, f"Transcribing with Whisper ({model_size})...")@@ -202,110 +320,13 @@ def transcribe_file(detected_lang = result.get("language", language or "en")- # ================================================================- # Step 2: Speaker diarization (if enabled)- # ================================================================- speaker_segments = []- speaker_summary = {"num_speakers": 0, "speakers": {}}- diarization_warning = None-- if enable_diarization:- try:- from services.speaker_detection import (- extract_audio_wav,- run_diarization,- assign_speakers_to_segments,- assign_speakers_to_words,- create_speaker_summary,- )-- if progress_callback:- progress_callback(55, "Extracting audio for speaker detection...")-- # Extract audio as WAV for pyannote- with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as tmp:- wav_path = tmp.name-- try:- extract_audio_wav(file_path, wav_path)-- if progress_callback:- progress_callback(60, "Running speaker diarization...")-- speaker_segments = run_diarization(- wav_path,- num_speakers=num_speakers,- progress_callback=lambda pct, msg: (- progress_callback(60 + int(pct * 0.3), msg) if progress_callback else None- ),- )-- if speaker_segments:- if progress_callback:- progress_callback(92, "Assigning speakers to transcript...")-- # Merge speaker labels into segments and words- segments = assign_speakers_to_segments(segments, speaker_segments)- words = assign_speakers_to_words(words, speaker_segments)- speaker_summary = create_speaker_summary(speaker_segments)-- if progress_callback:- progress_callback(- 95,- f"Found {speaker_summary['num_speakers']} speakers",- )-- finally:- if os.path.exists(wav_path):- os.unlink(wav_path)-- except ImportError as e:- diarization_warning = f"Speaker detection unavailable: {e}"- if progress_callback:- progress_callback(90, diarization_warning)- except PermissionError as e:- diarization_warning = str(e)- if progress_callback:- progress_callback(90, diarization_warning)- except Exception as e:- diarization_warning = f"Speaker detection failed: {e}"- if progress_callback:- progress_callback(90, diarization_warning)- else:- diarization_warning = "Speaker detection disabled"-- # Run face analysis on the video (maps speakers to face positions)- # Run silently — no progress callbacks to avoid interfering with CLI output- face_map = None- try:- if progress_callback:- progress_callback(95, "Analyzing face positions...")- from services.face_analysis import analyze_faces- face_map = analyze_faces(- video_path=file_path,- speaker_segments=speaker_segments,- duration=duration,- )- except Exception as e:- print(f"Warning: face analysis failed: {e}", file=sys.stderr)-- if progress_callback:- progress_callback(100, "Complete")-- result_data = {+ base = {"transcript": result.get("text", "").strip(),"segments": segments,"words": words,- "duration": round(duration, 3),+ "duration": duration,"language": detected_lang,- "speakers": speaker_summary,- "speaker_segments": speaker_segments,}-- if face_map:- result_data["face_map"] = face_map-- if diarization_warning:- result_data["diarization_warning"] = diarization_warning-- return result_data+ return _attach_speakers_and_faces(+ file_path, base, enable_diarization, num_speakers, progress_callback+ )diff --git a/backend/services/video_processor.py b/backend/services/video_processor.pyindex d953be9..cbf00d7 100644--- a/backend/services/video_processor.py+++ b/backend/services/video_processor.py@@ -1106,8 +1106,6 @@ def _track_and_crop(# breaks on every layout transition. For mixed layouts, use# simple per-frame largest-face following instead.is_mixed = face_map.get("is_mixed_layout", False) if face_map else False- if is_mixed and not is_mixed: # disabled — checking below- passif is_mixed:# Build a time→speaker lookup from segmentsdef _speaker_at(t_sec: float) -> str | None:diff --git a/cli/main.go b/cli/main.goindex 1308444..d3afbd5 100644--- a/cli/main.go+++ b/cli/main.go@@ -67,7 +67,7 @@ func wantsRuntime(args []string) bool {return true}switch args[0] {- case "process", "transcribe", "studio", "auto":+ case "process", "transcribe", "studio", "auto", "ui", "webui":return true}return false@@ -398,6 +398,7 @@ Usage:Engine commands (routed to the processing backend):process <video> Transcribe a video and export short-form clips+ ui Open the Studio web dashboard (http://localhost:3847)studio <video> Cut a fragment + intro/outro bookendsclips Browse and edit saved clipsthumbnails Generate thumbnailsdiff --git a/src/services/clips-history.ts b/src/services/clips-history.tsindex a4383ae..33c58e5 100644--- a/src/services/clips-history.ts+++ b/src/services/clips-history.ts@@ -44,8 +44,13 @@ export class ClipsHistory {// Write to a temp file and atomically rename so a crash or a concurrent// reader never sees a half-written clips.json.const tmp = `${this.historyPath}.${process.pid}.${uuidv4().slice(0, 8)}.tmp`;- await writeFile(tmp, JSON.stringify(entries, null, 2), "utf-8");- await rename(tmp, this.historyPath);+ try {+ await writeFile(tmp, JSON.stringify(entries, null, 2), "utf-8");+ await rename(tmp, this.historyPath);+ } catch (err) {+ await rm(tmp, { force: true }).catch(() => {});+ throw err;+ }}// Run load → mutate → save as one critical section, queued behind anydiff --git a/src/services/python-executor.ts b/src/services/python-executor.tsindex c85c30d..c4f984d 100644--- a/src/services/python-executor.ts+++ b/src/services/python-executor.ts@@ -1,10 +1,43 @@-import { spawn } from "child_process";+import { spawn, type ChildProcess } from "child_process";import { v4 as uuidv4 } from "uuid";import { paths } from "../config/paths.js";import type { TaskRequest, TaskResult, ProgressEvent } from "../models/index.js";type ProgressCallback = (event: ProgressEvent) => void;+const isWindows = process.platform === "win32";++function killProcessTree(proc: ChildProcess, signal: NodeJS.Signals): void {+ if (proc.pid === undefined) return;+ try {+ // Negative pid kills the whole group — the child is a detached group+ // leader, so its ffmpeg/whisper children die with it.+ if (isWindows) proc.kill(signal);+ else process.kill(-proc.pid, signal);+ } catch {+ // Already exited.+ }+}++function parseResultLine<T>(stdout: string): TaskResult<T> | null {+ // The result is the last stdout line that parses to a JSON object with a+ // status field; the backend may also print stray lines.+ const lines = stdout.trim().split("\n");+ for (let i = lines.length - 1; i >= 0; i--) {+ const trimmed = lines[i].trim();+ if (!trimmed.startsWith("{")) continue;+ try {+ const parsed = JSON.parse(trimmed);+ if (parsed && typeof parsed === "object" && "status" in parsed) {+ return parsed as TaskResult<T>;+ }+ } catch {+ continue;+ }+ }+ return null;+}+/*** Executes Python backend tasks via subprocess.* Communication: JSON over stdin (request) → stdout (result), stderr (progress logs).@@ -33,6 +66,7 @@ export class PythonExecutor {return new Promise<TaskResult<T>>((resolve, reject) => {const proc = spawn(paths.pythonPath, [paths.pythonBackend], {stdio: ["pipe", "pipe", "pipe"],+ detached: !isWindows,env: {...process.env,PYTHONUNBUFFERED: "1",@@ -43,17 +77,32 @@ export class PythonExecutor {let stdout = "";let stderr = "";+ let settled = false;+ let timer: NodeJS.Timeout | undefined;++ const finish = (action: () => void): void => {+ if (settled) return;+ settled = true;+ if (timer) clearTimeout(timer);+ action();+ };proc.stdout.on("data", (chunk: Buffer) => {stdout += chunk.toString();});+ // Buffer across chunks so a progress event split over a chunk boundary+ // isn't dropped.+ let stderrBuffer = "";proc.stderr.on("data", (chunk: Buffer) => {const raw = chunk.toString();stderr += raw;+ stderrBuffer += raw;++ const lines = stderrBuffer.split("\n");+ stderrBuffer = lines.pop() ?? "";- // Try to parse progress events (one per line)- for (const line of raw.split("\n")) {+ for (const line of lines) {const trimmed = line.trim();if (!trimmed || !trimmed.startsWith("{")) continue;try {@@ -62,57 +111,51 @@ export class PythonExecutor {onProgress(event);}} catch {- // Regular log line, ignore+ continue;}}});proc.on("error", (err) => {- reject(new Error(`Failed to spawn Python process: ${err.message}`));+ finish(() => reject(new Error(`Failed to spawn Python process: ${err.message}`)));});+ // Without this, an EPIPE from a fast-crashing child becomes an unhandled+ // error that crashes the server.+ proc.stdin.on("error", () => {});+proc.on("close", (code) => {- try {- // Find the last complete JSON object in stdout- const jsonMatch = stdout.trim().split("\n").filter(Boolean).pop();- if (!jsonMatch) {+ finish(() => {+ const result = parseResultLine<T>(stdout);+ if (!result) {reject(new Error(- `No output from Python task. Exit code: ${code}. Stderr: ${stderr.slice(-500)}`+ `No parseable output from Python task. Exit code: ${code}. ` ++ `Stdout: ${stdout.slice(-300)}. Stderr: ${stderr.slice(-300)}`));return;}- const result = JSON.parse(jsonMatch) as TaskResult<T>;-if (result.status === "error") {reject(new Error(result.error || "Unknown Python error"));return;}resolve(result);- } catch (parseErr) {- reject(- new Error(- `Failed to parse Python output. Exit code: ${code}. ` +- `Stdout: ${stdout.slice(-300)}. Stderr: ${stderr.slice(-300)}`- )- );- }+ });});- // Send request and close stdin- proc.stdin.write(JSON.stringify(request) + "\n");- proc.stdin.end();+ try {+ proc.stdin.write(JSON.stringify(request) + "\n");+ proc.stdin.end();+ } catch {}- // Timeout guard- const timer = setTimeout(() => {- proc.kill("SIGKILL");- reject(new Error(`Task timed out after ${this.timeoutMs / 1000}s`));+ timer = setTimeout(() => {+ killProcessTree(proc, "SIGTERM");+ setTimeout(() => killProcessTree(proc, "SIGKILL"), 2000).unref();+ finish(() => reject(new Error(`Task timed out after ${this.timeoutMs / 1000}s`)));}, this.timeoutMs);-- proc.on("close", () => clearTimeout(timer));});}}diff --git a/src/ui/public/css/styles.css b/src/ui/public/css/styles.cssindex 5e35d5e..ed13785 100644--- a/src/ui/public/css/styles.css+++ b/src/ui/public/css/styles.css@@ -1186,7 +1186,7 @@ input[type="range"]::-webkit-slider-thumb {.clip-card-del:hover:not(:disabled) { background: var(--red-subtle); color: var(--red); box-shadow: 0 5px #1a1a1f, 0 11px 18px -5px #000000d9, 0 0 0 1px var(--red-border), inset 0 1px #ffffff24; }.clip-card-del:active:not(:disabled) { transform: translateY(4px); box-shadow: 0 0 0 1px var(--red-border), inset 0 1px 0 rgba(255, 255, 255, 0.10); }.clip-card-del:disabled { opacity: 0.4; cursor: default; }-.clip-card-media { aspect-ratio: 9 / 16; width: 100%; display: block; object-fit: cover; background: #000; }+.clip-card-media { aspect-ratio: 9 / 16; width: 100%; display: block; object-fit: cover; background: #000; border-radius: calc(var(--radius) - 1px) calc(var(--radius) - 1px) 0 0; }.clip-card-media.empty { display: flex; align-items: center; justify-content: center; color: var(--text3); font-size: 22px; }.clip-card-body { padding: 10px 11px; }.clip-card-title { font-size: 12.5px; font-weight: 600; line-height: 1.3; display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden; }@@ -1275,7 +1275,7 @@ h1, h2, h3 { text-wrap: balance; }p, li, figcaption, blockquote, .subtitle, .file-preview, .card-desc, .int-row .desc, .set-note, .empty-state {text-wrap: pretty;}-.clip-card-media, .thumb-stage img, .thumb-variation img { outline: 1px solid rgba(255, 255, 255, 0.1); outline-offset: -1px; }+.thumb-stage img, .thumb-variation img { box-shadow: inset 0 0 0 1px rgba(255, 255, 255, 0.1); }.clip-card-meta, .clip-meta span, .clip-card-title { font-variant-numeric: tabular-nums; }/* ── Clip detail (player hero + editor) ── */diff --git a/src/ui/web-server.ts b/src/ui/web-server.tsindex 3101f61..540d3e5 100644--- a/src/ui/web-server.ts+++ b/src/ui/web-server.ts@@ -176,6 +176,17 @@ function loadPersistedState(): UIState {const uiState: UIState = loadPersistedState();+// Files the server confirmed the user selected; /api/stream-source serves only+// these, so a forged /api/ui-state can't grant reads of arbitrary files.+const allowedSourcePaths = new Set<string>();+function registerSourcePath(p: string | undefined | null): void {+ if (!p) return;+ try {+ allowedSourcePaths.add(realpathSync(path.resolve(p)));+ } catch {}+}+registerSourcePath(uiState.videoPath);+// Debounced save to disklet saveTimer: ReturnType<typeof setTimeout> | null = null;function persistState() {@@ -359,6 +370,7 @@ app.post("/api/upload", upload.single("file"), (req, res) => {res.status(400).json({ error: "No file uploaded" });return;}+ registerSourcePath(req.file.path);res.json({file_path: req.file.path,filename: req.file.originalname,@@ -376,6 +388,7 @@ app.post("/api/select-file", (req, res) => {return;}const stat = statSync(file_path);+ registerSourcePath(file_path);res.json({file_path,filename: basename(file_path),@@ -422,6 +435,7 @@ app.get("/api/browse-file", (_req, res) => {}const stat = statSync(filePath);+ registerSourcePath(filePath);res.json({file_path: filePath,filename: basename(filePath),@@ -594,6 +608,7 @@ app.post("/api/transcribe", async (req, res) => {uiState.transcript = result.data as unknown as typeof uiState.transcript;uiState.videoPath = file_path;uiState.filePath = file_path;+ registerSourcePath(file_path);uiState.lastUpdated = Date.now();persistState();// Cache it@@ -1053,30 +1068,55 @@ app.get("/api/stream-source", (req, res) => {res.status(404).json({ error: "File not found" });return;}- // Validate the path is the current session video or within the uploads directory- const resolvedPath = path.resolve(filePath);- const isSessionVideo =- uiState.videoPath && resolvedPath === path.resolve(uiState.videoPath);++ // Extension gate: only media/image types stream, so this never serves+ // .env/key/token files regardless of the path checks below.+ const mediaMime: Record<string, string> = {+ ".mp4": "video/mp4",+ ".m4v": "video/mp4",+ ".webm": "video/webm",+ ".mov": "video/quicktime",+ ".avi": "video/x-msvideo",+ ".mkv": "video/x-matroska",+ ".mp3": "audio/mpeg",+ ".wav": "audio/wav",+ ".m4a": "audio/mp4",+ ".png": "image/png",+ ".jpg": "image/jpeg",+ ".jpeg": "image/jpeg",+ ".webp": "image/webp",+ ".gif": "image/gif",+ ".svg": "image/svg+xml",+ };+ const mime = mediaMime[extname(filePath).toLowerCase()];+ if (!mime) {+ res.status(403).json({ error: "Access denied: unsupported media type" });+ return;+ }++ // realpath defeats symlinks pointing outside the allowed set.+ let resolvedPath: string;+ try {+ resolvedPath = realpathSync(path.resolve(filePath));+ } catch {+ res.status(404).json({ error: "File not found" });+ return;+ }+const uploadsRoot = path.resolve(join(paths.working, "uploads"));const relativeToUploads = path.relative(uploadsRoot, resolvedPath);const isUploadedFile =relativeToUploads !== "" &&!relativeToUploads.startsWith("..") &&!path.isAbsolute(relativeToUploads);- if (!isSessionVideo && !isUploadedFile) {+ if (!allowedSourcePaths.has(resolvedPath) && !isUploadedFile) {res.status(403)- .json({ error: "Access denied: path not in allowed directories" });+ .json({ error: "Access denied: path not in allowed sources" });return;}- const mimeTypes: Record<string, string> = {- ".webm": "video/webm",- ".mov": "video/quicktime",- ".avi": "video/x-msvideo",- ".mkv": "video/x-matroska",- };- streamVideo(req, res, filePath, mimeTypes[extname(filePath).toLowerCase()] || "video/mp4");+ streamVideo(req, res, filePath, mime);});// Route through the CLI so the Studio and the renderer resolve the same config@@ -2608,9 +2648,17 @@ async function main() {// Bind to loopback by default — the studio serves local files (clips, assets,// source video) with no auth. Set PODCLI_HOST=0.0.0.0 to expose it on the LAN.const HOST = process.env.PODCLI_HOST || "127.0.0.1";- app.listen(PORT, HOST, () => {+ const server = app.listen(PORT, HOST, () => {log.info(`podcli running at http://localhost:${PORT}`);});+ server.on("error", (err: NodeJS.ErrnoException) => {+ if (err.code === "EADDRINUSE") {+ log.error(`Port ${PORT} is already in use — is the studio already running? Set PORT to use another.`);+ } else {+ log.error("Web server failed to start", { err: err.message });+ }+ process.exit(1);+ });}main().catch((err) => {diff --git a/tests/test_transcription_engine.py b/tests/test_transcription_engine.pyindex d6c03db..6a6d330 100644--- a/tests/test_transcription_engine.py+++ b/tests/test_transcription_engine.py@@ -51,6 +51,15 @@ class TranscriptionEngineTests(unittest.TestCase):result = tr.transcribe_file(self._tmp.name, model_size="base", enable_diarization=False)self.assertEqual(result["engine"], "whispercpp")+ def test_whispercpp_skips_diarization_by_default(self):+ # Regression: the cpp path must not attempt torch-backed diarization even+ # with the default enable_diarization=True — importing a broken torch in a+ # native runtime hard-crashes the process. Face analysis still runs.+ os.environ["PODCLI_ENGINE"] = "whispercpp"+ result = tr.transcribe_file(self._tmp.name, model_size="base")+ self.assertEqual(result["engine"], "whispercpp")+ self.assertEqual(result.get("diarization_warning"), "Speaker detection disabled")+def test_explicit_whisper_py_still_errors(self):os.environ["PODCLI_ENGINE"] = "whisper-py"with self.assertRaises(RuntimeError):