Skip to content

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

32.3 KB
Raw Blame
"""
Thumbnail generator using HTML/CSS + headless browser screenshot.

Renders thumbnails via a headless browser for pixel-perfect CSS control
over fonts, letter-spacing, line-height, and highlight styling.

EVERY visual property is driven by config. The defaults here are generic;
brand-specific values live in .podcli/thumbnail-config.json.
"""

import json
import os
from html import escape as html_escape
from utils.log import warn as log_warn
from pathlib import Path
import re
import shutil
import subprocess
from config.paths import paths
from utils.proc import run as proc_run, ProcError
from utils.text import safe_upper
import sys
import tempfile
from typing import Optional


_THUMBNAIL_LEADING_FILLERS = {
    "a", "an", "the", "we", "i", "they", "he", "she", "it", "there", "this", "that",
    "these", "those", "our", "your", "their", "my", "so", "well", "and", "but",
}
_THUMBNAIL_LINE_STOPWORDS = {
    "a", "an", "and", "as", "at", "for", "from", "in", "into", "of", "on",
    "or", "that", "the", "to", "with",
}
_THUMBNAIL_SPLIT_SEPARATORS = (" / ", " \u2014 ", " \u2013 ", " - ", ": ", "; ", ", ")


def _load_config() -> dict:
    """Load thumbnail config, merged with defaults.

    Defaults are intentionally generic so each project gets its own look
    via .podcli/thumbnail-config.json.
    """
    defaults = {
        "width": 1080,
        "height": 1920,

        # Colors - placeholder palette. Override in your brand config
        # at `.podcli/thumbnail-config.json` (run `podcli init-thumbnail`
        # to scaffold one).
        "bg_color": "#FFFFFF",
        "text_color": "#000000",
        "accent_color": "#000000",

        # Frame border (around entire thumbnail)
        "frame_border_width": 3,
        "frame_border_color": None,  # None = accent

        # Text box
        "box_x": "40px",        # CSS left, near edge with safe area
        "box_y": "73%",         # CSS top (no photo)
        "box_y_with_photo": "76%",
        "box_width": "1000px",  # CSS width, max width with safe areas
        "box_min_height": "180px",
        "box_border_width": 3,
        "box_border_color": None,  # None = accent
        "box_fill_color": "rgba(255,255,255,0.92)",
        "box_padding": "24px 32px",

        # Line 1 (top line: typically white text)
        "line1_font_size": "56px",
        "line1_font_weight": "600",
        "line1_letter_spacing": "1px",
        "line1_line_height": 1.15,
        "line1_margin_bottom": "8px",
        "line1_uppercase": True,
        "line1_color": "#000000",
        "line1_nowrap": True,

        # Line 2 (bottom line: highlighted)
        "line2_font_size": "52px",
        "line2_font_weight": "400",
        "line2_font_style": "italic",
        "line2_letter_spacing": "1px",
        "line2_line_height": 1.15,
        "line2_uppercase": True,
        "line2_highlight_color": None,  # None = accent
        "line2_text_color": "#FFFFFF",
        "line2_highlight_padding": "4px 16px",

        # Photo
        "photo_brightness": 0.85,

        # Layout: "single" is one face behind the headline. "pair" puts two
        # people from the clip side by side, the guest left and the host right,
        # over the top of the canvas, with the headline in the clear space below.
        "layout": "single",
        "pair_photo_height": "70%",
        "pair_box_y": "85%",
        "pair_divider_width": 4,

        # Gradients
        "gradient_top_height": "25%",
        "gradient_top_start_color": "rgba(0,0,0,0.5)",
        "gradient_top_end_color": "transparent",
        "gradient_bottom_start": "50%",
        "gradient_bottom_end_color": "#FFFFFF",
        "gradient_bottom_fade_point": "70%",

        # Logo
        "logo_position": "bottom-center",  # top-left, top-right, top-center, bottom-center, none
        "logo_height": "50px",
        "logo_margin": "50px",
        "logo_opacity": 0.35,

        # Font. 'Inter' has no Georgian glyphs, so a Georgian-language show's
        # headline would fall through to the browser's generic sans-serif with
        # no brand voice at all. Noto Sans Georgian is the same family the
        # Remotion caption renderer bundles for the same reason (see
        # remotion/src/types.ts FONT), kept consistent so a thumbnail and its
        # clip's captions render the same typeface for non-Latin text.
        "font_family": "'Inter', 'Helvetica Neue', 'Arial', 'Noto Sans Georgian', sans-serif",
        "font_import_url": "https://fonts.googleapis.com/css2?family=Inter:ital,wght@0,400;0,500;0,600;0,700;1,400;1,500;1,600;1,700&family=Noto+Sans+Georgian:wght@400;700&display=swap",

        # Variations
        "variations": 3,
        "variation_offset_up": "3%",
        "variation_offset_down": "2%",
        "playwright_wait_ms": 1500,
        "playwright_timeout_ms": 150000,
    }

    config_path = paths["thumbnailConfig"]
    if os.path.exists(config_path):
        try:
            with open(config_path, encoding="utf-8") as f:
                user = json.load(f)
            defaults.update(user)
        except Exception as exc:
            log_warn("thumbnail", "thumbnail config is corrupt, using defaults", error=exc)
    return defaults


def _playwright_cli_candidates() -> list[list[str]]:
    """Return Playwright CLI commands in preference order."""
    repo_root = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "..")
    # On Windows the runnable shim is playwright.cmd; the extensionless file is a POSIX script.
    local_name = "playwright.cmd" if sys.platform == "win32" else "playwright"
    local_bin = os.path.join(repo_root, "node_modules", ".bin", local_name)

    candidates = []
    if os.path.exists(local_bin):
        candidates.append([local_bin])

    global_bin = shutil.which("playwright")
    if global_bin:
        candidates.append([global_bin])

    npx_bin = shutil.which("npx")
    if npx_bin:
        candidates.append([npx_bin, "--no-install", "playwright"])
        candidates.append([npx_bin, "playwright"])

    deduped = []
    seen = set()
    for cmd in candidates:
        key = tuple(cmd)
        if key not in seen:
            seen.add(key)
            deduped.append(cmd)
    return deduped


def _remotion_screenshot_script_path() -> str:
    """Return the local Remotion screenshot helper script path."""
    return os.path.join(
        os.path.dirname(os.path.abspath(__file__)),
        "..",
        "scripts",
        "remotion_screenshot.cjs",
    )


def _build_remotion_screenshot_command(
    script_path: str,
    html_path: str,
    output_path: str,
    width: int,
    height: int,
    wait_ms: int,
) -> Optional[list[str]]:
    """Build a Remotion-backed screenshot command if the repo can run it."""
    node_bin = os.environ.get("PODCLI_NODE") or shutil.which("node")
    repo_root = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "..")
    renderer_pkg = os.path.join(repo_root, "node_modules", "@remotion", "renderer", "package.json")
    if not node_bin or not os.path.exists(script_path) or not os.path.exists(renderer_pkg):
        return None

    return [
        node_bin,
        script_path,
        html_path,
        output_path,
        str(width),
        str(height),
        str(wait_ms),
    ]


def _build_playwright_screenshot_command(
    cli_cmd: list[str],
    html_path: str,
    output_path: str,
    width: int,
    height: int,
    wait_ms: int,
) -> list[str]:
    """Build one Playwright screenshot command."""
    return [
        *cli_cmd,
        "screenshot",
        "--viewport-size", f"{width}, {height}",
        "--wait-for-timeout", str(wait_ms),
        f"file://{html_path}",
        output_path,
    ]


def _compact_thumbnail_title(title: str, max_words: int = 7, max_chars: int = 42) -> str:
    """Turn transcript-like title text into compact thumbnail copy."""
    text = re.sub(r"\s+", " ", (title or "")).strip().strip("/").strip()
    if not text:
        return ""

    replacements = [
        (r"(?i)\b(\d+)\s+megawatts?\b", r"\1MW"),
        (r"(?i)\b(\d+)\s+gigawatts?\b", r"\1GW"),
        (r"(?i)\b(\d+)\s+kilowatts?\b", r"\1kW"),
        (r"(?i)\b(\d+)\s+million\b", r"\1M"),
        (r"(?i)\b(\d+)\s+billion\b", r"\1B"),
        (r"(?i)\b(\d+)\s+trillion\b", r"\1T"),
    ]
    for pattern, repl in replacements:
        text = re.sub(pattern, repl, text)

    if len(text) > max_chars:
        for sep in _THUMBNAIL_SPLIT_SEPARATORS[1:]:
            if sep in text:
                head = text.split(sep, 1)[0].strip()
                if len(head.split()) >= 3:
                    text = head
                    break

    words = text.split()
    while len(words) > 4 and words and words[0].lower().strip(".,!?") in _THUMBNAIL_LEADING_FILLERS:
        words = words[1:]

    if len(words) > max_words:
        words = words[:max_words]

    compact = " ".join(words).strip(" -\u2014\u2013,:;.!?")
    if len(compact) > max_chars:
        compact = compact[:max_chars].rsplit(" ", 1)[0].strip(" -\u2014\u2013,:;.!?")
    return compact


def _split_thumbnail_title(title: str, max_line_chars: int = 24) -> tuple[str, str]:
    """Split compact thumbnail copy into two punchy lines."""
    text = _compact_thumbnail_title(title)
    if not text:
        return "", ""

    for sep in _THUMBNAIL_SPLIT_SEPARATORS:
        if sep in text:
            left, right = [part.strip() for part in text.split(sep, 1)]
            if left and right:
                return left, right

    words = text.split()
    if len(words) <= 2:
        return words[0] if words else "", " ".join(words[1:])

    best_split = 1
    best_score = float("inf")
    for i in range(1, len(words)):
        left_words = words[:i]
        right_words = words[i:]
        left = " ".join(left_words)
        right = " ".join(right_words)
        score = 0.0

        score += max(0, len(left) - max_line_chars) * 5
        score += max(0, len(right) - max_line_chars) * 5
        score += abs(len(left_words) - 3) * 2.5
        score += abs(len(right_words) - 4) * 2.0
        score += abs(len(left) - len(right)) * 0.35
        if left_words[-1].lower().strip(".,!?") in _THUMBNAIL_LINE_STOPWORDS:
            score += 8
        if right_words[0].lower().strip(".,!?") in _THUMBNAIL_LINE_STOPWORDS:
            score += 8

        if score < best_score:
            best_score = score
            best_split = i

    return " ".join(words[:best_split]), " ".join(words[best_split:])


def _prepare_thumbnail_lines(
    title: str,
    line1: Optional[str] = None,
    line2: Optional[str] = None,
    max_line_chars: int = 24,
) -> tuple[str, str]:
    """Normalize AI or fallback title text into compact thumbnail lines."""
    raw_line1 = re.sub(r"\s+", " ", (line1 or "")).strip().strip("/").strip()
    raw_line2 = re.sub(r"\s+", " ", (line2 or "")).strip().strip("/").strip()

    if raw_line1 and raw_line2:
        total_words = len((raw_line1 + " " + raw_line2).split())
        if (
            len(raw_line1) <= max_line_chars
            and len(raw_line2) <= max_line_chars
            and total_words <= 8
        ):
            return raw_line1, raw_line2
        title = f"{raw_line1} / {raw_line2}"
    elif raw_line1:
        title = raw_line1

    return _split_thumbnail_title(title, max_line_chars=max_line_chars)


def _layer_html(layers) -> str:
    """
    The parts a show adds itself, drawn over the template.

    The template is a fixed anatomy: a box, two lines, a logo, some shading.
    It answers most thumbnails and none of the ones that need a badge, a
    price, an arrow, or a second picture. Those are these: an ordered list,
    each one placed by its own coordinates and drawn in the order given, so
    the last in the list is the one on top.

    Two kinds, because they cover what anybody actually reaches for. A layer
    this does not understand is skipped rather than drawn wrong.
    """
    if not isinstance(layers, list):
        return ""

    def esc(value) -> str:
        return (
            str(value)
            .replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
            .replace('"', "&quot;")
        )

    def place(layer) -> str:
        # Percentages travel between canvas sizes; pixels are what a drag
        # produces. Either is passed through as written.
        css = "position:absolute;"
        for edge in ("top", "right", "bottom", "left"):
            if layer.get(edge) not in (None, ""):
                css += f" {edge}:{esc(layer[edge])};"
        if layer.get("width") not in (None, ""):
            css += f" width:{esc(layer['width'])};"
        if layer.get("rotate"):
            css += f" transform:rotate({esc(layer['rotate'])}deg);"
        opacity = layer.get("opacity")
        if opacity is not None:
            css += f" opacity:{esc(opacity)};"
        return css

    drawn = []
    for index, layer in enumerate(layers):
        if not isinstance(layer, dict) or layer.get("hidden"):
            continue
        # Later in the list is nearer the front. Above the logo, which is the
        # topmost thing the template itself draws.
        css = place(layer) + f" z-index:{20 + index};"
        kind = layer.get("kind")

        if kind == "text":
            text = str(layer.get("text") or "").strip()
            if not text:
                continue
            css += (
                f" color:{esc(layer.get('color', '#FFFFFF'))};"
                f" font-size:{esc(layer.get('size', 48))}px;"
                f" font-weight:{esc(layer.get('weight', 700))};"
                " line-height:1.15; white-space:pre-wrap;"
            )
            if layer.get("background"):
                css += (
                    f" background:{esc(layer['background'])};"
                    f" padding:{esc(layer.get('padding', '10px 16px'))};"
                    f" border-radius:{esc(layer.get('radius', '10px'))};"
                )
            drawn.append(f'<div style="{css}">{esc(text)}</div>')

        elif kind == "image":
            src = str(layer.get("src") or "").strip()
            if not src:
                continue
            # A path from this machine needs the scheme; a URL already has one.
            #
            # as_uri rather than a prefix: a Windows path is D:\tmp\x.png, and
            # gluing "file://" to that gives a browser backslashes and a host
            # where it wants a third slash and a drive.
            if not src.startswith(("http://", "https://", "file://", "data:")):
                src = Path(os.path.abspath(src)).as_uri()
            css += " height:auto;"
            if layer.get("radius"):
                css += f" border-radius:{esc(layer['radius'])};"
            drawn.append(f'<img src="{esc(src)}" style="{css}" />')

    return "\n    ".join(drawn)


def pair_panel_size(config: dict) -> tuple[int, int]:
    """Pixel size of one person's panel in the pair layout."""
    height_pct = float(str(config.get("pair_photo_height", "70%")).rstrip("%") or 70)
    return int(config["width"]) // 2, int(int(config["height"]) * height_pct / 100)


def _single_photo_layer(cfg: dict, photo_path: str) -> tuple[str, str]:
    """CSS and markup for one photo filling the canvas."""
    w, h = cfg["width"], cfg["height"]
    # as_uri() rather than an f-string: a '#' or '?' anywhere in the path is
    # a fragment or a query to the browser, so the image silently drops and
    # the card renders as bg_color with a broken-image glyph.
    photo_uri = Path(photo_path).absolute().as_uri()
    css = f"""
        .photo {{
            position: absolute; top: 0; left: 0; width: {w}px; height: {h}px;
            overflow: hidden;
            z-index: 1;
        }}
        .photo img {{
            width: 100%; height: 100%;
            object-fit: cover;
            object-position: {cfg.get("photo_object_position", "center center")};
            filter: brightness({cfg.get("photo_brightness", 0.85)});
        }}
        .photo-vignette {{
            position: absolute; top: 0; left: 0; width: 100%; height: 100%;
            z-index: 1;
        }}
        """
    return css, f'<div class="photo"><img src="{photo_uri}" /></div><div class="photo-vignette"></div>'


def _pair_photo_layer(cfg: dict, people: list[dict]) -> tuple[str, str]:
    """CSS and markup for two portrait panels side by side, split by an accent rule."""
    panel_h = cfg.get("pair_photo_height", "70%")
    accent = cfg.get("frame_border_color") or cfg["accent_color"]
    css = f"""
        .pair {{
            position: absolute; top: 0; width: 50%; height: {panel_h};
            overflow: hidden;
            z-index: 1;
        }}
        .pair-left {{ left: 0; }}
        .pair-right {{ right: 0; }}
        .pair img {{
            width: 100%; height: 100%;
            object-fit: cover;
            object-position: center top;
            filter: brightness({cfg.get("photo_brightness", 0.85)});
        }}
        .pair-divider {{
            position: absolute; top: 0; left: 50%; height: {panel_h};
            width: {cfg.get("pair_divider_width", 4)}px; transform: translateX(-50%);
            background: {accent};
            z-index: 3;
        }}
        """
    panels = "".join(
        f'<div class="pair pair-{p["side"]}"><img src="{Path(p["path"]).absolute().as_uri()}" /></div>'
        for p in people
    )
    return css, panels + '<div class="pair-divider"></div>'


def _usable_pair(people: Optional[list[dict]]) -> bool:
    return bool(
        people
        and len(people) == 2
        and {p.get("side") for p in people} == {"left", "right"}
        and all(p.get("path") and os.path.exists(p["path"]) for p in people)
    )


def _build_html(
    line1: str,
    line2: str,
    photo_path: Optional[str] = None,
    logo_path: Optional[str] = None,
    config: Optional[dict] = None,
    variation: int = 0,
    face_info: Optional[dict] = None,
    people: Optional[list[dict]] = None,
) -> str:
    """Build the HTML for a single thumbnail: all values from config.

    Args:
        face_info: Dict with face_y_pct, face_h_pct etc. from frame extraction.
                   Used to auto-position the text box below the face.
        people: Two portrait panels from thumbnail_pair, each with a side and
                a path. When given, they replace the single photo.
    """
    cfg = _load_config()
    if config:
        cfg.update(config)

    w = cfg["width"]
    h = cfg["height"]
    bg = cfg["bg_color"]
    accent = cfg.get("frame_border_color") or cfg["accent_color"]
    box_border_color = cfg.get("box_border_color") or cfg["accent_color"]
    hl_color = cfg.get("line2_highlight_color") or cfg["accent_color"]

    # Clean any stray slashes from title split
    line1 = line1.strip().strip("/").strip()
    line2 = line2.strip().strip("/").strip()
    l1 = safe_upper(line1) if cfg.get("line1_uppercase", True) else line1
    l2 = safe_upper(line2) if cfg.get("line2_uppercase", True) else line2

    pair = _usable_pair(people)
    has_photo = pair or (photo_path and os.path.exists(str(photo_path)))

    # Auto-position text box below face if we have face data
    if pair:
        default_y = cfg.get("pair_box_y", "85%")
    elif face_info and has_photo:
        face_y = face_info.get("face_y_pct", 50)
        face_h = face_info.get("face_h_pct", 20)
        # Bottom edge of face as percentage
        face_bottom = face_y + face_h / 2
        # Place box center 15% below the face bottom, clamped to 65-85%
        auto_y = min(85, max(65, face_bottom + 15))
        default_y = f"{auto_y:.0f}%"
    elif has_photo:
        default_y = cfg.get("box_y_with_photo", cfg.get("box_y", "76%"))
    else:
        default_y = cfg.get("box_y", "73%")

    box_y = default_y
    offset_up = cfg.get("variation_offset_up", "3%")
    offset_down = cfg.get("variation_offset_down", "2%")
    if variation == 1:
        box_y = f"calc({default_y} - {offset_up})"
    elif variation == 2:
        box_y = f"calc({default_y} + {offset_down})"

    photo_css, photo_html = "", ""
    if pair:
        photo_css, photo_html = _pair_photo_layer(cfg, people)
    elif has_photo:
        photo_css, photo_html = _single_photo_layer(cfg, photo_path)

    # Logo
    logo_html = ""
    layers_html = _layer_html(cfg.get("layers"))
    logo_pos = cfg.get("logo_position", "none")
    if logo_path and os.path.exists(logo_path) and logo_pos != "none":
        logo_uri = Path(logo_path).absolute().as_uri()
        logo_h = cfg.get("logo_height", "50px")
        logo_margin = cfg.get("logo_margin", "50px")
        logo_opacity = cfg.get("logo_opacity", 0.35)
        logo_style = f"position:absolute; height:{logo_h}; width:auto; opacity:{logo_opacity}; z-index:8;"
        if logo_pos == "bottom-center":
            logo_style += f"bottom:{logo_margin}; left:50%; transform:translateX(-50%);"
        elif logo_pos == "top-left":
            logo_style += f"top:{logo_margin}; left:{logo_margin};"
        elif logo_pos == "top-right":
            logo_style += f"top:{logo_margin}; right:{logo_margin};"
        elif logo_pos == "top-center":
            logo_style += f"top:{logo_margin}; left:50%; transform:translateX(-50%);"
        logo_html = f'<img src="{logo_uri}" style="{logo_style}" />'

    # Config-driven values
    frame_w = cfg.get("frame_border_width", 3)
    box_x = cfg.get("box_x", "110px")
    box_width = cfg.get("box_width", "860px")
    box_min_h = cfg.get("box_min_height", "220px")
    box_border_w = cfg.get("box_border_width", 3)
    box_fill = cfg.get("box_fill_color", f"rgba(26,26,46,0.90)")
    box_padding = cfg.get("box_padding", "28px 36px")

    # Base font sizes from config: extract int from "64px", "1.5rem", or bare "64"
    def _px(val, default):
        import re
        m = re.search(r"(\d+)", str(val))
        return int(m.group(1)) if m else default

    l1_base_size = _px(cfg.get("line1_font_size", "56px"), 56)
    l2_base_size = _px(cfg.get("line2_font_size", "52px"), 52)
    l1_base_spacing = _px(cfg.get("line1_letter_spacing", "1px"), 1)
    l2_base_spacing = _px(cfg.get("line2_letter_spacing", "1px"), 1)

    # Auto-shrink: estimate text width vs box width, scale down if needed.
    box_w_px = int(str(box_width).replace("px", "")) if "px" in str(box_width) else 860
    # Parse horizontal padding (format: "Vpx Hpx" or "Apx")
    pad_parts = [int(p.replace("px", "")) for p in str(box_padding).split() if "px" in p]
    h_pad = pad_parts[1] if len(pad_parts) >= 2 else pad_parts[0] if pad_parts else 36
    usable_w = box_w_px - h_pad * 2  # Both sides

    def _fit_size(text, base_size, base_spacing):
        """Shrink font size so text fits on one line."""
        # Character width varies by font. Use conservative estimate:
        # uppercase chars ~0.68× font_size, lowercase ~0.52×, average ~0.60×
        # Add safety margin of 5% to prevent edge-case overflow
        is_upper = text == text.upper()
        char_ratio = 0.68 if is_upper else 0.58
        char_w = char_ratio * base_size + base_spacing
        est_width = len(text) * char_w
        if est_width <= usable_w * 0.95:  # 5% safety margin
            return base_size, base_spacing
        scale = (usable_w * 0.95) / est_width
        new_size = max(32, int(base_size * scale))
        new_spacing = max(0, int(base_spacing * scale))
        return new_size, new_spacing

    l1_px, l1_sp = _fit_size(l1, l1_base_size, l1_base_spacing)
    l2_px, l2_sp = _fit_size(l2, l2_base_size, l2_base_spacing)

    l1_size = f"{l1_px}px"
    l1_spacing = f"{l1_sp}px"
    l2_size = f"{l2_px}px"
    l2_spacing = f"{l2_sp}px"

    l1_weight = cfg.get("line1_font_weight", "600")
    l1_lh = cfg.get("line1_line_height", 1.15)
    l1_mb = cfg.get("line1_margin_bottom", "10px")
    l1_color = cfg.get("line1_color", "#FFFFFF")
    # Shrinking to fit is the default, so line 1 stays on one line. A template
    # that turns it off is asking to wrap instead.
    l1_nowrap = "nowrap" if cfg.get("line1_nowrap", True) else "normal"

    l2_weight = cfg.get("line2_font_weight", "500")
    l2_style = cfg.get("line2_font_style", "italic")
    l2_lh = cfg.get("line2_line_height", 1.15)
    l2_text_color = cfg.get("line2_text_color", "#1A1A2E")
    l2_hl_pad = cfg.get("line2_highlight_padding", "4px 16px")

    grad_top_h = cfg.get("gradient_top_height", "25%")
    grad_top_start = cfg.get("gradient_top_start_color", "rgba(0,0,0,0.5)")
    grad_top_end = cfg.get("gradient_top_end_color", "transparent")
    grad_bot_start = cfg.get("gradient_bottom_start", "50%")
    grad_bot_end_color = cfg.get("gradient_bottom_end_color", bg)
    grad_bot_fade = cfg.get("gradient_bottom_fade_point", "70%")

    font_family = cfg.get("font_family", "'Inter', sans-serif")
    font_url = cfg.get("font_import_url", "")
    font_import = f"@import url('{font_url}');" if font_url else ""

    return f"""<!DOCTYPE html>
<html>
<head>
<style>
{font_import}

* {{ margin: 0; padding: 0; box-sizing: border-box; }}

body {{
    width: {w}px;
    height: {h}px;
    overflow: hidden;
    background: {bg};
    font-family: {font_family};
    -webkit-font-smoothing: antialiased;
}}

.frame {{
    position: absolute;
    top: 0; left: 0; right: 0; bottom: 0;
    box-shadow: inset 0 0 0 {frame_w}px {accent};
    z-index: 10;
    pointer-events: none;
}}

{photo_css}
.photo {{ z-index: 1; }}

.gradient-top {{
    position: absolute; top: 0; left: 0; width: 100%; height: {grad_top_h};
    background: linear-gradient(to bottom, {grad_top_start} 0%, {grad_top_end} 100%);
    z-index: 2;
}}

.gradient-bottom {{
    position: absolute; top: {grad_bot_start}; left: 0; width: 100%; bottom: 0;
    background: linear-gradient(to bottom, transparent 0%, {grad_bot_end_color} {grad_bot_fade});
    z-index: 2;
}}

.text-box {{
    position: absolute;
    left: {box_x};
    top: {box_y};
    transform: translateY(-50%);
    width: {box_width};
    height: auto;
    min-height: {box_min_h};
    z-index: 5;
    border: {box_border_w}px solid {box_border_color};
    background: {box_fill};
    display: flex;
    flex-direction: column;
    align-items: center;
    justify-content: center;
    padding: {box_padding};
    box-sizing: border-box;
}}

.line1 {{
    font-size: {l1_size};
    font-weight: {l1_weight};
    letter-spacing: {l1_spacing};
    color: {l1_color};
    /* Casing is already resolved in Python via safe_upper(), which skips
       caseless scripts (e.g. Georgian) that CSS text-transform would
       otherwise still remap to a different alphabet (Mkhedruli -> Mtavruli). */
    text-transform: none;
    text-align: center;
    line-height: {l1_lh};
    margin-bottom: {l1_mb};
    white-space: {l1_nowrap};
    overflow: hidden;
    text-overflow: ellipsis;
    max-width: 100%;
}}

.line2 {{
    display: flex;
    justify-content: center;
}}

.line2 span {{
    font-size: {l2_size};
    font-weight: {l2_weight};
    font-style: {l2_style};
    letter-spacing: {l2_spacing};
    /* See .line1 above: casing is resolved in Python, not here. */
    text-transform: none;
    line-height: {l2_lh};
    background: {hl_color};
    color: {l2_text_color};
    padding: {l2_hl_pad};
    border-radius: 0;
    display: inline-block;
    box-decoration-break: clone;
    -webkit-box-decoration-break: clone;
}}

.logo {{ z-index: 8; }}
</style>
</head>
<body>
    <div class="frame"></div>
    {photo_html}
    <div class="gradient-top"></div>
    <div class="gradient-bottom"></div>
    <div class="text-box">
        <div class="line1">{html_escape(l1)}</div>
        <div class="line2"><span>{html_escape(l2)}</span></div>
    </div>
    {logo_html}
    {layers_html}
</body>
</html>"""


def generate_thumbnail(
    line1: str,
    line2: str,
    output_path: str,
    photo_path: Optional[str] = None,
    logo_path: Optional[str] = None,
    config: Optional[dict] = None,
    variation: int = 0,
    face_info: Optional[dict] = None,
    people: Optional[list[dict]] = None,
) -> str:
    """Generate a single thumbnail via HTML + headless browser screenshot."""
    cfg = _load_config()
    if config:
        cfg.update(config)

    html = _build_html(line1, line2, photo_path, logo_path, cfg, variation, face_info=face_info, people=people)

    # Write HTML to temp file
    tmp_html = tempfile.NamedTemporaryFile(suffix=".html", delete=False, mode="w")
    tmp_html.write(html)
    tmp_html.close()

    os.makedirs(os.path.dirname(output_path) or ".", exist_ok=True)

    try:
        w = cfg["width"]
        h = cfg["height"]
        wait_ms = int(cfg.get("playwright_wait_ms", 1500))
        timeout_s = max(30, int(cfg.get("playwright_timeout_ms", 150000)) // 1000)
        errors = []
        commands: list[list[str]] = []

        remotion_cmd = _build_remotion_screenshot_command(
            script_path=_remotion_screenshot_script_path(),
            html_path=tmp_html.name,
            output_path=output_path,
            width=w,
            height=h,
            wait_ms=wait_ms,
        )
        if remotion_cmd:
            commands.append(remotion_cmd)

        for cli_cmd in _playwright_cli_candidates():
            commands.append(
                _build_playwright_screenshot_command(
                    cli_cmd=cli_cmd,
                    html_path=tmp_html.name,
                    output_path=output_path,
                    width=w,
                    height=h,
                    wait_ms=wait_ms,
                )
            )

        if not commands:
            raise RuntimeError("No browser screenshot command available")

        screenshot_cwd = os.path.abspath(os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", ".."))

        for cmd in commands:
            cmd_label = " ".join(cmd[:3]) if len(cmd) > 3 else " ".join(cmd)
            try:
                result = subprocess.run(
                    cmd,
                    capture_output=True,
                    text=True,
                    timeout=timeout_s,
                    cwd=screenshot_cwd,
                    # .cmd/npx shims need cmd.exe on Windows; shell=True with a list breaks on POSIX.
                    shell=sys.platform == "win32",
                )
            except subprocess.TimeoutExpired:
                errors.append(f"{cmd_label} timed out after {timeout_s} seconds")
                continue

            if result.returncode == 0:
                return output_path

            detail = (result.stderr or result.stdout or "unknown error").strip()[:300]
            errors.append(f"{cmd_label} failed: {detail}")

        raise RuntimeError("Screenshot failed: " + " | ".join(errors))
    finally:
        os.unlink(tmp_html.name)


def generate_variations(
    title: str,
    output_dir: str,
    photo_path: Optional[str] = None,
    video_path: Optional[str] = None,
    logo_path: Optional[str] = None,
    config: Optional[dict] = None,
) -> list[str]:
    """Generate multiple thumbnail variations."""
    cfg = _load_config()
    if config:
        cfg.update(config)

    os.makedirs(output_dir, exist_ok=True)

    face_info = None

    # Auto-extract face frame from video if no photo
    if not photo_path and video_path:
        try:
            from services.thumbnail_generator import extract_face_frame
            frame_path = os.path.join(output_dir, "_face_frame.png")
            result = extract_face_frame(video_path, frame_path, target_width=cfg["width"], target_height=cfg["height"])
            if result:
                photo_path = result["path"]
                face_info = result
        except Exception as exc:
            log_warn("thumbnail", "face frame extraction failed", error=exc)

    line1, line2 = _prepare_thumbnail_lines(title)

    paths = []
    n = cfg.get("variations", 3)

    for i in range(n):
        path = os.path.join(output_dir, f"thumb_v{i+1}.png")
        generate_thumbnail(line1, line2, path, photo_path, logo_path, cfg, variation=i, face_info=face_info)
        paths.append(path)

    return paths


def thumbnail_to_video_frame(
    thumbnail_path: str,
    output_path: str,
    duration: float = 0.8,
    width: int = 1080,
    height: int = 1920,
) -> str:
    """Convert thumbnail PNG to a short video clip for appending.

    Includes a silent audio track so concat_outro's acrossfade filter
    works correctly. No baked-in fades: the crossfade transition
    handles the visual blend.
    """
    cmd = [
        "ffmpeg", "-y",
        "-loop", "1", "-i", thumbnail_path,
        "-f", "lavfi", "-i", "anullsrc=r=44100:cl=stereo",
        "-t", str(duration),
        "-vf", f"scale={width}:{height}:force_original_aspect_ratio=decrease,pad={width}:{height}:(ow-iw)/2:(oh-ih)/2:black",
        "-c:v", "libx264", "-crf", "18", "-preset", "fast",
        "-pix_fmt", "yuv420p",
        "-c:a", "aac", "-b:a", "192k",
        "-shortest",
        output_path,
    ]
    result = proc_run(cmd, timeout=120, check=False)
    if result.returncode != 0:
        raise RuntimeError(f"Thumbnail to video failed: {result.stderr[-300:]}")
    return output_path