Skip to content

Open-source AI podcast clipper. Generate vertical clips with face tracking and burned-in captions. CLI, MCP server, web app.

Add `podcli ui` + backend hardening and audit fixes (#30)

Nika Siradze2396637ebf3b
diff --git a/CLAUDE.md b/CLAUDE.md
index 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.md
index 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 burned
Open 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.py
index 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()
return
elif 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.py
index 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:
continue
chunk_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 progressively
parts = []
@@ -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:
continue
sent_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:
continue
line_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:
continue
chunk_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 casing
normalized = []
diff --git a/backend/services/claude_suggest.py b/backend/services/claude_suggest.py
index 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 selected
if 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 None
def _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 None
diff --git a/backend/services/face_analysis.py b/backend/services/face_analysis.py
index 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 / fps
faces = 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_gray
faces_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 += 1
cap.release()
diff --git a/backend/services/transcription.py b/backend/services/transcription.py
index 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_callba
vad_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.py
index 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
- pass
if is_mixed:
# Build a time→speaker lookup from segments
def _speaker_at(t_sec: float) -> str | None:
diff --git a/cli/main.go b/cli/main.go
index 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 bookends
clips Browse and edit saved clips
thumbnails Generate thumbnails
diff --git a/src/services/clips-history.ts b/src/services/clips-history.ts
index 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 any
diff --git a/src/services/python-executor.ts b/src/services/python-executor.ts
index 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.css
index 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.ts
index 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 disk
let 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.py
index 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):