Skip to content

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

fix: suppress transient frames at layout cuts (#180)

Nika Siradze6c622b1e5651
diff --git a/backend/services/motion_filters.py b/backend/services/motion_filters.py
index a57ba82..521647b 100644
--- a/backend/services/motion_filters.py
+++ b/backend/services/motion_filters.py
@@ -48,10 +48,13 @@ def build_cam_expr(
t1, x1 = keyframes[i + 1]
dt = max(0.01, t1 - t0)
jump = abs(x1 - x0)
- # In split/mixed layouts, avoid both long pans and hard snaps.
- # Force very short eased handoffs for virtually all jumps.
- blurred_cut_jump = 100000 if is_split else 180
- quick_reframe_jump = 24 if is_split else 90
+ # A split↔single layout change is already a source edit. Moving the
+ # crop for even a few frames after that edit creates a second, very
+ # noticeable jump (usually a flash of wall or the split seam). Treat
+ # it as an editorial cut instead: discard the micro-pan and hold the
+ # new framing from the source cut onward.
+ blurred_cut_jump = 24 if is_split else 180
+ quick_reframe_jump = 90
if jump < 2:
# Negligible movement — hold.
diff --git a/backend/services/video_processor.py b/backend/services/video_processor.py
index 98d2dc1..8f10461 100644
--- a/backend/services/video_processor.py
+++ b/backend/services/video_processor.py
@@ -172,6 +172,55 @@ def _run_step_crop_x_expr(runs: list, crop_x_for) -> str:
return expr
+def _replace_layout_flash_frames(video_path: str, cut_times: list[float], duration: float) -> bool:
+ """Replace the first frame at mixed-layout cuts with the prior clean frame.
+
+ Some Riverside switches briefly expose an empty tile. This post-pass is
+ deliberately video-only: the clone occupies the same frame slot, so audio
+ and caption timing remain untouched.
+ """
+ if not cut_times:
+ return True
+ try:
+ info = get_video_info(video_path)
+ stream = next(s for s in info["streams"] if s.get("codec_type") == "video")
+ num, den = str(stream.get("r_frame_rate", "24/1")).split("/", 1)
+ frame = float(den) / float(num)
+ except Exception:
+ frame = 1 / 24
+ cuts = sorted({round(float(t), 3) for t in cut_times if frame < t < duration - frame})
+ if not cuts:
+ return True
+
+ split_labels = "".join(f"[s{i}]" for i in range(len(cuts) + 1))
+ parts, labels, cursor = [f"[0:v]split={len(cuts) + 1}{split_labels}"], [], 0.0
+ for i, cut in enumerate(cuts):
+ end = max(cursor + 0.001, cut - 0.001)
+ label = f"g{i}"
+ parts.append(
+ f"[s{i}]trim=start={cursor:.3f}:end={end:.3f},setpts=PTS-STARTPTS,"
+ f"tpad=stop_mode=clone:stop_duration={frame:.3f}[{label}]"
+ )
+ labels.append(f"[{label}]")
+ # Start just before the first stable frame after the discarded one.
+ # A rounded timestamp at cut + frame can skip that stable frame too,
+ # shortening video by one frame at every guarded transition.
+ cursor = min(duration, cut + frame - 0.002)
+ last = f"g{len(cuts)}"
+ parts.append(f"[s{len(cuts)}]trim=start={cursor:.3f}:end={duration:.3f},setpts=PTS-STARTPTS[{last}]")
+ labels.append(f"[{last}]")
+ parts.append("".join(labels) + f"concat=n={len(labels)}:v=1:a=0[v]")
+ temp = video_path + ".layout-guard.mp4"
+ cmd = ["ffmpeg", "-y", "-i", video_path, "-filter_complex", ";".join(parts),
+ "-map", "[v]", "-map", "0:a?", "-c:v", "libx264", "-crf", "18", "-preset", "fast", "-pix_fmt", "yuv420p",
+ "-c:a", "copy", "-t", f"{duration:.3f}", "-movflags", "+faststart", temp]
+ result = proc_run(cmd, timeout=_FFMPEG_TIMEOUT, check=False)
+ if result.returncode != 0 or not os.path.exists(temp):
+ return False
+ os.replace(temp, video_path)
+ return True
+
+
def crop_to_vertical(
input_path: str,
output_path: str,
@@ -1633,6 +1682,12 @@ def _track_and_crop_inner(
output_path=output_path, label="crop_mixed_steps",
)
if stepped:
+ guard_cuts = [
+ snapped[i][1] for i in range(len(snapped) - 1)
+ if abs(snapped[i][1] - runs[i][1]) > 0.001
+ ]
+ if not _replace_layout_flash_frames(stepped, guard_cuts, duration):
+ log_event("crop", "layout_flash_guard_failed", level="warn")
return stepped
log_event("crop", "fallback", reason="mixed_steps_failed",
to="dissolve")
diff --git a/tests/test_motion_filters.py b/tests/test_motion_filters.py
index 485e92a..01ceeb0 100644
--- a/tests/test_motion_filters.py
+++ b/tests/test_motion_filters.py
@@ -44,6 +44,15 @@ class BuildCamExprTests(unittest.TestCase):
self.assertIsNotNone(expr)
self.assertIn("100", expr)
+ def test_split_layout_jump_is_an_immediate_cut(self):
+ expr = mf.build_cam_expr(
+ [(0.0, 120), (0.20, 360), (1.0, 360)],
+ duration=1.0,
+ is_split=True,
+ )
+ self.assertIn("if(between(t\\,0.000\\,0.200)\\,360\\,", expr)
+ self.assertNotIn("120+((360-120)", expr)
+
class MotionWindowsFromKeyframesTests(unittest.TestCase):
def test_no_keyframes_returns_empty(self):
diff --git a/tests/test_video_processor.py b/tests/test_video_processor.py
index ebe8c9e..01bc26d 100644
--- a/tests/test_video_processor.py
+++ b/tests/test_video_processor.py
@@ -607,16 +607,17 @@ class VideoProcessorTests(unittest.TestCase):
self.assertIn("if(between(t\\,0.000\\,0.180)\\,420\\,", expr)
self.assertNotIn("100+((420-100)", expr)
- def test_build_cam_expr_uses_short_eased_handoff_for_split_layout_jumps(self):
+ def test_build_cam_expr_cuts_split_layout_jumps_without_micro_pan(self):
expr = vp._build_cam_expr(
keyframes=[(0.0, 120), (0.20, 360), (1.0, 360)],
duration=1.0,
is_split=True,
)
- # Split transitions should avoid hard snaps and use a brief eased handoff.
- self.assertNotIn("if(between(t\\,0.000\\,0.200)\\,360\\,", expr)
- self.assertIn("120+((360-120)", expr)
+ # The source already changes layouts here. Do not add an 80ms crop pan
+ # on top of it: a direct cut removes the transient seam/wall frames.
+ self.assertIn("if(between(t\\,0.000\\,0.200)\\,360\\,", expr)
+ self.assertNotIn("120+((360-120)", expr)
def test_build_motion_blur_filter_targets_only_short_reframes(self):
blur = vp._build_motion_blur_filter(