Skip to content

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

65.2 KB
Raw Blame
"""
Clip generator: orchestrates the full pipeline for creating a short-form clip.

Pipeline: cut segment → crop to 9:16 → render captions → burn captions
          (+ optional gradient overlay + logo) → normalize audio
"""

import os
import sys
import tempfile
import shutil
import signal
import subprocess
import re
import threading
from typing import Optional, Callable

from utils.proc import run as proc_run, ProcError
from utils.text import safe_filename
from utils.log import timed, warn as log_warn
from config.paths import paths

sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

from services.caption_renderer import render_captions
from services.video_processor import (
    cut_segment,
    cut_multi_segment,
    crop_to_vertical,
    fit_to_frame,
    burn_captions,
    normalize_audio,
    concat_outro,
)
from services.video_cut import probe_has_audio_stream, verify_full_decode
from services.glyph_coverage import check_caption_font_coverage
from services.subtitle_export import write_sidecars
from services.opening_hook import (
    validate_hook,
    snap_hook_to_words,
    order_with_hook,
    keyframes_to_playback,
)
from config.caption_styles import get_style
from services.formats import get_format
from services.media_probe import align_av_duration, ffmpeg_timeout

_FILLER_WORDS = frozenset([
    "um", "uh", "uhh", "uhm", "umm", "hmm", "hm", "mhm",
    "ah", "er", "erm", "eh",
    "ummm", "ummmm", "ummmmm", "uhhh", "uhhhh", "uhhhhh",
    "hmmm", "hmmmm", "uhmm", "uhmmm",
    "mmm", "mmmm", "mhmm", "mmhm",
])

# Weak lead-in markers that often add setup without adding viral value.
# These are only used for opening-trim decisions (not caption deletion).
_WEAK_OPENING_WORDS = frozenset([
    "so", "well", "okay", "ok", "like", "you", "know",
    "right", "yeah", "yes", "actually", "basically",
]) | _FILLER_WORDS

_SCENE_TIME_RE = re.compile(r"pts_time:([0-9]+(?:\.[0-9]+)?)")


def _trim_weak_opening(
    words: list[dict],
    start_second: float,
    end_second: float,
    max_trim: float = 3.0,
    min_gain: float = 0.25,
) -> float:
    """
    Tighten clip opening toward the first substantive sentence.

    Rules:
    - Remove obvious dead air at the head.
    - Optionally skip a short run of weak opener words.
    - Never trim past max_trim seconds or into a likely hook ("?" / "!").
    """
    if not words or end_second <= start_second + 0.6:
        return start_second

    clip_words = sorted(
        [w for w in words if w["end"] > start_second and w["start"] < end_second],
        key=lambda w: w["start"],
    )
    if len(clip_words) < 2:
        return start_second

    candidate_start = start_second
    first_word = clip_words[0]

    # Dead air before first spoken word.
    if first_word["start"] - start_second >= 0.45:
        candidate_start = first_word["start"]

    weak_window_end = min(end_second, start_second + max_trim)
    weak_run_end = None
    saw_real_word_after_weak = False

    for w in clip_words:
        if w["start"] > weak_window_end:
            break
        raw = str(w.get("word", "")).strip()
        if not raw:
            continue
        # If the opening already has question/exclamation energy, keep it.
        if "?" in raw or "!" in raw:
            break
        bare = raw.lower().strip(".,!?;:-\u2013\u2014'\"")
        if bare in _WEAK_OPENING_WORDS:
            weak_run_end = max(float(w["end"]), weak_run_end or 0.0)
            continue
        saw_real_word_after_weak = True
        break

    if weak_run_end is not None and saw_real_word_after_weak:
        candidate_start = max(candidate_start, weak_run_end)

    candidate_start = min(candidate_start, start_second + max_trim, end_second - 0.5)
    if candidate_start - start_second >= min_gain:
        return round(candidate_start, 2)
    return start_second


def _get_media_duration(path: str) -> float:
    """Read media duration in seconds (best effort)."""
    try:
        cmd = [
            "ffprobe", "-v", "error",
            "-show_entries", "format=duration",
            "-of", "default=nk=1:nw=1",
            path,
        ]
        result = proc_run(cmd, timeout=10, check=False)
        if result.returncode != 0:
            return 0.0
        return float((result.stdout or "0").strip() or 0.0)
    except Exception:
        return 0.0


def _bound_range_to_source(
    start_second: float,
    end_second: float,
    keep_segments: Optional[list[dict]],
    source_duration: float,
) -> tuple[float, Optional[list[dict]]]:
    """Clamp the requested range (and any keep_segments) to the source's
    actual duration, so a too-long end_second can't silently truncate the
    render instead of failing. source_duration <= 0 means ffprobe couldn't
    read it; skip bounding rather than clamp against an unknown length.
    """
    if source_duration <= 0:
        return end_second, keep_segments
    if start_second >= source_duration:
        raise ValueError(
            f"start_second ({start_second}s) is at or past the end of the "
            f"source video ({source_duration:.2f}s)."
        )
    end_second = min(end_second, source_duration)
    if keep_segments:
        bounded_segments = []
        for seg in keep_segments:
            if seg["start"] >= source_duration:
                continue
            bounded_segments.append({**seg, "end": min(seg["end"], source_duration)})
        keep_segments = bounded_segments or None
    return end_second, keep_segments


def _detect_scene_cuts(path: str, threshold: float = 0.22, max_cuts: int = 32) -> list[float]:
    """
    Detect hard visual changes likely to feel like jump cuts.
    Returns scene-change timestamps in seconds.
    """
    try:
        cmd = [
            "ffmpeg", "-hide_banner",
            "-i", path,
            "-filter:v", f"select='gt(scene,{threshold})',showinfo",
            "-an",
            "-f", "null", "-",
        ]
        result = proc_run(cmd, timeout=90, check=False)
        text = (result.stderr or "") + "\n" + (result.stdout or "")
        raw = [float(m.group(1)) for m in _SCENE_TIME_RE.finditer(text)]
        if not raw:
            return []
        cuts: list[float] = []
        for t in raw:
            if not cuts or abs(t - cuts[-1]) > 0.08:
                cuts.append(round(t, 3))
            if len(cuts) >= max_cuts:
                break
        return cuts
    except Exception:
        return []


def _select_problematic_scene_cuts(cuts: list[float], duration: float) -> list[float]:
    """
    Pick cuts that are most likely to feel bad:
    - clustered cuts (rapid switches)
    - tail-end cuts right before clip ends
    """
    if not cuts or duration <= 0:
        return []

    flagged: list[float] = []
    for i, t in enumerate(cuts):
        prev_t = cuts[i - 1] if i > 0 else None
        next_t = cuts[i + 1] if i + 1 < len(cuts) else None
        is_clustered = (
            (prev_t is not None and (t - prev_t) <= 0.9)
            or (next_t is not None and (next_t - t) <= 0.9)
        )
        is_tail = (duration - t) <= 2.0
        if is_clustered or is_tail:
            flagged.append(t)

    # Keep order and de-dup (safety)
    out: list[float] = []
    for t in flagged:
        if not out or abs(t - out[-1]) > 0.08:
            out.append(t)
    return out


def _apply_local_transition_smoothing(
    input_path: str,
    output_path: str,
    cut_times: list[float],
    pass_index: int = 0,
) -> bool:
    """Apply short blur masks around selected cut times (adaptive by pass)."""
    if not cut_times:
        return False

    # Pass 0: clean/light smoothing. Pass 1+: stronger smoothing.
    if pass_index <= 0:
        outer_pad = 0.15
        core_pad = 0.08
        outer_sigma = 1.8
        core_sigma = 3.2
    else:
        outer_pad = 0.20
        core_pad = 0.11
        outer_sigma = 2.2
        core_sigma = 4.0

    outer_windows = [(max(0.0, t - outer_pad), t + outer_pad) for t in cut_times]
    core_windows = [(max(0.0, t - core_pad), t + core_pad) for t in cut_times]

    outer_expr = "+".join(f"between(t,{a:.3f},{b:.3f})" for a, b in outer_windows)
    core_expr = "+".join(f"between(t,{a:.3f},{b:.3f})" for a, b in core_windows)

    vf = (
        f"gblur=sigma={outer_sigma:.1f}:steps=1:enable='{outer_expr}',"
        f"gblur=sigma={core_sigma:.1f}:steps=1:enable='{core_expr}'"
    )
    cmd = [
        "ffmpeg", "-y",
        "-i", input_path,
        "-vf", vf,
        "-c:v", "libx264", "-crf", "18", "-preset", "medium",
        "-pix_fmt", "yuv420p",
        "-c:a", "copy",
        "-movflags", "+faststart",
        output_path,
    ]
    try:
        duration = _get_media_duration(input_path)
        result = proc_run(cmd, timeout=ffmpeg_timeout(duration), check=False)
        ok = result.returncode == 0 and os.path.exists(output_path) and os.path.getsize(output_path) > 0
        if not ok and os.path.exists(output_path):
            try:
                os.remove(output_path)
            except OSError:
                pass
        return ok
    except Exception:
        if os.path.exists(output_path):
            try:
                os.remove(output_path)
            except OSError:
                pass
        return False


_output_path_lock = threading.Lock()
_reserved_output_paths: set[str] = set()


def _reserve_output_path(output_dir: str, stem: str, ext: str) -> str:
    """Claim an output path no other clip in this run can take.

    Titles come from an LLM and are not deduped, so two clips in one batch can
    share a stem. Rendering both to the same path would interleave the copy and
    the in-place autofix re-encode into one corrupt file while both report
    success. Reservations are per-process, so re-rendering a clip in a later run
    still overwrites its own output instead of piling up suffixes.
    """
    with _output_path_lock:
        candidate = os.path.join(output_dir, f"{stem}{ext}")
        n = 2
        while candidate in _reserved_output_paths:
            candidate = os.path.join(output_dir, f"{stem}-{n}{ext}")
            n += 1
        _reserved_output_paths.add(candidate)
        return candidate


def _reframe_can_jump(
    reframe: bool,
    crop_strategy: str,
    crop_keyframes: list = None,
    keep_segments: list = None,
) -> bool:
    """Whether this render can contain hard visual jumps worth an autofix pass.

    The pass is only skipped where a jump is impossible: no reframe at all, a
    fixed centre crop, or a manual crop held on a single keyframe. Every
    tracked strategy can snap the crop between subjects, so it gets smoothed.
    Speaker labels are not consulted: the default whisper.cpp engine skips
    diarization, so they are absent exactly when face tracking is doing the
    most snapping.
    """
    if keep_segments and len(keep_segments) > 1:
        return True
    if not reframe:
        return False
    if crop_strategy == "center":
        return False
    if crop_strategy == "manual":
        return bool(crop_keyframes and len(crop_keyframes) > 1)
    return True


def _transition_autofix_passes(jumps_possible: bool) -> int:
    raw = (os.environ.get("PODCLI_TRANSITION_AUTOFIX_PASSES") or "").strip()
    if raw:
        try:
            return max(0, min(int(raw), 2))
        except ValueError:
            pass
    return 2 if jumps_possible else 0


def _render_transition_autofix_passes(
    preserve_timing: bool,
    reframe: bool,
    crop_strategy: str,
    crop_keyframes: list = None,
    keep_segments: list = None,
) -> int:
    if preserve_timing:
        return 0
    return _transition_autofix_passes(
        _reframe_can_jump(
            reframe=reframe,
            crop_strategy=crop_strategy,
            crop_keyframes=crop_keyframes,
            keep_segments=keep_segments,
        )
    )


DESIGNED_CUT_TOLERANCE = 0.3


def _designed_cuts(cards: Optional[list], offset: float = 0.0) -> list[float]:
    times: list[float] = []
    for card in cards or []:
        if not isinstance(card, dict):
            continue
        for key in ("start", "end"):
            value = card.get(key)
            if isinstance(value, (int, float)) and not isinstance(value, bool):
                times.append(float(value) + offset)
    return times


def _auto_fix_transition_jumps(
    video_path: str, max_passes: int = 1, designed: Optional[list[float]] = None,
) -> bool:
    """
    Bounded auto-fix for jumpy transitions. Never loops indefinitely.
    Returns True if at least one fix pass succeeded.
    """
    fixed_any = False
    if max_passes <= 0:
        return False

    current = video_path
    for i in range(max_passes):
        duration = _get_media_duration(current)
        scene_threshold = 0.22 if i == 0 else 0.18
        cuts = [
            t for t in _detect_scene_cuts(current, threshold=scene_threshold)
            if all(abs(t - d) > DESIGNED_CUT_TOLERANCE for d in designed or [])
        ]
        problematic = _select_problematic_scene_cuts(cuts, duration)
        if not problematic:
            break

        temp_out = current + f".autofix{i+1}.mp4"
        ok = _apply_local_transition_smoothing(
            current,
            temp_out,
            problematic,
            pass_index=i,
        )
        if not ok:
            break
        os.replace(temp_out, current)
        fixed_any = True

    return fixed_any


def _snap_to_sentence_end(
    transcript_words: list[dict], start_second: float, end_second: float,
    max_extension: float = 3.0,
) -> float:
    """Snap clip end_second forward to the nearest sentence boundary.

    Forward-only. Stops at speaker changes to avoid bleeding into a reply.
    """
    SENTENCE_ENDINGS = ".!?"

    clip_words = [w for w in transcript_words if w["end"] > start_second and w["start"] < end_second]
    if not clip_words:
        return end_second

    last_clip_word = clip_words[-1]
    last_word_text = last_clip_word.get("word", "").strip()
    last_speaker = last_clip_word.get("speaker")

    if last_word_text and last_word_text[-1] in SENTENCE_ENDINGS:
        return max(end_second, last_clip_word["end"])

    for w in sorted(transcript_words, key=lambda x: x["start"]):
        if w["start"] < last_clip_word["end"]:
            continue
        if w["end"] > end_second + max_extension:
            break
        if last_speaker is not None and w.get("speaker") is not None and w.get("speaker") != last_speaker:
            break
        text = w.get("word", "").strip()
        if text and text[-1] in SENTENCE_ENDINGS:
            return w["end"]

    return end_second


def _clean_transcript_words(words: list[dict]) -> list[dict]:
    """
    Remove filler words from transcript captions.

    - Strips obvious filler words (um, uh, hmm, etc.) so they don't appear in captions.
    - Does NOT shift timestamps: word timing must match the actual audio exactly.
    """
    cleaned = []
    for w in words:
        text = w.get("word", "").strip()
        # Strip punctuation for matching, but keep original text
        bare = text.lower().strip(".,!?;:-\u2013\u2014'\"")
        if bare in _FILLER_WORDS:
            continue
        cleaned.append(w)

    return cleaned


def _build_tight_segments(
    words: list[dict],
    start_second: float,
    end_second: float,
    silence_threshold: float = 0.55,
) -> list[dict]:
    """
    Build tight keep-segments from transcript words, cutting out:
    - Filler words (um, uh, hmm) that are isolated (not mid-sentence)
    - Long silences/pauses (> silence_threshold seconds)

    Returns list of {"start": float, "end": float} segments.
    If no cuts needed, returns a single segment spanning the full range.
    """
    # Get words in clip range
    clip_words = [
        w for w in words
        if w["end"] > start_second and w["start"] < end_second
    ]

    if len(clip_words) < 3:
        return [{"start": start_second, "end": end_second}]

    # Find gaps and filler words to cut
    segments = []
    seg_start = start_second

    for i, w in enumerate(clip_words):
        text = w.get("word", "").strip()
        bare = text.lower().strip(".,!?;:-\u2013\u2014'\"")
        is_filler = bare in _FILLER_WORDS

        # Check gap before this word
        prev_end = clip_words[i - 1]["end"] if i > 0 else start_second
        gap = w["start"] - prev_end

        if gap >= silence_threshold:
            # Long pause: end current segment, start new one
            if prev_end > seg_start + 0.5:  # Don't create tiny segments
                segments.append({"start": round(seg_start, 2), "end": round(prev_end, 2)})
            seg_start = w["start"]
        elif is_filler and gap >= 0.3:
            # Isolated filler word with a gap before it: skip it
            # End segment before the filler, start after it
            if w["start"] > seg_start + 0.5:
                segments.append({"start": round(seg_start, 2), "end": round(w["start"], 2)})
            seg_start = w["end"]

    # Close final segment
    final_end = min(end_second, clip_words[-1]["end"] + 0.3)
    if final_end > seg_start + 0.5:
        segments.append({"start": round(seg_start, 2), "end": round(final_end, 2)})

    if not segments:
        return [{"start": start_second, "end": end_second}]

    # Only return multi-segment if we actually saved meaningful time
    original_duration = end_second - start_second
    kept_duration = sum(s["end"] - s["start"] for s in segments)
    saved = original_duration - kept_duration

    if saved < 0.8 or len(segments) < 2:
        # Not worth the cuts: too little saved
        return [{"start": start_second, "end": end_second}]

    return segments


_remotion_available = None  # True/False/None: environment availability, not per-clip success


def _stop_process_tree(proc: subprocess.Popen) -> None:
    if hasattr(os, "killpg"):
        try:
            pgid = os.getpgid(proc.pid)
            os.killpg(pgid, signal.SIGTERM)
            try:
                proc.wait(timeout=5)
                return
            except subprocess.TimeoutExpired:
                pass
            os.killpg(pgid, signal.SIGKILL)
            proc.wait()
            return
        except OSError:
            pass
    proc.kill()
    proc.wait()


def _run_streaming(
    cmd: list[str],
    *,
    timeout: float,
    cwd: str,
    env: dict,
) -> subprocess.CompletedProcess:
    proc = subprocess.Popen(
        cmd,
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE,
        text=True,
        cwd=cwd,
        env=env,
        start_new_session=(os.name == "posix"),
    )
    captured: dict[str, list[str]] = {"out": [], "err": []}

    def pump(stream, label: str) -> None:
        for line in iter(stream.readline, ""):
            captured[label].append(line)
            text = line.rstrip()
            if text:
                print(f"  Remotion: {text[:200]}", file=sys.stderr, flush=True)
        stream.close()

    threads = [
        threading.Thread(target=pump, args=(proc.stdout, "out"), daemon=True),
        threading.Thread(target=pump, args=(proc.stderr, "err"), daemon=True),
    ]
    for t in threads:
        t.start()
    try:
        proc.wait(timeout=timeout)
    except subprocess.TimeoutExpired:
        _stop_process_tree(proc)
        for t in threads:
            t.join(timeout=5)
        raise subprocess.TimeoutExpired(
            cmd, timeout,
            output="".join(captured["out"]),
            stderr="".join(captured["err"]),
        )
    for t in threads:
        t.join(timeout=5)
    return subprocess.CompletedProcess(
        cmd, proc.returncode, "".join(captured["out"]), "".join(captured["err"]),
    )


def _report_remotion_failure(
    stage: str,
    stdout: str | bytes | None,
    stderr: str | bytes | None,
) -> None:
    """Print why Remotion gave up, on the stream the worker reads.

    The fallback to burned-in ASS is silent by design and was silent about its
    cause too, so a render that never once used the caption components the
    studio previews with looked exactly like one that did.

    Takes bytes as well as text. A killed render reaches this through
    TimeoutExpired, which carries whatever the child had written and does not
    honour text mode when it does.
    """
    for label, stream in (("out", stdout), ("err", stderr)):
        if isinstance(stream, bytes):
            stream = stream.decode("utf-8", "replace")
        lines = [line.strip() for line in (stream or "").strip().splitlines() if line.strip()]
        for line in lines[-3:]:
            print(f"  Remotion {stage} {label}: {line[:200]}", file=sys.stderr, flush=True)


# Watermark.tsx's own numbers, so the ffmpeg fallback puts the mark where the
# Remotion renderer would have put it. Authored against a 1920-tall frame and
# scaled by the height a render actually produced, exactly as captionScale does.
REMOTION_REFERENCE_HEIGHT = 1920
REMOTION_LOGO_HEIGHT = 126
REMOTION_LOGO_INSET = 180
REMOTION_LOGO_EDGE = 108


def _kept_caption_overlay_path(output_path: str) -> str:
    base, _ = os.path.splitext(os.path.abspath(output_path))
    return f"{base}_captions.mov"


def _render_with_remotion(
    video_path: str,
    words: list[dict],
    caption_style: str,
    output_path: str,
    time_offset: float = 0.0,
    logo_path: Optional[str] = None,
    name_card: Optional[dict] = None,
    motion: Optional[dict] = None,
    keep_caption_overlay: bool = False,
    caption_position: str = "auto",
    caption_font_scale: int = 100,
    logo_position: str = "top-left",
    logo_scale: float = 1.0,
    topic: Optional[dict] = None,
    progress: Optional[dict] = None,
    cards: Optional[list] = None,
    brand: Optional[dict] = None,
    font_family: Optional[str] = None,
    theme: Optional[dict] = None,
    captions: bool = True,
) -> tuple[bool, Optional[str]]:
    """
    Render captions using Remotion. Returns (success, optional_prores_overlay_path).
    """
    global _remotion_available
    import subprocess
    import json

    # Quick bail only if the environment is known unavailable for this session.
    # Transient per-clip render failures should not poison the rest of the batch.
    if _remotion_available is False:
        return False, None

    # Find the render script
    project_root = paths["project_root"]
    render_script = os.path.join(project_root, "remotion", "render.mjs")
    if not os.path.exists(render_script):
        _remotion_available = False
        return False, None

    # Check node is available
    node_path = os.environ.get("PODCLI_NODE") or shutil.which("node")
    if not node_path:
        _remotion_available = False
        return False, None

    # Cache the compiled bundle next to the render script. The compositions are
    # project-independent, so a single global bundle (in the managed runtime dir
    # for native installs) is reused across every project instead of rebuilt per
    # data/cache.
    bundle_cache_root = os.path.join(os.path.dirname(render_script), ".bundle-cache")
    remotion_env = {**os.environ, "PODCLI_CACHE_DIR": bundle_cache_root}

    cache_dir = os.path.join(bundle_cache_root, "remotion-bundle")
    bundle_index = os.path.join(cache_dir, "index.html")
    if not os.path.exists(bundle_index):
        try:
            r = subprocess.run(
                [node_path, render_script, "--prebundle"],
                timeout=180,
                cwd=project_root,
                env=remotion_env,
                capture_output=True,
                text=True,
            )
            if r.returncode != 0 or not os.path.exists(bundle_index):
                _remotion_available = False
                _report_remotion_failure("bundling", r.stdout, r.stderr)
                return False, None
        except Exception as exc:
            _remotion_available = False
            print(f"  Remotion bundling: {type(exc).__name__}: {exc}",
                  file=sys.stderr, flush=True)
            return False, None

    # Prepare words JSON (adjust timestamps by offset)
    #
    # Captions off draws every other part and none of the words. The logo, the
    # topic chip, the progress bar and the cards are all drawn by this one pass,
    # so the alternative to an empty list here is skipping the pass and losing
    # them with it, which is what "captions off" used to quietly mean.
    adjusted_words = []
    for w in (words if captions else []):
        adjusted = {
            "word": w.get("word", ""),
            "start": round(w["start"] - time_offset, 3),
            "end": round(w["end"] - time_offset, 3),
        }
        # The chunker starts a new caption card on a speaker change. Dropping the
        # field here left that rule dead in the render while the studio preview,
        # which keeps it, chunked the same words differently.
        if w.get("speaker") is not None:
            adjusted["speaker"] = w["speaker"]
        adjusted_words.append(adjusted)

    # Extract face Y positions so captions can avoid overlapping faces
    # Probe video dimensions
    face_y_norm = None  # normalized 0-1 (0=top, 1=bottom)
    cap = None
    try:
        probe_cmd = ["ffprobe", "-v", "error", "-select_streams", "v:0",
                     "-show_entries", "stream=height", "-of", "csv=p=0",
                     os.path.abspath(video_path)]
        vid_h = int(proc_run(probe_cmd, timeout=5, check=False).stdout.strip())

        # Get face center Y from the cropped video's face detection
        # Use a quick sample at the middle of the clip
        try:
            import cv2
            sys.path.insert(0, os.path.join(project_root, "backend"))
            from services.face_detector import create_detector, detect_faces
            cap = cv2.VideoCapture(os.path.abspath(video_path))
            if cap.isOpened():
                vid_w = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
                vid_h_actual = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
                dur = cap.get(cv2.CAP_PROP_FRAME_COUNT) / (cap.get(cv2.CAP_PROP_FPS) or 30)
                detector = create_detector(vid_w, vid_h_actual)
                if detector:
                    # Sample 5 frames
                    ys = []
                    for t in [dur * f for f in [0.1, 0.3, 0.5, 0.7, 0.9]]:
                        cap.set(cv2.CAP_PROP_POS_MSEC, t * 1000)
                        ret, frame = cap.read()
                        if ret:
                            faces = detect_faces(detector, frame, vid_w, vid_h_actual)
                            for f in faces:
                                ys.append(f["cy"] / vid_h_actual)
                    if ys:
                        face_y_norm = sum(ys) / len(ys)
        except Exception as exc:
            log_warn("clip", "face-position sampling failed, captions use default placement", error=exc)
        finally:
            if cap is not None:
                cap.release()
    except Exception as exc:
        log_warn("clip", "video height probe failed, captions use default placement", error=exc)

    words_file = output_path + ".words.json"
    try:
        payload = {
            "words": adjusted_words,
            "faceY": face_y_norm,  # normalized face center Y (0-1), null if unknown
        }
        with open(words_file, "w", encoding="utf-8") as f:
            json.dump(payload, f)

        cmd = [
            node_path, render_script,
            "--video", os.path.abspath(video_path),
            "--words", os.path.abspath(words_file),
            "--style", caption_style,
            "--output", os.path.abspath(output_path),
            "--caption-position", caption_position,
            "--caption-font-scale", str(caption_font_scale),
            "--logo-position", logo_position,
            "--logo-scale", str(logo_scale),
        ]
        if logo_path and os.path.exists(logo_path):
            cmd.extend(["--logo", os.path.abspath(logo_path)])
        if name_card and name_card.get("title"):
            cmd.extend(["--name-card", str(name_card["title"])])
            if name_card.get("subtitle"):
                cmd.extend(["--name-card-sub", str(name_card["subtitle"])])
            if name_card.get("seconds"):
                cmd.extend(["--name-card-seconds", str(name_card["seconds"])])
            if name_card.get("accent"):
                cmd.extend(["--name-card-accent", str(name_card["accent"])])
        if motion:
            cmd.extend(["--motion", json.dumps(motion)])
        # The parts a template switches on. Each is only sent when it has a
        # value, so a caller that passes none renders what it always rendered.
        if topic and topic.get("label"):
            cmd.extend(["--topic", str(topic["label"])])
            if topic.get("position"):
                cmd.extend(["--topic-position", str(topic["position"])])
            if topic.get("color"):
                cmd.extend(["--topic-color", str(topic["color"])])
            if topic.get("background"):
                cmd.extend(["--topic-background", str(topic["background"])])
        if progress:
            cmd.append("--progress")
            if progress.get("color"):
                cmd.extend(["--progress-color", str(progress["color"])])
        if cards:
            cmd.extend(["--cards", json.dumps(cards)])
        if brand:
            cmd.extend(["--brand", json.dumps(brand)])
        if font_family:
            cmd.extend(["--font-family", str(font_family)])
        if theme:
            cmd.extend(["--theme", json.dumps(theme)])
        if keep_caption_overlay:
            cmd.append("--keep-overlay")

        # Both pipes are captured. subprocess.run drains them together, so the
        # deadlock the old code avoided by pointing stderr at /dev/null could
        # not happen, and what it threw away was the only description of the
        # failure. Every clip on the Linux worker fell back to burned-in ASS
        # for months and the reason went to /dev/null with the rest of it.
        result = _run_streaming(
            cmd,
            timeout=2 * 50 * 60 + 300,
            cwd=project_root,
            env=remotion_env,
        )

        if result.returncode == 0 and os.path.exists(output_path):
            _remotion_available = True
            overlay_path = None
            if keep_caption_overlay:
                overlay_path = _kept_caption_overlay_path(output_path)
                if not os.path.exists(overlay_path):
                    overlay_path = None
            return True, overlay_path

        _report_remotion_failure("render", result.stdout, result.stderr)
        print("  Remotion: falling back to ASS for this clip", file=sys.stderr, flush=True)
        return False, None

    except subprocess.TimeoutExpired as exc:
        # Whatever the render said before it was killed, which is the half of a
        # hang worth having: a browser that never came up looks the same from
        # out here as a composition that took too long to draw.
        _report_remotion_failure("render", exc.stdout, exc.stderr)
        print("  Remotion: timed out, using ASS for this clip", file=sys.stderr, flush=True)
        return False, None
    except Exception as exc:
        print(f"  Remotion: {type(exc).__name__}: {exc}", file=sys.stderr, flush=True)
        print("  Remotion: render error, using ASS for this clip", file=sys.stderr, flush=True)
        return False, None
    finally:
        try:
            os.unlink(words_file)
        except Exception as exc:
            log_warn("clip", "could not remove words file", error=exc)


def generate_clip(
    video_path: str,
    start_second: float,
    end_second: float,
    caption_style: str = "hormozi",
    caption_position: str = "auto",
    caption_font_scale: int = 100,
    logo_position: str = "top-left",
    logo_scale: float = 1.0,
    crop_strategy: str = "face",
    format: str = "vertical",
    crop_keyframes: list[dict] = None,
    transcript_words: list[dict] = None,
    title: str = "clip",
    output_dir: Optional[str] = None,
    face_map: dict = None,
    logo_path: Optional[str] = None,
    outro_path: Optional[str] = None,
    intro_path: Optional[str] = None,
    name_card: Optional[dict] = None,
    motion: Optional[dict] = None,
    bookend_fade: float = 0.0,
    clean_fillers: bool = True,
    keep_segments: list[dict] = None,
    hook: Optional[dict] = None,
    trim_opening: Optional[bool] = None,
    preserve_timing: bool = False,
    allow_ass_fallback: bool = False,
    use_ass_captions: bool = False,
    keep_caption_overlay: bool = False,
    write_clean_variant: bool = False,
    topic: Optional[dict] = None,
    progress: Optional[dict] = None,
    cards: Optional[list] = None,
    brand: Optional[dict] = None,
    font_family: Optional[str] = None,
    theme: Optional[dict] = None,
    captions: bool = True,
    write_subtitles: Optional[bool] = None,
    progress_callback: Optional[Callable[[int, str], None]] = None,
) -> dict:
    """
    Generate a complete short-form video clip.

    Args:
        video_path: Path to source podcast video
        start_second: Clip start time
        end_second: Clip end time
        caption_style: "hormozi", "karaoke", "subtle", or "branded"
        crop_strategy: "center", "face", "speaker", or "speaker-hardcut"
        format: "vertical", "horizontal", or "square"
        transcript_words: Word-level timestamps from transcription
        title: Clip title (used in filename)
        output_dir: Where to save the final clip (defaults to temp)
        logo_path: Path to logo image (PNG). Used with "branded" style.
        hook: Optional {"start", "end", "mode"} on the source clock: a passage
            from inside the body played first. "repeat" plays it again in
            place, "move" removes it from the body.
        captions: Whether to burn captions into the video.
        write_subtitles: Whether to write .srt/.vtt sidecars. Defaults to
            following `captions` (no burned captions, no sidecars either);
            pass True to request them for a clean (caption-free) export.
        progress_callback: Optional (percent, message) callback

    Returns:
        {
            "output_path": str,
            "duration": float,
            "file_size_mb": float,
            "title": str,
        }
    """
    # Auto-enable caption overlay export when an editor integration that needs it is on.
    if not keep_caption_overlay:
        try:
            from services.integrations.manager import IntegrationsManager
            if IntegrationsManager().is_enabled("davinci_resolve"):
                keep_caption_overlay = True
        except Exception as exc:
            log_warn("clip", "could not check the DaVinci Resolve integration", error=exc)

    if not os.path.exists(video_path):
        raise FileNotFoundError(f"Video not found: {video_path}")

    if end_second <= start_second:
        raise ValueError("end_second must be greater than start_second")

    # A video-only source (e.g. a silent screen recording) never gets an
    # audio stream from any of the steps below, so requiring one would
    # reject every render of it as "broken" instead of a legitimately
    # silent clip.
    source_has_audio = probe_has_audio_stream(video_path)

    # ffmpeg's -ss/-t cut silently stops at EOF when end_second runs past the
    # source, so without this the render "succeeds" with a shorter clip than
    # requested while duration/end_second in the result still say the planned
    # (too-long) window. Bound every range to what the source actually has.
    source_duration = _get_media_duration(video_path)
    end_second, keep_segments = _bound_range_to_source(
        start_second, end_second, keep_segments, source_duration
    )

    # Checked against the requested body, before any tightening moves it.
    hook = validate_hook(hook, start_second, end_second, keep_segments)
    requested_start = start_second

    spec = get_format(format)

    # An episode that was never filmed takes the other road entirely. Branching
    # here rather than at the five call sites means every caller of this
    # function gets it, and none of them has to know the difference: what comes
    # back is the same dict describing the same window.
    from services.audiogram import is_audio_only
    if is_audio_only(video_path):
        if hook:
            raise ValueError(
                "An opening hook needs a video source. Audiogram clips play one "
                "continuous range. Drop the hook to render this audio-only clip."
            )
        from services.audiogram import render_audiogram
        return render_audiogram(
            audio_path=video_path,
            start_second=start_second,
            end_second=end_second,
            caption_style=caption_style,
            spec=spec,
            transcript_words=transcript_words,
            title=title,
            output_dir=output_dir,
            progress_callback=progress_callback,
        )

    if trim_opening is None:
        trim_opening = not (keep_segments and len(keep_segments) > 0)

    llm_start_second, llm_end_second = start_second, end_second
    orig_keep_segments = None
    if keep_segments and len(keep_segments) > 0:
        llm_start_second = keep_segments[0]["start"]
        llm_end_second = keep_segments[-1]["end"]
        orig_keep_segments = [dict(s) for s in keep_segments if s["end"] > s["start"]]
        llm_total = max(0.01, sum(s["end"] - s["start"] for s in orig_keep_segments))
    else:
        llm_total = max(0.01, llm_end_second - llm_start_second)

    # Multi-segment cutting: if keep_segments provided, use those ranges.
    # Otherwise auto-detect silences/fillers and build tight segments.
    if keep_segments and len(keep_segments) > 0:
        # Validate segments from Claude
        keep_segments = [s for s in keep_segments if s["end"] > s["start"]]
        keep_segments.sort(key=lambda s: s["start"])

        if trim_opening and transcript_words:
            trimmed_start = _trim_weak_opening(
                transcript_words,
                keep_segments[0]["start"],
                keep_segments[0]["end"],
            )
            if trimmed_start < keep_segments[0]["end"] - 0.5:
                keep_segments[0]["start"] = trimmed_start

        if transcript_words:
            snapped_end = _snap_to_sentence_end(
                transcript_words,
                keep_segments[-1]["start"],
                keep_segments[-1]["end"],
            )
            if snapped_end > keep_segments[-1]["end"]:
                keep_segments[-1]["end"] = snapped_end

        start_second = keep_segments[0]["start"]
        end_second = keep_segments[-1]["end"]

        # If Claude returned a single segment, still auto-trim pauses within it.
        # Multiple segments means Claude made deliberate editorial cuts. Trust those.
        if len(keep_segments) == 1 and transcript_words and clean_fillers:
            auto_segments = _build_tight_segments(
                transcript_words, start_second, end_second,
            )
            if len(auto_segments) > 1:
                keep_segments = auto_segments

        duration = sum(s["end"] - s["start"] for s in keep_segments)
    else:
        if trim_opening and transcript_words:
            start_second = _trim_weak_opening(transcript_words, start_second, end_second)

        if transcript_words:
            end_second = _snap_to_sentence_end(transcript_words, start_second, end_second)

        # Auto-build tight segments: cut long pauses and isolated fillers
        if transcript_words and clean_fillers:
            auto_segments = _build_tight_segments(
                transcript_words, start_second, end_second,
            )
            if len(auto_segments) > 1:
                keep_segments = auto_segments
                duration = sum(s["end"] - s["start"] for s in keep_segments)
            else:
                keep_segments = None
                duration = end_second - start_second
        else:
            keep_segments = None
            duration = end_second - start_second

    if duration < 0.75 * llm_total and llm_total >= 8.0:
        print(
            f"  Boundary revert: post-trim duration {duration:.1f}s < "
            f"75% of asked {llm_total:.1f}s - using original range",
            file=sys.stderr,
            flush=True,
        )
        if orig_keep_segments:
            keep_segments = [dict(s) for s in orig_keep_segments]
            keep_segments.sort(key=lambda s: s["start"])
            start_second = keep_segments[0]["start"]
            end_second = keep_segments[-1]["end"]
            duration = sum(s["end"] - s["start"] for s in keep_segments)
        elif (llm_end_second - llm_start_second) <= spec.dur_max:
            start_second = llm_start_second
            end_second = llm_end_second
            keep_segments = None
            duration = end_second - start_second

    # The body is final here. The hook is cut as given (widened only to whole
    # words) and put ahead of it, so every later step reads play_ranges, in
    # playback order, never re-sorted. None means one continuous range.
    play_ranges = keep_segments if keep_segments and len(keep_segments) > 1 else None
    if hook:
        hook = snap_hook_to_words(hook, transcript_words)
        body = keep_segments or [{"start": start_second, "end": end_second}]
        play_ranges = order_with_hook(body, hook)
        duration = sum(r["end"] - r["start"] for r in play_ranges)

    length_warning = None
    # A clip that asks for captions and renders without them used to be
    # indistinguishable from a clip that never wanted them. Two shipped clips
    # went out silent that way.
    caption_warning = None
    glyph_warning = None
    if duration > spec.dur_max:
        length_warning = f"{duration:.0f}s, over the {spec.dur_max}s {spec.name} target"
        print(f"  {length_warning}", file=sys.stderr, flush=True)

    # Load style config for branded-specific settings
    style_config = get_style(caption_style)

    # Create temp working directory
    work_dir = tempfile.mkdtemp(prefix="podcast_clip_")
    caption_overlay_path = None

    try:
        total_steps = 4 + (1 if outro_path and os.path.exists(str(outro_path)) else 0) + (
            1 if intro_path and os.path.exists(str(intro_path)) else 0
        )

        # Step 1: Cut the segment(s) from the source video
        if progress_callback:
            n_segs = len(play_ranges) if play_ranges else 1
            msg = f"Cutting {n_segs} segment{'s' if n_segs > 1 else ''} (1/{total_steps})"
            progress_callback(10, msg)

        segment_path = os.path.join(work_dir, "segment.mp4")
        part_durations: Optional[list[float]] = None
        with timed("render", "cut", segments=len(play_ranges) if play_ranges else 1):
            if play_ranges:
                _, part_durations = cut_multi_segment(video_path, segment_path, play_ranges)
            else:
                cut_segment(video_path, segment_path, start_second, end_second)

        # Remap transcript words for multi-segment clips, range by range in
        # playback order, so a repeated hook's words appear twice.
        # Needed before crop (speaker detection) and captions.
        remapped_words: list[dict] = []
        if play_ranges and transcript_words:
            cumulative_t = 0.0
            for i, seg in enumerate(play_ranges):
                seg_words = [
                    w for w in transcript_words
                    if w["end"] > seg["start"] and w["start"] < seg["end"]
                ]
                # Each part is encoded separately before the concat, and an
                # encoder snaps a cut to whole frames, so its real duration is
                # typically a few ms off the requested end - start. Advancing
                # cumulative_t by the planned length instead of the probed
                # one drifts captions further out of sync with every segment
                # concatenated in. Fall back to the planned length only if
                # the part couldn't be probed.
                requested_duration = seg["end"] - seg["start"]
                actual_duration = (
                    part_durations[i]
                    if part_durations and part_durations[i] > 0
                    else requested_duration
                )
                for w in seg_words:
                    # Clamp to segment bounds to avoid negative/overflow timestamps
                    # for words that straddle a segment boundary
                    remapped_start = max(cumulative_t, cumulative_t + (w["start"] - seg["start"]))
                    remapped_end = min(cumulative_t + actual_duration, cumulative_t + (w["end"] - seg["start"]))
                    if remapped_end > remapped_start:
                        remapped_words.append({
                            **w,
                            "start": round(remapped_start, 3),
                            "end": round(remapped_end, 3),
                        })
                cumulative_t += actual_duration
            crop_words = remapped_words
            crop_clip_start = 0
            caption_time_offset = 0
        else:
            # Filter words to just this clip's time range
            crop_words = [
                w for w in transcript_words
                if w["end"] > start_second and w["start"] < end_second
            ] if transcript_words else transcript_words
            crop_clip_start = start_second
            caption_time_offset = start_second

        # Step 2: Crop to vertical 9:16
        if progress_callback:
            progress_callback(30, f"Resizing for {spec.name} format (2/{total_steps})")

        playback_keyframes = keyframes_to_playback(
            crop_keyframes,
            requested_start,
            play_ranges or [{"start": start_second, "end": end_second}],
            part_durations,
        ) if crop_keyframes else crop_keyframes

        cropped_path = os.path.join(work_dir, "cropped.mp4")
        with timed("render", "crop", strategy=crop_strategy if spec.reframe else "fit"):
            if spec.reframe:
                crop_to_vertical(
                    segment_path, cropped_path,
                    strategy=crop_strategy,
                    transcript_words=crop_words,
                    clip_start=crop_clip_start,
                    face_map=face_map,
                    crop_keyframes=playback_keyframes,
                    target_dims=spec.dims,
                )
            else:
                fit_to_frame(segment_path, cropped_path, target_dims=spec.dims)

        # Only Remotion draws the name card, and --fast forces the ASS renderer,
        # which cannot. Refusing beats returning a clip that quietly lacks the
        # overlay that was asked for.
        #
        # Permitting the fallback is no longer a reason to refuse: a card is an
        # overlay, the pass that draws it runs for overlays whether or not there
        # are words to caption, and a failure there raises rather than handing
        # back a bare cut. Refusing on the permission alone meant every `studio`
        # render, which always permits it, could never draw one.
        if name_card and name_card.get("title") and use_ass_captions:
            raise ValueError(
                "A name card is drawn by the Remotion renderer, and --fast forces "
                "the ASS one. Drop --name-card, or drop --fast."
            )

        # Step 3: Render captions (Remotion-first; ASS fallback optional)
        #
        # The drawn layer is not only the words. The logo, topic chip, progress
        # bar and cards are drawn by the same Remotion pass, so a clip that
        # wants any of them needs that pass to run whether or not it is being
        # captioned. Without this, "captions off" silently meant "nothing on
        # screen at all", and a clip that had cards to draw ran the pass and
        # burned the default caption style over a file that had asked for none.
        wants_overlay = bool(
            logo_path or topic or progress or cards or theme
            or (name_card and name_card.get("title"))
        )
        # Default so the sidecar/clean-variant step below has something to
        # check even when neither branch below runs (no transcript, no overlay).
        clip_words = []
        if not captions and wants_overlay:
            print("  drawing the overlay without captions", flush=True)

        if not transcript_words and not wants_overlay:
            caption_warning = (
                f"rendered without captions: no transcript words were passed, so the "
                f"{caption_style} style had nothing to draw"
            )
            print(f"  {caption_warning}", file=sys.stderr, flush=True)

        if transcript_words or wants_overlay:
            if progress_callback:
                progress_callback(50, f"Adding {caption_style} captions (3/{total_steps})")

            if play_ranges:
                clip_words = remapped_words
            else:
                clip_words = [
                    w for w in (transcript_words or [])
                    if w["end"] > start_second and w["start"] < end_second
                ]

            words_in_range = len(clip_words)

            # Clean filler words
            if clean_fillers:
                clip_words = _clean_transcript_words(clip_words)

            if not clip_words:
                caption_warning = (
                    "rendered without captions: filler cleaning removed every one of "
                    f"the {words_in_range} words in range"
                    if words_in_range
                    else (
                        "rendered without captions: no transcript words fall between "
                        f"{start_second:.1f}s and {end_second:.1f}s"
                    )
                )
                print(f"  {caption_warning}", file=sys.stderr, flush=True)

            if clip_words and captions:
                caption_text = " ".join(w.get("word", "") for w in clip_words)
                glyph_warning = check_caption_font_coverage(
                    caption_text, style_config["font_name"], bool(style_config["bold"]),
                    use_ass=use_ass_captions,
                )
                if glyph_warning:
                    print(f"  {glyph_warning}", file=sys.stderr, flush=True)

            if (clip_words and captions) or wants_overlay:
                if progress_callback:
                    progress_callback(65, f"Rendering captions into video (3/{total_steps})")

                captioned_path = os.path.join(work_dir, "captioned.mp4")

                remotion_ok = False
                caption_overlay_path = None
                if not use_ass_captions:
                    remotion_ok, caption_overlay_path = _render_with_remotion(
                        video_path=cropped_path,
                        words=clip_words,
                        caption_style=caption_style,
                        output_path=captioned_path,
                        time_offset=caption_time_offset,
                        logo_path=logo_path or None,
                        name_card=name_card,
                        motion=motion,
                        keep_caption_overlay=keep_caption_overlay,
                        caption_position=caption_position,
                        caption_font_scale=caption_font_scale,
                        logo_position=logo_position,
                        logo_scale=logo_scale,
                        topic=topic,
                        progress=progress,
                        cards=cards,
                        brand=brand,
                        font_family=font_family,
                        theme=theme,
                        captions=captions,
                    )

                if not remotion_ok and not captions:
                    # Nothing else can draw a chip, a bar or a card: the ASS
                    # path burns words and an overlay is not words. Handing
                    # back the bare cut here would report success for a clip
                    # missing everything it was asked for, which is the failure
                    # this whole switch exists to stop being silent.
                    if wants_overlay:
                        raise RuntimeError(
                            "The overlay could not be drawn: the Remotion renderer "
                            "failed and nothing else draws a logo, chip, bar or card. "
                            "The clip is not being delivered without them."
                        )
                    # Only a trim and a reframe were asked for, and both are
                    # already in the cut.
                    captioned_path = cropped_path

                if not remotion_ok and captions and not allow_ass_fallback:
                    raise RuntimeError(
                        "Remotion caption render failed. ASS fallback is disabled "
                        "(set allow_ass_fallback=true to permit fallback)."
                    )

                if not remotion_ok and captions and allow_ass_fallback:
                    # Optional fallback: ASS subtitle burn-in
                    ass_path = os.path.join(work_dir, "captions.ass")
                    render_captions(
                        words=clip_words,
                        caption_style=caption_style,
                        output_path=ass_path,
                        time_offset=caption_time_offset,
                        caption_position=caption_position,
                        caption_font_scale=caption_font_scale,
                    )

                    use_gradient = style_config.get("gradient_overlay", False)
                    gradient_opacity = style_config.get("gradient_opacity", 0.6)
                    use_logo = bool(logo_path)

                    """
                    The mark, the size Remotion would have drawn it.

                    This path burns a logo with ffmpeg because Remotion could
                    not run, and it used a flat 80px in a fixed corner: it read
                    neither the frame height nor the template's logo scale. The
                    same clip therefore carried a different mark depending on
                    which renderer happened to succeed, and the studio preview
                    only ever showed the Remotion one. These are Watermark.tsx's
                    own numbers against the frame this render actually produced.
                    """
                    from services.video_processor import get_dimensions
                    _, out_h = get_dimensions(cropped_path)
                    logo_s = (out_h or REMOTION_REFERENCE_HEIGHT) / REMOTION_REFERENCE_HEIGHT

                    burn_captions(
                        input_path=cropped_path,
                        ass_path=ass_path,
                        output_path=captioned_path,
                        gradient_overlay=use_gradient,
                        gradient_opacity=gradient_opacity,
                        logo_path=logo_path if use_logo else None,
                        logo_height=round(REMOTION_LOGO_HEIGHT * logo_s * logo_scale),
                        logo_margin_x=round(REMOTION_LOGO_EDGE * logo_s),
                        logo_margin_y=round(REMOTION_LOGO_INSET * logo_s),
                        logo_position=logo_position,
                    )
            else:
                captioned_path = cropped_path
        else:
            captioned_path = cropped_path

        # Step 4: Normalize audio
        if progress_callback:
            progress_callback(70, f"Balancing audio levels (4/{total_steps})")

        normalized_path = os.path.join(work_dir, "normalized.mp4")
        normalize_audio(captioned_path, normalized_path)

        # Step 5: Prepend intro, then append outro (if provided).
        # concat_outro joins two clips head-to-tail, so passing the intro first
        # puts it in front of the clip.
        final_video_path = normalized_path
        intro_offset = 0.0
        if intro_path and os.path.exists(intro_path):
            if progress_callback:
                progress_callback(83, "Adding intro")
            # concat_outro outputs at its first arg's dimensions, so match the
            # intro to the clip's frame or a landscape intro reshapes the clip.
            from services.video_processor import get_dimensions, scale_to_frame
            cw, ch = get_dimensions(final_video_path)
            intro_scaled = os.path.join(work_dir, "intro_scaled.mp4")
            scale_to_frame(intro_path, intro_scaled, cw, ch)
            with_intro_path = os.path.join(work_dir, "with_intro.mp4")
            clip_duration = _get_media_duration(final_video_path)
            concat_outro(intro_scaled, final_video_path, with_intro_path,
                         crossfade_duration=bookend_fade)
            final_video_path = with_intro_path
            intro_offset = max(0.0, _get_media_duration(with_intro_path) - clip_duration)

        outro_offset = 0.0
        if outro_path and os.path.exists(outro_path):
            if progress_callback:
                progress_callback(85, f"Adding outro ({total_steps}/{total_steps})")

            pre_outro_duration = _get_media_duration(final_video_path)
            with_outro_path = os.path.join(work_dir, "with_outro.mp4")
            concat_outro(final_video_path, outro_path, with_outro_path,
                         crossfade_duration=bookend_fade)
            final_video_path = with_outro_path
            outro_offset = max(0.0, _get_media_duration(with_outro_path) - pre_outro_duration)

        # Step 6: Move to output
        if progress_callback:
            progress_callback(95, "Saving final clip...")

        if output_dir:
            os.makedirs(output_dir, exist_ok=True)
            final_path = _reserve_output_path(output_dir, f"{safe_filename(title)}_short", ".mp4")
        else:
            fd, final_path = tempfile.mkstemp(
                prefix=f"{safe_filename(title)}_short_", suffix=".mp4"
            )
            os.close(fd)

        shutil.copy2(final_video_path, final_path)

        align_av_duration(final_path)

        # Optional bounded QA/autofix pass for transition jumps.
        # Hard-capped to avoid any infinite rerender loop.
        max_autofix_passes = _render_transition_autofix_passes(
            preserve_timing=preserve_timing,
            reframe=spec.reframe,
            crop_strategy=crop_strategy,
            crop_keyframes=crop_keyframes,
            keep_segments=play_ranges,
        )
        if max_autofix_passes > 0:
            if progress_callback:
                progress_callback(97, "Quality gate: checking transitions...")
            # The cut from the hook into the body is deliberate. Smoothing
            # it would blur the first beat the hook exists to land.
            hook_cut = [intro_offset + (part_durations[0] if part_durations else 0.0)] if hook else []
            _auto_fix_transition_jumps(
                final_path,
                max_passes=max_autofix_passes,
                designed=_designed_cuts(cards, offset=intro_offset) + hook_cut,
            )

        # A 0-exit ffmpeg run can still have written a short, silent, or
        # corrupt file (source ran out under the requested range, a crop/
        # caption/normalize pass dropped the audio track, a concat mismatch).
        # Catch that here instead of returning a "successful" result that
        # describes a different clip than what landed on disk.
        expected_duration = duration + intro_offset + outro_offset
        actual_duration = _get_media_duration(final_path)
        duration_tolerance = max(0.75, 0.05 * expected_duration)
        if actual_duration <= 0 or abs(actual_duration - expected_duration) > duration_tolerance:
            os.remove(final_path)
            raise RuntimeError(
                f"Render produced a {actual_duration:.2f}s file but expected "
                f"~{expected_duration:.2f}s (body {duration:.2f}s"
                f"{f' + intro {intro_offset:.2f}s' if intro_offset else ''}"
                f"{f' + outro {outro_offset:.2f}s' if outro_offset else ''}). "
                f"The source video likely ended before the requested range, or "
                f"the render failed partway through."
            )
        if source_has_audio and not probe_has_audio_stream(final_path):
            os.remove(final_path)
            raise RuntimeError(
                "Render completed but the output has no audio stream. "
                "Re-check the source video and caption/crop pipeline."
            )
        decode_error = verify_full_decode(final_path)
        if decode_error:
            os.remove(final_path)
            raise RuntimeError(f"Render produced an undecodable output: {decode_error}")

        # Sidecar subtitles: the same words already burned into the video,
        # on the same playback clock as the delivered file (clip-local time,
        # shifted past whatever intro got prepended). clip_words is populated
        # for overlay-only renders too (logo/cards with captions off), so
        # gate on whether captions were actually requested rather than just
        # "were there words": otherwise a captions-off render still gets an
        # .srt/.vtt describing dialogue nothing on screen shows.
        want_subtitles = write_subtitles if write_subtitles is not None else captions
        output_base, _ = os.path.splitext(final_path)
        sidecar_paths: dict = {}
        # A re-render claims the same output path as last time
        # (_reserve_output_path), so a sidecar this pass doesn't produce can
        # be a leftover from a previous render of this clip, now describing
        # dialogue or a style that no longer matches. Clear it before
        # (maybe) writing a fresh one.
        for stale_ext in (".srt", ".vtt"):
            stale_sidecar = f"{output_base}{stale_ext}"
            if os.path.exists(stale_sidecar):
                os.remove(stale_sidecar)
        if want_subtitles:
            retimed_words = [
                {
                    "word": w.get("word", ""),
                    "start": round(max(0.0, w["start"] - caption_time_offset + intro_offset), 3),
                    "end": round(max(0.0, w["end"] - caption_time_offset + intro_offset), 3),
                }
                for w in clip_words
            ]
            sidecar_paths = write_sidecars(retimed_words, output_base)

        # Optional clean variant: the same audio, loudness, and intro/outro,
        # minus burned captions, built from the cropped (pre-caption)
        # source with the identical normalize_audio/concat_outro calls the
        # main render used, so the two files only differ in the overlay.
        clean_output_path = None
        stale_clean_path = f"{output_base}_clean.mp4"
        if os.path.exists(stale_clean_path):
            os.remove(stale_clean_path)
        if write_clean_variant and os.path.exists(cropped_path):
            clean_normalized_path = os.path.join(work_dir, "clean_normalized.mp4")
            normalize_audio(cropped_path, clean_normalized_path)
            clean_video_path = clean_normalized_path

            if intro_path and os.path.exists(intro_path):
                clean_with_intro_path = os.path.join(work_dir, "clean_with_intro.mp4")
                concat_outro(intro_scaled, clean_video_path, clean_with_intro_path,
                             crossfade_duration=bookend_fade)
                clean_video_path = clean_with_intro_path

            if outro_path and os.path.exists(outro_path):
                clean_with_outro_path = os.path.join(work_dir, "clean_with_outro.mp4")
                concat_outro(clean_video_path, outro_path, clean_with_outro_path,
                             crossfade_duration=bookend_fade)
                clean_video_path = clean_with_outro_path

            clean_output_path = f"{output_base}_clean.mp4"
            shutil.copy2(clean_video_path, clean_output_path)

        # Get file size
        file_size = os.path.getsize(final_path)
        file_size_mb = round(file_size / (1024 * 1024), 2)

        if progress_callback:
            progress_callback(100, "Clip complete!")

        # "duration" has always meant the content's own length: what
        # clip_history and the learnings it feeds record, not however long
        # the delivered file plays including intro/outro. Derive it from the
        # probed actual_duration (not the planned `duration` window) so a
        # source that ran out early still gets caught by the check above and
        # reported as shorter, instead of silently reporting the plan.
        content_duration = max(0.0, actual_duration - intro_offset - outro_offset)

        out = {
            "output_path": final_path,
            "duration": round(content_duration, 2),
            # The probed duration of the file actually on disk, including any
            # intro/outro, for callers that need the delivered file's full
            # playback length rather than just its content.
            "output_duration": round(actual_duration, 2),
            "file_size_mb": file_size_mb,
            "title": title,
            "start_second": start_second,
            "end_second": end_second,
            "caption_style": caption_style,
            "crop_strategy": crop_strategy,
            "format": spec.name,
            **sidecar_paths,
        }
        if clean_output_path:
            out["clean_output_path"] = clean_output_path
        if hook:
            out["hook"] = hook
        warnings = [w for w in (caption_warning, length_warning, glyph_warning) if w]
        if warnings:
            out["warning"] = "; ".join(warnings)
        if keep_caption_overlay and caption_overlay_path and os.path.exists(caption_overlay_path):
            # Copy out of work_dir before cleanup so the returned paths survive.
            base, _ = os.path.splitext(final_path)
            persisted_overlay = f"{base}_captions.mov"
            shutil.copy2(caption_overlay_path, persisted_overlay)
            out["caption_overlay_path"] = persisted_overlay
            if os.path.exists(cropped_path):
                persisted_source = f"{base}_source.mp4"
                shutil.copy2(cropped_path, persisted_source)
                out["cropped_source_path"] = persisted_source
        return out

    finally:
        if os.path.exists(work_dir):
            shutil.rmtree(work_dir, ignore_errors=True)