Skip to content

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

29.5 KB
Raw Blame
"""
Thumbnail generator for YouTube Shorts.

Generates multiple thumbnail variations per clip using Pillow.
Configurable via .podcli/thumbnail-config.json for brand customization.

Each thumbnail: 1080x1920 PNG with:
- Guest photo (background removed or darkened)
- Two-line title text (Line 1 white, Line 2 accent highlight)
- Logo/watermark
- Dark gradient overlay for text readability
"""

import json
import os
from utils.log import warn as log_warn
import sys
from typing import Optional

from config.paths import paths

try:
    from PIL import Image, ImageDraw, ImageFont, ImageFilter, ImageEnhance
except ImportError:
    print("Pillow not installed. Run: pip install Pillow", file=sys.stderr)
    sys.exit(1)


# ── Default config (overridden by .podcli/thumbnail-config.json) ──

DEFAULT_CONFIG = {
    # These defaults are intentionally a plain black/white placeholder.
    # The "real" look comes from the user's `.podcli/thumbnail-config.json`,
    # which they create by running `podcli init-thumbnail` (or by copying
    # `docs/thumbnail-config.example.json`). If you see white-bg / black-
    # text thumbnails you forgot to create your config - that's by design.
    "width": 1080,
    "height": 1920,

    # Colors - placeholder palette. Override in your brand config.
    "bg_color": "#FFFFFF",
    "text_color": "#000000",
    "accent_color": "#000000",

    # Text
    "font_size_line1": 80,
    "font_size_line2": 80,
    "line1_uppercase": True,
    "line1_bold": True,
    "line2_uppercase": True,
    "line2_bold": True,
    "line2_italic": True,
    "line2_color": None,           # None = accent_color
    "line2_style": "highlight",    # "highlight" = dark text on accent bg, "colored" = accent text
    "max_chars_per_line": 16,
    "text_y": 0.72,               # 0-1 vertical position

    # Text box: set "box_enabled" false for floating text
    "box_enabled": True,
    "box_border_color": None,      # None = accent_color
    "box_border_width": 4,
    "box_fill_color": "#0D0D0DE0", # Dark fill, E0 = 88% opacity
    "box_padding_x": 50,
    "box_padding_y": 30,
    "box_radius": 0,               # 0 = sharp corners, >0 = rounded

    # Guest photo
    "photo_brightness": 0.85,      # 1.0 = unchanged, 0 = black
    "photo_blur": 0,               # 0 = sharp, >0 = gaussian blur px
    "photo_position": "center",    # center, top, bottom
    "photo_zoom": 1.0,             # 1.0 = fill, >1 = zoom in on face

    # Gradient overlays (0 = off, 1 = full black)
    "gradient_bottom": 0.85,       # Dark gradient at bottom (text area)
    "gradient_top": 0.4,           # Subtle gradient at top (logo area)

    # Logo / Watermark
    "logo_position": "bottom-center",  # top-left, top-right, top-center, bottom-center, none
    "logo_height": 60,
    "logo_margin": 50,
    "logo_opacity": 0.7,           # 0-1

    # Auto face extraction
    "auto_face_frame": True,       # Extract best face frame from video automatically
    "face_frame_count": 10,        # How many frames to sample

    # Frame border (around entire image)
    "frame_border_width": 4,       # 0 = no frame
    "frame_border_color": None,    # None = accent_color

    # Variations
    "variations": 3,
}


def _load_config() -> dict:
    """Load thumbnail config from .podcli/thumbnail-config.json, merged with defaults."""
    config = {**DEFAULT_CONFIG}
    config_path = paths["thumbnailConfig"]
    if os.path.exists(config_path):
        try:
            with open(config_path, encoding="utf-8") as f:
                user = json.load(f)
            config.update(user)
        except (json.JSONDecodeError, IOError):
            pass
    return config


def _get_font(size: int, bold: bool = True, italic: bool = False) -> ImageFont.FreeTypeFont:
    """Get the best available font. Uses Helvetica Neue for clean look."""

    # TTC files need an index to select the right face
    ttc_options = []

    if bold and italic:
        ttc_options = [
            ("/System/Library/Fonts/HelveticaNeue.ttc", 3),    # Helvetica Neue Bold Italic
            ("/System/Library/Fonts/Helvetica.ttc", 3),
            ("C:/Windows/Fonts/arialbi.ttf", 0),
        ]
    elif bold:
        ttc_options = [
            ("/System/Library/Fonts/HelveticaNeue.ttc", 1),    # Helvetica Neue Bold
            ("/System/Library/Fonts/Helvetica.ttc", 1),
            ("C:/Windows/Fonts/arialbd.ttf", 0),
        ]
    elif italic:
        ttc_options = [
            ("/System/Library/Fonts/HelveticaNeue.ttc", 2),    # Helvetica Neue Italic
            ("/System/Library/Fonts/Helvetica.ttc", 2),
            ("C:/Windows/Fonts/ariali.ttf", 0),
        ]
    else:
        ttc_options = [
            ("/System/Library/Fonts/HelveticaNeue.ttc", 0),    # Helvetica Neue Regular
            ("/System/Library/Fonts/Helvetica.ttc", 0),
            ("C:/Windows/Fonts/arial.ttf", 0),
        ]

    for path, idx in ttc_options:
        if os.path.exists(path):
            try:
                return ImageFont.truetype(path, size, index=idx)
            except Exception:
                continue

    # Fallback to standalone font files
    fallbacks = []
    if bold:
        fallbacks = [
            "/System/Library/Fonts/Supplemental/Arial Bold.ttf",
            "/Library/Fonts/Arial Bold.ttf",
            "C:/Windows/Fonts/arialbd.ttf",
            "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf",
            "/usr/share/fonts/truetype/liberation/LiberationSans-Bold.ttf",
        ]
    else:
        fallbacks = [
            "/System/Library/Fonts/Supplemental/Arial.ttf",
            "/Library/Fonts/Arial.ttf",
            "C:/Windows/Fonts/arial.ttf",
            "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
        ]

    for path in fallbacks:
        if os.path.exists(path):
            try:
                return ImageFont.truetype(path, size)
            except Exception:
                continue

    return ImageFont.load_default()


def _wrap_text(text: str, max_chars: int, font=None, max_width: int = 0) -> list[str]:
    """Wrap text into lines, using pixel width if font provided, otherwise char count."""
    words = text.split()
    lines = []
    current = ""

    if font and max_width > 0:
        # Pixel-accurate wrapping using actual font metrics
        from PIL import ImageDraw, Image
        _measure = ImageDraw.Draw(Image.new("RGBA", (1, 1)))
        for word in words:
            test = f"{current} {word}".strip()
            bbox = _measure.textbbox((0, 0), test, font=font)
            if (bbox[2] - bbox[0]) <= max_width:
                current = test
            else:
                if current:
                    lines.append(current)
                current = word
    else:
        # Fallback: char-count wrapping
        for word in words:
            test = f"{current} {word}".strip()
            if len(test) <= max_chars:
                current = test
            else:
                if current:
                    lines.append(current)
                current = word

    if current:
        lines.append(current)
    return lines


def _draw_gradients(img: Image.Image, bottom: float = 0.8, top: float = 0.0) -> Image.Image:
    """Draw configurable gradient overlays (bottom and/or top)."""
    w, h = img.size
    gradient = Image.new("RGBA", (w, h), (0, 0, 0, 0))
    draw = ImageDraw.Draw(gradient)

    # Bottom gradient (for text readability)
    if bottom > 0:
        start_y = int(h * 0.4)
        for y in range(start_y, h):
            progress = (y - start_y) / (h - start_y)
            alpha = int(255 * bottom * progress)
            draw.line([(0, y), (w, y)], fill=(0, 0, 0, alpha))

    # Top gradient (for logo readability)
    if top > 0:
        end_y = int(h * 0.15)
        for y in range(0, end_y):
            progress = 1 - (y / end_y)
            alpha = int(255 * top * progress)
            draw.line([(0, y), (w, y)], fill=(0, 0, 0, alpha))

    return Image.alpha_composite(img.convert("RGBA"), gradient)


def extract_face_frame(
    video_path: str,
    output_path: str,
    sample_count: int = 10,
    target_width: int = 1080,
    target_height: int = 1920,
    start_second: Optional[float] = None,
    end_second: Optional[float] = None,
) -> Optional[dict]:
    """
    Extract the best face frame from a video for use as thumbnail background.

    Samples frames, detects faces, picks the frame with the largest/clearest face.
    Saves the FULL frame (no crop), the HTML template's CSS `background: cover`
    handles the 9:16 crop so we get a natural chest-up portrait instead of an
    over-zoomed face slice.

    Returns dict with 'path' and 'face_x' (face center as 0-100%), or None.
    """
    try:
        import cv2
        import numpy as np

        cap = cv2.VideoCapture(video_path)
        if not cap.isOpened():
            return None

        total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
        fps = cap.get(cv2.CAP_PROP_FPS) or 30
        duration = total_frames / fps

        # Load face detector
        from services.face_detector import create_detector, detect_faces
        src_w = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
        src_h = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
        detector = create_detector(src_w, src_h)

        if detector is None:
            cap.release()
            return None

        best_frame = None
        best_score = 0
        best_face_cx = None
        best_face_cy = None
        best_face_w = 0
        best_face_h = 0

        # Track per-frame leftmost/rightmost face centers so we can later
        # tell a TRUE split-screen (two video tiles with a gap between
        # subjects, like Riverside) from an in-person podcast with two
        # heads sharing one camera close to center.
        split_left_cxs = []
        split_right_cxs = []

        # Sample frames from the clip's time range, or middle 80% of video
        if start_second is not None and end_second is not None and end_second > start_second:
            start_t = max(0.0, float(start_second))
            end_t = min(duration, float(end_second))
        else:
            start_t = duration * 0.1
            end_t = duration * 0.9
        sample_times = [start_t + i * (end_t - start_t) / sample_count for i in range(sample_count)]

        for t in sample_times:
            cap.set(cv2.CAP_PROP_POS_MSEC, t * 1000)
            ret, frame = cap.read()
            if not ret:
                continue

            h, w = frame.shape[:2]
            faces_detected = detect_faces(detector, frame, src_w, src_h)

            qualifying = []
            for f in faces_detected:
                conf = f["confidence"]
                face_w = f["fw"]
                face_h = f["fh"]

                if face_w < w * 0.08:
                    continue

                qualifying.append(f)

                # Score: confidence × face size (prefer larger/closer faces)
                score = conf * (face_w * face_h)
                if score > best_score:
                    best_score = score
                    best_frame = frame.copy()
                    best_face_cx = f["cx"]
                    best_face_cy = f["cy"]
                    best_face_w = face_w
                    best_face_h = face_h

            if len(qualifying) >= 2:
                qualifying.sort(key=lambda f: f["cx"])
                split_left_cxs.append(qualifying[0]["cx"])
                split_right_cxs.append(qualifying[-1]["cx"])

        cap.release()

        if best_frame is None:
            return None

        h, w = best_frame.shape[:2]
        mid_x = w // 2
        seam_margin = 20

        # TRUE split-screen detection requires BOTH conditions:
        #   1. ≥3 sampled frames had ≥2 qualifying faces
        #   2. Median horizontal gap between leftmost and rightmost face
        #      across those frames exceeds 20% of source width
        # Pure presence on both halves (#1) is not enough: an in-person
        # podcast with two heads sharing one camera will satisfy #1 but
        # not #2, and applying the seam clamp there would push a centered
        # face to the crop edge.
        is_split_screen = False
        winner_side = "left" if best_face_cx < mid_x else "right"
        if len(split_left_cxs) >= 3:
            gap = int(np.median(split_right_cxs)) - int(np.median(split_left_cxs))
            if gap > w * 0.20:
                is_split_screen = True

        # Compute the natural 9:16 crop window.
        target_ratio = target_width / target_height  # 0.5625
        crop_h = h
        crop_w = int(crop_h * target_ratio)
        if crop_w > w:
            crop_w = w
            crop_h = int(crop_w / target_ratio)

        # Seam-exclusion strategy for split-screen sources:
        #   a) Natural crop already fits inside the winner's half → no-op
        #      and clamp will be a no-op too
        #   b) Crop is too wide for one half (square/near-square sources)
        #      → shrink crop window to fit, then the resize step below
        #      stretches it back to 1080×1920 (tighter zoom, no bleed)
        #   c) Shrinking would produce a hyper-zoomed image (< 30% of
        #      source width or < 200px) → bail on seam exclusion; some
        #      bleed is better than a degenerate thumbnail
        MIN_CROP_W = max(200, int(w * 0.30))
        if is_split_screen:
            half_room = (mid_x - seam_margin) if winner_side == "left" else (w - mid_x - seam_margin)
            if half_room < MIN_CROP_W:
                is_split_screen = False
            elif crop_w > half_room:
                shrunk_w = half_room
                shrunk_h = int(shrunk_w / target_ratio)
                if shrunk_h <= h and shrunk_w >= MIN_CROP_W:
                    crop_w = shrunk_w
                    crop_h = shrunk_h
                else:
                    is_split_screen = False

        # Center horizontally on face, then clamp to keep the seam outside
        # the crop window on true split-screen sources. When the winner
        # face sits very close to the seam, the clamp will push it toward
        # the crop's inner edge: that's intentional and a strictly better
        # failure mode than showing the other speaker's tile bleed.
        crop_x = best_face_cx - crop_w // 2
        if is_split_screen:
            if winner_side == "left":
                crop_x = min(crop_x, mid_x - crop_w - seam_margin)
            else:
                crop_x = max(crop_x, mid_x + seam_margin)
        crop_x = max(0, min(crop_x, w - crop_w))

        # Place face at ~25% from top so it's centered in the visible photo
        # area (top 78% of the final thumbnail). This shows head + shoulders
        # naturally without over-cropping.
        crop_y = best_face_cy - int(crop_h * 0.25)
        crop_y = max(0, min(crop_y, h - crop_h))

        cropped = best_frame[crop_y:crop_y + crop_h, crop_x:crop_x + crop_w]
        resized = cv2.resize(cropped, (target_width, target_height), interpolation=cv2.INTER_LANCZOS4)

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

        # Calculate actual face position in the cropped/resized frame
        actual_face_x = round((best_face_cx - crop_x) / crop_w * 100, 1)
        actual_face_y = round((best_face_cy - crop_y) / crop_h * 100, 1)
        actual_face_w = round(best_face_w / crop_w * 100, 1)
        actual_face_h = round(best_face_h / crop_h * 100, 1)
        return {
            "path": output_path,
            "face_x_pct": actual_face_x,
            "face_y_pct": actual_face_y,
            "face_w_pct": actual_face_w,
            "face_h_pct": actual_face_h,
        }

    except ImportError:
        return None
    except Exception:
        return None


def _hex_to_rgb(hex_color: str) -> tuple:
    """Convert hex color to RGB tuple."""
    hex_color = hex_color.lstrip("#")
    return tuple(int(hex_color[i:i+2], 16) for i in (0, 2, 4))


def _hex_to_rgba(hex_color: str) -> tuple:
    """Convert hex color (with optional alpha like #RRGGBBAA) to RGBA tuple."""
    hex_color = hex_color.lstrip("#")
    if len(hex_color) == 8:
        r, g, b, a = int(hex_color[0:2], 16), int(hex_color[2:4], 16), int(hex_color[4:6], 16), int(hex_color[6:8], 16)
        return (r, g, b, a)
    elif len(hex_color) == 6:
        return (*_hex_to_rgb(hex_color), 255)
    return (0, 0, 0, 255)


def generate_thumbnail(
    title_line1: str,
    title_line2: str,
    output_path: str,
    guest_photo_path: Optional[str] = None,
    logo_path: Optional[str] = None,
    config: Optional[dict] = None,
    variation: int = 0,
) -> str:
    """
    Generate a single thumbnail image.

    Args:
        title_line1: Top line of title text (e.g., "WHY DATA CENTERS")
        title_line2: Bottom line with accent (e.g., "MUST LEAVE EARTH")
        output_path: Where to save the PNG
        guest_photo_path: Optional guest photo (fills background)
        logo_path: Optional logo (top corner)
        config: Override config dict (merged with defaults)
        variation: Variation index (0, 1, 2) that changes layout slightly

    Returns:
        Path to generated thumbnail
    """
    cfg = _load_config()
    if config:
        cfg.update(config)

    w, h = cfg["width"], cfg["height"]
    bg_color = _hex_to_rgb(cfg["bg_color"])
    text_color = _hex_to_rgb(cfg["text_color"])
    accent_color = _hex_to_rgb(cfg.get("line2_color") or cfg["accent_color"])
    border_color = _hex_to_rgb(cfg.get("box_border_color") or cfg["accent_color"])

    # ── Layer 0: Frame border ──
    frame_border = cfg.get("frame_border_width", 4)
    frame_color = _hex_to_rgb(cfg.get("frame_border_color") or cfg["accent_color"])

    # ── Layer 1: Background ──
    img = Image.new("RGBA", (w, h), (*bg_color, 255))

    # ── Layer 2: Guest photo ──
    if guest_photo_path and os.path.exists(guest_photo_path):
        try:
            photo = Image.open(guest_photo_path).convert("RGBA")
            photo_ratio = photo.width / photo.height
            target_ratio = w / h

            zoom = cfg.get("photo_zoom", 1.0)
            if photo_ratio > target_ratio:
                new_h = int(h * zoom)
                new_w = int(new_h * photo_ratio)
            else:
                new_w = int(w * zoom)
                new_h = int(new_w / photo_ratio)

            photo = photo.resize((new_w, new_h), Image.LANCZOS)

            x_offset = (w - new_w) // 2
            pos = cfg["photo_position"]
            if pos == "top":
                y_offset = 0
            elif pos == "bottom":
                y_offset = h - new_h
            else:
                y_offset = (h - new_h) // 2

            # Variation: slight shift
            if variation == 1:
                y_offset -= int(h * 0.04)
            elif variation == 2:
                y_offset += int(h * 0.04)

            # Brightness + blur
            brightness = cfg.get("photo_brightness", 0.85)
            if brightness != 1.0:
                photo = ImageEnhance.Brightness(photo).enhance(brightness)
            blur = cfg.get("photo_blur", 0)
            if blur > 0:
                photo = photo.filter(ImageFilter.GaussianBlur(blur))

            img.paste(photo, (x_offset, y_offset))
        except Exception as exc:
            log_warn("thumbnail", "photo layer skipped", error=exc)

    # ── Layer 3: Gradient overlays ──
    img = _draw_gradients(img, bottom=cfg.get("gradient_bottom", 0.8), top=cfg.get("gradient_top", 0.0))

    draw = ImageDraw.Draw(img)

    # ── Layer 4: Text box + text ──
    # Safe text area: 80% of image width with margins
    safe_margin = int(w * 0.08)
    max_text_w = w - safe_margin * 2

    font1 = _get_font(cfg["font_size_line1"], bold=cfg.get("line1_bold", True))
    font2 = _get_font(cfg["font_size_line2"], bold=cfg.get("line2_bold", True), italic=cfg.get("line2_italic", True))

    l1_text = title_line1.upper() if cfg.get("line1_uppercase", True) else title_line1
    l2_text = title_line2.upper() if cfg.get("line2_uppercase", True) else title_line2

    # Pixel-aware wrapping with auto-shrink if text still overflows
    def _wrap_and_fit(text, font, font_size, bold=True, italic=False):
        """Wrap text using pixel width, shrink font if any single word is too wide."""
        current_font = font
        current_size = font_size
        for _ in range(5):  # max 5 shrink attempts
            lines = _wrap_text(text, cfg["max_chars_per_line"], font=current_font, max_width=max_text_w)
            # Check if any line overflows
            overflow = False
            for line in lines:
                bbox = draw.textbbox((0, 0), line, font=current_font)
                if (bbox[2] - bbox[0]) > max_text_w:
                    overflow = True
                    break
            if not overflow:
                return lines, current_font
            # Shrink font by 15%
            current_size = max(28, int(current_size * 0.85))
            current_font = _get_font(current_size, bold=bold, italic=italic)
        return lines, current_font

    l1_lines, font1 = _wrap_and_fit(l1_text, font1, cfg["font_size_line1"], bold=cfg.get("line1_bold", True))
    l2_lines, font2 = _wrap_and_fit(l2_text, font2, cfg["font_size_line2"], bold=cfg.get("line2_bold", True), italic=cfg.get("line2_italic", True))

    line2_style = cfg.get("line2_style", "highlight")
    hl_pad_x, hl_pad_y = 16, 8

    # Measure Line 1 block
    l1_sizes = []
    for line in l1_lines:
        bbox = draw.textbbox((0, 0), line, font=font1)
        l1_sizes.append((bbox[2] - bbox[0], bbox[3] - bbox[1]))

    # Measure Line 2 block
    l2_sizes = []
    for line in l2_lines:
        bbox = draw.textbbox((0, 0), line, font=font2)
        l2_sizes.append((bbox[2] - bbox[0], bbox[3] - bbox[1]))

    l1_line_gap = 10
    block_gap = 24  # Clear gap between Line 1 and Line 2

    l1_block_h = sum(s[1] for s in l1_sizes) + l1_line_gap * max(0, len(l1_sizes) - 1)
    l2_block_h = sum(s[1] + hl_pad_y * 2 for s in l2_sizes) if line2_style == "highlight" else sum(s[1] for s in l2_sizes)
    total_content_h = l1_block_h + block_gap + l2_block_h

    # Max width for box sizing: clamp to image bounds
    all_widths = [s[0] for s in l1_sizes] + [s[0] + hl_pad_x * 2 for s in l2_sizes]
    max_content_w = min(max(all_widths) if all_widths else 400, max_text_w)

    # Vertical position + variation shift
    text_y_ratio = cfg.get("text_y", 0.72)
    if variation == 1:
        text_y_ratio -= 0.04
    elif variation == 2:
        text_y_ratio += 0.03
    content_top = int(h * text_y_ratio) - total_content_h // 2
    # Clamp: keep text within image bounds
    content_top = max(10, min(content_top, h - total_content_h - 10))

    # Draw text box
    box_enabled = cfg.get("box_enabled", True)
    if box_enabled:
        pad_x = cfg.get("box_padding_x", 50)
        pad_y = cfg.get("box_padding_y", 35)
        box_l = max(0, (w - max_content_w) // 2 - pad_x)
        box_t = max(0, content_top - pad_y)
        box_r = min(w, (w + max_content_w) // 2 + pad_x)
        box_b = min(h, content_top + total_content_h + pad_y)

        fill_rgba = _hex_to_rgba(cfg.get("box_fill_color", "#0D0D0DE0"))
        border_w = cfg.get("box_border_width", 4)
        radius = cfg.get("box_radius", 0)

        try:
            if radius > 0:
                draw.rounded_rectangle([box_l, box_t, box_r, box_b], radius=radius, fill=fill_rgba, outline=(*border_color, 255), width=border_w)
            else:
                draw.rectangle([box_l, box_t, box_r, box_b], fill=fill_rgba, outline=(*border_color, 255), width=border_w)
        except TypeError:
            draw.rectangle([box_l, box_t, box_r, box_b], fill=fill_rgba)

    # Draw Line 1: white text, no background
    y = content_top
    for i, line in enumerate(l1_lines):
        tw, th = l1_sizes[i]
        x = (w - tw) // 2
        draw.text((x, y), line, fill=(*text_color, 255), font=font1)
        y += th + l1_line_gap

    # Gap between blocks
    y = content_top + l1_block_h + block_gap

    # Draw Line 2: dark text on accent highlight, or accent text
    dark_text = _hex_to_rgb(cfg.get("bg_color", "#0D0D0D"))
    for i, line in enumerate(l2_lines):
        tw, th = l2_sizes[i]
        x = (w - tw) // 2

        if line2_style == "highlight":
            draw.rectangle(
                [x - hl_pad_x, y - hl_pad_y, x + tw + hl_pad_x, y + th + hl_pad_y],
                fill=(*accent_color, 255),
            )
            draw.text((x, y), line, fill=(*dark_text, 255), font=font2)
            y += th + hl_pad_y * 2
        else:
            draw.text((x, y), line, fill=(*accent_color, 255), font=font2)
            y += th

    # ── Layer 5: Logo / Watermark ──
    if logo_path and os.path.exists(logo_path) and cfg.get("logo_position", "none") != "none":
        try:
            logo = Image.open(logo_path).convert("RGBA")
            logo_h = cfg.get("logo_height", 60)
            logo_w = int(logo.width * (logo_h / logo.height))
            logo = logo.resize((logo_w, logo_h), Image.LANCZOS)

            # Apply opacity
            opacity = cfg.get("logo_opacity", 0.7)
            if opacity < 1.0:
                alpha = logo.split()[3]
                alpha = alpha.point(lambda p: int(p * opacity))
                logo.putalpha(alpha)

            margin = cfg.get("logo_margin", 50)
            pos = cfg["logo_position"]
            if pos == "top-left":
                lx, ly = margin, margin
            elif pos == "top-right":
                lx, ly = w - logo_w - margin, margin
            elif pos == "top-center":
                lx, ly = (w - logo_w) // 2, margin
            elif pos == "bottom-center":
                lx, ly = (w - logo_w) // 2, h - logo_h - margin
            elif pos == "bottom-left":
                lx, ly = margin, h - logo_h - margin
            elif pos == "bottom-right":
                lx, ly = w - logo_w - margin, h - logo_h - margin
            else:
                lx, ly = margin, margin

            img.paste(logo, (lx, ly), logo)
        except Exception as exc:
            log_warn("thumbnail", "logo layer skipped", error=exc)

    # ── Layer 6: Frame border around entire image ──
    if frame_border > 0:
        frame_draw = ImageDraw.Draw(img)
        fb = frame_border
        frame_draw.rectangle([fb//2, fb//2, w - fb//2, h - fb//2], outline=(*frame_color, 255), width=fb)

    # Save
    os.makedirs(os.path.dirname(output_path) or ".", exist_ok=True)
    img.save(output_path, "PNG")
    return output_path


def generate_variations(
    title: str,
    output_dir: str,
    guest_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 for a clip.

    If no guest photo provided but video_path is given, auto-extracts the best
    face frame from the video.

    Splits title into two lines and generates variations with different:
    - Text positions (shifted up/down)
    - Photo positions (shifted)

    Returns list of generated file paths.
    """
    cfg = _load_config()
    if config:
        cfg.update(config)

    os.makedirs(output_dir, exist_ok=True)

    # Auto-extract face frame from video if no photo provided
    if not guest_photo_path and video_path and cfg.get("auto_face_frame", True):
        frame_path = os.path.join(output_dir, "_face_frame.png")
        result = extract_face_frame(
            video_path, frame_path,
            sample_count=cfg.get("face_frame_count", 10),
            target_width=cfg["width"],
            target_height=cfg["height"],
        )
        if result:
            guest_photo_path = result["path"]

    # Split title into two lines (smart split: try to balance)
    words = title.split()
    if len(words) <= 2:
        line1 = words[0] if words else ""
        line2 = " ".join(words[1:])
    else:
        # Try splits and pick the most balanced one
        best_split = len(words) // 2
        best_diff = float("inf")
        for split_at in range(1, len(words)):
            l1 = " ".join(words[:split_at])
            l2 = " ".join(words[split_at:])
            diff = abs(len(l1) - len(l2))
            if diff < best_diff:
                best_diff = diff
                best_split = split_at
        line1 = " ".join(words[:best_split])
        line2 = " ".join(words[best_split:])

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

    for i in range(n_variations):
        filename = f"thumb_v{i+1}.png"
        path = os.path.join(output_dir, filename)
        generate_thumbnail(
            title_line1=line1,
            title_line2=line2,
            output_path=path,
            guest_photo_path=guest_photo_path,
            logo_path=logo_path,
            config=cfg,
            variation=i,
        )
        paths.append(path)

    return paths


def thumbnail_to_video_frame(
    thumbnail_path: str,
    output_path: str,
    duration: float = 0.8,
    fade_in: float = 0.3,
    fade_out: float = 0.3,
    width: int = 1080,
    height: int = 1920,
) -> str:
    """
    Convert a thumbnail image to a short video clip with fade in/out.

    Used to append thumbnail as the last 2 seconds of a short video.
    """
    from utils.proc import run as proc_run

    cmd = [
        "ffmpeg", "-y",
        "-loop", "1",
        "-i", thumbnail_path,
        "-t", str(duration),
        "-vf", (
            f"scale={width}:{height}:force_original_aspect_ratio=decrease,"
            f"pad={width}:{height}:(ow-iw)/2:(oh-ih)/2:black,"
            f"fade=t=in:st=0:d={fade_in},"
            f"fade=t=out:st={duration - fade_out}:d={fade_out}"
        ),
        "-c:v", "libx264", "-crf", "18", "-preset", "fast",
        "-pix_fmt", "yuv420p",
        "-an",  # No audio for the thumbnail frame
        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