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
#!/usr/bin/env python3
"""
podcli: Python Backend Entry Point
Reads a JSON task request from stdin, dispatches to the appropriate service,
and writes a JSON result to stdout. Progress events go to stderr.
"""
import json
import os
from utils.log import warn as log_warn
import sys
# Windows streams default to cp1252; IPC is UTF-8. stdin matters as much as the
# others: the task JSON arrives from Node, and a curly quote (U+201D) carries byte
# 0x9D, which cp1252 leaves undefined, so decoding it raised UnicodeDecodeError
# before the request was ever parsed.
for _stream in (sys.stdin, sys.stdout, sys.stderr):
if hasattr(_stream, "reconfigure"):
try:
_stream.reconfigure(encoding="utf-8", errors="replace")
except (ValueError, OSError):
pass
# Load .env file (for HF_TOKEN, etc.)
try:
from dotenv import load_dotenv
load_dotenv(os.environ.get("PODCLI_ENV_FILE") or os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", ".env"))
except ImportError:
pass
import threading
import traceback
from version import VERSION
# Serializes event writes so parallel clip workers can't interleave JSON lines.
_emit_lock = threading.Lock()
def emit_progress(task_id: str, stage: str, percent: int, message: str, **extra):
"""Write a progress event to stderr (picked up by TypeScript executor)."""
event = {
"task_id": task_id,
"stage": stage,
"percent": percent,
"message": message,
}
event.update(extra)
with _emit_lock:
print(json.dumps(event), file=sys.stderr, flush=True)
def emit_result(task_id: str, status: str, data=None, error=None):
"""Write the final result to stdout."""
result = {
"task_id": task_id,
"status": status,
}
if data is not None:
result["data"] = data
if error is not None:
result["error"] = error
with _emit_lock:
print(json.dumps(result), flush=True)
def handle_ping(task_id: str, params: dict):
"""Simple health check."""
emit_result(task_id, "success", data={"message": "pong", "version": VERSION})
def handle_resolve_transcribe_engine(task_id: str, params: dict):
"""Predict transcribe_file's engine resolution without transcribing, so
callers can build the right cache key before deciding whether to run it."""
from services.transcription import resolve_engine_info
emit_result(
task_id,
"success",
data=resolve_engine_info(params.get("engine"), params.get("model_size", "base")),
)
def handle_transcribe(task_id: str, params: dict):
"""Transcribe a podcast video/audio file with speaker detection."""
from services.transcription import transcribe_file
from services.corrections import apply_corrections
from services.transcript_packer import compute_cache_hash, cache_key_suffix, write_packed
emit_progress(task_id, "transcribing", 0, "Starting transcription...")
file_path = params["file_path"]
engine = params.get("engine")
model_size = params.get("model_size", "base")
language = params.get("language")
previous_engine = os.environ.get("PODCLI_ENGINE")
previous_assemblyai_key = os.environ.get("ASSEMBLYAI_API_KEY")
if engine:
os.environ["PODCLI_ENGINE"] = engine
if params.get("assemblyai_api_key"):
os.environ["ASSEMBLYAI_API_KEY"] = params["assemblyai_api_key"]
start_seconds = params.get("start_seconds")
duration_seconds = params.get("duration_seconds")
# Matches src/handlers/transcribe.handler.ts and web-server.ts exactly:
# a sample is a *positive* window, not merely a present key. A caller
# that explicitly passes null (dropped by JSON on the TS side, but
# still visible here as None) or duration_seconds: 0 must get the full
# transcription path, the same as not passing the field at all.
is_sample = (duration_seconds or 0) > 0 or (start_seconds or 0) > 0
# One shared 16 kHz mono wav feeds transcription, energy and reactions
# instead of decoding the source three times. Skipped for a sample run:
# transcribe_file extracts its own trimmed window, and decoding the full
# source here would undo the whole point of a quick sample.
shared_wav = None
if not is_sample:
try:
from services.audio_extract import extract_wav_16k_mono
shared_wav = extract_wav_16k_mono(file_path)
except Exception:
shared_wav = None
try:
result = transcribe_file(
file_path=file_path,
model_size=params.get("model_size", "base"),
engine=engine,
language=params.get("language"),
enable_diarization=params.get("enable_diarization", True),
num_speakers=params.get("num_speakers"),
start_seconds=start_seconds,
duration_seconds=duration_seconds,
progress_callback=lambda pct, msg: emit_progress(task_id, "transcribing", pct, msg),
wav_path=shared_wav,
)
# Apply word corrections (Whisper misheard proper nouns)
apply_corrections(result.get("words", []), result.get("segments", []))
# A sample is a throwaway language/quality check on a slice of the
# source. Energy/event signals and the packed view are keyed by the
# full file and meant to describe the whole episode, so skip them
# rather than caching partial (or source-wide-but-wrongly-expensive)
# data under those keys.
if not is_sample:
energy_data = None
try:
from services.audio_analyzer import extract_audio_energy
energy_data = extract_audio_energy(file_path, wav_path=shared_wav)
except Exception:
pass # energy is a nice-to-have
events_data = None
try:
from services.audio_events import extract_audio_events
events_data = extract_audio_events(file_path, wav_path=shared_wav)
except Exception:
pass # reactions are a nice-to-have
# Cached so clip suggestion reuses these instead of decoding the source again.
from services.signal_cache import save_signals
save_signals(file_path, energy_data=energy_data, events_data=events_data)
# Auto-pack: emit compact LLM-readable markdown alongside raw JSON.
# Pulls energy data so the packed view includes peak moments for clip reasoning.
try:
cache_hash = compute_cache_hash(file_path) + cache_key_suffix(
engine=result.get("engine") or engine, model=model_size, language=language
)
packed_path, packed_md = write_packed(
result,
cache_hash,
source_label=os.path.basename(file_path),
energy_data=energy_data,
events_data=events_data,
)
result["packed_path"] = packed_path
result["packed_size_bytes"] = len(packed_md.encode("utf-8"))
except Exception as e:
# Non-fatal: transcription result is still useful without the packed view
emit_progress(task_id, "packing", 99, f"Packer skipped: {e}")
finally:
if previous_engine is None:
os.environ.pop("PODCLI_ENGINE", None)
else:
os.environ["PODCLI_ENGINE"] = previous_engine
if previous_assemblyai_key is None:
os.environ.pop("ASSEMBLYAI_API_KEY", None)
else:
os.environ["ASSEMBLYAI_API_KEY"] = previous_assemblyai_key
if shared_wav and os.path.exists(shared_wav):
try:
os.unlink(shared_wav)
except OSError:
pass
emit_result(task_id, "success", data=result)
def handle_create_clip(task_id: str, params: dict):
"""Create a single finished short-form clip."""
from services.clip_generator import generate_clip
from services import asset_store
emit_progress(task_id, "starting", 0, "Preparing clip...")
result = generate_clip(
video_path=params["video_path"],
start_second=params["start_second"],
end_second=params["end_second"],
caption_style=params.get("caption_style", "hormozi"),
caption_position=params.get("caption_position", "auto"),
caption_font_scale=params.get("caption_font_scale", 100),
logo_position=params.get("logo_position", "top-left"),
topic=params.get("topic"),
progress=params.get("progress"),
cards=params.get("cards"),
brand=params.get("brand"),
font_family=params.get("font_family"),
crop_strategy=params.get("crop_strategy", "face"),
format=params.get("format", "vertical"),
crop_keyframes=params.get("crop_keyframes"),
transcript_words=params.get("transcript_words", []),
title=params.get("title", "clip"),
output_dir=params.get("output_dir"),
logo_path=asset_store.resolve(params.get("logo_path")),
outro_path=asset_store.resolve(params.get("outro_path")),
intro_path=asset_store.resolve(params.get("intro_path")),
name_card=params.get("name_card"),
motion=params.get("motion"),
bookend_fade=params.get("bookend_fade", 0.0),
clean_fillers=params.get("clean_fillers", True),
face_map=params.get("face_map"),
keep_segments=params.get("keep_segments"),
hook=params.get("hook"),
trim_opening=params.get("trim_opening"),
preserve_timing=params.get("preserve_timing", False),
allow_ass_fallback=params.get("allow_ass_fallback", False),
use_ass_captions=params.get("use_ass_captions", False),
keep_caption_overlay=params.get("keep_caption_overlay", False),
write_clean_variant=params.get("write_clean_variant", False),
progress_callback=lambda pct, msg: emit_progress(task_id, "processing", pct, msg),
)
emit_result(task_id, "success", data=result)
def _render_concurrency() -> int:
raw = (os.environ.get("PODCLI_RENDER_CONCURRENCY") or "").strip()
if raw:
try:
return max(1, int(raw))
except ValueError:
pass
return 2 if (os.cpu_count() or 1) >= 8 else 1
def handle_batch_clips(task_id: str, params: dict):
"""Create multiple clips with a bounded worker pool."""
from concurrent.futures import ThreadPoolExecutor
from services.clip_generator import generate_clip
from services import asset_store
clips = params["clips"]
total = len(clips)
results = [None] * total
completed = 0
completed_lock = threading.Lock()
def render_one(i: int, clip: dict) -> dict:
emit_progress(
task_id,
"batch",
int((i / total) * 100),
f"Processing clip {i + 1}/{total}...",
)
result = generate_clip(
video_path=params["video_path"],
start_second=clip["start_second"],
end_second=clip["end_second"],
caption_style=clip.get("caption_style", "hormozi"),
caption_position=clip.get("caption_position", params.get("caption_position", "auto")),
caption_font_scale=clip.get("caption_font_scale", params.get("caption_font_scale", 100)),
logo_position=clip.get("logo_position", params.get("logo_position", "top-left")),
topic=clip.get("topic", params.get("topic")),
progress=clip.get("progress", params.get("progress")),
cards=clip.get("cards", params.get("cards")),
brand=clip.get("brand", params.get("brand")),
font_family=clip.get("font_family", params.get("font_family")),
crop_strategy=clip.get("crop_strategy", "face"),
format=clip.get("format", params.get("format", "vertical")),
transcript_words=params.get("transcript_words", []),
title=clip.get("title", f"clip_{i + 1}"),
output_dir=params.get("output_dir"),
logo_path=asset_store.resolve(clip.get("logo_path") or params.get("logo_path")),
outro_path=asset_store.resolve(params.get("outro_path")),
intro_path=asset_store.resolve(clip.get("intro_path") or params.get("intro_path")),
name_card=clip.get("name_card") or params.get("name_card"),
motion=clip.get("motion") or params.get("motion"),
bookend_fade=params.get("bookend_fade", 0.0),
clean_fillers=params.get("clean_fillers", True),
face_map=params.get("face_map"),
keep_segments=clip.get("keep_segments"),
hook=clip.get("hook"),
allow_ass_fallback=clip.get("allow_ass_fallback", params.get("allow_ass_fallback", False)),
use_ass_captions=clip.get("use_ass_captions", params.get("use_ass_captions", False)),
keep_caption_overlay=clip.get(
"keep_caption_overlay", params.get("keep_caption_overlay", False)
),
write_clean_variant=clip.get(
"write_clean_variant", params.get("write_clean_variant", False)
),
progress_callback=lambda pct, msg, _i=i: emit_progress(
task_id, "batch", int((_i / total) * 100 + pct / total), msg
),
)
return {
"clip_index": i,
"status": "success",
"start_second": clip["start_second"],
"end_second": clip["end_second"],
**result,
}
def run_and_record(i: int, clip: dict) -> None:
nonlocal completed
try:
row = results[i] = render_one(i, clip)
message = f"Clip {i + 1}/{total} complete"
except Exception as e:
row = results[i] = {
"clip_index": i,
"status": "error",
"start_second": clip.get("start_second"),
"end_second": clip.get("end_second"),
"error": str(e),
}
message = f"Clip {i + 1}/{total} failed"
with completed_lock:
completed += 1
done = completed
emit_progress(
task_id,
"clip_complete",
int((done / total) * 100),
message,
clip_result=row,
)
workers = min(_render_concurrency(), max(1, total))
if workers <= 1:
for i, clip in enumerate(clips):
run_and_record(i, clip)
else:
with ThreadPoolExecutor(max_workers=workers) as pool:
futures = [pool.submit(run_and_record, i, clip) for i, clip in enumerate(clips)]
for f in futures:
f.result()
emit_result(
task_id,
"success",
data={
"results": results,
"total_clips": total,
"successful_clips": sum(1 for r in results if r and r["status"] == "success"),
},
)
def handle_parse_transcript(task_id: str, params: dict):
"""Parse a speaker-labeled transcript into word-level timestamps."""
import hashlib
from services.transcript_parser import detect_and_parse
from services.corrections import apply_corrections
from services.transcript_packer import write_packed
raw_text = params.get("raw_text", "")
total_duration = params.get("total_duration")
time_adjust = params.get("time_adjust", 0.0)
language = params.get("language")
if not raw_text:
emit_result(task_id, "error", error="raw_text is required")
return
emit_progress(task_id, "parsing", 50, "Parsing transcript...")
result = detect_and_parse(
raw_text, total_duration=total_duration, time_adjust=time_adjust, language=language
)
if "error" in result:
emit_result(task_id, "error", error=result["error"])
return
# Apply word corrections (proper nouns, brand names)
apply_corrections(result.get("words", []), result.get("segments", []))
# Auto-pack: key pasted transcripts by content hash since there's no source file.
try:
content_hash = hashlib.sha256(raw_text.encode("utf-8")).hexdigest()[:16]
packed_path, packed_md = write_packed(
result, content_hash, source_label="pasted-transcript"
)
result["packed_path"] = packed_path
result["packed_size_bytes"] = len(packed_md.encode("utf-8"))
result["content_hash"] = content_hash
except Exception as e:
emit_progress(task_id, "packing", 99, f"Packer skipped: {e}")
emit_progress(task_id, "parsing", 100, "Transcript parsed!")
emit_result(task_id, "success", data=result)
def handle_pack_transcript(task_id: str, params: dict):
"""Pack a transcript dict into LLM-readable markdown. Used to backfill
the packed view for caches that predate auto-packing."""
from services.transcript_packer import write_packed
transcript = params.get("transcript")
cache_hash = params.get("cache_hash")
if not transcript or not cache_hash:
emit_result(task_id, "error", error="transcript and cache_hash are required")
return
energy_data = params.get("energy_data")
events_data = params.get("events_data")
if params.get("file_path"):
if energy_data is None:
try:
from services.audio_analyzer import extract_audio_energy
energy_data = extract_audio_energy(params["file_path"])
except Exception as exc:
log_warn("main", "audio energy extraction failed", error=exc)
if events_data is None:
try:
from services.audio_events import extract_audio_events
events_data = extract_audio_events(params["file_path"])
except Exception as exc:
log_warn("main", "audio event extraction failed", error=exc)
path, md = write_packed(
transcript,
cache_hash,
source_label=params.get("source_label"),
energy_data=energy_data,
events_data=events_data,
)
emit_result(task_id, "success", data={
"packed_path": path,
"size_bytes": len(md.encode("utf-8")),
})
def handle_analyze_energy(task_id: str, params: dict):
"""Analyze audio energy of a video to improve clip scoring."""
from services.audio_analyzer import get_energy_profile
video_path = params.get("video_path", "")
segments = params.get("segments", [])
if not video_path:
emit_result(task_id, "error", error="video_path is required")
return
result = get_energy_profile(
video_path=video_path,
segments=segments,
progress_callback=lambda pct, msg: emit_progress(task_id, "analyzing", pct, msg),
)
emit_result(task_id, "success", data=result)
def handle_detect_highlights(task_id: str, params: dict):
"""Detect highlight clips from a video's fused signal curve (party/action profiles).
Accepts a single `video_path`, or a list of `video_paths` to pool and rank
highlights across a whole folder of clips.
"""
from services.saliency import detect_highlights, detect_highlights_pooled
video_paths = params.get("video_paths")
video_path = params.get("video_path", "")
if not video_paths and not video_path:
emit_result(task_id, "error", error="video_path or video_paths is required")
return
common = dict(
profile_name=params.get("profile", "party"),
min_dur=float(params.get("min_dur", 8.0)),
max_dur=float(params.get("max_dur", 60.0)),
progress_callback=lambda pct, msg: emit_progress(task_id, "detecting", pct, msg),
)
if video_paths:
clips = detect_highlights_pooled(
video_paths=video_paths, top_n=int(params.get("top_n", 15)), **common
)
else:
clips = detect_highlights(
video_path=video_path, top_n=int(params.get("top_n", 8)), **common
)
emit_result(task_id, "success", data={"clips": clips, "count": len(clips)})
def handle_manage_reel(task_id: str, params: dict):
"""Create and iterate on a highlights reel: the MCP surface over the reel service.
Actions: new (detect + build), list, show, edit (adjust one moment + rebuild),
build, delete.
"""
import hashlib
from dataclasses import asdict
from services.reel import (
ReelSession, seed_session, seed_session_pooled, edit_moment, build_reel,
list_sessions, delete_session,
)
action = params.get("action", "show")
def payload(session, reel=None):
moments = []
for i, m in enumerate(session.moments, 1):
d = asdict(m)
d["clip_path"] = os.path.join(session.out_dir, "clips", f"clip_{i:02d}.mp4")
d["clip_exists"] = os.path.exists(d["clip_path"])
moments.append(d)
reel_file = reel or os.path.join(session.out_dir, "highlights_reel.mp4")
sources = sorted({m.source for m in session.moments if m.source}) or [session.source]
return {
"session_id": session.session_id,
"source": session.source,
"sources": sources,
"format": session.format,
"logo": session.logo,
"out_dir": session.out_dir,
"reel_path": reel_file if os.path.exists(reel_file) else None,
"moments": moments,
}
try:
if action == "new":
from services.transcript_packer import compute_cache_hash, load_cached_transcript_for_video
video_paths = params.get("video_paths") or []
# Auto lets the saliency threshold decide how many moments clear the bar,
# capped for sanity, with a wide length range so windows aren't constrained.
auto = bool(params.get("auto"))
from services import asset_store
common = dict(
profile=params.get("profile", "auto"),
format=params.get("format", "horizontal"),
top_n=50 if auto else int(params.get("top_n", 10)),
min_dur=5.0 if auto else float(params.get("min_dur", 15.0)),
max_dur=120.0 if auto else float(params.get("max_dur", 60.0)),
logo=params.get("logo") or asset_store.default_logo() or "",
progress_callback=lambda p, m: emit_progress(task_id, "detecting", p, m),
)
if video_paths:
sid = hashlib.sha256("\n".join(sorted(video_paths)).encode()).hexdigest()[:16]
out_dir = params.get("out_dir") or os.path.join(os.getcwd(), f"reel_{sid[:8]}")
session = seed_session_pooled(sid, video_paths, out_dir, **common)
else:
video = params["video_path"]
sid = compute_cache_hash(video)
out_dir = params.get("out_dir") or os.path.join(os.getcwd(), f"reel_{sid[:8]}")
cached = load_cached_transcript_for_video(video)
words = cached.get("words") if cached else None
session = seed_session(sid, video, out_dir, words=words, **common)
reel = build_reel(session, progress_callback=lambda p, m: emit_progress(task_id, "building", p, m))
emit_result(task_id, "success", data=payload(session, reel))
elif action == "list":
emit_result(task_id, "success", data={"sessions": list_sessions()})
elif action == "delete":
ok = delete_session(params["session_id"])
emit_result(task_id, "success", data={"deleted": ok, "session_id": params["session_id"]})
elif action == "show":
emit_result(task_id, "success", data=payload(ReelSession.load(params["session_id"])))
elif action == "edit":
session = edit_moment(
ReelSession.load(params["session_id"]),
int(params["index"]), params["op"], float(params.get("seconds", 0.0)),
start=params.get("start"), end=params.get("end"),
)
reel = build_reel(session, progress_callback=lambda p, m: emit_progress(task_id, "building", p, m))
emit_result(task_id, "success", data=payload(session, reel))
elif action == "build":
session = ReelSession.load(params["session_id"])
if "logo" in params:
session.logo = params.get("logo") or ""
for mm in session.moments:
mm.dirty = True
reel = build_reel(session, progress_callback=lambda p, m: emit_progress(task_id, "building", p, m))
emit_result(task_id, "success", data=payload(session, reel))
else:
emit_result(task_id, "error", error=f"unknown reel action {action!r}")
except (KeyError, IndexError, ValueError, FileNotFoundError) as e:
emit_result(task_id, "error", error=str(e))
def handle_detect_encoder(task_id: str, params: dict):
"""Detect available hardware encoders."""
from services.encoder import get_encoder_info
emit_result(task_id, "success", data=get_encoder_info())
def handle_presets(task_id: str, params: dict):
"""Manage presets (list, get, save, delete)."""
from presets import list_presets, get_preset, save_preset, delete_preset
action = params.get("action", "list")
name = params.get("name", "default")
if action == "list":
emit_result(task_id, "success", data={"presets": list_presets()})
elif action in ("get", "load"): # MCP manage_presets uses "load"
try:
preset = get_preset(name)
emit_result(task_id, "success", data={"config": preset, "name": name})
except FileNotFoundError as e:
emit_result(task_id, "error", error=str(e))
elif action == "save":
config = params.get("config", {})
path = save_preset(name, config)
emit_result(task_id, "success", data={"path": path, "name": name})
elif action == "delete":
ok = delete_preset(name)
emit_result(task_id, "success", data={"deleted": ok})
else:
emit_result(task_id, "error", error=f"Unknown presets action: {action}")
def handle_corrections(task_id: str, params: dict):
"""Manage transcript word corrections (get, set, add, remove)."""
from services.corrections import get_corrections, save_corrections
action = params.get("action", "get")
if action == "get":
emit_result(task_id, "success", data={"corrections": get_corrections()})
elif action == "set":
corrections = params.get("corrections", {})
path = save_corrections(corrections)
emit_result(task_id, "success", data={"corrections": corrections, "path": path})
elif action == "add":
wrong = params.get("wrong", "")
correct = params.get("correct", "")
if not wrong or not correct:
emit_result(task_id, "error", error="'wrong' and 'correct' are required")
return
current = get_corrections()
current[wrong] = correct
save_corrections(current)
emit_result(task_id, "success", data={"corrections": current})
elif action == "remove":
wrong = params.get("wrong", "")
current = get_corrections()
current.pop(wrong, None)
save_corrections(current)
emit_result(task_id, "success", data={"corrections": current})
else:
emit_result(task_id, "error", error=f"Unknown corrections action: {action}")
def _extract_signals(
task_id: str,
video_path: str,
want_energy: bool,
want_events: bool,
) -> tuple[list | None, list | None]:
"""Decode the source once and derive whichever profiles aren't cached yet."""
from services.audio_events import is_available as audio_events_available
want_events = want_events and audio_events_available()
if not want_energy and not want_events:
return None, None
wav_path = None
try:
from services.audio_extract import extract_wav_16k_mono
emit_progress(task_id, "suggesting", 2, "Extracting audio...")
wav_path = extract_wav_16k_mono(video_path)
except Exception:
wav_path = None
energy_data = None
events_data = None
try:
if want_energy:
emit_progress(task_id, "suggesting", 5, "Analyzing audio energy...")
try:
from services.audio_analyzer import extract_audio_energy
energy_data = extract_audio_energy(video_path, wav_path=wav_path)
except Exception:
pass # energy is a nice-to-have
if want_events:
emit_progress(task_id, "suggesting", 15, "Detecting laughter and reactions...")
try:
from services.audio_events import extract_audio_events
events_data = extract_audio_events(video_path, wav_path=wav_path)
except Exception:
pass # reactions are a nice-to-have
finally:
if wav_path and os.path.exists(wav_path):
try:
os.unlink(wav_path)
except OSError:
pass
return energy_data, events_data
def _signal_profiles_for_suggest(
task_id: str,
params: dict,
) -> tuple[list | None, list | None, list | None]:
"""Energy and reaction profiles for the suggester: caller-supplied first, then
what transcription cached for this video, and only then a fresh analysis."""
from services.audio_events import reaction_times as reaction_times_from_events
from services.signal_cache import load_signals, save_signals
energy_data = params.get("energy_data")
events_data = params.get("events_data")
anchors = params.get("reaction_times")
if anchors is not None:
anchors = [float(t) for t in anchors]
video_path = params.get("video_path")
if video_path and os.path.exists(video_path) and (energy_data is None or events_data is None):
cached = load_signals(video_path)
if energy_data is None:
energy_data = cached.get("energy_data")
if events_data is None:
events_data = cached.get("events_data")
if energy_data is None or events_data is None:
fresh_energy, fresh_events = _extract_signals(
task_id,
video_path,
want_energy=energy_data is None,
want_events=events_data is None,
)
save_signals(video_path, energy_data=fresh_energy, events_data=fresh_events)
energy_data = energy_data if energy_data is not None else fresh_energy
events_data = events_data if events_data is not None else fresh_events
if anchors is None and events_data:
anchors = reaction_times_from_events(events_data)
return energy_data, events_data, anchors
def handle_suggest_clips(task_id: str, params: dict):
"""AI-powered clip suggestion using Claude/Codex and PodStack knowledge base."""
from services import ai_provider
from services.claude_suggest import (
ClipBounds,
drop_published,
select_clips_with_signal_scores,
suggest_initial_with_claude,
)
segments = params.get("segments", [])
top_n = params.get("top_n", 5)
existing_clips = params.get("existing_clips", [])
bounds = ClipBounds.of(
params.get("format"),
params.get("min_duration"),
params.get("max_duration"),
)
if not segments:
emit_result(task_id, "error", error="segments is required")
return
# Gate on the provider chain, not on a local binary: a signed-in Pro user
# has AI available without installing anything.
if not ai_provider.available():
emit_result(
task_id,
"error",
error=(
"No AI available. Sign in with `podcli login`, install Claude Code "
"or Codex, or set ANTHROPIC_API_KEY."
),
)
return
errors: list[str] = []
energy_data, events_data, reaction_times = _signal_profiles_for_suggest(task_id, params)
candidate_top_n = top_n * 2
clips = suggest_initial_with_claude(
segments=segments,
top_n=candidate_top_n,
exclude_clips=existing_clips,
progress_callback=lambda pct, msg: emit_progress(task_id, "suggesting", pct, msg),
error_sink=errors,
reaction_times=reaction_times,
bounds=bounds,
)
if clips is None:
detail = errors[-1] if errors else "check claude/codex login and try again"
emit_result(task_id, "error", error=detail)
return
clips = select_clips_with_signal_scores(
clips,
top_n=top_n,
energy_data=energy_data,
events_data=events_data,
progress_callback=lambda pct, msg: emit_progress(task_id, "suggesting", pct, msg),
)
emit_result(task_id, "success", data={"clips": drop_published(clips)})
def handle_rank_candidates(task_id: str, params: dict):
"""Sentence-aligned heuristic ranking. Returns a shortlist, not the transcript."""
from services.transcript_packer import load_cached_transcript_for_video
import cli as cli_mod
segments = params.get("segments") or []
video_path = params.get("video_path")
if not segments:
if not video_path:
emit_result(task_id, "error", error="video_path or segments is required")
return
cached = load_cached_transcript_for_video(video_path)
if not cached:
emit_result(
task_id,
"error",
error="No transcript cached for this video. Call transcribe_podcast first.",
)
return
segments = cached.get("segments") or []
if not segments:
emit_result(task_id, "error", error="Transcript has no segments to rank")
return
top_n = int(params.get("top_n") or 20)
top_n = max(1, min(top_n, 40))
emit_progress(task_id, "ranking", 10, f"Ranking up to {top_n} sentence-aligned candidates...")
clips = cli_mod._suggest_clips(segments=segments, top_n=top_n)
candidates = []
for i, clip in enumerate(clips):
preview = clip.get("preview") or clip.get("preview_text") or clip.get("quote") or ""
candidates.append({
"rank": i + 1,
"start_second": clip.get("start_second"),
"end_second": clip.get("end_second"),
"duration": clip.get("duration"),
"score": clip.get("score"),
"title": clip.get("title"),
"preview": str(preview)[:180],
"reasons": clip.get("reasons") or [],
})
emit_result(task_id, "success", data={"count": len(candidates), "candidates": candidates})
def handle_process_episode(task_id: str, params: dict):
"""Run `process` non-interactively and return the --json payload."""
import argparse
import io
import cli as cli_mod
video_path = params.get("video_path") or params.get("file_path")
if not video_path:
emit_result(task_id, "error", error="video_path is required")
return
emit_progress(task_id, "process", 1, "Processing episode...")
args = argparse.Namespace(
video=video_path,
transcript=params.get("transcript"),
top=params.get("top") or params.get("top_n"),
output=params.get("output"),
preset=params.get("preset"),
engine=params.get("engine"),
assemblyai_api_key=params.get("assemblyai_api_key"),
fast=bool(params.get("fast")),
thumbnails=params.get("thumbnails"),
caption_style=params.get("caption_style"),
crop=params.get("crop"),
format=params.get("format"),
profile=params.get("profile"),
logo=params.get("logo"),
outro=params.get("outro"),
no_outro=bool(params.get("no_outro", False)),
intro=params.get("intro"),
time_adjust=params.get("time_adjust"),
no_energy=bool(params.get("no_energy", False)),
no_speakers=bool(params.get("no_speakers", False)),
no_cache=bool(params.get("no_cache", False)),
no_resume=bool(params.get("no_resume", False)),
quality=params.get("quality"),
allow_ass_fallback=bool(params.get("allow_ass_fallback", False)),
review_each=False,
post_review=False,
json=True,
yes=True,
quiet=True,
no_banner=True,
cloud=False,
language=params.get("language"),
template=None,
caption_position=None,
caption_scale=None,
face_map=None,
crop_keyframes=None,
thumbnail_placement=None,
logo_position=None,
logo_scale=None,
topic=None,
progress=False,
progress_color=None,
brand=None,
style=None,
font_family=None,
name_card=None,
motion=None,
bookend_fade=None,
)
buf = io.StringIO()
old_out = sys.stdout
try:
sys.stdout = buf
cli_mod.cmd_process(args)
except SystemExit as exc:
code = exc.code if isinstance(exc.code, int) else 1
if code not in (0, None):
emit_result(task_id, "error", error=f"process exited {code}")
return
finally:
sys.stdout = old_out
raw = buf.getvalue().strip()
payload = None
for line in reversed(raw.splitlines() or [""]):
line = line.strip()
if line.startswith("{"):
try:
payload = json.loads(line)
break
except json.JSONDecodeError:
continue
if payload is None:
emit_result(task_id, "error", error="process finished without a JSON result")
return
emit_result(task_id, "success", data=payload)
def handle_manage_env(task_id: str, params: dict):
"""List/set/unset user secrets in the global .env (e.g. HF_TOKEN)."""
from services.env_settings import run_env_action
try:
data = run_env_action(params.get("action", "list"), params.get("key"), params.get("value"))
except ValueError as e:
emit_result(task_id, "error", error=str(e))
return
emit_result(task_id, "success", data=data)
def handle_ai_cli_status(task_id: str, params: dict):
from services.ai_cli import get_ai_cli_status
emit_result(task_id, "success", data=get_ai_cli_status())
def handle_ai_provider_status(task_id: str, params: dict):
"""Everything podcli can use for AI, not just local binaries, so the studio
can tell "nothing installed" apart from "signed in, nothing needed"."""
from services import ai_provider
emit_result(task_id, "success", data=ai_provider.status())
def handle_find_moment(task_id: str, params: dict):
"""Locate user-pasted/described moments in the transcript via the AI CLI."""
from services.claude_suggest import find_moments_from_text
text = (params.get("text") or params.get("description") or "").strip()
segments = params.get("segments", [])
existing_clips = params.get("existing_clips", [])
max_results = params.get("max_results", 8)
if not text:
emit_result(task_id, "error", error="text is required")
return
if not segments:
emit_result(task_id, "error", error="segments is required")
return
clips = find_moments_from_text(
text,
segments,
existing_clips,
progress_callback=lambda pct, msg: emit_progress(task_id, "searching", pct, msg),
max_results=max_results,
)
emit_result(task_id, "success", data={"clips": clips})
def handle_generate_content(task_id: str, params: dict):
"""Generate titles, descriptions, tags for a clip using PodStack knowledge base."""
from services.content_generator import generate_clip_content
from services import ai_provider
clip = params.get("clip", {})
transcript_segments = params.get("transcript_segments", [])
if not clip:
emit_result(task_id, "error", error="clip is required")
return
# Gate on the provider chain, not on a local binary: a signed-in Pro user
# has AI available without installing anything.
if not ai_provider.available():
emit_result(
task_id,
"error",
error=(
"No AI available. Sign in with `podcli login`, install Claude Code "
"or Codex, or set ANTHROPIC_API_KEY."
),
)
return
result = generate_clip_content(
clip=clip,
transcript_segments=transcript_segments,
progress_callback=lambda pct, msg: emit_progress(task_id, "generating", pct, msg),
mode=params.get("mode", "shorts"),
partial_callback=lambda partial: emit_progress(
task_id, "generating", 60, "Writing content...", partial=partial
),
)
if result is None:
emit_result(
task_id,
"error",
error="Content generation failed: check that your AI provider is reachable and try again",
)
return
emit_result(task_id, "success", data=result)
def handle_generate_custom(task_id: str, params: dict):
"""Run a free-form content request against the AI CLI with KB + transcript context."""
from services.content_generator import generate_custom_content
instruction = str(params.get("instruction", "")).strip()
if not instruction:
emit_result(task_id, "error", error="instruction is required")
return
result = generate_custom_content(
instruction=instruction,
transcript_segments=params.get("transcript_segments", []),
mode=params.get("mode", "shorts"),
progress_callback=lambda pct, msg: emit_progress(task_id, "generating", pct, msg),
)
if result is None:
# The gate above admits a workspace session or an API key as well as a
# local binary, so naming only the binary sends cloud users to install
# something they will never use.
emit_result(task_id, "error", error="No AI provider available: sign in to podcli Pro, install Claude Code or Codex, or set ANTHROPIC_API_KEY")
return
emit_result(task_id, "success", data=result)
def handle_manage_integrations(task_id: str, params: dict):
from services.integrations import IntegrationsManager
manager = IntegrationsManager()
action = params.get("action", "list")
if action == "list":
emit_result(task_id, "success", data={"integrations": manager.list_all()})
return
name = params.get("name", "")
if action in ("enable", "disable"):
try:
manager.set_enabled(name, action == "enable")
emit_result(task_id, "success", data={"name": name, "enabled": action == "enable"})
except ValueError as e:
emit_result(task_id, "error", error=str(e))
return
emit_result(task_id, "error", error=f"Unknown action: {action}")
def handle_manage_config(task_id: str, params: dict):
from config_bundle import run_config_action
try:
data = run_config_action(
params.get("action", "status"),
bundle_path=params.get("bundle_path") or params.get("bundle"),
home=params.get("home"),
activate=bool(params.get("activate", False)),
dry_run=bool(params.get("dry_run", False)),
)
emit_result(task_id, "success", data=data)
except ValueError as e:
emit_result(task_id, "error", error=str(e))
def handle_analyze_silence(task_id: str, params: dict):
"""Analyze a full episode locally and return a conservative cut plan."""
from services.silence_removal import analyze_silence
try:
result = analyze_silence(
video_path=params.get("video_path", ""),
transcript_words=params.get("transcript_words") or [],
threshold=float(params.get("threshold", 0.5)),
min_silence_seconds=float(params.get("min_silence_seconds", 0.65)),
padding_seconds=float(params.get("padding_seconds", 0.12)),
progress_callback=lambda pct, msg: emit_progress(
task_id, "silence_analysis", pct, msg
),
)
emit_result(task_id, "success", data=result)
except (FileNotFoundError, RuntimeError, ValueError) as e:
emit_result(task_id, "error", error=str(e))
def handle_compare_engines(task_id: str, params: dict):
"""Transcribe the same sample window with two engines and report where
they disagree. See services/engine_comparison.py for the scoring."""
import time as _time
from config.paths import paths
from services.engine_comparison import compare_engines
file_path = params.get("file_path", "")
if not file_path or not os.path.exists(file_path):
emit_result(task_id, "error", error=f"File not found: {file_path}")
return
output_dir = params.get("output_dir") or os.path.join(
paths["output"], "engine-comparisons", f"{int(_time.time())}"
)
try:
emit_progress(task_id, "comparing", 10, f"Transcribing with {params.get('engine_a')}...")
report = compare_engines(
file_path,
params.get("engine_a", "whispercpp"),
params.get("engine_b", "whisper-py"),
start_seconds=params.get("start_seconds", 0.0) or 0.0,
duration_seconds=params.get("duration_seconds", 120.0) or 120.0,
window_seconds=params.get("window_seconds", 20.0) or 20.0,
model_size=params.get("model_size", "base"),
language=params.get("language"),
output_dir=output_dir,
)
emit_progress(task_id, "comparing", 100, "Comparison complete")
emit_result(task_id, "success", data=report)
except (FileNotFoundError, RuntimeError, ValueError) as e:
emit_result(task_id, "error", error=str(e))
def handle_render_silence_removed(task_id: str, params: dict):
"""Render the approved local cut plan and remap transcript timestamps."""
from config.paths import paths
from services.silence_removal import render_silence_removed
try:
result = render_silence_removed(
video_path=params.get("video_path", ""),
keep_segments=params.get("keep_segments") or [],
transcript=params.get("transcript") or {},
output_dir=params.get("output_dir") or paths["output"],
progress_callback=lambda pct, msg: emit_progress(
task_id, "silence_render", pct, msg
),
)
emit_result(task_id, "success", data=result)
except (FileNotFoundError, RuntimeError, ValueError) as e:
emit_result(task_id, "error", error=str(e))
MULTICAM_MAP_KEYS = ("people", "sources", "range_start", "range_end", "cut_settings", "speaker_map", "look", "removals")
def handle_manage_multicam(task_id: str, params: dict):
"""Multicam podcast editing: map sources, sync, plan cuts, render, export.
Actions: new (folder or files, people), list, show, map, sync, plan, cut
(swap one shot's camera), set_cuts (replace the whole cut), activity (who
speaks when), previews (stills), preview (playback proxies), render,
export (premiere|fcpxml, review keeps removals in place for an editor to judge),
import_timeline (path: an edited FCP 7 XML timeline becomes the cut and removals), delete.
sync, plan and render apply any mapping fields sent with them first.
"""
from services import multicam as mc
action = params.get("action", "show")
def progress(stage):
return lambda p, m: emit_progress(task_id, stage, p, m)
try:
if action == "list":
emit_result(task_id, "success", data={"sessions": mc.list_sessions()})
return
if action == "new":
session = mc.new_session(
folder=str(params.get("folder") or ""),
files=params.get("files"),
people=params.get("people"),
name=str(params.get("name") or ""),
progress_callback=progress("scanning"),
)
emit_result(task_id, "success", data=mc.payload(session))
return
session_id = params.get("session_id")
if not isinstance(session_id, str) or not session_id:
raise ValueError("session_id is required. Get one from action 'new' or 'list'.")
if action == "delete":
mc.delete_session(session_id)
emit_result(task_id, "success", data={"deleted": True, "session_id": session_id})
return
session = mc.open_session(session_id)
if action == "render" and any(k in params for k in MULTICAM_MAP_KEYS if k != "look"):
# A mapping change can drop the cut, and a render needs one: map, then plan, then render.
raise ValueError("render takes only look and stems. Change the mapping with 'map', then 'plan' again.")
if action in ("map", "sync", "plan", "render") and any(k in params for k in MULTICAM_MAP_KEYS):
session = mc.update_mapping(session, params)
data: dict = {}
if action in ("show", "map"):
pass
elif action == "sync":
session = mc.sync_session(session, force=bool(params.get("force")), progress_callback=progress("syncing"))
elif action == "plan":
session = mc.plan_session(session, progress_callback=progress("planning"))
elif action == "preview":
session = mc.build_preview(session, progress_callback=progress("preview"))
elif action == "activity":
data["activity"] = mc.activity(session)
elif action == "set_cuts":
session = mc.set_cuts(session, params.get("cuts"))
elif action == "cut":
index, source_id = params.get("index"), params.get("source_id")
if not isinstance(index, int) or not isinstance(source_id, str):
raise ValueError("cut needs index (0-based shot number) and source_id (a camera's id)")
session = mc.set_cut(session, index, source_id)
elif action == "previews":
data["previews"] = mc.previews(session, looks=bool(params.get("looks")), at=params.get("at"))
elif action == "render":
stems = params.get("stems", True)
if not isinstance(stems, bool):
raise ValueError("stems is true or false")
validate = params.get("validate", "sample")
if validate not in ("sample", "full"):
raise ValueError("validate must be 'sample' or 'full'")
mc.render_session(session, stems=stems, validate=validate, progress_callback=progress("rendering"))
elif action == "export":
data["export_path"] = mc.export_xml(session, params.get("format", "premiere"), review=bool(params.get("review")))
elif action == "import_timeline":
if not isinstance(params.get("path"), str):
raise ValueError("import_timeline needs path: an FCP 7 XML timeline exported from Premiere or Resolve")
data["imported"] = mc.import_timeline(session, params["path"])
session = mc.MulticamSession.load(session.session_id)
elif action == "cloud":
from services import multicam_cloud
session = multicam_cloud.push(session, progress_callback=progress("sending"))
elif action == "pull":
from services import multicam_cloud
session = multicam_cloud.pull(session)
mc.render_session(session, stems=True, progress_callback=progress("rendering"))
else:
raise ValueError(f"Unknown multicam action {action!r}")
emit_result(task_id, "success", data={**mc.payload(session), **data})
except KeyError as e:
emit_result(task_id, "error", error=f"Missing field {e.args[0]!r}")
except Exception as e:
# Callers get one sentence; the full trace goes to the log, never to a client.
print(traceback.format_exc(), file=sys.stderr, flush=True)
emit_result(task_id, "error", error=str(e) or type(e).__name__)
def handle_run_integration_tool(task_id: str, params: dict):
from services.integrations import IntegrationRegistry, IntegrationsManager
integration_name = params.get("integration", "")
tool_name = params.get("tool", "")
tool_params = params.get("params", {})
manager = IntegrationsManager()
if not manager.is_enabled(integration_name):
emit_result(
task_id,
"error",
error=f"Integration '{integration_name}' is disabled. Enable via manage_integrations.",
)
return
integration = IntegrationRegistry.get(integration_name)
if integration is None:
emit_result(task_id, "error", error=f"Unknown integration: {integration_name}")
return
tool = next((t for t in integration.tools() if t.name == tool_name), None)
if tool is None:
emit_result(task_id, "error", error=f"Unknown tool '{tool_name}' on '{integration_name}'")
return
try:
result = tool.handler(tool_params)
emit_result(task_id, "success", data=result)
except Exception as e:
print(traceback.format_exc(), file=sys.stderr, flush=True)
emit_result(task_id, "error", error=f"{type(e).__name__}: {e}")
TASK_HANDLERS = {
"ping": handle_ping,
"resolve_transcribe_engine": handle_resolve_transcribe_engine,
"transcribe": handle_transcribe,
"compare_engines": handle_compare_engines,
"parse_transcript": handle_parse_transcript,
"create_clip": handle_create_clip,
"batch_clips": handle_batch_clips,
"analyze_energy": handle_analyze_energy,
"detect_highlights": handle_detect_highlights,
"manage_reel": handle_manage_reel,
"pack_transcript": handle_pack_transcript,
"detect_encoder": handle_detect_encoder,
"presets": handle_presets,
"corrections": handle_corrections,
"suggest_clips": handle_suggest_clips,
"rank_candidates": handle_rank_candidates,
"process_episode": handle_process_episode,
"find_moment": handle_find_moment,
"manage_env": handle_manage_env,
"ai_cli_status": handle_ai_cli_status,
"ai_provider_status": handle_ai_provider_status,
"generate_content": handle_generate_content,
"generate_custom": handle_generate_custom,
"manage_integrations": handle_manage_integrations,
"run_integration_tool": handle_run_integration_tool,
"manage_config": handle_manage_config,
"analyze_silence": handle_analyze_silence,
"render_silence_removed": handle_render_silence_removed,
"manage_multicam": handle_manage_multicam,
}
def _maybe_auto_migrate_backend(task_type: str, params: dict) -> None:
if task_type == "manage_config":
action = params.get("action", "status")
if action == "status" or (action == "migrate" and params.get("dry_run")):
return
try:
from config_bundle import auto_migrate_legacy_if_pending
auto_migrate_legacy_if_pending(quiet=True)
except Exception as e:
print(f"Warning: auto-migrate skipped: {e}", file=sys.stderr, flush=True)
def main():
try:
raw = sys.stdin.readline().strip()
if not raw:
emit_result("unknown", "error", error="Empty input")
sys.exit(1)
request = json.loads(raw)
task_id = request.get("task_id", "unknown")
task_type = request.get("task_type", "")
params = request.get("params", {})
_maybe_auto_migrate_backend(task_type, params)
handler = TASK_HANDLERS.get(task_type)
if not handler:
emit_result(task_id, "error", error=f"Unknown task type: {task_type}")
sys.exit(1)
handler(task_id, params)
except Exception as e:
task_id = "unknown"
try:
task_id = json.loads(raw).get("task_id", "unknown")
except Exception as exc:
log_warn("main", "could not read task_id from request", error=exc)
emit_result(task_id, "error", error=f"{type(e).__name__}: {e}\n{traceback.format_exc()}")
sys.exit(1)
if __name__ == "__main__":
main()