Skip to content

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

Export a review timeline and read an edited one back (#255)

Nika Siradze5f8263abc46a
diff --git a/backend/cli.py b/backend/cli.py
index 886362a..2d05929 100644
--- a/backend/cli.py
+++ b/backend/cli.py
@@ -931,7 +931,14 @@ def _run_multicam(args, mc, target: str):
}
if cut_edits:
session = mc.update_mapping(session, cut_edits)
- if args.cuts:
+ if args.timeline and (args.cuts or args.removals):
+ raise ValueError("--timeline sets the cut and the removals itself. Drop --cuts and --removals.")
+ if args.timeline:
+ got = mc.import_timeline(session, args.timeline)
+ print(f" ✓ Took the cut from {os.path.basename(args.timeline)}: {got['shots']} shots, "
+ f"{got['removals']} stretches removed"
+ + (f", {got['skipped_clips']} clips of other files left out" if got["skipped_clips"] else ""))
+ elif args.cuts:
session = mc.set_cuts(session, _load_cuts(args.cuts))
elif not session.cuts:
report, done = _multicam_progress("Cutting")
@@ -955,7 +962,7 @@ def _run_multicam(args, mc, target: str):
for fmt in (["premiere", "fcpxml"] if args.export == "all" else [args.export] if args.export else []):
try:
- print(f" ✓ {mc.export_xml(session, fmt)}")
+ print(f" ✓ {mc.export_xml(session, fmt, review=args.review)}")
except ValueError as e:
print(f" ! Skipped the {fmt} export: {e}", file=sys.stderr)
if args.transcript:
@@ -4957,6 +4964,8 @@ def main():
" podcli multicam ~/Podcasts/ep12 --people \"Nika, Ana\"\n"
" podcli multicam ~/Podcasts/ep12 --set cam_b.mp4=camera:Ana --set zoom_lr.wav=mic:Nika,Ana -y\n"
" podcli multicam 3f9c2a1b7e40 --export premiere --no-render\n"
+ " podcli multicam 3f9c2a1b7e40 --export premiere --review --no-render\n"
+ " podcli multicam 3f9c2a1b7e40 --timeline ~/Desktop/edited.xml\n"
" podcli multicam list",
formatter_class=argparse.RawDescriptionHelpFormatter,
)
@@ -4979,6 +4988,12 @@ def main():
mc_p.add_argument("--look", choices=["none", "natural", "warm", "contrast"], help="Color look for the render")
mc_p.add_argument("--export", choices=["premiere", "fcpxml", "all"],
help="Also write an editor timeline that points at the original files")
+ mc_p.add_argument("--review", action="store_true",
+ help="With --export: keep the whole episode, every camera on its own track, and the removals in "
+ "place, marked, for an editor to judge")
+ mc_p.add_argument("--timeline", metavar="FILE",
+ help="Take the cut and removals from an edited FCP 7 XML timeline (Premiere, or Resolve's "
+ "File > Export > Timeline > FCP 7 XML)")
mc_p.add_argument("--no-render", action="store_true", dest="no_render", help="Skip the MP4 render (fast, export only)")
mc_p.add_argument("--no-stems", action="store_true", dest="no_stems", help="Skip the per-person WAV files")
mc_p.add_argument("--resync", action="store_true",
diff --git a/backend/main.py b/backend/main.py
index 0fcb9ba..a124f3b 100644
--- a/backend/main.py
+++ b/backend/main.py
@@ -972,7 +972,8 @@ def handle_manage_multicam(task_id: str, params: dict):
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), delete.
+ 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
@@ -1037,7 +1038,12 @@ def handle_manage_multicam(task_id: str, params: dict):
raise ValueError("stems is true or false")
mc.render_session(session, stems=stems, progress_callback=progress("rendering"))
elif action == "export":
- data["export_path"] = mc.export_xml(session, params.get("format", "premiere"))
+ 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"))
diff --git a/backend/services/integrations/_shared/multicam_xml.py b/backend/services/integrations/_shared/multicam_xml.py
index 1d0689d..f9dd6ce 100644
--- a/backend/services/integrations/_shared/multicam_xml.py
+++ b/backend/services/integrations/_shared/multicam_xml.py
@@ -10,6 +10,11 @@ Both follow the same render plan as the MP4, so removed stretches drop out of
picture and mics at the same frames. Clock drift can't be expressed as a clip
property in either format, so a drifting mic is split at every shot and each
piece gets its own in-point, which keeps it within a millisecond of picture.
+
+A review timeline keeps the whole episode instead: every camera on its own
+track under the cut, and each removed stretch left in place, split out on
+every track, named "Remove", labelled orange in Premiere and marked with its
+reason. The editor deletes what should go and imports the result back.
"""
from __future__ import annotations
@@ -37,13 +42,14 @@ def _text(parent: ET.Element, tag: str, value) -> ET.Element:
return el
-def _audio_pieces(source, plan, fps: float) -> list[tuple[int, int, float]]:
- """(output_frame_in, output_frame_out, source_seconds_at_in) for one mic across the episode.
+def _pieces(source, plan, fps: float) -> list[tuple[int, int, float, dict | None]]:
+ """(output_frame_in, output_frame_out, source_seconds_at_in, removal) for one file across the episode.
Follows the render plan, so removed stretches drop out of the mics exactly
where they drop out of the picture. Pieces that continue each other on the
- timeline are joined; a drifting mic is left split at every shot, so each
- piece gets its own in-point and stays within a millisecond of picture.
+ timeline are joined unless one of them is a removal; a drifting file is left
+ split at every shot, so each piece gets its own in-point and stays within a
+ millisecond of picture.
"""
pieces: list[list] = []
joinable = abs(source.speed - 1.0) <= 1e-6
@@ -58,10 +64,11 @@ def _audio_pieces(source, plan, fps: float) -> list[tuple[int, int, float]]:
f1 = p.out_frame + round((hi - a) * fps)
if f1 <= f0:
continue
- if joinable and pieces and pieces[-1][1] == f0 and last_end is not None and abs(last_end - lo) < 1e-3:
+ if (joinable and pieces and pieces[-1][1] == f0 and pieces[-1][3] is p.removal
+ and last_end is not None and abs(last_end - lo) < 1e-3):
pieces[-1][1] = f1
else:
- pieces.append([f0, f1, source.source_time(p.tl_start + (f0 - p.out_frame) / fps)])
+ pieces.append([f0, f1, source.source_time(p.tl_start + (f0 - p.out_frame) / fps), p.removal])
last_end = hi
return [tuple(x) for x in pieces]
@@ -72,6 +79,29 @@ def _label(session, source, channel: int, person: str) -> str:
return f"{base} ({os.path.basename(source.path)}{'' if channel < 0 else f' ch{channel + 1}'})"
+def _removed_name(name: str, removal: dict | None) -> str:
+ if removal is None:
+ return name
+ return f"Remove ({removal['reason']}): {name}" if removal.get("reason") else f"Remove: {name}"
+
+
+def _removal_runs(plan) -> list[tuple[int, int, dict]]:
+ """(first_frame, end_frame, removal) for each removed stretch of a review plan."""
+ runs: list[list] = []
+ for p in plan:
+ if p.removal is None:
+ continue
+ if runs and runs[-1][2] is p.removal and runs[-1][1] == p.out_frame:
+ runs[-1][1] = p.out_frame + p.frames
+ else:
+ runs.append([p.out_frame, p.out_frame + p.frames, p.removal])
+ return [tuple(r) for r in runs]
+
+
+def _angles(session) -> list:
+ return [c for c in session.cameras() if c.synced and not c.virtual]
+
+
def _mic_tracks(session, *, split_stereo: bool = False) -> list[tuple[object, int, str]]:
"""(source, channel, person) per audio track; channel -1 is the whole file.
@@ -91,10 +121,10 @@ def _mic_tracks(session, *, split_stereo: bool = False) -> list[tuple[object, in
return out
-def write_xmeml(session, out_path: Path, *, width: int, height: int, fps: float) -> None:
+def write_xmeml(session, out_path: Path, *, width: int, height: int, fps: float, review: bool = False) -> None:
from services.multicam import render_plan
- plan = render_plan(session, fps)
+ plan = render_plan(session, fps, review=review)
total = sum(p.frames for p in plan)
root = ET.Element("xmeml", {"version": "4"})
@@ -110,7 +140,6 @@ def write_xmeml(session, out_path: Path, *, width: int, height: int, fps: float)
_text(chars, "width", width)
_text(chars, "height", height)
_text(chars, "pixelaspectratio", "square")
- vtrack = ET.SubElement(video, "track")
declared: set[str] = set()
counter = [0]
@@ -138,10 +167,10 @@ def write_xmeml(session, out_path: Path, *, width: int, height: int, fps: float)
_text(a, "channelcount", max(1, source.audio_channels))
def clipitem(track: ET.Element, source, f0: int, f1: int, src_seconds: float,
- *, name: str, audio_channel: int | None = None) -> None:
+ *, name: str, audio_channel: int | None = None, removal: dict | None = None) -> None:
counter[0] += 1
item = ET.SubElement(track, "clipitem", {"id": f"clipitem-{counter[0]}"})
- _text(item, "name", name)
+ _text(item, "name", _removed_name(name, removal))
_text(item, "enabled", "TRUE")
_text(item, "duration", round(source.duration * fps))
_rate(item, fps)
@@ -155,22 +184,38 @@ def write_xmeml(session, out_path: Path, *, width: int, height: int, fps: float)
st = ET.SubElement(item, "sourcetrack")
_text(st, "mediatype", "audio")
_text(st, "trackindex", max(1, audio_channel + 1))
-
+ if removal is not None:
+ labels = ET.SubElement(item, "labels")
+ _text(labels, "label2", "Mango")
+
+ for cam in _angles(session) if review else []:
+ track = ET.SubElement(video, "track")
+ for f0, f1, src_seconds, removal in _pieces(cam, plan, fps):
+ clipitem(track, cam, f0, f1, src_seconds, name=os.path.basename(cam.path), removal=removal)
+ vtrack = ET.SubElement(video, "track")
for p in plan:
if not p.source_id:
continue
cam = session.source(p.source_id)
- clipitem(vtrack, cam, p.out_frame, p.out_frame + p.frames, cam.source_time(p.tl_start), name=os.path.basename(cam.path))
+ clipitem(vtrack, cam, p.out_frame, p.out_frame + p.frames, cam.source_time(p.tl_start),
+ name=os.path.basename(cam.path), removal=p.removal)
audio = ET.SubElement(media, "audio")
_text(audio, "numOutputChannels", 2)
for source, channel, person in _mic_tracks(session, split_stereo=True):
track = ET.SubElement(audio, "track")
label = _label(session, source, channel, person)
- for f0, f1, src_seconds in _audio_pieces(source, plan, fps):
- clipitem(track, source, f0, f1, src_seconds, name=label, audio_channel=channel)
+ for f0, f1, src_seconds, removal in _pieces(source, plan, fps):
+ clipitem(track, source, f0, f1, src_seconds, name=label, audio_channel=channel, removal=removal)
_text(track, "enabled", "TRUE")
+ for f0, f1, removal in _removal_runs(plan):
+ marker = ET.SubElement(seq, "marker")
+ _text(marker, "name", removal.get("reason") or "Remove")
+ _text(marker, "comment", "Marked for removal by podcli. Delete it to cut it, keep it to restore it.")
+ _text(marker, "in", f0)
+ _text(marker, "out", f1)
+
ET.indent(ET.ElementTree(root), space=" ")
out_path.parent.mkdir(parents=True, exist_ok=True)
out_path.write_text(
@@ -180,10 +225,11 @@ def write_xmeml(session, out_path: Path, *, width: int, height: int, fps: float)
)
-def write_fcpxml(session, out_path: Path, *, width: int, height: int, fps: float) -> None:
+def write_fcpxml(session, out_path: Path, *, width: int, height: int, fps: float, review: bool = False) -> None:
from services.multicam import render_plan
- plan = render_plan(session, fps)
+ plan = render_plan(session, fps, review=review)
+ angles = _angles(session) if review else []
total = sum(p.frames for p in plan)
def t(frame_count: int) -> str:
@@ -202,7 +248,7 @@ def write_fcpxml(session, out_path: Path, *, width: int, height: int, fps: float
resources = [fx.make_format(fmt_id, fps, width, height)]
asset_ids: dict[str, str] = {}
formats: dict[str, str] = {}
- used = {p.source_id for p in plan if p.source_id} | {s.id for s, _, _ in _mic_tracks(session)}
+ used = {p.source_id for p in plan if p.source_id} | {s.id for s, _, _ in _mic_tracks(session)} | {c.id for c in angles}
for i, source in enumerate(s for s in session.sources if s.id in used):
aid = f"a{i + 1}"
asset_ids[source.id] = aid
@@ -249,29 +295,45 @@ def write_fcpxml(session, out_path: Path, *, width: int, height: int, fps: float
# lanes, so every clip is positioned against the same zero.
gap = ET.SubElement(spine, "gap", {"name": "Episode", "offset": "0s", "start": "0s", "duration": t(total)})
+ for lane, cam in enumerate(angles, start=1):
+ for f0, f1, src_seconds, removal in _pieces(cam, plan, fps):
+ ET.SubElement(gap, "asset-clip", {
+ "ref": asset_ids[cam.id],
+ "lane": str(lane),
+ "offset": t(f0),
+ "start": src_t(cam, src_seconds),
+ "duration": t(f1 - f0),
+ "name": _removed_name(os.path.basename(cam.path), removal),
+ "srcEnable": "video",
+ })
for p in plan:
if not p.source_id:
continue
cam = session.source(p.source_id)
- ET.SubElement(gap, "asset-clip", {
+ start = src_t(cam, cam.source_time(p.tl_start))
+ clip = ET.SubElement(gap, "asset-clip", {
"ref": asset_ids[p.source_id],
- "lane": "1",
+ "lane": str(len(angles) + 1),
"offset": t(p.out_frame),
- "start": src_t(cam, cam.source_time(p.tl_start)),
+ "start": start,
"duration": t(p.frames),
- "name": os.path.basename(cam.path),
+ "name": _removed_name(os.path.basename(cam.path), p.removal),
"srcEnable": "video",
})
+ if p.removal is not None:
+ ET.SubElement(clip, "marker", {
+ "start": start, "duration": t(p.frames), "value": p.removal.get("reason") or "Remove",
+ })
for lane, (source, channel, person) in enumerate(_mic_tracks(session), start=1):
- for f0, f1, src_seconds in _audio_pieces(source, plan, fps):
+ for f0, f1, src_seconds, removal in _pieces(source, plan, fps):
clip = ET.SubElement(gap, "asset-clip", {
"ref": asset_ids[source.id],
"lane": str(-lane),
"offset": t(f0),
"start": src_t(source, src_seconds),
"duration": t(f1 - f0),
- "name": _label(session, source, channel, person),
+ "name": _removed_name(_label(session, source, channel, person), removal),
"audioRole": "dialogue",
"srcEnable": "audio",
})
diff --git a/backend/services/multicam.py b/backend/services/multicam.py
index 262e649..4994033 100644
--- a/backend/services/multicam.py
+++ b/backend/services/multicam.py
@@ -1685,44 +1685,54 @@ class Piece:
out_frame: int # first frame in the finished episode
frames: int
tl_start: float # timeline second shown on that first frame
+ removal: Optional[dict] = None # set only in a review plan, where removed stretches stay in place
-def kept_segments(session: MulticamSession) -> list[tuple[float, float]]:
- """The episode range minus the removed stretches, in timeline seconds."""
+def _segments(session: MulticamSession) -> list[tuple[float, float, Optional[dict]]]:
+ """The episode range in order, split at removals: (start, end, the removal or None)."""
start, end = session.cuts[0]["start"], session.cuts[-1]["end"]
- kept, cursor = [], start
+ out, cursor = [], start
for r in session.removals:
a, b = max(start, r["start"]), min(end, r["end"])
if b <= cursor or a >= end:
continue
if a > cursor:
- kept.append((cursor, a))
- cursor = max(cursor, b)
+ out.append((cursor, a, None))
+ out.append((max(a, cursor), b, r))
+ cursor = b
if cursor < end:
- kept.append((cursor, end))
- return kept
+ out.append((cursor, end, None))
+ return out
-def render_plan(session: MulticamSession, fps: float) -> list[Piece]:
+def kept_segments(session: MulticamSession) -> list[tuple[float, float]]:
+ """The episode range minus the removed stretches, in timeline seconds."""
+ return [(a, b) for a, b, r in _segments(session) if r is None]
+
+
+def render_plan(session: MulticamSession, fps: float, *, review: bool = False) -> list[Piece]:
"""Every shot, split at removals, laid end to end on one output frame grid.
One grid over the whole episode keeps piece lengths from accumulating
rounding drift against the audio; the MP4, the stems, and both editor
timelines are all built from this list so they agree frame for frame.
+ A review plan keeps the removed stretches in place, tagged with their removal.
"""
pieces: list[Piece] = []
out_t, out_f = 0.0, 0
- def emit(source_id: Optional[str], a: float, b: float) -> None:
+ def emit(source_id: Optional[str], a: float, b: float, removal: Optional[dict]) -> None:
nonlocal out_t, out_f
out_end = out_t + (b - a)
f_end = round(out_end * fps)
if f_end > out_f:
- pieces.append(Piece(source_id, out_f, f_end - out_f, a + (out_f / fps - out_t)))
+ pieces.append(Piece(source_id, out_f, f_end - out_f, a + (out_f / fps - out_t), removal))
out_f = f_end
out_t = out_end
- for a, b in kept_segments(session):
+ for a, b, removal in _segments(session):
+ if removal is not None and not review:
+ continue
t = a
for c in session.cuts:
if c["end"] <= t:
@@ -1730,13 +1740,13 @@ def render_plan(session: MulticamSession, fps: float) -> list[Piece]:
if c["start"] >= b:
break
if c["start"] > t:
- emit(None, t, c["start"])
+ emit(None, t, c["start"], removal)
t = c["start"]
e = min(c["end"], b)
- emit(c["source_id"], t, e)
+ emit(c["source_id"], t, e, removal)
t = e
if t < b:
- emit(None, t, b)
+ emit(None, t, b, removal)
return pieces
@@ -1896,7 +1906,7 @@ def render_session(
shutil.rmtree(work, ignore_errors=True)
-def export_xml(session: MulticamSession, fmt: str) -> str:
+def export_xml(session: MulticamSession, fmt: str, *, review: bool = False) -> str:
from services.integrations._shared import multicam_xml
if not session.cuts:
@@ -1908,17 +1918,185 @@ def export_xml(session: MulticamSession, fmt: str) -> str:
"screen) yet. Render the MP4 instead.")
width, height, fps = _output_format(session)
out_dir = _output_dir(session)
+ tag = "-review" if review else ""
if fmt == "premiere":
- out = out_dir / "episode-premiere.xml"
- multicam_xml.write_xmeml(session, out, width=width, height=height, fps=fps)
+ out = out_dir / f"episode{tag}-premiere.xml"
+ multicam_xml.write_xmeml(session, out, width=width, height=height, fps=fps, review=review)
else:
- out = out_dir / "episode.fcpxml"
- multicam_xml.write_fcpxml(session, out, width=width, height=height, fps=fps)
- session.outputs = {**session.outputs, fmt: str(out)}
+ out = out_dir / f"episode{tag}.fcpxml"
+ multicam_xml.write_fcpxml(session, out, width=width, height=height, fps=fps, review=review)
+ session.outputs = {**session.outputs, f"{fmt}_review" if review else fmt: str(out)}
session.save()
return str(out)
+MAX_TIMELINE_BYTES = 200 * 1024 * 1024
+
+
+def _xml_fps(el) -> Optional[float]:
+ rate = el.find("rate")
+ if rate is None or not (rate.findtext("timebase") or "").strip():
+ return None
+ base = float(rate.findtext("timebase"))
+ return base * 1000 / 1001 if (rate.findtext("ntsc") or "").strip().upper() == "TRUE" else base
+
+
+def _xml_path(pathurl: str) -> str:
+ from urllib.parse import unquote, urlparse
+
+ url = urlparse(pathurl)
+ path = unquote(url.path)
+ if re.match(r"^/[A-Za-z]:/", path):
+ path = path[1:]
+ return os.path.normcase(os.path.realpath(path))
+
+
+def _merged(cuts: list[dict]) -> list[dict]:
+ out: list[dict] = []
+ for c in cuts:
+ if out and out[-1]["source_id"] == c["source_id"]:
+ out[-1]["end"] = c["end"]
+ else:
+ out.append(dict(c))
+ return out
+
+
+def import_timeline(session: MulticamSession, path: str) -> dict:
+ """Take the cut and removals from an edited FCP 7 XML timeline (Premiere, or Resolve's FCP 7 XML export).
+
+ Picture decides the edit: at every frame the topmost enabled clip of one of
+ this edit's cameras is on air, and episode time that no clip shows is
+ removed. Clips of other files (b-roll, titles) and the audio tracks are
+ left out, because podcli rebuilds the mics from the picture.
+ """
+ import xml.etree.ElementTree as ET
+
+ file = Path(path).expanduser()
+ if file.suffix.lower() != ".xml" or not file.is_file():
+ raise ValueError("Pass an FCP 7 XML timeline (.xml). In Resolve: File > Export > Timeline > FCP 7 XML.")
+ if file.stat().st_size > MAX_TIMELINE_BYTES:
+ raise ValueError("That timeline file is too big to be one episode")
+ try:
+ root = ET.parse(file).getroot()
+ except ET.ParseError as e:
+ raise ValueError(f"{file.name} isn't valid XML: {e}") from None
+ seq = root.find("sequence") if root.tag == "xmeml" else None
+ if seq is None:
+ seq = next(root.iter("sequence"), None)
+ if root.tag != "xmeml" or seq is None or seq.find("media/video") is None:
+ raise ValueError(f"{file.name} isn't an FCP 7 XML timeline with video")
+ seq_fps = _xml_fps(seq)
+ if not seq_fps:
+ raise ValueError("The timeline has no frame rate")
+
+ files = {}
+ for f in root.iter("file"):
+ if f.get("id") and f.findtext("pathurl"):
+ files[f.get("id")] = _xml_path(f.findtext("pathurl"))
+ cams = [c for c in session.cameras() if c.synced and not c.virtual]
+ by_path = {os.path.normcase(os.path.realpath(c.path)): c for c in cams}
+ by_name: dict[str, list[Source]] = {}
+ for c in cams:
+ by_name.setdefault(os.path.basename(c.path).lower(), []).append(c)
+
+ def camera_of(path: str) -> Optional[Source]:
+ if path in by_path:
+ return by_path[path]
+ same = by_name.get(os.path.basename(path).lower(), [])
+ return same[0] if len(same) == 1 else None
+
+ clips, skipped = [], 0
+ for level, track in enumerate(seq.findall("media/video/track")):
+ if (track.findtext("enabled") or "TRUE").strip().upper() == "FALSE":
+ continue
+ for item in track.findall("clipitem"):
+ if (item.findtext("enabled") or "TRUE").strip().upper() == "FALSE":
+ continue
+ ref = item.find("file")
+ cam = camera_of(files.get(ref.get("id"), "")) if ref is not None else None
+ if cam is None:
+ skipped += 1
+ continue
+ start, end = int(item.findtext("start", "-1")), int(item.findtext("end", "-1"))
+ src_in, src_out = int(item.findtext("in", "-1")), int(item.findtext("out", "-1"))
+ if start < 0 or end < 0:
+ raise ValueError("A camera clip touches a transition. Remove the transitions and export again.")
+ if end <= start:
+ continue
+ clip_fps = _xml_fps(item) or seq_fps
+ if abs((src_out - src_in) / clip_fps - (end - start) / seq_fps) > 1.5 / seq_fps:
+ raise ValueError(f"{os.path.basename(cam.path)} is sped up or slowed down at frame {start}. "
+ "podcli keeps the conversation at real speed, so remove the speed change.")
+ clips.append((start, end, level, cam, src_in / clip_fps))
+ if not clips:
+ raise ValueError("No clip on the timeline uses this edit's camera files")
+
+ clips.sort(key=lambda c: c[0])
+ edges = sorted({f for c in clips for f in (c[0], c[1])})
+ shots: list[list] = []
+ active: list[tuple] = []
+ k = 0
+ for a, b in zip(edges, edges[1:]):
+ while k < len(clips) and clips[k][0] <= a:
+ active.append(clips[k])
+ k += 1
+ active = [c for c in active if c[1] > a]
+ if not active:
+ continue
+ start, _, _, cam, src_seconds = max(active, key=lambda c: c[2])
+ tl_a = cam.timeline_start() + (src_seconds + (a - start) / seq_fps) * cam.speed
+ tl_b = tl_a + (b - a) / seq_fps
+ if shots and shots[-1][2] is cam and abs(shots[-1][1] - tl_a) < 1e-3:
+ shots[-1][1] = tl_b
+ else:
+ shots.append([tl_a, tl_b, cam])
+
+ tolerance = 1.5 / seq_fps
+ for (_, prev_end, _), (start, _, _) in zip(shots, shots[1:]):
+ if start < prev_end - tolerance:
+ raise ValueError(f"The timeline plays {start:.1f}s of the conversation again or out of order. "
+ "podcli keeps it in order, so move that clip back or delete it.")
+
+ reasons = [r for r in session.removals if r.get("reason")]
+ removals = []
+ for (_, end, _), (nxt, _, _) in zip(shots, shots[1:]):
+ if nxt - end > tolerance:
+ known = next((r for r in reasons if r["start"] < nxt and r["end"] > end), None)
+ removals.append({"start": end, "end": nxt, **({"reason": known["reason"]} if known else {})})
+
+ def covers(cam: Source, a: float, b: float) -> bool:
+ return cam.timeline_start() <= a + 1e-3 and cam.timeline_end() >= b - 1e-3
+
+ cuts: list[dict] = []
+ for start, end, cam in shots:
+ start, end = max(start, cam.timeline_start()), min(end, cam.timeline_end())
+ if cuts and start > cuts[-1]["end"]:
+ prev = cuts[-1]
+ prev["end"] = min(start, session.source(prev["source_id"]).timeline_end())
+ start = max(prev["end"], cam.timeline_start())
+ if start > prev["end"] + 1e-3:
+ cover = next((c for c in cams if covers(c, prev["end"], start)), None)
+ if cover is None:
+ raise ValueError(f"No camera was recording at {prev['end']:.1f}s, where the timeline removes "
+ "a stretch. Keep a little more around it.")
+ cuts.append({"start": prev["end"], "end": start, "source_id": cover.id})
+ elif cuts:
+ start = cuts[-1]["end"]
+ cuts.append({"start": start, "end": end, "source_id": cam.id})
+ for i, c in enumerate(cuts):
+ if c["end"] - c["start"] >= 0.1:
+ continue
+ for other in (cuts[i - 1] if i else None, cuts[i + 1] if i + 1 < len(cuts) else None):
+ if other and covers(session.source(other["source_id"]), c["start"], c["end"]):
+ c["source_id"] = other["source_id"]
+ break
+
+ session.removals = []
+ set_cuts(session, _merged(cuts))
+ set_removals(session, removals)
+ return {"shots": len(session.cuts), "removals": len(session.removals), "skipped_clips": skipped}
+
+
# ---------------------------------------------------------------------------
# Listing and payloads
# ---------------------------------------------------------------------------
diff --git a/src/server.ts b/src/server.ts
index fc7b41c..2419bd8 100644
--- a/src/server.ts
+++ b/src/server.ts
@@ -2237,10 +2237,13 @@ export function createServer(): McpServer {
"'preview' (background job: playback proxies, a mic mix and stills, for a browser editor such as podcli cloud), 'delete'. " +
"'cloud' (background job, needs podcli login and Pro: sends previews and the edit to the podcli cloud editor; camera files stay here) and " +
"'pull' (background job: renders the cut made in that editor from the files here). " +
+ "'export' with review: true writes a review timeline: the whole episode, every camera on its own track under the cut, and each removal left in place, named 'Remove', labelled orange in Premiere and marked with its reason. " +
+ "'import_timeline' (path) reads an FCP 7 XML timeline edited in Premiere or Resolve back as the cut and removals: deleted stretches become removals, kept ones are restored. " +
+ "With the DaVinci Resolve MCP server connected, import the review timeline into a Resolve project, color the 'Remove' clips, let the editor review, export the timeline as FCP 7 XML, then call 'import_timeline'. " +
"Call recordings work too: one file per person becomes a split screen, one gallery recording is split into a camera per tile; Premiere and FCPXML export refuse those layouts for now.",
{
action: z
- .enum(["new", "list", "show", "map", "sync", "plan", "cut", "set_cuts", "activity", "previews", "preview", "render", "export", "cloud", "pull", "delete"])
+ .enum(["new", "list", "show", "map", "sync", "plan", "cut", "set_cuts", "activity", "previews", "preview", "render", "export", "import_timeline", "cloud", "pull", "delete"])
.describe("What to do"),
session_id: z.string().optional().describe("Session id returned by 'new' (every action except new/list)"),
folder: z.string().optional().describe("For 'new': folder holding one episode's recordings, scanned recursively"),
@@ -2283,6 +2286,8 @@ export function createServer(): McpServer {
force: z.boolean().optional().describe("For 'sync': also re-measure offsets that were set by hand"),
stems: z.boolean().optional().describe("For 'render': also write one WAV per person (default true)"),
format: z.enum(["premiere", "fcpxml"]).optional().describe("For 'export': premiere (FCP7 XML, also opens in Resolve) or fcpxml (Final Cut Pro, Resolve)"),
+ review: z.boolean().optional().describe("For 'export': keep the whole episode with every camera on its own track and the removals in place, marked"),
+ path: z.string().optional().describe("For 'import_timeline': an FCP 7 XML timeline exported from Premiere or Resolve"),
index: z.number().int().min(0).optional().describe("For 'cut': 0-based shot index"),
source_id: z.string().optional().describe("For 'cut': camera source id to use for that shot"),
removals: z
diff --git a/src/ui/web-server.ts b/src/ui/web-server.ts
index 7e49b7e..4a10756 100644
--- a/src/ui/web-server.ts
+++ b/src/ui/web-server.ts
@@ -2245,7 +2245,7 @@ app.get("/api/reel-download", (req, res) => {
// --- Multicam: map sources, sync, cut, render one recording ---
const MULTICAM_JOB_ACTIONS = new Set(["sync", "plan", "render", "preview", "cloud", "pull"]);
// activity saves the session when it refreshes its cache, so it waits for jobs like any write.
-const MULTICAM_WRITE_ACTIONS = new Set(["map", "cut", "set_cuts", "export", "delete", "activity", ...MULTICAM_JOB_ACTIONS]);
+const MULTICAM_WRITE_ACTIONS = new Set(["map", "cut", "set_cuts", "export", "import_timeline", "delete", "activity", ...MULTICAM_JOB_ACTIONS]);
const multicamPreviewDir = join(paths.working, "multicam");
// A multi-hour, multi-camera render outlasts the default one-hour task limit.
const multicamExecutor = new PythonExecutor(8 * 3600_000);
diff --git a/tests/test_multicam.py b/tests/test_multicam.py
index a9412e0..4ea2c34 100644
--- a/tests/test_multicam.py
+++ b/tests/test_multicam.py
@@ -810,3 +810,145 @@ def test_cli_json_always_prints_one_object(episode, monkeypatch, capsys, tmp_pat
assert "error" in json.loads(capsys.readouterr().out)
assert run_cli(monkeypatch, str(episode), "--delete", "--json") == 0
assert json.loads(capsys.readouterr().out)["deleted"] is True
+
+
+# --- review timelines and importing an edited timeline ---------------------------
+
+def _two_camera_session(sandbox):
+ a = _source(str(sandbox / "cam_a.mp4"), role="camera", person="nika", offset=0.0)
+ b = _source(str(sandbox / "cam_b.mp4"), role="camera", person="ana", offset=1.0)
+ m = _source(str(sandbox / "room.wav"), kind="audio", role="mic", offset=0.0)
+ session = mc.MulticamSession(session_id="abc123abc777", name="ep", sources=[a, b, m], reference_id="room",
+ cuts=[{"start": 2.0, "end": 10.0, "source_id": "cam_a"},
+ {"start": 10.0, "end": 20.0, "source_id": "cam_b"},
+ {"start": 20.0, "end": 30.0, "source_id": "cam_a"}])
+ session.save()
+ return mc.set_removals(session, [{"start": 12.0, "end": 14.0, "reason": "retake"}])
+
+
+def _ripple_delete(xml_path, index):
+ """Delete one shot from the picture track and close the gap, as an editor would."""
+ tree = ET.parse(xml_path)
+ track = tree.getroot().findall("./sequence/media/video/track")[-1]
+ items = track.findall("clipitem")
+ gone = items[index]
+ length = int(gone.findtext("end")) - int(gone.findtext("start"))
+ track.remove(gone)
+ for item in items[index + 1:]:
+ for tag in ("start", "end"):
+ item.find(tag).text = str(int(item.findtext(tag)) - length)
+ tree.write(xml_path)
+
+
+def test_review_plan_keeps_removals_in_place_and_tagged(sandbox):
+ session = _two_camera_session(sandbox)
+ plan = mc.render_plan(session, 30.0, review=True)
+ assert sum(p.frames for p in plan) == 28 * 30
+ removed = [p for p in plan if p.removal]
+ assert [(p.source_id, p.out_frame, p.frames) for p in removed] == [("cam_b", 300, 60)]
+ assert removed[0].removal["reason"] == "retake"
+ assert sum(p.frames for p in mc.render_plan(session, 30.0)) == 26 * 30
+
+
+def test_review_export_stacks_every_camera_and_marks_removals(sandbox):
+ session = _two_camera_session(sandbox)
+ premiere = ET.parse(mc.export_xml(session, "premiere", review=True)).getroot()
+ tracks = premiere.findall("./sequence/media/video/track")
+ assert len(tracks) == 3
+ assert int(premiere.findtext("./sequence/duration")) == 28 * 30
+ flagged = [c for c in premiere.iter("clipitem") if c.findtext("labels/label2") == "Mango"]
+ assert len(flagged) == 4
+ assert all(c.findtext("name").startswith("Remove (retake): ") for c in flagged)
+ marker = premiere.find("./sequence/marker")
+ assert (marker.findtext("name"), marker.findtext("in"), marker.findtext("out")) == ("retake", "300", "360")
+ assert session.outputs["premiere_review"].endswith("episode-review-premiere.xml")
+
+ fcp = ET.parse(mc.export_xml(session, "fcpxml", review=True)).getroot()
+ assert {c.get("lane") for c in fcp.iter("asset-clip")} == {"1", "2", "3", "-1"}
+ assert [m.get("value") for m in fcp.iter("marker")] == ["retake"]
+
+ plain = ET.parse(mc.export_xml(session, "premiere")).getroot()
+ assert len(plain.findall("./sequence/media/video/track")) == 1
+ assert plain.find("./sequence/marker") is None
+
+
+def test_an_untouched_timeline_imports_as_the_same_edit(sandbox):
+ session = _two_camera_session(sandbox)
+ cuts, removals = [dict(c) for c in session.cuts], [dict(r) for r in session.removals]
+ got = mc.import_timeline(session, mc.export_xml(session, "premiere"))
+ assert got == {"shots": 3, "removals": 1, "skipped_clips": 0}
+ assert [c["source_id"] for c in session.cuts] == [c["source_id"] for c in cuts]
+ for new, old in zip(session.cuts, cuts):
+ assert new["start"] == pytest.approx(old["start"], abs=0.04)
+ assert new["end"] == pytest.approx(old["end"], abs=0.04)
+ assert session.removals[0]["start"] == pytest.approx(removals[0]["start"], abs=0.04)
+ assert session.removals[0]["end"] == pytest.approx(removals[0]["end"], abs=0.04)
+ assert session.removals[0]["reason"] == "retake"
+
+
+def test_keeping_a_marked_stretch_in_review_restores_it(sandbox):
+ session = _two_camera_session(sandbox)
+ mc.import_timeline(session, mc.export_xml(session, "premiere", review=True))
+ assert session.removals == []
+ assert session.cuts[0]["start"] == pytest.approx(2.0, abs=0.04)
+ assert session.cuts[-1]["end"] == pytest.approx(30.0, abs=0.04)
+
+
+def test_deleting_a_shot_in_the_editor_becomes_a_removal(sandbox):
+ session = _two_camera_session(sandbox)
+ mc.set_removals(session, [])
+ path = mc.export_xml(session, "premiere")
+ _ripple_delete(path, 1)
+ got = mc.import_timeline(session, path)
+ assert got["removals"] == 1
+ assert session.removals[0]["start"] == pytest.approx(10.0, abs=0.04)
+ assert session.removals[0]["end"] == pytest.approx(20.0, abs=0.04)
+ assert [c["source_id"] for c in session.cuts] == ["cam_a"]
+ assert session.cuts[0]["start"] == pytest.approx(2.0, abs=0.04)
+ assert session.cuts[0]["end"] == pytest.approx(30.0, abs=0.04)
+
+
+def test_import_refuses_reordered_or_foreign_timelines(sandbox):
+ session = _two_camera_session(sandbox)
+ path = mc.export_xml(session, "premiere")
+ tree = ET.parse(path)
+ items = tree.getroot().findall("./sequence/media/video/track")[-1].findall("clipitem")
+ first, last = items[0], items[-1]
+ length = int(last.findtext("out")) - int(last.findtext("in"))
+ last.find("in").text = first.findtext("in")
+ last.find("out").text = str(int(first.findtext("in")) + length)
+ tree.write(path)
+ before = [dict(c) for c in session.cuts]
+ with pytest.raises(ValueError, match="out of order"):
+ mc.import_timeline(session, path)
+ assert session.cuts == before
+
+ notes = sandbox / "notes.txt"
+ notes.write_text("hi")
+ with pytest.raises(ValueError, match="FCP 7 XML"):
+ mc.import_timeline(session, str(notes))
+ other = sandbox / "other.xml"
+ other.write_text('<?xml version="1.0"?><fcpxml version="1.10"/>')
+ with pytest.raises(ValueError, match="isn't an FCP 7 XML timeline"):
+ mc.import_timeline(session, str(other))
+
+
+def test_a_removal_where_cameras_stop_and_start_is_bridged_by_another_camera(sandbox):
+ a = _source(str(sandbox / "cam_a.mp4"), role="camera", person="nika", offset=0.0, duration=11.0)
+ b = _source(str(sandbox / "cam_b.mp4"), role="camera", person="ana", offset=13.0, duration=50.0)
+ w = _source(str(sandbox / "cam_w.mp4"), role="camera", person="wide", offset=0.0)
+ m = _source(str(sandbox / "room.wav"), kind="audio", role="mic", offset=0.0)
+ session = mc.MulticamSession(session_id="abc123abc778", name="ep", sources=[a, b, w, m], reference_id="room",
+ cuts=[{"start": 2.0, "end": 10.0, "source_id": "cam_a"},
+ {"start": 10.0, "end": 30.0, "source_id": "cam_w"}])
+ session.save()
+ mc.set_cuts(session, [{"start": 2.0, "end": 10.0, "source_id": "cam_a"},
+ {"start": 10.0, "end": 16.0, "source_id": "cam_w"},
+ {"start": 16.0, "end": 30.0, "source_id": "cam_b"}])
+ mc.set_removals(session, [{"start": 10.0, "end": 16.0}])
+ mc.import_timeline(session, mc.export_xml(session, "premiere"))
+ assert [c["source_id"] for c in session.cuts] == ["cam_a", "cam_w", "cam_b"]
+ assert session.cuts[0]["end"] == pytest.approx(11.0, abs=0.04)
+ assert session.cuts[1]["end"] == pytest.approx(13.0, abs=0.04)
+ assert session.removals[0]["start"] == pytest.approx(10.0, abs=0.04)
+ assert session.removals[0]["end"] == pytest.approx(16.0, abs=0.04)