Skip to content

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

feat: config-driven thumbnails with auto face positioning

Nika Siradze59eb3b49e311
diff --git a/.claude/commands/plan-thumbnails.md b/.claude/commands/plan-thumbnails.md
index f8fc308..ff72abb 100644
--- a/.claude/commands/plan-thumbnails.md
+++ b/.claude/commands/plan-thumbnails.md
@@ -86,4 +86,7 @@ What is the single most compelling image or concept?
- Text position: Lower third, centered
**Designer notes:** [specific direction]
+
+**Generate thumbnail:** `./podcli thumbnails "[LINE 1] / [LINE 2]" --logo [asset]`
+_(The " / " separator tells the generator where to split lines)_
```
diff --git a/.gitignore b/.gitignore
index f66b2c5..e51f0be 100644
--- a/.gitignore
+++ b/.gitignore
@@ -26,6 +26,11 @@ __pycache__/
# DNN models (large binaries, downloaded by setup.sh)
backend/models/*.caffemodel
+# Test output
+test_thumbs/
+thumbnails/
+tmp*.txt
+
# Media & temp files
*.mp4
*.mp3
diff --git a/backend/cli.py b/backend/cli.py
index 917790b..e9767d5 100644
--- a/backend/cli.py
+++ b/backend/cli.py
@@ -346,56 +346,60 @@ def cmd_process(args):
success = sum(1 for r in results if "output_path" in r)
print(f"\n {success}/{len(clips)} clips exported in {elapsed:.1f}s")
- # ── Step 4b: Generate thumbnails for each clip ──
+ # ── Step 4b: Generate thumbnails (opt-in via thumbnail-config.json) ──
thumb_dir = os.path.join(output_dir, "thumbnails")
- try:
- from services.thumbnail_generator import generate_variations, thumbnail_to_video_frame
- from services.asset_store import resolve as resolve_thumb_asset
-
- logo_for_thumb = config.get("logo_path") or None
- # Try to find a guest photo from assets
- guest_photo = None
+ _thumb_enabled = True
+ _tc_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", ".podcli", "thumbnail-config.json")
+ if os.path.exists(_tc_path):
try:
- from services.asset_store import list_assets as list_thumb_assets
- photos = [a for a in list_thumb_assets() if a["type"] == "image" and os.path.exists(a["path"])]
- if photos:
- guest_photo = photos[0]["path"]
+ with open(_tc_path) as _tcf:
+ _thumb_enabled = json.load(_tcf).get("enabled", True)
except Exception:
pass
- print(f"\n [4b/5] Generating thumbnails...")
- for i, clip in enumerate(clips):
- clip_thumb_dir = os.path.join(thumb_dir, f"clip_{i+1}")
- paths = generate_variations(
- title=clip.get("title", f"Clip {i+1}"),
- output_dir=clip_thumb_dir,
- guest_photo_path=guest_photo,
- logo_path=logo_for_thumb,
- )
- print(f" Clip {i+1}: {len(paths)} variations → {os.path.basename(clip_thumb_dir)}/")
-
- # Append thumbnail as 2-sec frame to the rendered clip
- clip_result = results[i] if i < len(results) else None
- if clip_result and clip_result.get("output_path") and paths:
- # Use first variation as default (user can re-run with specific choice)
- thumb_video = os.path.join(clip_thumb_dir, "thumb_frame.mp4")
- try:
- thumbnail_to_video_frame(paths[0], thumb_video)
- # Append to clip
- from services.video_processor import concat_outro
- final_with_thumb = clip_result["output_path"].replace(".mp4", "_with_thumb.mp4")
- concat_outro(clip_result["output_path"], thumb_video, final_with_thumb, crossfade_duration=0.3)
- # Replace original
- os.replace(final_with_thumb, clip_result["output_path"])
- print(f" + thumbnail appended (2s fade)")
- except Exception as e:
- print(f" ⚠ thumbnail append failed: {e}")
-
- print(f" Thumbnails saved to {thumb_dir}/")
- except ImportError:
- print(f"\n [4b/5] Thumbnails skipped (pip install Pillow)")
- except Exception as e:
- print(f"\n [4b/5] Thumbnails skipped: {e}")
+ if _thumb_enabled:
+ try:
+ from services.thumbnail_ai import generate_variations, thumbnail_to_video_frame
+
+ logo_for_thumb = config.get("logo_path") or None
+ guest_photo = None
+ try:
+ from services.asset_store import list_assets as list_thumb_assets
+ photos = [a for a in list_thumb_assets() if a["type"] == "image" and os.path.exists(a["path"])]
+ if photos:
+ guest_photo = photos[0]["path"]
+ except Exception:
+ pass
+
+ print(f"\n [4b/5] Generating thumbnails (Claude + Playwright)...")
+ for i, clip in enumerate(clips):
+ clip_thumb_dir = os.path.join(thumb_dir, f"clip_{i+1}")
+ paths = generate_variations(
+ title=clip.get("title", f"Clip {i+1}"),
+ output_dir=clip_thumb_dir,
+ photo_path=guest_photo,
+ video_path=video_path,
+ logo_path=logo_for_thumb,
+ )
+ print(f" Clip {i+1}: {len(paths)} variations → {os.path.basename(clip_thumb_dir)}/")
+
+ # Append first thumbnail as 2-sec frame to the clip
+ clip_result = results[i] if i < len(results) else None
+ if clip_result and clip_result.get("output_path") and paths:
+ thumb_video = os.path.join(clip_thumb_dir, "thumb_frame.mp4")
+ try:
+ thumbnail_to_video_frame(paths[0], thumb_video)
+ from services.video_processor import concat_outro
+ final_with_thumb = clip_result["output_path"].replace(".mp4", "_with_thumb.mp4")
+ concat_outro(clip_result["output_path"], thumb_video, final_with_thumb, crossfade_duration=0.3)
+ os.replace(final_with_thumb, clip_result["output_path"])
+ print(f" + thumbnail appended (2s fade)")
+ except Exception as e:
+ print(f" ⚠ thumbnail append failed: {e}")
+
+ print(f" Thumbnails saved to {thumb_dir}/")
+ except Exception as e:
+ print(f"\n [4b/5] Thumbnails skipped: {e}")
print(f"\n Output: {output_dir}/")
@@ -871,7 +875,7 @@ def cmd_assets(args):
def cmd_thumbnails(args):
"""Generate thumbnail variations for a title."""
- from services.thumbnail_generator import generate_variations
+ from services.thumbnail_ai import generate_variations
from services.asset_store import resolve as resolve_asset
accent = "\033[38;2;212;135;74m"
@@ -900,10 +904,13 @@ def cmd_thumbnails(args):
print(f"\n {bold}Generating {args.variations} thumbnail variations...{reset}")
print(f" Title: {accent}{args.title}{reset}")
+ video = getattr(args, "video", None)
+
paths = generate_variations(
title=args.title,
output_dir=args.output,
- guest_photo_path=photo,
+ photo_path=photo,
+ video_path=video,
logo_path=logo,
config={"variations": args.variations},
)
@@ -1085,6 +1092,7 @@ def main():
thumb.add_argument("title", help="Title text for the thumbnail")
thumb.add_argument("-o", "--output", default="./thumbnails", help="Output directory")
thumb.add_argument("--photo", help="Guest photo (asset name or path)")
+ thumb.add_argument("--video", help="Video to extract face frame from")
thumb.add_argument("--logo", help="Logo (asset name or path)")
thumb.add_argument("-n", "--variations", type=int, default=3, help="Number of variations")
diff --git a/backend/services/thumbnail_ai.py b/backend/services/thumbnail_ai.py
new file mode 100644
index 0000000..2fe36b3
--- /dev/null
+++ b/backend/services/thumbnail_ai.py
@@ -0,0 +1,501 @@
+"""
+AI-driven thumbnail generator.
+
+1. Extract candidate frames from video (OpenCV)
+2. Claude analyzes frames + clip content → generates HTML with exact CSS
+3. Playwright renders HTML → PNG
+
+Claude makes ALL visual decisions: crop, text size, positioning, colors.
+The config provides brand constraints (accent color, logo, font), Claude works within them.
+"""
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import base64
+from typing import Optional
+
+
+def _load_brand_config() -> dict:
+ """Load brand constraints from thumbnail-config.json."""
+ defaults = {
+ "width": 1080,
+ "height": 1920,
+ "accent_color": "#00CED1",
+ "bg_color": "#0D0D0D",
+ "font_family": "'Inter', 'Helvetica Neue', 'Arial', sans-serif",
+ "enabled": True,
+ "variations": 3,
+ }
+ config_path = os.path.join(
+ os.path.dirname(os.path.abspath(__file__)), "..", "..", ".podcli", "thumbnail-config.json"
+ )
+ if os.path.exists(config_path):
+ try:
+ with open(config_path) as f:
+ defaults.update(json.load(f))
+ except Exception:
+ pass
+ return defaults
+
+
+def _frame_sharpness(frame, face_roi=None) -> float:
+ """Laplacian variance — higher = sharper. Measures face region if provided."""
+ import cv2
+ if face_roi is not None:
+ x1, y1, x2, y2 = face_roi
+ region = frame[y1:y2, x1:x2]
+ else:
+ region = frame
+ gray = cv2.cvtColor(region, cv2.COLOR_BGR2GRAY)
+ return cv2.Laplacian(gray, cv2.CV_64F).var()
+
+
+def extract_candidate_frames(
+ video_path: str,
+ output_dir: str,
+ count: int = 5,
+) -> list[dict]:
+ """
+ Extract candidate frames with detected faces from a video.
+ Returns list of {path, face_x, face_y, face_w, face_h, confidence, timestamp}.
+
+ Scoring favors:
+ - High confidence (frontal, clear face)
+ - Sharp face region (eyes open, not blurry)
+ - Medium face size (natural portrait, not extreme close-up)
+ """
+ try:
+ import cv2
+ import numpy as np
+ except ImportError:
+ return []
+
+ cap = cv2.VideoCapture(video_path)
+ if not cap.isOpened():
+ return []
+
+ total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+ fps = cap.get(cv2.CAP_PROP_FPS) or 30
+ duration = total_frames / fps
+ src_w = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+ src_h = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+ is_portrait = src_h > src_w # Already 9:16 or similar
+
+ # Load face detector
+ backend_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+ proto = os.path.join(backend_dir, "models", "deploy.prototxt")
+ model = os.path.join(backend_dir, "models", "res10_300x300_ssd_iter_140000.caffemodel")
+
+ if not (os.path.exists(proto) and os.path.exists(model)):
+ cap.release()
+ return []
+
+ detector = cv2.dnn.readNetFromCaffe(proto, model)
+ os.makedirs(output_dir, exist_ok=True)
+
+ # Sample more frames for better candidates
+ start_t = duration * 0.1
+ end_t = duration * 0.9
+ sample_count = max(count * 6, 30)
+ candidates = []
+
+ for i in range(sample_count):
+ t = start_t + i * (end_t - start_t) / sample_count
+ cap.set(cv2.CAP_PROP_POS_MSEC, t * 1000)
+ ret, frame = cap.read()
+ if not ret:
+ continue
+
+ h, w = frame.shape[:2]
+ blob = cv2.dnn.blobFromImage(cv2.resize(frame, (300, 300)), 1.0, (300, 300), (104.0, 177.0, 123.0))
+ detector.setInput(blob)
+ detections = detector.forward()
+
+ for j in range(detections.shape[2]):
+ conf = detections[0, 0, j, 2]
+ if conf > 0.7:
+ x1 = max(0, int(detections[0, 0, j, 3] * w))
+ y1 = max(0, int(detections[0, 0, j, 4] * h))
+ x2 = min(w, int(detections[0, 0, j, 5] * w))
+ y2 = min(h, int(detections[0, 0, j, 6] * h))
+ fw = x2 - x1
+ fh = y2 - y1
+
+ if fw < w * 0.10:
+ continue
+
+ # Split-screen check
+ face_cx = (x1 + x2) / 2
+ if 0.4 * w < face_cx < 0.6 * w and fw < w * 0.25:
+ continue
+
+ # Sharpness of face region (proxy for eyes open, good expression)
+ sharpness = _frame_sharpness(frame, (x1, y1, x2, y2))
+
+ # Face size as fraction of frame
+ face_area_pct = (fw * fh) / (w * h) * 100
+
+ # Score: confidence × sharpness × size_preference
+ # Prefer faces that are 5-25% of frame area (natural portrait)
+ # Penalize extreme close-ups (>35%) and tiny faces (<3%)
+ if face_area_pct > 35:
+ size_factor = 0.4 # Too zoomed in
+ elif face_area_pct > 25:
+ size_factor = 0.7
+ elif face_area_pct < 3:
+ size_factor = 0.5 # Too small
+ else:
+ size_factor = 1.0 # Sweet spot
+
+ score = (conf ** 2) * (sharpness ** 0.5) * size_factor
+
+ candidates.append({
+ "frame": frame.copy(),
+ "timestamp": round(t, 1),
+ "confidence": round(float(conf), 3),
+ "face_x_pct": round((x1 + x2) / 2 / w * 100, 1),
+ "face_y_pct": round((y1 + y2) / 2 / h * 100, 1),
+ "face_w_pct": round(fw / w * 100, 1),
+ "face_h_pct": round(fh / h * 100, 1),
+ "sharpness": round(sharpness, 1),
+ "score": score,
+ })
+
+ cap.release()
+
+ if not candidates:
+ return []
+
+ # Pick top N by score, spaced apart in time
+ candidates.sort(key=lambda c: c["score"], reverse=True)
+ selected = []
+ for c in candidates:
+ if len(selected) >= count:
+ break
+ too_close = any(abs(c["timestamp"] - s["timestamp"]) < 3 for s in selected)
+ if not too_close:
+ selected.append(c)
+
+ # Detect split-screen: if all faces are in the left or right third,
+ # the video is likely a Riverside/multi-cam layout. Pre-crop to just
+ # the half containing the face.
+ if selected:
+ avg_face_x = sum(c["face_x_pct"] for c in selected) / len(selected)
+ is_split = avg_face_x < 35 or avg_face_x > 65
+
+ if is_split:
+ for c in selected:
+ h_frame, w_frame = c["frame"].shape[:2]
+ face_px = int(w_frame * c["face_x_pct"] / 100)
+ if avg_face_x < 35:
+ c["frame"] = c["frame"][:, :w_frame // 2]
+ new_w = w_frame // 2
+ c["face_x_pct"] = round(face_px / new_w * 100, 1)
+ else:
+ c["frame"] = c["frame"][:, w_frame // 2:]
+ new_w = w_frame - w_frame // 2
+ c["face_x_pct"] = round((face_px - w_frame // 2) / new_w * 100, 1)
+ c["face_w_pct"] = c["face_w_pct"] * 2
+ # After split crop, source is no longer portrait
+ is_portrait = False
+
+ # Crop/compose each frame to 9:16
+ target_ratio = 9 / 16 # 0.5625
+ target_w, target_h = 1080, 1920
+
+ for c in selected:
+ frame = c["frame"]
+ fh, fw = frame.shape[:2]
+ face_cx = int(fw * c["face_x_pct"] / 100)
+ face_cy = int(fh * c["face_y_pct"] / 100)
+ src_ratio = fw / fh
+
+ if is_portrait and src_ratio > 0.5:
+ # Already portrait (9:16 ish) — scale to fit width, place face
+ # in upper portion with dark padding below for text area.
+ scale = target_w / fw
+ new_w = target_w
+ new_h = int(fh * scale)
+
+ resized = cv2.resize(frame, (new_w, new_h), interpolation=cv2.INTER_LANCZOS4)
+ face_cy_scaled = int(face_cy * scale)
+
+ # Place face at ~30% from top of the 1920px canvas
+ y_offset = int(target_h * 0.30) - face_cy_scaled
+ # Clamp: don't go above top, and keep as much of the frame visible
+ y_offset = max(0, min(y_offset, target_h - new_h))
+
+ # Compose onto dark canvas
+ canvas = np.zeros((target_h, target_w, 3), dtype=np.uint8)
+ canvas[:] = (13, 13, 13) # #0D0D0D in BGR
+ end_y = min(y_offset + new_h, target_h)
+ canvas[y_offset:end_y] = resized[:end_y - y_offset]
+
+ c["frame"] = canvas
+ c["face_x_pct"] = round(face_cx * scale / target_w * 100, 1)
+ c["face_y_pct"] = round((face_cy_scaled + y_offset) / target_h * 100, 1)
+ else:
+ # Landscape source — crop to 9:16 centered on face
+ crop_h = fh
+ crop_w = int(crop_h * target_ratio)
+ if crop_w > fw:
+ crop_w = fw
+ crop_h = int(crop_w / target_ratio)
+
+ crop_x = face_cx - crop_w // 2
+ crop_x = max(0, min(crop_x, fw - crop_w))
+
+ crop_y = face_cy - int(crop_h * 0.25)
+ crop_y = max(0, min(crop_y, fh - crop_h))
+
+ c["frame"] = frame[crop_y:crop_y + crop_h, crop_x:crop_x + crop_w]
+ new_face_cx = face_cx - crop_x
+ new_face_cy = face_cy - crop_y
+ c["face_x_pct"] = round(new_face_cx / crop_w * 100, 1)
+ c["face_y_pct"] = round(new_face_cy / crop_h * 100, 1)
+
+ # Save frames
+ results = []
+ for i, c in enumerate(selected):
+ path = os.path.join(output_dir, f"frame_{i}.jpg")
+ frame = c["frame"]
+ fh, fw = frame.shape[:2]
+ if (fw, fh) != (target_w, target_h):
+ frame = cv2.resize(frame, (target_w, target_h), interpolation=cv2.INTER_LANCZOS4)
+ cv2.imwrite(path, frame, [cv2.IMWRITE_JPEG_QUALITY, 92])
+ results.append({
+ "path": path,
+ "timestamp": c["timestamp"],
+ "confidence": c["confidence"],
+ "face_x_pct": c["face_x_pct"],
+ "face_y_pct": c["face_y_pct"],
+ "face_w_pct": c["face_w_pct"],
+ "face_h_pct": c["face_h_pct"],
+ })
+
+ return results
+
+
+def ask_claude_for_layout(
+ title: str,
+ frame_path: str,
+ frame_info: Optional[dict] = None,
+ logo_path: Optional[str] = None,
+ config: Optional[dict] = None,
+) -> Optional[dict]:
+ """
+ Ask Claude to generate ALL layout values for the thumbnail.
+ Claude sees the frame info and decides everything dynamically.
+
+ Returns dict with line1, line2, box_y, photo_object_position, etc.
+ """
+ from services.claude_suggest import _find_claude
+ claude_path = _find_claude()
+ if not claude_path:
+ return None
+
+ cfg = config or _load_brand_config()
+
+ face_ctx = "No face detected."
+ if frame_info:
+ face_ctx = (
+ f"Face center: x={frame_info.get('face_x_pct', 50)}%, y={frame_info.get('face_y_pct', 40)}%.\n"
+ f"Face size: {frame_info.get('face_w_pct', 20)}% width, {frame_info.get('face_h_pct', 25)}% height.\n"
+ f"The frame is already pre-cropped to 1080x1920 (9:16) with face centered horizontally."
+ )
+
+ prompt = f"""You are a thumbnail layout engine. Given a title and face position, return CSS values for a YouTube Shorts thumbnail (1080x1920).
+
+TITLE: "{title}"
+
+PHOTO INFO:
+{face_ctx}
+
+Return ONLY valid JSON with these fields:
+{{
+ "line1": "FIRST LINE TEXT",
+ "line2": "SECOND LINE TEXT",
+ "box_y": "75%",
+ "photo_object_position": "center 20%",
+ "line1_font_size": "96px",
+ "line2_font_size": "90px"
+}}
+
+RULES:
+- Split the title into 2 impactful lines. Line 1 = setup, Line 2 = payoff.
+- box_y: position the text box so it does NOT overlap the face. If face is high (y<40%), use 80-85%. If face is centered (y~50%), use 75-78%. If face is low, use 68-72%.
+- photo_object_position: CSS value to show the face well. The photo is already 1080x1920 with face centered, so "center top" usually works. Adjust if face_y is unusual.
+- Font sizes: for short text (1-2 words per line) use 96-110px. For medium (3-4 words) use 80-96px. For long (5+ words) use 64-80px. Line 2 should be 85-95% of Line 1.
+- No slashes in the text lines."""
+
+ project_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "..")
+
+ try:
+ with tempfile.NamedTemporaryFile(mode="w", suffix=".txt", delete=False, dir=project_dir) as f:
+ f.write(prompt)
+ prompt_file = f.name
+
+ result = subprocess.run(
+ f'cat "{prompt_file}" | "{claude_path}" --print -p -',
+ capture_output=True, text=True, shell=True, timeout=30,
+ cwd=project_dir,
+ )
+ os.unlink(prompt_file)
+
+ if result.returncode != 0:
+ return None
+
+ text = result.stdout.strip()
+ start = text.find("{")
+ end = text.rfind("}") + 1
+ if start >= 0 and end > start:
+ return json.loads(text[start:end])
+ except Exception:
+ pass
+ return None
+
+
+def generate_thumbnail_with_template(
+ title: str,
+ frame_path: str,
+ output_path: str,
+ logo_path: Optional[str] = None,
+ frame_info: Optional[dict] = None,
+ config: Optional[dict] = None,
+ variation: int = 0,
+) -> Optional[str]:
+ """
+ Template + AI layout. Claude decides all dynamic values per frame.
+ Template provides consistent visual structure.
+ """
+ from services.thumbnail_html import generate_thumbnail, _load_config
+
+ cfg = _load_config()
+ if config:
+ cfg.update(config)
+
+ # Ask Claude for ALL layout decisions
+ layout = ask_claude_for_layout(title, frame_path, frame_info, logo_path, cfg)
+
+ if layout:
+ line1 = layout.get("line1", title).strip().strip("/").strip()
+ line2 = layout.get("line2", "").strip().strip("/").strip()
+ # Apply Claude's CSS decisions to config
+ if layout.get("box_y"):
+ cfg["box_y"] = layout["box_y"]
+ cfg["box_y_with_photo"] = layout["box_y"]
+ if layout.get("photo_object_position"):
+ cfg["photo_object_position"] = layout["photo_object_position"]
+ if layout.get("line1_font_size"):
+ cfg["line1_font_size"] = layout["line1_font_size"]
+ if layout.get("line2_font_size"):
+ cfg["line2_font_size"] = layout["line2_font_size"]
+ else:
+ # Fallback
+ if " / " in title:
+ parts = title.split(" / ", 1)
+ line1, line2 = parts[0].strip(), parts[1].strip()
+ else:
+ words = title.split()
+ mid = len(words) // 2 or 1
+ line1 = " ".join(words[:mid])
+ line2 = " ".join(words[mid:])
+
+ return generate_thumbnail(
+ line1, line2, output_path,
+ photo_path=frame_path if frame_path and os.path.exists(frame_path) else None,
+ logo_path=logo_path,
+ config=cfg,
+ variation=variation,
+ face_info=frame_info,
+ )
+
+
+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 thumbnail variations using AI.
+
+ 1. Extract candidate frames from video (if no photo provided)
+ 2. For each variation, Claude generates the HTML layout
+ 3. Playwright renders to PNG
+
+ Falls back to template-based generation if Claude is unavailable.
+ """
+ cfg = _load_brand_config()
+ if config:
+ cfg.update(config)
+
+ os.makedirs(output_dir, exist_ok=True)
+ n = cfg.get("variations", 3)
+
+ # Get frames
+ frames = []
+ if photo_path and os.path.exists(photo_path):
+ frames = [{"path": photo_path}]
+ elif video_path:
+ frames_dir = os.path.join(output_dir, "_frames")
+ frames = extract_candidate_frames(video_path, frames_dir, count=n)
+
+ if not frames:
+ frames = [{"path": None}] # No photo — dark bg only
+
+ paths = []
+ for i in range(n):
+ frame = frames[i % len(frames)]
+ frame_path = frame.get("path") or ""
+ out_path = os.path.join(output_dir, f"thumb_v{i+1}.png")
+
+ result = generate_thumbnail_with_template(
+ title=title,
+ frame_path=frame_path,
+ output_path=out_path,
+ logo_path=logo_path,
+ frame_info=frame if frame_path else None,
+ config=cfg,
+ variation=i,
+ )
+
+ if result:
+ paths.append(result)
+
+ return paths
+
+
+def thumbnail_to_video_frame(
+ thumbnail_path: str,
+ output_path: str,
+ duration: float = 2.0,
+ fade_in: float = 0.3,
+ fade_out: float = 0.3,
+ width: int = 1080,
+ height: int = 1920,
+) -> str:
+ """Convert thumbnail to a short video clip with fade."""
+ 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",
+ output_path,
+ ]
+ result = subprocess.run(cmd, capture_output=True, text=True)
+ if result.returncode != 0:
+ raise RuntimeError(f"Failed: {result.stderr[-300:]}")
+ return output_path
diff --git a/backend/services/thumbnail_generator.py b/backend/services/thumbnail_generator.py
index dc5d862..f99c115 100644
--- a/backend/services/thumbnail_generator.py
+++ b/backend/services/thumbnail_generator.py
@@ -29,35 +29,58 @@ DEFAULT_CONFIG = {
"width": 1080,
"height": 1920,
- # Colors
- "bg_color": "#0D0D0D",
+ # Colors — change these to match your brand
+ "bg_color": "#1A1A1A",
"text_color": "#FFFFFF",
"accent_color": "#00CED1",
- "highlight_bg": "#0D0D0D",
# Text
- "font_size_line1": 64,
- "font_size_line2": 64,
+ "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 = use accent_color
- "text_position": "lower", # "lower", "center", "upper"
- "max_chars_per_line": 18,
+ "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_darken": 0.4, # 0 = black, 1 = original brightness
- "photo_blur": 2, # Gaussian blur px
- "photo_position": "center", # "center", "top", "bottom"
-
- # Logo
- "logo_position": "top-left", # "top-left", "top-right", "top-center", "none"
- "logo_height": 80,
+ "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
- # Gradient
- "gradient_strength": 0.8, # 0-1, bottom gradient opacity
+ # Frame border (around entire image)
+ "frame_border_width": 4, # 0 = no frame
+ "frame_border_color": None, # None = accent_color
- # Variations to generate
+ # Variations
"variations": 3,
}
@@ -79,35 +102,56 @@ def _load_config() -> dict:
def _get_font(size: int, bold: bool = True, italic: bool = False) -> ImageFont.FreeTypeFont:
- """Get the best available font. Tries system fonts, falls back to default."""
- font_candidates = []
+ """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:
- font_candidates += [
- "/System/Library/Fonts/Helvetica.ttc",
- "/usr/share/fonts/truetype/dejavu/DejaVuSans-BoldOblique.ttf",
+ ttc_options = [
+ ("/System/Library/Fonts/HelveticaNeue.ttc", 3), # Helvetica Neue Bold Italic
+ ("/System/Library/Fonts/Helvetica.ttc", 3),
]
elif bold:
- font_candidates += [
- "/System/Library/Fonts/SFCompact.ttf",
- "/System/Library/Fonts/Helvetica.ttc",
- "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf",
- "/usr/share/fonts/truetype/liberation/LiberationSans-Bold.ttf",
+ ttc_options = [
+ ("/System/Library/Fonts/HelveticaNeue.ttc", 1), # Helvetica Neue Bold
+ ("/System/Library/Fonts/Helvetica.ttc", 1),
]
elif italic:
- font_candidates += [
- "/System/Library/Fonts/Helvetica.ttc",
- "/usr/share/fonts/truetype/dejavu/DejaVuSans-Oblique.ttf",
+ ttc_options = [
+ ("/System/Library/Fonts/HelveticaNeue.ttc", 2), # Helvetica Neue Italic
+ ("/System/Library/Fonts/Helvetica.ttc", 2),
+ ]
+ else:
+ ttc_options = [
+ ("/System/Library/Fonts/HelveticaNeue.ttc", 0), # Helvetica Neue Regular
+ ("/System/Library/Fonts/Helvetica.ttc", 0),
]
- # Always try Arial as fallback
- font_candidates += [
- "/Library/Fonts/Arial Bold.ttf",
- "/Library/Fonts/Arial.ttf",
- "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
- ]
+ 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",
+ "/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",
+ "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
+ ]
- for path in font_candidates:
+ for path in fallbacks:
if os.path.exists(path):
try:
return ImageFont.truetype(path, size)
@@ -135,34 +179,187 @@ def _wrap_text(text: str, max_chars: int) -> list[str]:
return lines
-def _draw_gradient(img: Image.Image, strength: float = 0.8) -> Image.Image:
- """Draw a bottom-to-top dark gradient overlay."""
+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 60% gets gradient
- start_y = int(h * 0.4)
- for y in range(start_y, h):
- progress = (y - start_y) / (h - start_y)
- alpha = int(255 * strength * progress)
- draw.line([(0, y), (w, y)], fill=(0, 0, 0, alpha))
-
- # Also light gradient at top for logo readability
- for y in range(0, int(h * 0.15)):
- progress = 1 - (y / (h * 0.15))
- alpha = int(100 * strength * progress)
- draw.line([(0, y), (w, y)], fill=(0, 0, 0, alpha))
+ # 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,
+) -> 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
+ backend_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+ proto = os.path.join(backend_dir, "models", "deploy.prototxt")
+ model = os.path.join(backend_dir, "models", "res10_300x300_ssd_iter_140000.caffemodel")
+
+ if not (os.path.exists(proto) and os.path.exists(model)):
+ cap.release()
+ return None
+
+ detector = cv2.dnn.readNetFromCaffe(proto, model)
+
+ best_frame = None
+ best_score = 0
+ best_face_cx = None
+ best_face_cy = None
+ best_face_w = 0
+ best_face_h = 0
+
+ # Sample frames evenly (skip first/last 10% to avoid intro/outro)
+ 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]
+ blob = cv2.dnn.blobFromImage(cv2.resize(frame, (300, 300)), 1.0, (300, 300), (104.0, 177.0, 123.0))
+ detector.setInput(blob)
+ detections = detector.forward()
+
+ for j in range(detections.shape[2]):
+ conf = detections[0, 0, j, 2]
+ if conf > 0.6:
+ x1 = int(detections[0, 0, j, 3] * w)
+ y1 = int(detections[0, 0, j, 4] * h)
+ x2 = int(detections[0, 0, j, 5] * w)
+ y2 = int(detections[0, 0, j, 6] * h)
+ face_w = x2 - x1
+ face_h = y2 - y1
+
+ if face_w < w * 0.08:
+ continue
+
+ # 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 = (x1 + x2) // 2
+ best_face_cy = (y1 + y2) // 2
+ best_face_w = face_w
+ best_face_h = face_h
+
+ cap.release()
+
+ if best_frame is None:
+ return None
+
+ h, w = best_frame.shape[:2]
+
+ # Crop a vertical (9:16) slice centered on the face.
+ # The HTML template shows the photo in the top ~78% (1498px of 1920px),
+ # so we need the face well-centered in that visible zone.
+ 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)
+
+ # Center horizontally on face exactly
+ crop_x = best_face_cx - crop_w // 2
+ 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,
@@ -195,150 +392,204 @@ def generate_thumbnail(
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"])
- # Create base image
+ # ── 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))
- # Guest photo as background
+ # ── Layer 2: Guest photo ──
if guest_photo_path and os.path.exists(guest_photo_path):
try:
photo = Image.open(guest_photo_path).convert("RGBA")
-
- # Resize to fill width, position based on config
photo_ratio = photo.width / photo.height
target_ratio = w / h
+ zoom = cfg.get("photo_zoom", 1.0)
if photo_ratio > target_ratio:
- new_h = h
+ new_h = int(h * zoom)
new_w = int(new_h * photo_ratio)
else:
- new_w = w
+ new_w = int(w * zoom)
new_h = int(new_w / photo_ratio)
photo = photo.resize((new_w, new_h), Image.LANCZOS)
- # Position
x_offset = (w - new_w) // 2
- if cfg["photo_position"] == "top":
+ pos = cfg["photo_position"]
+ if pos == "top":
y_offset = 0
- elif cfg["photo_position"] == "bottom":
+ elif pos == "bottom":
y_offset = h - new_h
else:
y_offset = (h - new_h) // 2
- # Variation: shift photo position slightly
+ # Variation: slight shift
if variation == 1:
- y_offset -= int(h * 0.05)
+ y_offset -= int(h * 0.04)
elif variation == 2:
- y_offset += int(h * 0.05)
+ y_offset += int(h * 0.04)
- # Darken + blur
- enhancer = ImageEnhance.Brightness(photo)
- photo = enhancer.enhance(cfg["photo_darken"])
- if cfg["photo_blur"] > 0:
- photo = photo.filter(ImageFilter.GaussianBlur(cfg["photo_blur"]))
+ # 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:
- pass # Failed to load photo, continue with solid bg
+ pass
- # Gradient overlay
- img = _draw_gradient(img, cfg["gradient_strength"])
+ # ── 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)
- # Logo
- if logo_path and os.path.exists(logo_path) and cfg["logo_position"] != "none":
- try:
- logo = Image.open(logo_path).convert("RGBA")
- logo_h = cfg["logo_height"]
- logo_w = int(logo.width * (logo_h / logo.height))
- logo = logo.resize((logo_w, logo_h), Image.LANCZOS)
+ # ── Layer 4: Text box + text ──
+ 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))
- margin = cfg["logo_margin"]
- if cfg["logo_position"] == "top-left":
- logo_x, logo_y = margin, margin
- elif cfg["logo_position"] == "top-right":
- logo_x, logo_y = w - logo_w - margin, margin
- elif cfg["logo_position"] == "top-center":
- logo_x, logo_y = (w - logo_w) // 2, margin
- else:
- logo_x, logo_y = margin, margin
+ 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
+ l1_lines = _wrap_text(l1_text, cfg["max_chars_per_line"])
+ l2_lines = _wrap_text(l2_text, cfg["max_chars_per_line"])
- img.paste(logo, (logo_x, logo_y), logo)
- except Exception:
- pass
+ 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
- # Title text
- font1 = _get_font(cfg["font_size_line1"], bold=True)
- font2 = _get_font(cfg["font_size_line2"], bold=True, italic=cfg.get("line2_italic", True))
-
- # Process line1
- line1_text = title_line1.upper() if cfg["line1_uppercase"] else title_line1
- line1_lines = _wrap_text(line1_text, cfg["max_chars_per_line"])
-
- # Process line2
- line2_text = title_line2
- line2_lines = _wrap_text(line2_text, cfg["max_chars_per_line"])
-
- # Calculate text block height
- line_spacing = 12
- total_lines = line1_lines + line2_lines
- line_heights = []
- for i, line in enumerate(total_lines):
- font = font1 if i < len(line1_lines) else font2
- bbox = draw.textbbox((0, 0), line, font=font)
- line_heights.append(bbox[3] - bbox[1])
-
- total_text_h = sum(line_heights) + line_spacing * (len(total_lines) - 1)
-
- # Text Y position based on config + variation
- if cfg["text_position"] == "lower":
- base_y = int(h * 0.68)
- elif cfg["text_position"] == "center":
- base_y = (h - total_text_h) // 2
- else: # upper
- base_y = int(h * 0.25)
-
- # Variation shifts
+ 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
+ all_widths = [s[0] for s in l1_sizes] + [s[0] + hl_pad_x * 2 for s in l2_sizes]
+ max_content_w = max(all_widths) if all_widths else 400
+
+ # Vertical position + variation shift
+ text_y_ratio = cfg.get("text_y", 0.72)
if variation == 1:
- base_y -= int(h * 0.05)
+ text_y_ratio -= 0.04
elif variation == 2:
- base_y += int(h * 0.03)
-
- # Draw each line
- y = base_y
- for i, line in enumerate(total_lines):
- is_line2 = i >= len(line1_lines)
- font = font2 if is_line2 else font1
- color = accent_color if is_line2 else text_color
-
- bbox = draw.textbbox((0, 0), line, font=font)
- text_w = bbox[2] - bbox[0]
- text_h = bbox[3] - bbox[1]
- x = (w - text_w) // 2
-
- # Line2 gets a highlight background box
- if is_line2:
- pad_x, pad_y = 16, 8
- highlight_bg = _hex_to_rgb(cfg.get("highlight_bg", cfg["bg_color"]))
- # Draw rounded-ish rectangle (PIL doesn't have rounded_rectangle in older versions)
+ text_y_ratio += 0.03
+ content_top = int(h * text_y_ratio) - total_content_h // 2
+
+ # 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 = (w - max_content_w) // 2 - pad_x
+ box_t = content_top - pad_y
+ box_r = (w + max_content_w) // 2 + pad_x
+ box_b = 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":
try:
draw.rounded_rectangle(
- [x - pad_x, y - pad_y, x + text_w + pad_x, y + text_h + pad_y],
- radius=10,
- fill=(*highlight_bg, 220),
+ [x - hl_pad_x, y - hl_pad_y, x + tw + hl_pad_x, y + th + hl_pad_y],
+ radius=4, fill=(*accent_color, 255),
)
except AttributeError:
- # Older Pillow without rounded_rectangle
draw.rectangle(
- [x - pad_x, y - pad_y, x + text_w + pad_x, y + text_h + pad_y],
- fill=(*highlight_bg, 220),
+ [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
- # Draw text
- draw.text((x, y), line, fill=(*color, 255), font=font)
- y += text_h + line_spacing
+ # ── 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:
+ pass
+
+ # ── 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)
@@ -350,15 +601,19 @@ 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 (lower, center, shifted)
- - Photo positions (centered, shifted up/down)
+ - Text positions (shifted up/down)
+ - Photo positions (shifted)
Returns list of generated file paths.
"""
@@ -366,18 +621,42 @@ def generate_variations(
if config:
cfg.update(config)
- # Split title into two lines
+ 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()
- mid = len(words) // 2
- if mid == 0:
- mid = 1
- line1 = " ".join(words[:mid])
- line2 = " ".join(words[mid:])
+ 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:])
- os.makedirs(output_dir, exist_ok=True)
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)
diff --git a/backend/services/thumbnail_html.py b/backend/services/thumbnail_html.py
new file mode 100644
index 0000000..520c5cc
--- /dev/null
+++ b/backend/services/thumbnail_html.py
@@ -0,0 +1,485 @@
+"""
+Thumbnail generator using HTML/CSS + Playwright 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
+import subprocess
+import sys
+import tempfile
+from typing import Optional
+
+
+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
+ "bg_color": "#1A1A2E",
+ "text_color": "#FFFFFF",
+ "accent_color": "#E94560",
+
+ # Frame border (around entire thumbnail)
+ "frame_border_width": 3,
+ "frame_border_color": None, # None = accent
+
+ # Text box
+ "box_x": "110px", # CSS left
+ "box_y": "73%", # CSS top (no photo)
+ "box_y_with_photo": "76%",
+ "box_width": "860px", # CSS width
+ "box_min_height": "220px",
+ "box_border_width": 3,
+ "box_border_color": None, # None = accent
+ "box_fill_color": "rgba(26,26,46,0.90)",
+ "box_padding": "28px 36px",
+
+ # Line 1 (top line — typically white text)
+ "line1_font_size": "64px",
+ "line1_font_weight": "600",
+ "line1_letter_spacing": "1px",
+ "line1_line_height": 1.15,
+ "line1_margin_bottom": "10px",
+ "line1_uppercase": True,
+ "line1_color": "#FFFFFF",
+ "line1_nowrap": True,
+
+ # Line 2 (bottom line — highlighted)
+ "line2_font_size": "60px",
+ "line2_font_weight": "500",
+ "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": "#1A1A2E",
+ "line2_highlight_padding": "4px 16px",
+
+ # Photo
+ "photo_brightness": 0.85,
+
+ # 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": "#1A1A2E",
+ "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
+ "font_family": "'Inter', 'Helvetica Neue', 'Arial', 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&display=swap",
+
+ # Variations
+ "variations": 3,
+ "variation_offset_up": "3%",
+ "variation_offset_down": "2%",
+ }
+
+ config_path = os.path.join(
+ os.path.dirname(os.path.abspath(__file__)), "..", "..", ".podcli", "thumbnail-config.json"
+ )
+ if os.path.exists(config_path):
+ try:
+ with open(config_path) as f:
+ user = json.load(f)
+ defaults.update(user)
+ except Exception:
+ pass
+ return defaults
+
+
+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,
+) -> 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.
+ """
+ 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 = line1.upper() if cfg.get("line1_uppercase", True) else line1
+ l2 = line2.upper() if cfg.get("line2_uppercase", True) else line2
+
+ has_photo = photo_path and os.path.exists(str(photo_path))
+
+ # Auto-position text box below face if we have face data
+ if 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_css = ""
+ photo_uri = ""
+ if has_photo:
+ photo_uri = f"file://{os.path.abspath(photo_path)}"
+ brightness = cfg.get("photo_brightness", 0.85)
+ photo_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: center center;
+ filter: brightness({brightness});
+ }}
+ .photo-vignette {{
+ position: absolute; top: 0; left: 0; width: 100%; height: 100%;
+ z-index: 1;
+ }}
+ """
+
+ # Logo
+ logo_html = ""
+ logo_pos = cfg.get("logo_position", "none")
+ if logo_path and os.path.exists(logo_path) and logo_pos != "none":
+ logo_uri = f"file://{os.path.abspath(logo_path)}"
+ 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")
+
+ l1_size = cfg.get("line1_font_size", "64px")
+ l1_weight = cfg.get("line1_font_weight", "600")
+ l1_spacing = cfg.get("line1_letter_spacing", "1px")
+ l1_lh = cfg.get("line1_line_height", 1.15)
+ l1_mb = cfg.get("line1_margin_bottom", "10px")
+ l1_color = cfg.get("line1_color", "#FFFFFF")
+ l1_nowrap = "nowrap" if cfg.get("line1_nowrap", True) else "normal"
+
+ l2_size = cfg.get("line2_font_size", "60px")
+ l2_weight = cfg.get("line2_font_weight", "500")
+ l2_style = cfg.get("line2_font_style", "italic")
+ l2_spacing = cfg.get("line2_letter_spacing", "1px")
+ 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};
+ text-transform: uppercase;
+ text-align: center;
+ line-height: {l1_lh};
+ margin-bottom: {l1_mb};
+ white-space: {l1_nowrap};
+}}
+
+.line2 {{
+ display: flex;
+ justify-content: center;
+}}
+
+.line2 span {{
+ font-size: {l2_size};
+ font-weight: {l2_weight};
+ font-style: {l2_style};
+ letter-spacing: {l2_spacing};
+ text-transform: uppercase;
+ line-height: {l2_lh};
+ background: {hl_color};
+ color: {l2_text_color};
+ padding: {l2_hl_pad};
+ display: inline-block;
+ box-decoration-break: clone;
+ -webkit-box-decoration-break: clone;
+}}
+
+.logo {{ z-index: 8; }}
+</style>
+</head>
+<body>
+ <div class="frame"></div>
+ {f'<div class="photo"><img src="{photo_uri}" /></div><div class="photo-vignette"></div>' if has_photo else ''}
+ <div class="gradient-top"></div>
+ <div class="gradient-bottom"></div>
+ <div class="text-box">
+ <div class="line1">{l1}</div>
+ <div class="line2"><span>{l2}</span></div>
+ </div>
+ {logo_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,
+) -> str:
+ """Generate a single thumbnail via HTML + Playwright screenshot."""
+ cfg = _load_config()
+ if config:
+ cfg.update(config)
+
+ html = _build_html(line1, line2, photo_path, logo_path, cfg, variation, face_info=face_info)
+
+ # 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"]
+
+ result = subprocess.run(
+ [
+ "npx", "playwright", "screenshot",
+ "--viewport-size", f"{w}, {h}",
+ "--wait-for-timeout", "1500",
+ f"file://{tmp_html.name}",
+ output_path,
+ ],
+ capture_output=True, text=True, timeout=30,
+ )
+
+ if result.returncode != 0:
+ raise RuntimeError(f"Screenshot failed: {result.stderr[:300]}")
+
+ return output_path
+ 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:
+ pass
+
+ # Title split — if title contains " / " use that as the split point
+ # (PodStack /plan-thumbnails outputs "LINE 1 / LINE 2" format)
+ if " / " in title:
+ parts = title.split(" / ", 1)
+ line1 = parts[0].strip()
+ line2 = parts[1].strip()
+ else:
+ # Auto-split: balance character count across two lines
+ words = title.split()
+ if len(words) <= 2:
+ line1 = words[0] if words else ""
+ line2 = " ".join(words[1:])
+ else:
+ best_split = len(words) // 2
+ best_diff = float("inf")
+ for i in range(1, len(words)):
+ diff = abs(len(" ".join(words[:i])) - len(" ".join(words[i:])))
+ if diff < best_diff:
+ best_diff = diff
+ best_split = i
+ line1 = " ".join(words[:best_split])
+ line2 = " ".join(words[best_split:])
+
+ 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 = 2.0,
+ fade_in: float = 0.3,
+ fade_out: float = 0.3,
+ width: int = 1080,
+ height: int = 1920,
+) -> str:
+ """Convert thumbnail PNG to a short video clip with fade."""
+ cmd = [
+ "ffmpeg", "-y",
+ "-loop", "1", "-i", thumbnail_path,
+ "-t", str(duration),
+ "-vf", f"scale={width}:{height}:force_original_aspect_ratio=decrease,pad={width}:{height}:(ow-iw)/2:(oh-ih)/2:black,fade=t=in:st=0:d={fade_in},fade=t=out:st={duration-fade_out}:d={fade_out}",
+ "-c:v", "libx264", "-crf", "18", "-preset", "fast",
+ "-pix_fmt", "yuv420p", "-an",
+ output_path,
+ ]
+ result = subprocess.run(cmd, capture_output=True, text=True)
+ if result.returncode != 0:
+ raise RuntimeError(f"Thumbnail to video failed: {result.stderr[-300:]}")
+ return output_path