Skip to content

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

8.1 KB
Raw Blame
"""Pure helpers for building ffmpeg motion-aware filter expressions.

All functions here are side-effect-free: they take keyframe / window
lists and return strings or lists. No ffmpeg is actually invoked from
this module: the caller passes the returned expressions into a
filter_complex graph.

Extracted from video_processor.py so the pure math can be unit-tested
in isolation.
"""

from __future__ import annotations


def build_cam_expr(
    keyframes: list,
    duration: float,
    is_split: bool,
    max_parts: int = 80,
) -> str | None:
    """Build an FFmpeg crop_x expression from SmoothedCameraman keyframes.

    keyframes: [(time, crop_x), ...]
    Returns the expression string, or None if too complex to express.
    """
    if not keyframes:
        return None
    # Ensure t=0 covered.
    if keyframes[0][0] > 0.05:
        keyframes = [(0, keyframes[0][1])] + keyframes
    if len(keyframes) == 1:
        return str(keyframes[0][1])

    def _eased_move_expr(start_t: float, move_t: float, start_x: int, end_x: int) -> str:
        # Smootherstep (6t^5 − 15t^4 + 10t^3) gives a softer start/landing
        # than smoothstep while still finishing inside the bounded window.
        progress = f"((t-{start_t:.3f})/{move_t:.3f})"
        eased = (
            f"((6*({progress})*({progress})*({progress})*({progress})*({progress}))"
            f"-(15*({progress})*({progress})*({progress})*({progress}))"
            f"+(10*({progress})*({progress})*({progress})))"
        )
        return f"{start_x}+(({end_x}-{start_x})*{eased})"

    parts: list[str] = []
    for i in range(len(keyframes) - 1):
        t0, x0 = keyframes[i]
        t1, x1 = keyframes[i + 1]
        dt = max(0.01, t1 - t0)
        jump = abs(x1 - x0)
        # 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.
            parts.append(f"if(between(t\\,{t0:.3f}\\,{t1:.3f})\\,{x0}\\,")
        elif jump >= blurred_cut_jump:
            # Very large jumps in non-split layouts still read better as
            # short blurred cuts than long animated slides.
            parts.append(f"if(between(t\\,{t0:.3f}\\,{t1:.3f})\\,{x1}\\,")
        elif jump >= quick_reframe_jump:
            # Moderate jump: use a short bounded reframe, but keep it
            # much tighter than a literal camera pan.
            pan_t = min(0.08 if is_split else 0.18, dt)
            pan_end_t = round(t0 + pan_t, 3)
            parts.append(
                f"if(between(t\\,{t0:.3f}\\,{pan_end_t:.3f})\\,"
                f"{_eased_move_expr(t0, pan_t, x0, x1)}\\,"
            )
            if pan_end_t < t1:
                parts.append(f"if(between(t\\,{pan_end_t:.3f}\\,{t1:.3f})\\,{x1}\\,")
        else:
            # Small pans still benefit from eased starts/stops so they
            # read like a camera operator, not a value sliding on rails.
            parts.append(
                f"if(between(t\\,{t0:.3f}\\,{t1:.3f})\\,"
                f"{_eased_move_expr(t0, dt, x0, x1)}\\,"
            )

    if len(parts) > max_parts:
        return None

    return "".join(parts) + str(keyframes[-1][1]) + ")" * len(parts)


def motion_windows_from_keyframes(
    keyframes: list,
    min_jump: int = 60,
    max_window_duration: float = 0.5,
    max_windows: int = 16,
) -> list[tuple[float, float]]:
    """Find short reframe windows worth accenting with blur / zoom."""
    windows: list[tuple[float, float]] = []
    for i in range(len(keyframes) - 1):
        t0, x0 = keyframes[i]
        t1, x1 = keyframes[i + 1]
        if abs(x1 - x0) < min_jump:
            continue
        dt = t1 - t0
        if dt <= 0.01 or dt > max_window_duration:
            continue
        windows.append((t0, t1))

    if not windows or len(windows) > max_windows:
        return []
    return windows


def expand_motion_windows(
    windows: list[tuple[float, float]],
    pad_before: float = 0.03,
    pad_after: float = 0.05,
) -> list[tuple[float, float]]:
    """Pad and merge adjacent motion windows so blur eases in and out."""
    if not windows:
        return []

    expanded: list[tuple[float, float]] = []
    for t0, t1 in windows:
        start = max(0.0, t0 - pad_before)
        end = t1 + pad_after
        if expanded and start <= expanded[-1][1] + 0.01:
            expanded[-1] = (expanded[-1][0], max(expanded[-1][1], end))
        else:
            expanded.append((start, end))
    return expanded


def build_motion_blur_filter(
    keyframes: list,
    min_jump: int = 60,
    max_window_duration: float = 0.5,
    max_windows: int = 16,
    core_sigma: float = 3.8,
    core_steps: int = 2,
    core_pad_before: float = 0.02,
    core_pad_after: float = 0.05,
    outer_sigma: float = 1.6,
    outer_steps: int = 1,
    outer_pad_before: float = 0.05,
    outer_pad_after: float = 0.08,
) -> str:
    """Build a layered full-frame blur filter for motion windows.

    A soft outer blur eases the transition in and out, while a tighter
    core blur covers the actual crop move. Empty string when no windows
    qualify (caller concatenates safely).
    """
    base_windows = motion_windows_from_keyframes(
        keyframes=keyframes,
        min_jump=min_jump,
        max_window_duration=max_window_duration,
        max_windows=max_windows,
    )
    if not base_windows:
        return ""

    outer_windows = expand_motion_windows(
        base_windows,
        pad_before=outer_pad_before,
        pad_after=outer_pad_after,
    )
    core_windows = expand_motion_windows(
        base_windows,
        pad_before=core_pad_before,
        pad_after=core_pad_after,
    )

    outer_enable = "+".join(
        f"between(t\\,{t0:.3f}\\,{t1:.3f})" for t0, t1 in outer_windows
    )
    core_enable = "+".join(
        f"between(t\\,{t0:.3f}\\,{t1:.3f})" for t0, t1 in core_windows
    )
    return (
        f",gblur=sigma={outer_sigma:.1f}:steps={outer_steps}:enable='{outer_enable}'"
        f",gblur=sigma={core_sigma:.1f}:steps={core_steps}:enable='{core_enable}'"
    )


def build_motion_zoom_filter(
    keyframes: list,
    target_w: int,
    target_h: int,
    min_jump: int = 60,
    max_window_duration: float = 0.5,
    max_windows: int = 16,
    max_zoom: float = 0.018,
) -> str:
    """Build a tiny center-zoom bump filter for motion windows.

    The goal is a subliminal push that reads as an editorial beat, not
    a visible punch-in. Empty string when no windows qualify.
    """
    windows = motion_windows_from_keyframes(
        keyframes=keyframes,
        min_jump=min_jump,
        max_window_duration=max_window_duration,
        max_windows=max_windows,
    )
    if not windows:
        return ""

    bumps: list[str] = []
    for t0, t1 in windows:
        dt = max(0.01, t1 - t0)
        progress = f"((t-{t0:.3f})/{dt:.3f})"
        bumps.append(
            f"(16*pow({progress}\\,2)*pow((1-{progress})\\,2)*between(t\\,{t0:.3f}\\,{t1:.3f}))"
        )

    zoom_expr = "+".join(bumps)
    return (
        f",scale=w='iw*(1+{max_zoom:.4f}*({zoom_expr}))'"
        f":h='ih*(1+{max_zoom:.4f}*({zoom_expr}))'"
        f":eval=frame,crop={target_w}:{target_h}:(iw-{target_w})/2:(ih-{target_h})/2"
    )


def simplify_keyframes(keyframes: list, tolerance: int = 5) -> list:
    """Remove intermediate keyframes that lie on a line between neighbours."""
    if len(keyframes) <= 2:
        return keyframes
    result = [keyframes[0]]
    for i in range(1, len(keyframes) - 1):
        t_prev, x_prev = result[-1]
        t_curr, x_curr = keyframes[i]
        t_next, x_next = keyframes[i + 1]
        dt_total = t_next - t_prev
        if dt_total < 0.01:
            continue
        expected = x_prev + (x_next - x_prev) * (t_curr - t_prev) / dt_total
        if abs(x_curr - expected) > tolerance:
            result.append(keyframes[i])
    result.append(keyframes[-1])
    return result