Skip to content

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

Add editable highlight-reel sessions (CLI + MCP)

Nika Siradzeba33be9dd4da
diff --git a/backend/cli.py b/backend/cli.py
index 2f53fa9..d6a927e 100644
--- a/backend/cli.py
+++ b/backend/cli.py
@@ -396,6 +396,53 @@ def cmd_studio(args):
sys.exit(rc)
+def cmd_reel(args):
+ """Create and iterate on a highlights reel — detect once, then edit moments fast."""
+ from services.reel import ReelSession, seed_session, edit_moment, build_reel
+ from services.transcript_packer import compute_cache_hash, load_cached_transcript_for_video
+
+ def _mmss(s):
+ return f"{int(s // 60)}:{int(s % 60):02d}"
+
+ def _show(session):
+ for i, m in enumerate(session.moments, 1):
+ flag = "" if m.enabled else " (disabled)"
+ print(f" [{i}] {_mmss(m.start)}-{_mmss(m.end)} ({m.duration:.0f}s, {m.why}){flag}")
+ if m.text:
+ print(" " + (m.text[:150] + "…" if len(m.text) > 150 else m.text))
+
+ action = getattr(args, "reel_action", None)
+ if action == "new":
+ video = _clean_path(args.video)
+ sid = compute_cache_hash(video)
+ out_dir = args.output 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
+ print(" Detecting moments (one-time)...")
+ session = seed_session(
+ sid, video, out_dir, profile=args.profile or "party", top_n=args.top or 10,
+ words=words, progress_callback=lambda p, m: print(f" {m}") if m else None,
+ )
+ _show(session)
+ print(" Building reel...")
+ reel = build_reel(session)
+ print(f" ✓ {reel}")
+ print(f" session: {sid}")
+ print(f" edit with: podcli reel edit {sid} <N> <longer|shorter|earlier|later|shift|drop|toggle> [secs]")
+ elif action == "show":
+ _show(ReelSession.load(args.session))
+ elif action == "edit":
+ session = edit_moment(ReelSession.load(args.session), args.index, args.op, args.seconds)
+ reel = build_reel(session)
+ print(f" ✓ rebuilt {reel}")
+ _show(session)
+ elif action == "build":
+ reel = build_reel(ReelSession.load(args.session))
+ print(f" ✓ {reel}")
+ else:
+ print(" Usage: podcli reel new <video> | show <session> | edit <session> N <op> [secs] | build <session>")
+
+
def cmd_process(args):
"""Full auto pipeline: transcribe → suggest → export."""
from services.clip_generator import generate_clip
@@ -3416,6 +3463,24 @@ def main():
proc.add_argument("--review-each", action="store_true", help="Review each rendered clip interactively")
proc.add_argument("--post-review", action="store_true", help="Open the post-render review loop after export")
+ # ── reel (highlights, detect once then iterate fast) ──
+ reel_p = sub.add_parser("reel", help="Create and iterate on a highlights reel")
+ reel_sub = reel_p.add_subparsers(dest="reel_action")
+ rn = reel_sub.add_parser("new", help="Detect moments and build a reel")
+ rn.add_argument("video", help="Path to the source video")
+ rn.add_argument("--profile", choices=["party", "action"], default="party")
+ rn.add_argument("-n", "--top", type=int, help="Number of moments (default 10)")
+ rn.add_argument("-o", "--output", help="Output directory")
+ rsh = reel_sub.add_parser("show", help="List the moments in a reel session")
+ rsh.add_argument("session", help="Session id (printed by 'reel new')")
+ red = reel_sub.add_parser("edit", help="Adjust one moment and rebuild")
+ red.add_argument("session")
+ red.add_argument("index", type=int, help="1-based moment number")
+ red.add_argument("op", choices=["longer", "shorter", "earlier", "later", "shift", "drop", "toggle"])
+ red.add_argument("seconds", type=float, nargs="?", default=0.0)
+ rbd = reel_sub.add_parser("build", help="Rebuild the reel (re-cuts only changed moments)")
+ rbd.add_argument("session")
+
# ── studio ──
studio = sub.add_parser("studio", help="Cut a fragment + add Remotion intro/outro (follow-us) bookends")
studio.add_argument("video", nargs="?", default=None, help="Path to the source video (omit only with --save-brand)")
@@ -3673,6 +3738,8 @@ def main():
cmd_process(args)
elif args.command == "studio":
cmd_studio(args)
+ elif args.command == "reel":
+ cmd_reel(args)
elif args.command == "thumbnails":
cmd_thumbnails(args)
elif args.command == "thumbnail-config":
diff --git a/backend/main.py b/backend/main.py
index 98a45a9..e99832b 100644
--- a/backend/main.py
+++ b/backend/main.py
@@ -359,6 +359,58 @@ def handle_detect_highlights(task_id: str, params: dict):
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), show, edit (adjust one moment + rebuild), build.
+ """
+ from dataclasses import asdict
+ from services.reel import ReelSession, seed_session, edit_moment, build_reel
+
+ action = params.get("action", "show")
+
+ def payload(session, reel=None):
+ return {
+ "session_id": session.session_id,
+ "out_dir": session.out_dir,
+ "reel_path": reel,
+ "moments": [asdict(m) for m in session.moments],
+ }
+
+ try:
+ if action == "new":
+ from services.transcript_packer import compute_cache_hash, load_cached_transcript_for_video
+ 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, profile=params.get("profile", "party"),
+ top_n=int(params.get("top_n", 10)), words=words,
+ progress_callback=lambda p, m: emit_progress(task_id, "detecting", p, m),
+ )
+ 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 == "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)),
+ )
+ 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"])
+ 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
@@ -653,6 +705,7 @@ TASK_HANDLERS = {
"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,
diff --git a/backend/services/reel.py b/backend/services/reel.py
new file mode 100644
index 0000000..a066b9e
--- /dev/null
+++ b/backend/services/reel.py
@@ -0,0 +1,177 @@
+"""Editable highlight-reel sessions — the shared core behind the CLI, MCP, and UI.
+
+Detection (the slow signal analysis) runs once into a persisted session of moments.
+Every later edit — longer, shorter, shift, drop, reorder — mutates that session and
+re-cuts only the changed moment straight from the source (~seconds), then rebuilds the
+reel. No re-detection, no heavy render. All three surfaces operate on the same session
+so an edit made in one shows up in the others.
+"""
+
+import json
+import os
+import subprocess
+from dataclasses import dataclass, field, asdict
+from typing import Optional, Callable
+
+from utils.proc import run as proc_run
+from config.paths import paths
+
+
+def _sessions_dir() -> str:
+ # paths["packed"] is .podcli/packed; its parent is the .podcli root.
+ d = os.path.join(os.path.dirname(paths["packed"]), "reels")
+ os.makedirs(d, exist_ok=True)
+ return d
+
+
+def session_path(session_id: str) -> str:
+ return os.path.join(_sessions_dir(), f"{session_id}.json")
+
+
+@dataclass
+class Moment:
+ start: float
+ end: float
+ why: str = "energy_peak"
+ text: str = ""
+ enabled: bool = True
+ dirty: bool = True # needs a re-cut before the next build
+
+ @property
+ def duration(self) -> float:
+ return round(self.end - self.start, 1)
+
+
+@dataclass
+class ReelSession:
+ session_id: str
+ source: str
+ profile: str
+ out_dir: str
+ moments: list[Moment] = field(default_factory=list)
+
+ def save(self) -> str:
+ path = session_path(self.session_id)
+ data = asdict(self)
+ with open(path, "w") as f:
+ json.dump(data, f, indent=2)
+ return path
+
+ @classmethod
+ def load(cls, session_id: str) -> "ReelSession":
+ with open(session_path(session_id)) as f:
+ data = json.load(f)
+ data["moments"] = [Moment(**m) for m in data.get("moments", [])]
+ return cls(**data)
+
+
+def _clip_text(words: list[dict], a: float, b: float) -> str:
+ return " ".join(
+ str(w.get("word", "")).strip()
+ for w in words
+ if w.get("start", 0) >= a - 0.05 and w.get("end", 0) <= b + 0.05
+ )
+
+
+def seed_session(
+ session_id: str,
+ source: str,
+ out_dir: str,
+ profile: str = "party",
+ top_n: int = 10,
+ min_dur: float = 15.0,
+ max_dur: float = 60.0,
+ words: Optional[list[dict]] = None,
+ progress_callback: Optional[Callable] = None,
+) -> ReelSession:
+ """Run detection once and persist the moments as an editable session."""
+ from services.saliency import detect_highlights
+
+ clips = detect_highlights(
+ source, profile_name=profile, top_n=top_n, min_dur=min_dur, max_dur=max_dur,
+ words=words, progress_callback=progress_callback,
+ )
+ moments = [
+ Moment(
+ start=round(c["start_second"], 1),
+ end=round(c["end_second"], 1),
+ why=c.get("reasons", ["energy_peak"])[0],
+ text=_clip_text(words, c["start_second"], c["end_second"]) if words else "",
+ )
+ for c in clips
+ ]
+ session = ReelSession(session_id, source, profile, out_dir, moments)
+ session.save()
+ return session
+
+
+_EDITS = {
+ "longer": lambda m, s: setattr(m, "end", round(m.end + s, 1)),
+ "shorter": lambda m, s: setattr(m, "end", round(max(m.start + 1, m.end - s), 1)),
+ "earlier": lambda m, s: setattr(m, "start", round(max(0.0, m.start - s), 1)),
+ "later": lambda m, s: setattr(m, "start", round(min(m.end - 1, m.start + s), 1)),
+ "shift": lambda m, s: (setattr(m, "start", round(max(0.0, m.start + s), 1)),
+ setattr(m, "end", round(m.end + s, 1))),
+}
+
+
+def edit_moment(session: ReelSession, index: int, op: str, seconds: float = 0.0) -> ReelSession:
+ """Apply an edit to one moment (1-based index) and mark it for re-cut."""
+ if not (1 <= index <= len(session.moments)):
+ raise IndexError(f"no moment {index} (have {len(session.moments)})")
+ m = session.moments[index - 1]
+ if op == "drop":
+ session.moments.pop(index - 1)
+ elif op == "toggle":
+ m.enabled = not m.enabled
+ elif op in _EDITS:
+ _EDITS[op](m, seconds)
+ m.dirty = True
+ else:
+ raise ValueError(f"unknown op {op!r}")
+ session.save()
+ return session
+
+
+def _cut(source: str, out_dir: str, idx: int, m: Moment) -> str:
+ clips_dir = os.path.join(out_dir, "clips")
+ os.makedirs(clips_dir, exist_ok=True)
+ out = os.path.join(clips_dir, f"clip_{idx:02d}.mp4")
+ proc_run([
+ "ffmpeg", "-y", "-ss", str(m.start), "-i", source, "-t", str(m.duration),
+ "-vf", "scale=1920:1080:force_original_aspect_ratio=decrease,"
+ "pad=1920:1080:(ow-iw)/2:(oh-ih)/2",
+ "-c:v", "libx264", "-preset", "veryfast", "-crf", "20",
+ "-c:a", "aac", "-b:a", "192k", out, "-loglevel", "error",
+ ], timeout=120, check=True)
+ return out
+
+
+def build_reel(session: ReelSession, progress_callback: Optional[Callable] = None) -> str:
+ """Re-cut only dirty moments, then concatenate all enabled moments into the reel."""
+ os.makedirs(session.out_dir, exist_ok=True)
+ files = []
+ active = [(i, m) for i, m in enumerate(session.moments, 1) if m.enabled]
+ for n, (i, m) in enumerate(active, 1):
+ clip = os.path.join(session.out_dir, "clips", f"clip_{i:02d}.mp4")
+ if m.dirty or not os.path.exists(clip):
+ if progress_callback:
+ progress_callback(int(n / len(active) * 90), f"cutting moment {i}")
+ clip = _cut(session.source, session.out_dir, i, m)
+ m.dirty = False
+ files.append(clip)
+ session.save()
+
+ reel = os.path.join(session.out_dir, "highlights_reel.mp4")
+ lst = os.path.join(session.out_dir, "_concat.txt")
+ with open(lst, "w") as f:
+ f.write("".join(f"file '{os.path.abspath(x)}'\n" for x in files))
+ r = proc_run(["ffmpeg", "-y", "-f", "concat", "-safe", "0", "-i", lst,
+ "-c", "copy", reel, "-loglevel", "error"], timeout=300, check=False)
+ if r.returncode != 0:
+ proc_run(["ffmpeg", "-y", "-f", "concat", "-safe", "0", "-i", lst,
+ "-c:v", "libx264", "-c:a", "aac", reel, "-loglevel", "error"],
+ timeout=600, check=True)
+ if progress_callback:
+ progress_callback(100, f"built reel with {len(files)} moments")
+ return reel
diff --git a/tests/test_reel.py b/tests/test_reel.py
new file mode 100644
index 0000000..8c9c56d
--- /dev/null
+++ b/tests/test_reel.py
@@ -0,0 +1,94 @@
+"""Tests for backend.services.reel session + edit logic (no video/render)."""
+
+import os
+import sys
+import unittest
+
+ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+BACKEND_ROOT = os.path.join(ROOT, "backend")
+if BACKEND_ROOT not in sys.path:
+ sys.path.insert(0, BACKEND_ROOT)
+
+from services import reel as R
+
+
+def _session(**kw):
+ return R.ReelSession(
+ session_id=kw.get("sid", "unittest_reel"),
+ source="/tmp/fake.mp4",
+ profile="party",
+ out_dir="/tmp/fake_out",
+ moments=[R.Moment(100.0, 120.0, "energy_peak", "one"),
+ R.Moment(200.0, 215.0, "reaction", "two")],
+ )
+
+
+class MomentTests(unittest.TestCase):
+ def test_duration(self):
+ self.assertEqual(R.Moment(10.0, 25.0).duration, 15.0)
+
+
+class EditTests(unittest.TestCase):
+ def setUp(self):
+ self.s = _session()
+
+ def tearDown(self):
+ p = R.session_path(self.s.session_id)
+ if os.path.exists(p):
+ os.remove(p)
+
+ def test_longer_extends_end_and_marks_dirty(self):
+ R.edit_moment(self.s, 1, "longer", 10)
+ self.assertEqual(self.s.moments[0].end, 130.0)
+ self.assertTrue(self.s.moments[0].dirty)
+
+ def test_shorter_pulls_end_in(self):
+ R.edit_moment(self.s, 1, "shorter", 5)
+ self.assertEqual(self.s.moments[0].end, 115.0)
+
+ def test_earlier_moves_start_back(self):
+ R.edit_moment(self.s, 1, "earlier", 8)
+ self.assertEqual(self.s.moments[0].start, 92.0)
+
+ def test_shift_moves_both_bounds(self):
+ R.edit_moment(self.s, 2, "shift", -20)
+ self.assertEqual(self.s.moments[1].start, 180.0)
+ self.assertEqual(self.s.moments[1].end, 195.0)
+
+ def test_drop_removes_moment(self):
+ R.edit_moment(self.s, 1, "drop")
+ self.assertEqual(len(self.s.moments), 1)
+ self.assertEqual(self.s.moments[0].text, "two")
+
+ def test_toggle_disables_without_removing(self):
+ R.edit_moment(self.s, 1, "toggle")
+ self.assertFalse(self.s.moments[0].enabled)
+ self.assertEqual(len(self.s.moments), 2)
+
+ def test_bad_index_raises(self):
+ with self.assertRaises(IndexError):
+ R.edit_moment(self.s, 99, "longer", 5)
+
+ def test_unknown_op_raises(self):
+ with self.assertRaises(ValueError):
+ R.edit_moment(self.s, 1, "flip", 5)
+
+
+class PersistenceTests(unittest.TestCase):
+ def tearDown(self):
+ p = R.session_path("roundtrip_reel")
+ if os.path.exists(p):
+ os.remove(p)
+
+ def test_save_and_load_roundtrip(self):
+ s = _session(sid="roundtrip_reel")
+ s.save()
+ loaded = R.ReelSession.load("roundtrip_reel")
+ self.assertEqual(loaded.session_id, "roundtrip_reel")
+ self.assertEqual(len(loaded.moments), 2)
+ self.assertEqual(loaded.moments[1].why, "reaction")
+ self.assertIsInstance(loaded.moments[0], R.Moment)
+
+
+if __name__ == "__main__":
+ unittest.main()