Skip to content

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

feat: CLI, server, and rendering improvements

Nika Siradzea3e60912222d
diff --git a/.env.example b/.env.example
index bb05286..34b1c1e 100644
--- a/.env.example
+++ b/.env.example
@@ -25,6 +25,9 @@ HF_TOKEN=
# low=fast/small, high=great quality (default), max=near-lossless
PODCLI_QUALITY=high
+# Transition QA/autofix passes (0=off, 1-2 allowed; renderer hard-caps at 2)
+PODCLI_TRANSITION_AUTOFIX_PASSES=2
+
PORT=3847 # Web UI port
# Logging
diff --git a/backend/cli.py b/backend/cli.py
index 58363e6..fa89fdc 100644
--- a/backend/cli.py
+++ b/backend/cli.py
@@ -40,6 +40,10 @@ if os.path.exists(_env_file):
if _key and _val:
os.environ.setdefault(_key, _val)
+# Quality defaults (can be overridden via .env or shell env).
+# Keep transition autofix enabled by default with a strict hard cap in renderer.
+os.environ.setdefault("PODCLI_TRANSITION_AUTOFIX_PASSES", "2")
+
# Add parent dir to path
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
@@ -110,6 +114,52 @@ def _ensure_ssl_certs():
print(" ⚠ SSL verification disabled for this session (model downloads only)")
+def _sanitize_path_component(value: str) -> str:
+ """Convert a user-facing label into a safe directory name."""
+ safe = "".join(c if c.isalnum() or c in "-_." else "_" for c in value.strip())
+ safe = safe.strip("._")
+ return safe or "default"
+
+
+def _resolve_output_dir(
+ video_path: str,
+ preset_name: str | None,
+ configured_output_dir: str | None,
+ explicit_output_dir: str | None,
+) -> str:
+ """
+ Resolve the clip output directory.
+
+ Rules:
+ - Explicit --output wins exactly as given.
+ - Otherwise use preset/default output root.
+ - Preset-driven runs get their own subfolder by preset name to avoid
+ collisions when multiple presets run in parallel.
+ """
+ if explicit_output_dir:
+ return explicit_output_dir
+
+ base_output_dir = configured_output_dir or os.path.join(os.path.dirname(video_path), "clips")
+ if not preset_name:
+ return base_output_dir
+
+ preset_folder = _sanitize_path_component(preset_name)
+ normalized_base = os.path.normpath(base_output_dir)
+ if os.path.basename(normalized_base) == preset_folder:
+ return base_output_dir
+ return os.path.join(base_output_dir, preset_folder)
+
+
+def _has_successful_results(results: list) -> bool:
+ """Return True if at least one clip rendered successfully."""
+ return any(isinstance(r, dict) and r.get("output_path") for r in results)
+
+
+def _should_enter_post_render_loop(config: dict, interrupted: bool, results: list) -> bool:
+ """Open the post-render rerender flow on explicit config or partial interrupt recovery."""
+ return bool(config.get("post_render_review", False) or (interrupted and _has_successful_results(results)))
+
+
def cmd_process(args):
"""Full auto pipeline: transcribe → suggest → export."""
from services.clip_generator import generate_clip
@@ -206,8 +256,14 @@ def cmd_process(args):
quality = config.get("quality", os.environ.get("PODCLI_QUALITY", "max"))
os.environ["PODCLI_QUALITY"] = quality
- # Output directory: CLI arg > preset > default
- output_dir = args.output or config.get("output_dir") or os.path.join(os.path.dirname(video_path), "clips")
+ # Output directory: explicit --output wins. Otherwise preset runs get
+ # their own subfolder under the configured/default clips root.
+ output_dir = _resolve_output_dir(
+ video_path=video_path,
+ preset_name=args.preset,
+ configured_output_dir=config.get("output_dir"),
+ explicit_output_dir=args.output,
+ )
os.makedirs(output_dir, exist_ok=True)
enc_info = get_encoder_info()
@@ -371,13 +427,13 @@ def cmd_process(args):
clips = None
# Try an AI CLI first (uses PodStack knowledge base for intelligent selection)
- from services.claude_suggest import suggest_with_claude, _engine_label, _find_ai_cli
+ from services.claude_suggest import suggest_initial_with_claude, _engine_label, _find_ai_cli
ai_path, ai_engine = _find_ai_cli()
if ai_path:
ai_label = _engine_label(ai_engine)
print(f" [3/4] Selecting moments with {ai_label} (PodStack)...")
- clips = suggest_with_claude(
+ clips = suggest_initial_with_claude(
segments=segments,
top_n=top_n,
progress_callback=lambda pct, msg: print(f" {msg}") if msg else None,
@@ -454,238 +510,246 @@ def cmd_process(args):
results = []
t0 = time.time()
_skip_review = not config.get("review_each_clip", False)
+ interrupted = False
- for i, clip in enumerate(clips):
- ok = False
- result = None
- with _Spinner(f"Clip {i+1}/{len(clips)}: {clip['title'][:40]}...") as sp:
- try:
- result = generate_clip(
- video_path=video_path,
- start_second=clip["start_second"],
- end_second=clip["end_second"],
- caption_style=config.get("caption_style", "branded"),
- crop_strategy=config.get("crop_strategy", "face"),
- transcript_words=words,
- title=clip.get("title", f"clip_{i+1}"),
- output_dir=output_dir,
- logo_path=config.get("logo_path") or None,
- outro_path=config.get("outro_path") or None,
- keep_segments=clip.get("segments"),
- face_map=face_map,
- )
- results.append(result)
- ok = True
- except Exception as e:
- print(f"\n ✗ {e}")
- results.append({"status": "error", "error": str(e)})
- continue
- if ok:
- print(f" ✓ Clip {i+1}/{len(clips)}: {result['file_size_mb']}MB")
-
- # Generate thumbnail and append to clip immediately
- if _thumb_enabled and _thumb_gen and result.get("output_path"):
- try:
- clip_thumb_dir = os.path.join(thumb_dir, f"clip_{i+1}")
- paths = _thumb_gen(
- title=clip.get("title", f"Clip {i+1}"),
- output_dir=clip_thumb_dir,
- photo_path=_thumb_photo,
- video_path=video_path,
- logo_path=_thumb_logo,
- )
- if paths:
- thumb_video = os.path.join(clip_thumb_dir, "thumb_frame.mp4")
- _thumb_to_video(paths[0], thumb_video, duration=1.5)
- from services.video_processor import concat_outro
- final_with_thumb = result["output_path"].replace(".mp4", "_with_thumb.mp4")
- concat_outro(result["output_path"], thumb_video, final_with_thumb, crossfade_duration=0.15)
- os.replace(final_with_thumb, result["output_path"])
- print(f" + thumbnail appended ({len(paths)} variations in {os.path.basename(clip_thumb_dir)}/)")
- except Exception as e:
- print(f" ⚠ thumbnail: {e}")
-
- # Generate titles, descriptions, tags for this clip immediately
- if _ai_cli_path and result.get("output_path"):
- try:
- from services.content_generator import generate_clip_content
- content_result = generate_clip_content(
- clip=clip,
- transcript_segments=segments,
- )
- if content_result and content_result.get("raw_text"):
- # Save per-clip content to file
- _content_path = result["output_path"].replace(".mp4", "_content.md")
- with open(_content_path, "w") as _cf:
- _cf.write(f"# {clip.get('title', 'Clip')}\n\n{content_result['raw_text']}")
-
- # Pretty-print in terminal
- _accent = "\033[38;2;212;135;74m"
- _bold = "\033[1m"
- _dim = "\033[2m"
- _yellow = "\033[33m"
- _reset = "\033[0m"
-
- print(f"\n {'─' * 45}")
- print(f" {_bold}📋 Clip {i+1}: {clip['title'][:45]}{_reset}")
- print(f" {'─' * 45}")
- for line in content_result["raw_text"].split("\n"):
- stripped = line.strip()
- if not stripped:
- continue
- if stripped.startswith("TITLES") or stripped.startswith("DESCRIPTION") or stripped.startswith("TAGS") or stripped.startswith("HASHTAGS") or stripped.startswith("TOP PICK"):
- print(f" {_bold}{stripped}{_reset}")
- elif stripped[0:1].isdigit() and ". " in stripped[:4]:
- print(f" {_accent}{stripped}{_reset}")
- elif stripped.startswith("#"):
- print(f" {_yellow}{stripped}{_reset}")
- else:
- print(f" {_dim}{stripped}{_reset}")
- print(f" {_dim}Saved: {os.path.basename(_content_path)}{_reset}")
- print()
- except Exception as e:
- print(f" ⚠ content: {e}")
+ try:
+ for i, clip in enumerate(clips):
+ ok = False
+ result = None
+ with _Spinner(f"Clip {i+1}/{len(clips)}: {clip['title'][:40]}...") as sp:
+ try:
+ result = generate_clip(
+ video_path=video_path,
+ start_second=clip["start_second"],
+ end_second=clip["end_second"],
+ caption_style=config.get("caption_style", "branded"),
+ crop_strategy=config.get("crop_strategy", "speaker"),
+ transcript_words=words,
+ title=clip.get("title", f"clip_{i+1}"),
+ output_dir=output_dir,
+ logo_path=config.get("logo_path") or None,
+ outro_path=config.get("outro_path") or None,
+ keep_segments=clip.get("segments"),
+ face_map=face_map,
+ )
+ results.append(result)
+ ok = True
+ except Exception as e:
+ print(f"\n ✗ {e}")
+ results.append({"status": "error", "error": str(e)})
+ continue
+ if ok:
+ print(f" ✓ Clip {i+1}/{len(clips)}: {result['file_size_mb']}MB")
+
+ # Generate thumbnail and append to clip immediately
+ if _thumb_enabled and _thumb_gen and result.get("output_path"):
+ try:
+ clip_thumb_dir = os.path.join(thumb_dir, f"clip_{i+1}")
+ paths = _thumb_gen(
+ title=clip.get("title", f"Clip {i+1}"),
+ output_dir=clip_thumb_dir,
+ photo_path=_thumb_photo,
+ video_path=video_path,
+ logo_path=_thumb_logo,
+ )
+ if paths:
+ thumb_video = os.path.join(clip_thumb_dir, "thumb_frame.mp4")
+ _thumb_to_video(paths[0], thumb_video, duration=1.5)
+ from services.video_processor import concat_outro
+ final_with_thumb = result["output_path"].replace(".mp4", "_with_thumb.mp4")
+ concat_outro(result["output_path"], thumb_video, final_with_thumb, crossfade_duration=0.15)
+ os.replace(final_with_thumb, result["output_path"])
+ print(f" + thumbnail appended ({len(paths)} variations in {os.path.basename(clip_thumb_dir)}/)")
+ except Exception as e:
+ print(f" ⚠ thumbnail: {e}")
+
+ # Generate titles, descriptions, tags for this clip immediately
+ if _ai_cli_path and result.get("output_path"):
+ try:
+ from services.content_generator import generate_clip_content
+ content_result = generate_clip_content(
+ clip=clip,
+ transcript_segments=segments,
+ )
+ if content_result and content_result.get("raw_text"):
+ # Save per-clip content to file
+ _content_path = result["output_path"].replace(".mp4", "_content.md")
+ with open(_content_path, "w") as _cf:
+ _cf.write(f"# {clip.get('title', 'Clip')}\n\n{content_result['raw_text']}")
+
+ # Pretty-print in terminal
+ _accent = "\033[38;2;212;135;74m"
+ _bold = "\033[1m"
+ _dim = "\033[2m"
+ _yellow = "\033[33m"
+ _reset = "\033[0m"
+
+ print(f"\n {'─' * 45}")
+ print(f" {_bold}📋 Clip {i+1}: {clip['title'][:45]}{_reset}")
+ print(f" {'─' * 45}")
+ for line in content_result["raw_text"].split("\n"):
+ stripped = line.strip()
+ if not stripped:
+ continue
+ if stripped.startswith("TITLES") or stripped.startswith("DESCRIPTION") or stripped.startswith("TAGS") or stripped.startswith("HASHTAGS") or stripped.startswith("TOP PICK"):
+ print(f" {_bold}{stripped}{_reset}")
+ elif stripped[0:1].isdigit() and ". " in stripped[:4]:
+ print(f" {_accent}{stripped}{_reset}")
+ elif stripped.startswith("#"):
+ print(f" {_yellow}{stripped}{_reset}")
+ else:
+ print(f" {_dim}{stripped}{_reset}")
+ print(f" {_dim}Saved: {os.path.basename(_content_path)}{_reset}")
+ print()
+ except Exception as e:
+ print(f" ⚠ content: {e}")
+
+ # ── Per-clip review: open video, ask for feedback ──
+ if ok and not _skip_review and result.get("output_path") and os.path.exists(result["output_path"]):
+ import subprocess as _review_sp
+ _review_sp.Popen(["open", result["output_path"]] if sys.platform == "darwin" else ["xdg-open", result["output_path"]])
+
+ while True:
+ import questionary as _rq
+ from questionary import Style as _RS
+ _rstyle = _RS([
+ ("qmark", "fg:#d4874a bold"), ("question", "bold"),
+ ("answer", "fg:#4ade80"), ("pointer", "fg:#d4874a bold"),
+ ("highlighted", "fg:#d4874a bold"), ("selected", "fg:#4ade80"),
+ ])
+ _raction = _rq.select(
+ f"Clip {i+1}/{len(clips)}: {clip['title'][:40]}",
+ choices=[
+ _rq.Choice("Looks good — next clip", value="next"),
+ _rq.Choice("Change caption style", value="style"),
+ _rq.Choice("Make shorter (trim 5s from end)", value="shorter"),
+ _rq.Choice("Make longer (extend 5s)", value="longer"),
+ _rq.Choice("Start earlier (5s)", value="earlier"),
+ _rq.Choice("Start later (3s)", value="later"),
+ _rq.Choice("Swap speaker (camera on wrong person)", value="swap"),
+ _rq.Choice("Tell me what to change", value="custom"),
+ _rq.Choice("Render the rest without asking", value="skip_review"),
+ ],
+ style=_rstyle,
+ instruction="",
+ ).ask()
- # ── Per-clip review: open video, ask for feedback ──
- if ok and not _skip_review and result.get("output_path") and os.path.exists(result["output_path"]):
- import subprocess as _review_sp
- _review_sp.Popen(["open", result["output_path"]] if sys.platform == "darwin" else ["xdg-open", result["output_path"]])
+ if _raction is None or _raction == "next":
+ break
- while True:
- import questionary as _rq
- from questionary import Style as _RS
- _rstyle = _RS([
- ("qmark", "fg:#d4874a bold"), ("question", "bold"),
- ("answer", "fg:#4ade80"), ("pointer", "fg:#d4874a bold"),
- ("highlighted", "fg:#d4874a bold"), ("selected", "fg:#4ade80"),
- ])
- _raction = _rq.select(
- f"Clip {i+1}/{len(clips)}: {clip['title'][:40]}",
- choices=[
- _rq.Choice("Looks good — next clip", value="next"),
- _rq.Choice("Change caption style", value="style"),
- _rq.Choice("Make shorter (trim 5s from end)", value="shorter"),
- _rq.Choice("Make longer (extend 5s)", value="longer"),
- _rq.Choice("Start earlier (5s)", value="earlier"),
- _rq.Choice("Start later (3s)", value="later"),
- _rq.Choice("Swap speaker (camera on wrong person)", value="swap"),
- _rq.Choice("Tell me what to change", value="custom"),
- _rq.Choice("Render the rest without asking", value="skip_review"),
- ],
- style=_rstyle,
- instruction="",
- ).ask()
-
- if _raction is None or _raction == "next":
- break
+ if _raction == "skip_review":
+ _skip_review = True
+ break
- if _raction == "skip_review":
- _skip_review = True
- break
+ if _raction == "swap":
+ # Swap speaker labels in the words for this clip's time range
+ # so the camera follows the other person
+ clip_speakers = sorted(set(
+ w.get("speaker") for w in words
+ if w.get("speaker") and w["start"] >= clip["start_second"] and w["end"] <= clip["end_second"]
+ ))
+ if len(clip_speakers) >= 2:
+ swap_map = {clip_speakers[0]: clip_speakers[1], clip_speakers[1]: clip_speakers[0]}
+ for w in words:
+ if w["start"] >= clip["start_second"] and w["end"] <= clip["end_second"]:
+ sp = w.get("speaker")
+ if sp in swap_map:
+ w["speaker"] = swap_map[sp]
+ print(f" Swapped speakers: {clip_speakers[0]} ↔ {clip_speakers[1]}")
+ else:
+ print(f" Only one speaker detected in this clip")
+ continue
- if _raction == "swap":
- # Swap speaker labels in the words for this clip's time range
- # so the camera follows the other person
- clip_speakers = sorted(set(
- w.get("speaker") for w in words
- if w.get("speaker") and w["start"] >= clip["start_second"] and w["end"] <= clip["end_second"]
- ))
- if len(clip_speakers) >= 2:
- swap_map = {clip_speakers[0]: clip_speakers[1], clip_speakers[1]: clip_speakers[0]}
- for w in words:
- if w["start"] >= clip["start_second"] and w["end"] <= clip["end_second"]:
- sp = w.get("speaker")
- if sp in swap_map:
- w["speaker"] = swap_map[sp]
- print(f" Swapped speakers: {clip_speakers[0]} ↔ {clip_speakers[1]}")
- else:
- print(f" Only one speaker detected in this clip")
- continue
-
- if _raction == "custom":
- _feedback = _rq.text(
- "What should I change?",
- style=_rstyle,
- ).ask()
- if _feedback and _feedback.strip():
- fb = _feedback.strip().lower()
- # Parse into a known action
- if any(w in fb for w in ["shorter", "trim", "cut"]):
- _raction = "shorter"
- elif any(w in fb for w in ["longer", "extend", "more"]):
- _raction = "longer"
- elif any(w in fb for w in ["earlier", "before", "back"]):
- _raction = "earlier"
- elif any(w in fb for w in ["later", "forward"]):
- _raction = "later"
- elif any(w in fb for w in ["hormozi", "karaoke", "subtle", "branded"]):
- _raction = "style"
- for s in ["hormozi", "karaoke", "subtle", "branded"]:
- if s in fb:
- config["caption_style"] = s
- break
- elif any(w in fb for w in ["wrong person", "swap", "other speaker", "other face", "wrong face", "wrong speaker"]):
- _raction = "swap"
+ if _raction == "custom":
+ _feedback = _rq.text(
+ "What should I change?",
+ style=_rstyle,
+ ).ask()
+ if _feedback and _feedback.strip():
+ fb = _feedback.strip().lower()
+ # Parse into a known action
+ if any(w in fb for w in ["shorter", "trim", "cut"]):
+ _raction = "shorter"
+ elif any(w in fb for w in ["longer", "extend", "more"]):
+ _raction = "longer"
+ elif any(w in fb for w in ["earlier", "before", "back"]):
+ _raction = "earlier"
+ elif any(w in fb for w in ["later", "forward"]):
+ _raction = "later"
+ elif any(w in fb for w in ["hormozi", "karaoke", "subtle", "branded"]):
+ _raction = "style"
+ for s in ["hormozi", "karaoke", "subtle", "branded"]:
+ if s in fb:
+ config["caption_style"] = s
+ break
+ elif any(w in fb for w in ["wrong person", "swap", "other speaker", "other face", "wrong face", "wrong speaker"]):
+ _raction = "swap"
+ else:
+ print(f" Couldn't parse that. Try: 'shorter', 'longer 10', 'start earlier', 'hormozi style', 'wrong person'")
+ continue
else:
- print(f" Couldn't parse that. Try: 'shorter', 'longer 10', 'start earlier', 'hormozi style', 'wrong person'")
continue
- else:
- continue
-
- # Apply change
- _adj = 5 # default seconds for timing adjustments
- if _raction == "style":
- _new_style = _rq.select("Style:", choices=[
- _rq.Choice("branded", value="branded"),
- _rq.Choice("hormozi", value="hormozi"),
- _rq.Choice("karaoke", value="karaoke"),
- _rq.Choice("subtle", value="subtle"),
- ], style=_rstyle).ask()
- if _new_style:
- config["caption_style"] = _new_style
- elif _raction == "shorter":
- clip["end_second"] -= _adj
- clip["duration"] = max(10, clip["duration"] - _adj)
- print(f" Trimming {_adj}s from end")
- elif _raction == "longer":
- clip["end_second"] += _adj
- clip["duration"] += _adj
- print(f" Extending {_adj}s")
- elif _raction == "earlier":
- clip["start_second"] = max(0, clip["start_second"] - _adj)
- print(f" Starting {_adj}s earlier")
- elif _raction == "later":
- clip["start_second"] += 3
- print(f" Starting 3s later")
-
- # Re-render
- with _Spinner(f"Re-rendering clip {i+1}..."):
- try:
- result = generate_clip(
- video_path=video_path,
- start_second=clip["start_second"],
- end_second=clip["end_second"],
- caption_style=config.get("caption_style", "branded"),
- crop_strategy=config.get("crop_strategy", "face"),
- transcript_words=words,
- title=clip.get("title", f"clip_{i+1}"),
- output_dir=output_dir,
- logo_path=config.get("logo_path") or None,
- outro_path=config.get("outro_path") or None,
- keep_segments=clip.get("segments"),
- face_map=face_map,
- )
- results[-1] = result
- print(f" ✓ Re-rendered: {result['file_size_mb']}MB")
- # Open new version
- _review_sp.Popen(["open", result["output_path"]] if sys.platform == "darwin" else ["xdg-open", result["output_path"]])
- except Exception as _re:
- print(f" ✗ {_re}")
- break
+
+ # Apply change
+ _adj = 5 # default seconds for timing adjustments
+ if _raction == "style":
+ _new_style = _rq.select("Style:", choices=[
+ _rq.Choice("branded", value="branded"),
+ _rq.Choice("hormozi", value="hormozi"),
+ _rq.Choice("karaoke", value="karaoke"),
+ _rq.Choice("subtle", value="subtle"),
+ ], style=_rstyle).ask()
+ if _new_style:
+ config["caption_style"] = _new_style
+ elif _raction == "shorter":
+ clip["end_second"] -= _adj
+ clip["duration"] = max(10, clip["duration"] - _adj)
+ print(f" Trimming {_adj}s from end")
+ elif _raction == "longer":
+ clip["end_second"] += _adj
+ clip["duration"] += _adj
+ print(f" Extending {_adj}s")
+ elif _raction == "earlier":
+ clip["start_second"] = max(0, clip["start_second"] - _adj)
+ print(f" Starting {_adj}s earlier")
+ elif _raction == "later":
+ clip["start_second"] += 3
+ print(f" Starting 3s later")
+
+ # Re-render
+ with _Spinner(f"Re-rendering clip {i+1}..."):
+ try:
+ result = generate_clip(
+ video_path=video_path,
+ start_second=clip["start_second"],
+ end_second=clip["end_second"],
+ caption_style=config.get("caption_style", "branded"),
+ crop_strategy=config.get("crop_strategy", "speaker"),
+ transcript_words=words,
+ title=clip.get("title", f"clip_{i+1}"),
+ output_dir=output_dir,
+ logo_path=config.get("logo_path") or None,
+ outro_path=config.get("outro_path") or None,
+ keep_segments=clip.get("segments"),
+ face_map=face_map,
+ )
+ results[-1] = result
+ print(f" ✓ Re-rendered: {result['file_size_mb']}MB")
+ # Open new version
+ _review_sp.Popen(["open", result["output_path"]] if sys.platform == "darwin" else ["xdg-open", result["output_path"]])
+ except Exception as _re:
+ print(f" ✗ {_re}")
+ break
+ except KeyboardInterrupt:
+ interrupted = True
+ print(f"\n ⚠ Render interrupted — keeping completed clips")
elapsed = time.time() - t0
success = sum(1 for r in results if "output_path" in r)
- print(f"\n {success}/{len(clips)} clips exported in {elapsed:.1f}s")
+ if interrupted:
+ print(f"\n Interrupted with {success}/{len(clips)} completed clips in {elapsed:.1f}s")
+ else:
+ print(f"\n {success}/{len(clips)} clips exported in {elapsed:.1f}s")
if _thumb_enabled:
print(f" Thumbnails saved to {thumb_dir}/")
@@ -700,7 +764,9 @@ def cmd_process(args):
print(f"\n {gray}For titles, descriptions & tags: install Claude Code or Codex CLI{reset}")
# ── Post-render iteration ──
- if config.get("post_render_review", False):
+ if _should_enter_post_render_loop(config, interrupted, results):
+ if interrupted and not config.get("post_render_review", False):
+ print(f"\n Reviewing completed clips so you can rerender what already finished.")
_post_render_loop(
clips=clips,
results=results,
@@ -1113,7 +1179,7 @@ def _post_render_loop(
start_second=clip["start_second"],
end_second=clip["end_second"],
caption_style=config.get("caption_style", "branded"),
- crop_strategy=config.get("crop_strategy", "face"),
+ crop_strategy=config.get("crop_strategy", "speaker"),
transcript_words=words,
title=clip.get("title", "clip"),
output_dir=output_dir,
@@ -1296,7 +1362,7 @@ def _post_render_loop(
start_second=f_clip["start_second"],
end_second=f_clip["end_second"],
caption_style=config.get("caption_style", "branded"),
- crop_strategy=config.get("crop_strategy", "face"),
+ crop_strategy=config.get("crop_strategy", "speaker"),
transcript_words=words,
title=f_clip.get("title", "clip"),
output_dir=output_dir,
@@ -1348,7 +1414,7 @@ def _post_render_loop(
start_second=nc["start_second"],
end_second=nc["end_second"],
caption_style=config.get("caption_style", "branded"),
- crop_strategy=config.get("crop_strategy", "face"),
+ crop_strategy=config.get("crop_strategy", "speaker"),
transcript_words=words,
title=nc.get("title", "clip"),
output_dir=output_dir,
@@ -2246,7 +2312,7 @@ def print_help():
print(f" {green}-o{reset}, {green}--output{reset} {gray}<dir>{reset} Output directory {dim}(default: ./clips){reset}")
print(f" {green}-p{reset}, {green}--preset{reset} {gray}<name>{reset} Load a saved preset")
print(f" {green}--caption-style{reset} {gray}<style>{reset} branded | hormozi | karaoke | subtle")
- print(f" {green}--crop{reset} {gray}<strategy>{reset} center | face")
+ print(f" {green}--crop{reset} {gray}<strategy>{reset} speaker | face | center")
print(f" {green}--logo{reset} {gray}<asset|path>{reset} Overlay logo image")
print(f" {green}--outro{reset} {gray}<asset|path>{reset} Append outro video")
print(f" {green}--quality{reset} {gray}<level>{reset} low | medium | high | max")
@@ -2294,7 +2360,7 @@ def main():
proc.add_argument("-o", "--output", help="Output directory (default: ./clips)")
proc.add_argument("-p", "--preset", help="Load a saved preset")
proc.add_argument("--caption-style", choices=["branded", "hormozi", "karaoke", "subtle"])
- proc.add_argument("--crop", choices=["center", "face"])
+ proc.add_argument("--crop", choices=["center", "face", "speaker"])
proc.add_argument("--logo", help="Logo image (asset name or path)")
proc.add_argument("--outro", help="Outro video (asset name or path)")
proc.add_argument("--time-adjust", type=float, help="Timestamp offset in seconds")
@@ -2317,7 +2383,7 @@ def main():
pre_save.add_argument("--transcript", help="Default transcript path")
pre_save.add_argument("--output", help="Default output directory")
pre_save.add_argument("--caption-style", choices=["branded", "hormozi", "karaoke", "subtle"])
- pre_save.add_argument("--crop", choices=["center", "face"])
+ pre_save.add_argument("--crop", choices=["center", "face", "speaker"])
pre_save.add_argument("--logo", help="Logo (asset name or path)")
pre_save.add_argument("--outro", help="Outro (asset name or path)")
pre_save.add_argument("--top", type=int, help="Default top clips count")
@@ -2889,8 +2955,8 @@ def _interactive_presets():
# Crop strategy
crop = questionary.select(
"Crop strategy:",
- choices=["face", "center"],
- default=config.get("crop_strategy", "face"),
+ choices=["speaker", "face", "center"],
+ default=config.get("crop_strategy", "speaker"),
style=qstyle,
).ask()
if crop:
diff --git a/backend/main.py b/backend/main.py
index ce13175..e3f0069 100644
--- a/backend/main.py
+++ b/backend/main.py
@@ -85,6 +85,7 @@ def handle_create_clip(task_id: str, params: dict):
clean_fillers=params.get("clean_fillers", True),
face_map=params.get("face_map"),
keep_segments=params.get("keep_segments"),
+ allow_ass_fallback=params.get("allow_ass_fallback", False),
progress_callback=lambda pct, msg: emit_progress(task_id, "processing", pct, msg),
)
emit_result(task_id, "success", data=result)
@@ -120,6 +121,7 @@ def handle_batch_clips(task_id: str, params: dict):
clean_fillers=params.get("clean_fillers", True),
face_map=params.get("face_map"),
keep_segments=clip.get("keep_segments"),
+ allow_ass_fallback=clip.get("allow_ass_fallback", params.get("allow_ass_fallback", False)),
progress_callback=lambda pct, msg, _i=i: emit_progress(
task_id, "batch", int((_i / total) * 100 + pct / total), msg
),
diff --git a/remotion/render.mjs b/remotion/render.mjs
index 0dfa6ce..45368cf 100644
--- a/remotion/render.mjs
+++ b/remotion/render.mjs
@@ -214,7 +214,8 @@ async function main() {
const cpus = os.cpus().length;
const concurrency = Math.max(2, Math.min(cpus, 8));
// Store overlay in /tmp to survive temp dir cleanup
- const overlayId = path.basename(opts.output, ".mp4");
+ const overlaySeed = `${path.resolve(opts.output)}:${process.pid}:${Date.now()}`;
+ const overlayId = crypto.createHash("md5").update(overlaySeed).digest("hex").slice(0, 12);
const captionOverlay = path.join(os.tmpdir(), `remotion_overlay_${overlayId}.mov`);
let lastPct = -1;
diff --git a/src/handlers/batch-clips.handler.ts b/src/handlers/batch-clips.handler.ts
index cf1e69e..16242fd 100644
--- a/src/handlers/batch-clips.handler.ts
+++ b/src/handlers/batch-clips.handler.ts
@@ -58,7 +58,10 @@ export const batchClipsToolDef = {
},
crop_strategy: {
type: "string",
- enum: ["center", "face"],
+ enum: ["center", "face", "speaker"],
+ },
+ allow_ass_fallback: {
+ type: "boolean",
},
},
required: ["start_second", "end_second"],
@@ -70,6 +73,12 @@ export const batchClipsToolDef = {
"Remove filler words (um, uh, hmm) from captions and compress long silences. Default: true",
default: true,
},
+ allow_ass_fallback: {
+ type: "boolean",
+ description:
+ "Allow fallback to legacy ASS captions if Remotion caption rendering fails. Default: false.",
+ default: false,
+ },
transcript_words: {
type: "array",
description:
@@ -122,7 +131,8 @@ export async function handleBatchClips(
title: s.title || `clip_${num}`,
caption_style:
(s.suggested_caption_style as string) || settings.captionStyle || "hormozi",
- crop_strategy: settings.cropStrategy || "face",
+ crop_strategy: settings.cropStrategy || "speaker",
+ allow_ass_fallback: input.allow_ass_fallback === true,
logo_path: settings.logoPath || null,
// Preserve multi-cut segments from suggestion
...(Array.isArray(s.segments) && s.segments.length > 0 && { keep_segments: s.segments }),
@@ -173,6 +183,7 @@ export async function handleBatchClips(
clips,
transcript_words: transcriptWords,
clean_fillers: input.clean_fillers !== false,
+ allow_ass_fallback: input.allow_ass_fallback === true,
output_dir: paths.output,
logo_path: settings.logoPath || null,
});
diff --git a/src/handlers/create-clip.handler.ts b/src/handlers/create-clip.handler.ts
index 94afad2..3a78452 100644
--- a/src/handlers/create-clip.handler.ts
+++ b/src/handlers/create-clip.handler.ts
@@ -24,7 +24,7 @@ export const createClipToolDef = {
"Output: H.264 MP4 with burned-in captions, normalized audio (-14 LUFS).\n\n" +
"For batch export, use batch_create_clips instead.\n" +
"Caption styles: branded (professional), hormozi (bold/yellow), karaoke (progressive highlight), subtle (minimal).\n" +
- "Crop modes: face (follows the speaker), center (fixed center crop).",
+ "Crop modes: speaker (speaker-aware), face (face tracking), center (fixed center crop).",
inputSchema: {
type: "object" as const,
properties: {
@@ -57,7 +57,7 @@ export const createClipToolDef = {
},
crop_strategy: {
type: "string",
- enum: ["center", "face"],
+ enum: ["center", "face", "speaker"],
description:
"How to crop to vertical. Auto-loaded from session settings if omitted.",
},
@@ -91,6 +91,12 @@ export const createClipToolDef = {
"Remove filler words (um, uh, hmm) from captions and compress long silences. Default: true",
default: true,
},
+ allow_ass_fallback: {
+ type: "boolean",
+ description:
+ "Allow fallback to legacy ASS captions if Remotion caption rendering fails. Default: false.",
+ default: false,
+ },
outro_path: {
type: "string",
description: "Path to an outro video to append at the end of the clip",
@@ -139,7 +145,7 @@ export async function handleCreateClip(
settings.captionStyle ||
"hormozi";
const cropStrategy =
- (input.crop_strategy as string) || settings.cropStrategy || "face";
+ (input.crop_strategy as string) || settings.cropStrategy || "speaker";
const logoPath =
(input.logo_path as string) || settings.logoPath || null;
const outroPath =
@@ -173,6 +179,7 @@ export async function handleCreateClip(
title,
output_dir: paths.output,
clean_fillers: input.clean_fillers !== false,
+ allow_ass_fallback: input.allow_ass_fallback === true,
logo_path: logoPath,
outro_path: outroPath,
...(keepSegments && { keep_segments: keepSegments }),
diff --git a/src/models/index.ts b/src/models/index.ts
index 2fc7953..9b5622d 100644
--- a/src/models/index.ts
+++ b/src/models/index.ts
@@ -68,7 +68,7 @@ export interface TranscriptResult {
// === Clip Models ===
export type CaptionStyle = "branded" | "hormozi" | "karaoke" | "subtle";
-export type CropStrategy = "center" | "face";
+export type CropStrategy = "center" | "face" | "speaker";
export interface ClipRequest {
video_path: string;
diff --git a/src/server.ts b/src/server.ts
index 8828cbe..cc6b844 100644
--- a/src/server.ts
+++ b/src/server.ts
@@ -271,10 +271,15 @@ export function createServer(): McpServer {
.default("hormozi")
.describe("Caption style"),
crop_strategy: z
- .enum(["center", "face"])
+ .enum(["center", "face", "speaker"])
.optional()
- .default("face")
+ .default("speaker")
.describe("Cropping strategy"),
+ allow_ass_fallback: z
+ .boolean()
+ .optional()
+ .default(false)
+ .describe("Allow ASS caption fallback if Remotion rendering fails (default: false)"),
transcript_words: z
.array(
z.object({
@@ -344,7 +349,7 @@ export function createServer(): McpServer {
params.start_second as number,
params.end_second as number,
(params.caption_style || "hormozi") as string,
- (params.crop_strategy || "face") as string
+ (params.crop_strategy || "speaker") as string
);
if (dup) {
return {
@@ -369,7 +374,8 @@ export function createServer(): McpServer {
end_second: params.end_second,
title: (params.title || "clip") as string,
caption_style: params.caption_style || "hormozi",
- crop_strategy: params.crop_strategy || "face",
+ crop_strategy: params.crop_strategy || "speaker",
+ allow_ass_fallback: params.allow_ass_fallback === true,
...(keepSegments && { segments: keepSegments }),
}],
transcript_words: params.transcript_words,
@@ -427,7 +433,7 @@ export function createServer(): McpServer {
start_second: params.start_second as number,
end_second: params.end_second as number,
caption_style: (params.caption_style || "hormozi") as string,
- crop_strategy: (params.crop_strategy || "face") as string,
+ crop_strategy: (params.crop_strategy || "speaker") as string,
logo_path: params.logo_path as string | undefined,
title: (params.title || "clip") as string,
output_path: parsed.output_path,
@@ -478,7 +484,8 @@ export function createServer(): McpServer {
end_second: z.number(),
title: z.string().optional(),
caption_style: z.enum(["hormozi", "karaoke", "subtle", "branded"]).optional(),
- crop_strategy: z.enum(["center", "face"]).optional(),
+ crop_strategy: z.enum(["center", "face", "speaker"]).optional(),
+ allow_ass_fallback: z.boolean().optional(),
})
)
.optional()
@@ -522,7 +529,8 @@ export function createServer(): McpServer {
end_second: s.end_second,
title: s.title || `clip_${i + 1}`,
caption_style: (s.suggested_caption_style as string) || settings.captionStyle || "hormozi",
- crop_strategy: settings.cropStrategy || "face",
+ crop_strategy: settings.cropStrategy || "speaker",
+ allow_ass_fallback: false,
...(Array.isArray(s.segments) && s.segments.length > 0 && { keep_segments: s.segments }),
})) as any;
} else if (params.clip_numbers) {
@@ -535,7 +543,8 @@ export function createServer(): McpServer {
end_second: s.end_second,
title: s.title || `clip_${n}`,
caption_style: (s.suggested_caption_style as string) || settings.captionStyle || "hormozi",
- crop_strategy: settings.cropStrategy || "face",
+ crop_strategy: settings.cropStrategy || "speaker",
+ allow_ass_fallback: false,
...(Array.isArray(s.segments) && s.segments.length > 0 && { keep_segments: s.segments }),
};
}) as any;
@@ -609,7 +618,7 @@ export function createServer(): McpServer {
start_second: r.start_second || 0,
end_second: r.end_second || 0,
caption_style: r.caption_style || "hormozi",
- crop_strategy: r.crop_strategy || "face",
+ crop_strategy: r.crop_strategy || "speaker",
title: r.title || "clip",
output_path: r.output_path,
file_size_mb: r.file_size_mb || 0,
@@ -779,7 +788,7 @@ export function createServer(): McpServer {
if (action === "check" && source_video && start_second !== undefined && end_second !== undefined) {
const dup = await history.findDuplicate(
source_video, start_second, end_second,
- caption_style || "hormozi", crop_strategy || "face"
+ caption_style || "hormozi", crop_strategy || "speaker"
);
if (dup) {
return { content: [{ type: "text" as const, text: `Duplicate found: "${dup.title}" created ${dup.created_at}\nOutput: ${dup.output_path}` }] };
@@ -1073,7 +1082,7 @@ export function createServer(): McpServer {
"Update rendering settings (caption style, crop strategy, logo, outro) in the Web UI.",
{
caption_style: z.enum(["hormozi", "karaoke", "subtle", "branded"]).optional().describe("Caption style"),
- crop_strategy: z.enum(["center", "face"]).optional().describe("Cropping strategy"),
+ crop_strategy: z.enum(["center", "face", "speaker"]).optional().describe("Cropping strategy"),
logo_path: z.string().optional().describe("Path or registered asset name for PNG logo"),
outro_path: z.string().optional().describe("Path or registered asset name for outro video"),
},
@@ -1159,7 +1168,7 @@ export function createServer(): McpServer {
name: z.string().optional().describe("Preset name (required for save/load/delete)"),
config: z.object({
caption_style: z.enum(["hormozi", "karaoke", "subtle", "branded"]).optional(),
- crop_strategy: z.enum(["center", "face"]).optional(),
+ crop_strategy: z.enum(["center", "face", "speaker"]).optional(),
logo_path: z.string().optional(),
outro_path: z.string().optional(),
}).optional().describe("Preset config (for save action)"),
diff --git a/src/ui/public/index.html b/src/ui/public/index.html
index e89a1d1..99ff741 100644
--- a/src/ui/public/index.html
+++ b/src/ui/public/index.html
@@ -209,7 +209,7 @@
const [timeAdjust, setTimeAdjust] = useState(-1);
const [whisperModel, setWhisperModel] = useState('base');
const [captionStyle, setCaptionStyle] = useState('branded');
- const [cropStrategy, setCropStrategy] = useState('face');
+ const [cropStrategy, setCropStrategy] = useState('speaker');
const [logoPath, setLogoPath] = useState('');
const logoRef = useRef();
const [outroPath, setOutroPath] = useState('');
@@ -1003,7 +1003,7 @@
<div>
<label className="field-label">Crop</label>
<select value={cropStrategy} onChange={e => onCropChange(e.target.value)} disabled={isProcessing}>
- <option value="center">Center</option><option value="face">Face Detection</option>
+ <option value="speaker">Speaker Aware</option><option value="face">Face Detection</option><option value="center">Center</option>
</select>
</div>
</div>
@@ -1501,4 +1501,4 @@
</script>
</body>
-</html>
\ No newline at end of file
+</html>
diff --git a/src/ui/web-server.ts b/src/ui/web-server.ts
index 3aa0da7..5904d4f 100644
--- a/src/ui/web-server.ts
+++ b/src/ui/web-server.ts
@@ -102,7 +102,7 @@ function loadPersistedState(): UIState {
deselectedIndices: saved.deselectedIndices || [],
settings: {
captionStyle: saved.settings?.captionStyle || "branded",
- cropStrategy: saved.settings?.cropStrategy || "face",
+ cropStrategy: saved.settings?.cropStrategy || "speaker",
logoPath: saved.settings?.logoPath || "",
outroPath: saved.settings?.outroPath || "",
},
@@ -119,7 +119,7 @@ function loadPersistedState(): UIState {
rawTranscriptText: "",
suggestions: [],
deselectedIndices: [],
- settings: { captionStyle: "branded", cropStrategy: "face", logoPath: "", outroPath: "" },
+ settings: { captionStyle: "branded", cropStrategy: "speaker", logoPath: "", outroPath: "" },
phase: "idle",
lastUpdated: 0,
};
@@ -411,12 +411,13 @@ app.post("/api/create-clip", async (req, res) => {
start_second,
end_second,
caption_style = "hormozi",
- crop_strategy = "face",
+ crop_strategy = "speaker",
transcript_words = [],
title = "clip",
logo_path = null,
outro_path = null,
clean_fillers = false,
+ allow_ass_fallback = false,
} = req.body;
if (!video_path || !existsSync(video_path)) {
@@ -451,7 +452,7 @@ app.post("/api/create-clip", async (req, res) => {
res.status(400).json({ error: `Invalid caption style. Use: ${validStyles.join(", ")}` });
return;
}
- const validCrops = ["center", "face"];
+ const validCrops = ["center", "face", "speaker"];
if (!validCrops.includes(crop_strategy)) {
res.status(400).json({ error: `Invalid crop strategy. Use: ${validCrops.join(", ")}` });
return;
@@ -487,6 +488,7 @@ app.post("/api/create-clip", async (req, res) => {
logo_path,
outro_path,
clean_fillers,
+ allow_ass_fallback,
},
(event) => {
job.progress = event.percent;
@@ -604,7 +606,7 @@ app.post("/api/batch-clips", async (req, res) => {
start_second: r.start_second || 0,
end_second: r.end_second || 0,
caption_style: r.caption_style || "hormozi",
- crop_strategy: r.crop_strategy || "face",
+ crop_strategy: r.crop_strategy || "speaker",
title: r.title || "clip",
output_path: r.output_path,
file_size_mb: r.file_size_mb || 0,
@@ -991,7 +993,7 @@ app.get("/api/history", async (req, res) => {
app.get("/api/history/check", async (req, res) => {
try {
- const { source, start, end, style = "hormozi", crop = "face" } = req.query;
+ const { source, start, end, style = "hormozi", crop = "speaker" } = req.query;
if (!source || !start || !end) {
res.json({ duplicate: null });
return;
@@ -1456,7 +1458,8 @@ app.post("/api/mcp/export", async (req, res) => {
const logoPath = req.body.logo_path || uiState.settings.logoPath || null;
const outroPath = req.body.outro_path || (uiState.settings as any).outroPath || null;
const captionStyle = req.body.caption_style || uiState.settings.captionStyle || "branded";
- const cropStrategy = req.body.crop_strategy || uiState.settings.cropStrategy || "face";
+ const cropStrategy = req.body.crop_strategy || uiState.settings.cropStrategy || "speaker";
+ const allowAssFallback = req.body.allow_ass_fallback === true;
if (!videoPath || !existsSync(videoPath)) {
res.status(400).json({ error: "Video file not found" });
@@ -1476,6 +1479,7 @@ app.post("/api/mcp/export", async (req, res) => {
title: (c.title || "clip").slice(0, 40),
caption_style: c.caption_style || captionStyle,
crop_strategy: c.crop_strategy || cropStrategy,
+ allow_ass_fallback: c.allow_ass_fallback === true || allowAssFallback,
// Preserve multi-cut segments from suggestions
...(Array.isArray(c.segments) && c.segments.length > 0 && { keep_segments: c.segments }),
}));
diff --git a/tests/test_cli_output_dir.py b/tests/test_cli_output_dir.py
new file mode 100644
index 0000000..ad2845f
--- /dev/null
+++ b/tests/test_cli_output_dir.py
@@ -0,0 +1,104 @@
+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)
+
+import cli as cli_mod
+
+
+class CliOutputDirTests(unittest.TestCase):
+ def test_resolve_output_dir_uses_preset_subfolder_by_default(self):
+ output_dir = cli_mod._resolve_output_dir(
+ video_path="/Users/nik/Downloads/episode.mp4",
+ preset_name="deeptech-show",
+ configured_output_dir="",
+ explicit_output_dir=None,
+ )
+
+ self.assertEqual(output_dir, "/Users/nik/Downloads/clips/deeptech-show")
+
+ def test_resolve_output_dir_uses_configured_root_with_preset_subfolder(self):
+ output_dir = cli_mod._resolve_output_dir(
+ video_path="/Users/nik/Downloads/episode.mp4",
+ preset_name="deeptech-show",
+ configured_output_dir="/Users/nik/Downloads/renders",
+ explicit_output_dir=None,
+ )
+
+ self.assertEqual(output_dir, "/Users/nik/Downloads/renders/deeptech-show")
+
+ def test_resolve_output_dir_keeps_explicit_output_exact(self):
+ output_dir = cli_mod._resolve_output_dir(
+ video_path="/Users/nik/Downloads/episode.mp4",
+ preset_name="deeptech-show",
+ configured_output_dir="/Users/nik/Downloads/renders",
+ explicit_output_dir="/Users/nik/Downloads/custom-job",
+ )
+
+ self.assertEqual(output_dir, "/Users/nik/Downloads/custom-job")
+
+ def test_resolve_output_dir_avoids_double_appending_preset_name(self):
+ output_dir = cli_mod._resolve_output_dir(
+ video_path="/Users/nik/Downloads/episode.mp4",
+ preset_name="deeptech-show",
+ configured_output_dir="/Users/nik/Downloads/renders/deeptech-show",
+ explicit_output_dir=None,
+ )
+
+ self.assertEqual(output_dir, "/Users/nik/Downloads/renders/deeptech-show")
+
+ def test_has_successful_results_true_when_output_exists(self):
+ self.assertTrue(
+ cli_mod._has_successful_results(
+ [
+ {"status": "error", "error": "boom"},
+ {"output_path": "/tmp/clip.mp4"},
+ ]
+ )
+ )
+
+ def test_has_successful_results_false_without_outputs(self):
+ self.assertFalse(
+ cli_mod._has_successful_results(
+ [
+ {"status": "error", "error": "boom"},
+ {"status": "error", "error": "still boom"},
+ ]
+ )
+ )
+
+ def test_should_enter_post_render_loop_when_interrupted_with_completed_results(self):
+ should_enter = cli_mod._should_enter_post_render_loop(
+ config={"post_render_review": False},
+ interrupted=True,
+ results=[{"output_path": "/tmp/clip.mp4"}],
+ )
+
+ self.assertTrue(should_enter)
+
+ def test_should_not_enter_post_render_loop_when_interrupted_without_completed_results(self):
+ should_enter = cli_mod._should_enter_post_render_loop(
+ config={"post_render_review": False},
+ interrupted=True,
+ results=[{"status": "error", "error": "boom"}],
+ )
+
+ self.assertFalse(should_enter)
+
+ def test_should_enter_post_render_loop_when_config_enabled(self):
+ should_enter = cli_mod._should_enter_post_render_loop(
+ config={"post_render_review": True},
+ interrupted=False,
+ results=[],
+ )
+
+ self.assertTrue(should_enter)
+
+
+if __name__ == "__main__":
+ unittest.main()