Skip to content

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

feat: centralize duration limits, fix outro transitions, improve thumbnails

Nika Siradze15b28901999b
diff --git a/backend/cli.py b/backend/cli.py
index fa89fdc..611289d 100644
--- a/backend/cli.py
+++ b/backend/cli.py
@@ -46,6 +46,7 @@ os.environ.setdefault("PODCLI_TRANSITION_AUTOFIX_PASSES", "2")
# Add parent dir to path
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from presets import MIN_CLIP_DURATION, MAX_CLIP_DURATION, TARGET_CLIP_DURATION_MIN, TARGET_CLIP_DURATION_MAX
def _ensure_ssl_certs():
@@ -166,7 +167,7 @@ def cmd_process(args):
from services.transcript_parser import parse_speaker_transcript
from services.audio_analyzer import get_energy_profile
from services.encoder import get_encoder_info
- from presets import get_preset, DEFAULT_PRESET
+ from presets import get_preset, DEFAULT_PRESET, MIN_CLIP_DURATION, MAX_CLIP_DURATION, TARGET_CLIP_DURATION_MIN, TARGET_CLIP_DURATION_MAX
# Load preset or defaults
if args.preset:
@@ -453,8 +454,8 @@ def cmd_process(args):
segments=segments,
energy_scores=energy_scores,
top_n=top_n,
- min_dur=config.get("min_clip_duration", 20),
- max_dur=config.get("max_clip_duration", 90),
+ min_dur=config.get("min_clip_duration", MIN_CLIP_DURATION),
+ max_dur=config.get("max_clip_duration", MAX_CLIP_DURATION),
)
if not clips:
@@ -495,13 +496,10 @@ def cmd_process(args):
_thumb_gen = _tv
_thumb_to_video = _ttv
_thumb_logo = config.get("logo_path") or 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:
- _thumb_photo = photos[0]["path"]
- except Exception:
- pass
+ # Do not auto-pick a static photo for clip exports.
+ # Using a single image causes all thumbnail variations to show
+ # the same face moment. Prefer video-derived frames by default.
+ _thumb_photo = None
except Exception:
_thumb_enabled = False
@@ -541,7 +539,7 @@ def cmd_process(args):
if ok:
print(f" ✓ Clip {i+1}/{len(clips)}: {result['file_size_mb']}MB")
- # Generate thumbnail and append to clip immediately
+ # Generate thumbnail and hard-cut append to clip end
if _thumb_enabled and _thumb_gen and result.get("output_path"):
try:
clip_thumb_dir = os.path.join(thumb_dir, f"clip_{i+1}")
@@ -550,6 +548,8 @@ def cmd_process(args):
output_dir=clip_thumb_dir,
photo_path=_thumb_photo,
video_path=video_path,
+ start_second=clip.get("start_second"),
+ end_second=clip.get("end_second"),
logo_path=_thumb_logo,
)
if paths:
@@ -557,7 +557,9 @@ def cmd_process(args):
_thumb_to_video(paths[0], thumb_video, duration=1.5)
from services.video_processor import concat_outro
final_with_thumb = result["output_path"].replace(".mp4", "_with_thumb.mp4")
- concat_outro(result["output_path"], thumb_video, final_with_thumb, crossfade_duration=0.15)
+ # Hard cut — no crossfade, so thumbnail appears cleanly
+ # after outro ends, no overlap with captions
+ concat_outro(result["output_path"], thumb_video, final_with_thumb, crossfade_duration=0.0)
os.replace(final_with_thumb, result["output_path"])
print(f" + thumbnail appended ({len(paths)} variations in {os.path.basename(clip_thumb_dir)}/)")
except Exception as e:
@@ -837,6 +839,7 @@ def _print_clips(clips: list):
def _find_moment_with_claude(description: str, segments: list, existing_clips: list) -> list:
"""Use Claude to find a specific moment described by the user."""
from services.claude_suggest import _find_ai_cli_candidates, _run_ai_command
+ from presets import MIN_CLIP_DURATION, MAX_CLIP_DURATION, TARGET_CLIP_DURATION_MIN, TARGET_CLIP_DURATION_MAX
candidates = _find_ai_cli_candidates()
if not candidates:
@@ -871,7 +874,7 @@ RULES:
- Find the EXACT moment matching the user's description
- Return 1-3 matching moments (best match first)
- All timestamps in SECONDS as numbers
-- Duration target: 25-40 seconds, max 50 seconds
+- Duration target: {TARGET_CLIP_DURATION_MIN}-{TARGET_CLIP_DURATION_MAX} seconds, max {MAX_CLIP_DURATION} seconds
- Cut tight: start at the hook, end when the point lands
- Use segments to cut filler if needed
@@ -955,7 +958,7 @@ Transcript:
keep_segments = [{"start": start_sec, "end": end_sec}]
kept_duration = sum(seg["end"] - seg["start"] for seg in keep_segments)
- if kept_duration < 10 or kept_duration > 90:
+ if kept_duration < MIN_CLIP_DURATION or kept_duration > MAX_CLIP_DURATION:
continue
found.append({
@@ -1442,8 +1445,8 @@ def _suggest_clips(
segments: list,
energy_scores: list | None = None,
top_n: int = 5,
- min_dur: float = 20,
- max_dur: float = 90,
+ min_dur: float = MIN_CLIP_DURATION,
+ max_dur: float = MAX_CLIP_DURATION,
) -> list:
"""
Score and rank transcript segments into viral clip suggestions.
@@ -1924,6 +1927,149 @@ def cmd_thumbnails(args):
print(f" {gray}Edit .podcli/thumbnail-config.json to customize colors, fonts, layout.{reset}\n")
+def cmd_swap_thumbnail(args):
+ """Regenerate and swap the thumbnail on an existing rendered clip."""
+ from services.thumbnail_ai import generate_variations, thumbnail_to_video_frame
+ from services.video_processor import concat_outro, _get_media_duration_seconds
+ from services.asset_store import resolve as resolve_asset
+
+ accent = "\033[38;2;212;135;74m"
+ green = "\033[38;2;74;222;128m"
+ gray = "\033[38;5;245m"
+ bold = "\033[1m"
+ reset = "\033[0m"
+
+ clip_path = args.clip
+ if not os.path.exists(clip_path):
+ print(f" Clip not found: {clip_path}", file=sys.stderr)
+ sys.exit(1)
+
+ # Thumbnail duration that was appended (default 1.5s)
+ thumb_duration = getattr(args, "thumb_duration", 1.5)
+ title = getattr(args, "title", None) or os.path.splitext(os.path.basename(clip_path))[0].replace("_", " ")
+
+ # Source video for extracting a new face frame — required to avoid
+ # pulling frames from rendered clips (which have captions burned in)
+ source_video = getattr(args, "source_video", None)
+ if not source_video:
+ print(f" ✗ --source-video is required (rendered clips have captions burned in)", file=sys.stderr)
+ sys.exit(1)
+ if not os.path.exists(source_video):
+ print(f" ✗ Source video not found: {source_video}", file=sys.stderr)
+ sys.exit(1)
+
+ logo = None
+ if getattr(args, "logo", None):
+ logo = resolve_asset(args.logo)
+ else:
+ try:
+ from services.asset_store import list_assets
+ logos = [a for a in list_assets() if a["type"] == "logo" and os.path.exists(a["path"])]
+ if logos:
+ logo = logos[0]["path"]
+ except Exception:
+ pass
+
+ # Step 1: Trim the old thumbnail from the clip
+ clip_duration = _get_media_duration_seconds(clip_path, default=0.0)
+ if clip_duration <= thumb_duration:
+ print(f" Clip too short ({clip_duration:.1f}s) to trim thumbnail", file=sys.stderr)
+ sys.exit(1)
+
+ content_duration = clip_duration - thumb_duration
+ print(f"\n {bold}Swapping thumbnail on:{reset} {os.path.basename(clip_path)}")
+ print(f" {gray}Clip: {clip_duration:.1f}s → content: {content_duration:.1f}s + new thumbnail{reset}")
+
+ import tempfile
+ work_dir = tempfile.mkdtemp(prefix="swap_thumb_")
+
+ # Trim off old thumbnail
+ trimmed_path = os.path.join(work_dir, "trimmed.mp4")
+ import subprocess
+ trim_cmd = [
+ "ffmpeg", "-y", "-i", clip_path,
+ "-t", str(content_duration),
+ "-c", "copy", "-movflags", "+faststart",
+ trimmed_path,
+ ]
+ result = subprocess.run(trim_cmd, capture_output=True, text=True, timeout=60)
+ if result.returncode != 0:
+ print(f" Failed to trim: {result.stderr[-200:]}", file=sys.stderr)
+ sys.exit(1)
+
+ # Step 2: Generate new thumbnail
+ thumb_dir = os.path.join(work_dir, "thumbnails")
+ print(f" {bold}Generating new thumbnails...{reset}")
+
+ timestamp = getattr(args, "timestamp", None)
+ start_sec = getattr(args, "start", None)
+ end_sec = getattr(args, "end", None)
+
+ # If exact timestamp given, extract that specific frame
+ frame_path = None
+ if timestamp is not None:
+ import cv2
+ cap = cv2.VideoCapture(source_video)
+ cap.set(cv2.CAP_PROP_POS_MSEC, timestamp * 1000)
+ ret, frame = cap.read()
+ cap.release()
+ if ret:
+ frame_path = os.path.join(thumb_dir, "_manual_frame.png")
+ os.makedirs(thumb_dir, exist_ok=True)
+ cv2.imwrite(frame_path, frame)
+ print(f" {green}✓{reset} Using frame at {timestamp}s")
+ else:
+ print(f" ⚠ Could not read frame at {timestamp}s, falling back to auto", file=sys.stderr)
+
+ paths = generate_variations(
+ title=title,
+ output_dir=thumb_dir,
+ photo_path=frame_path,
+ video_path=source_video,
+ start_second=start_sec,
+ end_second=end_sec,
+ logo_path=logo,
+ config={"variations": getattr(args, "variations", 3)},
+ )
+
+ if not paths:
+ print(f" Failed to generate thumbnails", file=sys.stderr)
+ sys.exit(1)
+
+ # Show variations
+ for i, p in enumerate(paths):
+ print(f" {green}✓{reset} Variation {i+1}: {p}")
+
+ # Use first variation (or user-specified)
+ pick = getattr(args, "pick", 1) - 1
+ pick = max(0, min(pick, len(paths) - 1))
+ chosen = paths[pick]
+ print(f" {accent}Using variation {pick + 1}{reset}")
+
+ # Step 3: Convert to video frame and append
+ thumb_video = os.path.join(work_dir, "thumb_frame.mp4")
+ thumbnail_to_video_frame(chosen, thumb_video, duration=thumb_duration)
+
+ final_path = os.path.join(work_dir, "final.mp4")
+ concat_outro(trimmed_path, thumb_video, final_path, crossfade_duration=0.0, transition="fade")
+
+ # Step 4: Replace original
+ import shutil
+ shutil.move(final_path, clip_path)
+
+ # Copy thumbnail PNGs next to the clip
+ clip_dir = os.path.dirname(clip_path)
+ for p in paths:
+ dest = os.path.join(clip_dir, os.path.basename(p))
+ shutil.copy2(p, dest)
+
+ # Cleanup
+ shutil.rmtree(work_dir, ignore_errors=True)
+
+ print(f" {green}✓ Thumbnail swapped!{reset}")
+ print(f" {gray}Variations saved next to clip for future swaps.{reset}\n")
+
+
def cmd_corrections(args):
"""Manage transcript word corrections."""
from services.corrections import get_corrections, save_corrections
@@ -2427,6 +2573,19 @@ def main():
thumb.add_argument("--logo", help="Logo (asset name or path)")
thumb.add_argument("-n", "--variations", type=int, default=3, help="Number of variations")
+ # ── swap-thumbnail ──
+ st = sub.add_parser("swap-thumbnail", help="Regenerate thumbnail on an existing clip")
+ st.add_argument("clip", help="Path to rendered clip (.mp4)")
+ st.add_argument("--title", help="Title text (defaults to filename)")
+ st.add_argument("--source-video", required=True, help="Original source video (required — rendered clips have captions burned in)")
+ st.add_argument("--start", type=float, help="Clip start time in source video (seconds)")
+ st.add_argument("--end", type=float, help="Clip end time in source video (seconds)")
+ st.add_argument("--timestamp", type=float, help="Exact second in source video to use as frame (skips auto-detection)")
+ st.add_argument("--logo", help="Logo (asset name or path)")
+ st.add_argument("--pick", type=int, default=1, help="Which variation to use (1-3, default 1)")
+ st.add_argument("-n", "--variations", type=int, default=3, help="Number of variations to generate")
+ st.add_argument("--thumb-duration", type=float, default=1.5, help="Duration of thumbnail end card (default 1.5s)")
+
# ── corrections ──
corr = sub.add_parser("corrections", help="Manage transcript word corrections (Whisper fixes)")
corr_sub = corr.add_subparsers(dest="corrections_action")
@@ -2470,6 +2629,8 @@ def main():
cmd_process(args)
elif args.command == "thumbnails":
cmd_thumbnails(args)
+ elif args.command == "swap-thumbnail":
+ cmd_swap_thumbnail(args)
elif args.command == "presets":
cmd_presets(args)
elif args.command == "assets":
diff --git a/backend/presets.py b/backend/presets.py
index 9e6c646..3d15514 100644
--- a/backend/presets.py
+++ b/backend/presets.py
@@ -19,6 +19,13 @@ PRESETS_DIR = os.path.join(
"presets",
)
+# ── Clip duration constants (single source of truth) ──
+# These are for clip CONTENT only — outro is appended separately.
+MIN_CLIP_DURATION = 20
+MAX_CLIP_DURATION = 45 # hard limit with buffer (outro not included)
+TARGET_CLIP_DURATION_MIN = 20
+TARGET_CLIP_DURATION_MAX = 35 # Claude targets this range
+
DEFAULT_PRESET = {
"caption_style": "branded",
"crop_strategy": "speaker",
@@ -30,8 +37,8 @@ DEFAULT_PRESET = {
"output_dir": "",
"whisper_model": "base",
"top_clips": 5,
- "max_clip_duration": 40,
- "min_clip_duration": 15,
+ "max_clip_duration": MAX_CLIP_DURATION,
+ "min_clip_duration": MIN_CLIP_DURATION,
"target_lufs": -14.0,
"energy_boost": True,
"quality": "max",
diff --git a/backend/services/claude_suggest.py b/backend/services/claude_suggest.py
index 71da193..683b96e 100644
--- a/backend/services/claude_suggest.py
+++ b/backend/services/claude_suggest.py
@@ -15,6 +15,9 @@ import sys
import tempfile
from typing import Optional, Callable
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from presets import MIN_CLIP_DURATION, MAX_CLIP_DURATION, TARGET_CLIP_DURATION_MIN, TARGET_CLIP_DURATION_MAX
+
def _find_cli(name: str, extra_paths: list[str] = None) -> Optional[str]:
"""Find a CLI binary by name. Checks extra_paths first, then PATH."""
@@ -222,11 +225,11 @@ TIMESTAMP FORMAT: All timestamps in the transcript are in SECONDS (e.g., [123.4s
All timestamps you return MUST be in SECONDS as numbers (e.g., 123.4), NOT minutes:seconds.
DURATION RULES (CRITICAL):
-- Target: 25-40 seconds (this is the viral sweet spot)
-- Maximum: 50 seconds (absolute hard limit — anything longer loses viewers)
-- Minimum: 15 seconds (too short = no payoff)
-- SHORTER IS BETTER. A punchy 25s clip outperforms a 50s clip every time.
-- If a thought takes longer than 40s, use segments to cut the filler in the middle
+- Target: {TARGET_CLIP_DURATION_MIN}-{TARGET_CLIP_DURATION_MAX} seconds (this is the viral sweet spot)
+- Maximum: {MAX_CLIP_DURATION} seconds (absolute hard limit — anything longer WILL FAIL rendering)
+- Minimum: {MIN_CLIP_DURATION} seconds (too short = no payoff)
+- SHORTER IS BETTER. A punchy 25s clip outperforms a 40s clip every time.
+- If a thought takes longer than {TARGET_CLIP_DURATION_MAX}s, use segments to cut the filler in the middle
CUTTING RULES (CRITICAL):
- Cut TIGHT. Every second must earn its place.
@@ -235,7 +238,7 @@ CUTTING RULES (CRITICAL):
- NEVER cut mid-sentence or mid-thought. The viewer must feel closure.
- The last sentence must feel like a natural ending, a punchline, or a mic-drop
- If there's filler/tangent in the middle, use multiple segments to skip it
-- A 30s clip with zero dead weight beats a 50s clip with 20s of fluff
+- A 30s clip with zero dead weight beats a {MAX_CLIP_DURATION}s clip with fluff
MOMENT SELECTION (think like a TikTok editor):
- Would YOU stop scrolling for this? If no, skip it.
@@ -292,7 +295,7 @@ SEGMENTS RULES:
- Example: speaker makes great point (10s), rambles (8s), delivers punchline (12s) → 2 segments, 22s total
Rules:
-- Final clip duration (sum of segments) MUST be 15-50 seconds (target 25-40s)
+- Final clip duration (sum of segments) MUST be {MIN_CLIP_DURATION}-{MAX_CLIP_DURATION} seconds (target {TARGET_CLIP_DURATION_MIN}-{TARGET_CLIP_DURATION_MAX}s)
- Each segment must start and end on COMPLETE SENTENCES — never mid-thought
- The LAST segment must end on a sentence that feels like a natural conclusion
- Must make sense standalone when stitched together
@@ -501,7 +504,7 @@ def suggest_with_claude(
keep_segments = [{"start": start_sec, "end": end_sec}]
kept_duration = sum(seg["end"] - seg["start"] for seg in keep_segments)
- if kept_duration < 15 or kept_duration > 45:
+ if kept_duration < MIN_CLIP_DURATION or kept_duration > MAX_CLIP_DURATION:
continue
normalized.append({
diff --git a/backend/services/clip_generator.py b/backend/services/clip_generator.py
index 2e3fad8..b8c7924 100644
--- a/backend/services/clip_generator.py
+++ b/backend/services/clip_generator.py
@@ -25,6 +25,7 @@ from services.video_processor import (
concat_outro,
)
from config.caption_styles import get_style
+from presets import MAX_CLIP_DURATION
# Filler words to strip from captions (not aggressive — just obvious fillers)
_FILLER_WORDS = frozenset([
@@ -646,8 +647,8 @@ def generate_clip(
keep_segments = None
duration = end_second - start_second
- if duration > 45:
- raise ValueError(f"Clip too long ({duration:.0f}s). Max 45 seconds for shorts.")
+ if duration > MAX_CLIP_DURATION:
+ raise ValueError(f"Clip too long ({duration:.0f}s). Max {MAX_CLIP_DURATION} seconds for shorts.")
# Load style config for branded-specific settings
style_config = get_style(caption_style)
diff --git a/backend/services/thumbnail_ai.py b/backend/services/thumbnail_ai.py
index aa4a24a..862b6be 100644
--- a/backend/services/thumbnail_ai.py
+++ b/backend/services/thumbnail_ai.py
@@ -120,9 +120,20 @@ def _face_expression_quality(frame, x1: int, y1: int, x2: int, y2: int) -> float
if aspect < 0.7 or aspect > 1.4:
return 0.35 # Odd angle or distortion
- # Combine: eye sharpness × symmetry × (1 - mouth penalty)
+ # 7) Expressiveness — reward animated faces over flat/neutral ones.
+ # Engaged speakers have higher variance in the eyebrow region (raised brows)
+ # and moderate mouth activity (mid-speech, not slack-jawed).
+ brow_region = gray[int(h * 0.15):int(h * 0.30), :]
+ brow_var = cv2.Laplacian(brow_region, cv2.CV_64F).var() if brow_region.size > 0 else 30
+ # Mouth slightly open (mid-word) is more engaging than closed/neutral
+ mouth_activity = mouth_var if mouth_region.size > 0 else 30
+ # Brow raise + moderate mouth = expressive. Flat brow + closed mouth = neutral.
+ expressiveness = min(1.0, (brow_var / 80.0) * 0.6 + min(1.0, mouth_activity / 80.0) * 0.4)
+ expressiveness = max(0.3, expressiveness) # don't zero out, just penalize flat
+
+ # Combine: eye sharpness × symmetry × (1 - mouth penalty) × expressiveness
eye_score = min(1.0, eye_sharpness / 60.0)
- quality = eye_score * symmetry * (1.0 - mouth_penalty)
+ quality = eye_score * symmetry * (1.0 - mouth_penalty) * expressiveness
return max(0.15, min(1.0, quality))
@@ -130,6 +141,8 @@ def extract_candidate_frames(
video_path: str,
output_dir: str,
count: int = 5,
+ start_second: Optional[float] = None,
+ end_second: Optional[float] = None,
) -> list[dict]:
"""
Extract candidate frames with detected faces from a video.
@@ -167,10 +180,23 @@ def extract_candidate_frames(
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)
+ # Sample frames in requested window (clip-local), otherwise use middle 80%.
+ 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))
+ # Small in-window margin so we avoid hard boundary frames.
+ span = max(0.0, end_t - start_t)
+ margin = min(0.6, span * 0.08)
+ start_t = min(end_t, start_t + margin)
+ end_t = max(start_t, end_t - margin)
+ else:
+ start_t = duration * 0.1
+ end_t = duration * 0.9
+
+ if end_t - start_t < 0.2:
+ start_t = max(0.0, duration * 0.1)
+ end_t = min(duration, duration * 0.9)
+ sample_count = max(count * 10, 40)
candidates = []
for i in range(sample_count):
@@ -195,67 +221,97 @@ def extract_candidate_frames(
if fw < w * 0.08:
continue
- # Split-screen check — only for landscape sources where
- # a small centered face likely means a multi-cam layout.
- # Portrait sources naturally have centered faces.
- face_cx = (x1 + x2) / 2
- if not is_portrait and 0.4 * w < face_cx < 0.6 * w and fw < w * 0.15:
- continue
+ # Split-screen check — only for landscape sources where
+ # a small centered face likely means a multi-cam layout.
+ # Portrait sources naturally have centered faces.
+ face_cx = (x1 + x2) / 2
+ if not is_portrait and 0.4 * w < face_cx < 0.6 * w and fw < w * 0.15:
+ continue
- # Sharpness of face region (proxy for eyes open, good expression)
- sharpness = _frame_sharpness(frame, (x1, y1, x2, y2))
+ # Sharpness of face region (proxy for eyes open, good expression)
+ sharpness = _frame_sharpness(frame, (x1, y1, x2, y2))
- # Skip very blurry faces (motion blur, out of focus)
- if sharpness < 12:
- continue
+ # Skip very blurry faces (motion blur, out of focus)
+ if sharpness < 12:
+ continue
- # Face expression quality — filter blinking, open mouths
- expression_quality = _face_expression_quality(frame, x1, y1, x2, y2)
- if expression_quality < 0.45:
- continue # Bad expression (looking down, blinking, mouth open, etc.)
-
- # Face size as fraction of frame
- face_area_pct = (fw * fh) / (w * h) * 100
-
- # Score: confidence × sharpness × size_preference × expression
- # 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 * expression_quality
-
- 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,
- })
+ # Face expression quality — filter blinking, open mouths
+ expression_quality = _face_expression_quality(frame, x1, y1, x2, y2)
+ if expression_quality < 0.45:
+ continue # Bad expression (looking down, blinking, mouth open, etc.)
+
+ # Face size as fraction of frame
+ face_area_pct = (fw * fh) / (w * h) * 100
+
+ # Score: confidence × sharpness × size_preference × expression
+ # 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
+
+ # Prefer frames from the middle 60% of the clip — that's where
+ # the emotional peak usually is, and it avoids identical-looking
+ # boundary frames when consecutive clips share the same speaker.
+ mid_t = (start_t + end_t) / 2
+ span = max(0.1, end_t - start_t)
+ distance_from_mid = abs(t - mid_t) / (span / 2) # 0 = center, 1 = edge
+ position_boost = 1.0 - 0.4 * min(1.0, distance_from_mid)
+
+ score = (conf ** 2) * (sharpness ** 0.5) * size_factor * expression_quality * position_boost
+
+ 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
+ # Pick top N by score, while enforcing diversity in both time and framing.
candidates.sort(key=lambda c: c["score"], reverse=True)
selected = []
+
+ def _too_similar(a: dict, b: dict) -> bool:
+ return (
+ abs(a["timestamp"] - b["timestamp"]) < 2.5
+ and abs(a["face_x_pct"] - b["face_x_pct"]) < 4.0
+ and abs(a["face_y_pct"] - b["face_y_pct"]) < 4.0
+ and abs(a["face_w_pct"] - b["face_w_pct"]) < 5.0
+ )
+
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:
+ too_similar = any(_too_similar(c, s) for s in selected)
+ if not too_close and not too_similar:
+ selected.append(c)
+
+ # If strict diversity rejected too much, relax time-only spacing to still
+ # fill requested variations while preserving different moments first.
+ if len(selected) < count:
+ for c in candidates:
+ if len(selected) >= count:
+ break
+ if c in selected:
+ continue
+ if any(_too_similar(c, s) for s in selected):
+ continue
selected.append(c)
# Detect split-screen: if all faces are in the left or right third,
@@ -514,6 +570,8 @@ def generate_variations(
output_dir: str,
photo_path: Optional[str] = None,
video_path: Optional[str] = None,
+ start_second: Optional[float] = None,
+ end_second: Optional[float] = None,
logo_path: Optional[str] = None,
config: Optional[dict] = None,
) -> list[str]:
@@ -539,7 +597,14 @@ def generate_variations(
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)
+ # Ask for extra candidates so each variation can use a distinct moment.
+ frames = extract_candidate_frames(
+ video_path,
+ frames_dir,
+ count=max(n + 2, n * 2),
+ start_second=start_second,
+ end_second=end_second,
+ )
if not frames and video_path:
# Fallback: simpler face extraction with less aggressive filters
@@ -548,7 +613,9 @@ def generate_variations(
fallback_path = os.path.join(output_dir, "_face_frame.png")
result = extract_face_frame(video_path, fallback_path,
target_width=cfg.get("width", 1080),
- target_height=cfg.get("height", 1920))
+ target_height=cfg.get("height", 1920),
+ start_second=start_second,
+ end_second=end_second)
if result:
frames = [result]
except Exception:
@@ -559,7 +626,7 @@ def generate_variations(
paths = []
for i in range(n):
- frame = frames[i % len(frames)]
+ frame = frames[i] if i < len(frames) else frames[i % len(frames)]
frame_path = frame.get("path") or ""
out_path = os.path.join(output_dir, f"thumb_v{i+1}.png")
diff --git a/backend/services/thumbnail_generator.py b/backend/services/thumbnail_generator.py
index 08523f9..b54b396 100644
--- a/backend/services/thumbnail_generator.py
+++ b/backend/services/thumbnail_generator.py
@@ -227,6 +227,8 @@ def extract_face_frame(
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.
@@ -267,9 +269,13 @@ def extract_face_frame(
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 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:
diff --git a/backend/services/video_processor.py b/backend/services/video_processor.py
index 55290ec..c36aac6 100644
--- a/backend/services/video_processor.py
+++ b/backend/services/video_processor.py
@@ -3006,7 +3006,8 @@ def concat_outro(
input_path: str,
outro_path: str,
output_path: str,
- crossfade_duration: float = 0.5,
+ crossfade_duration: float = 0.8,
+ transition: str = "fadeblack",
) -> str:
"""
Append an outro video to the end of the main clip with a crossfade transition.
@@ -3017,7 +3018,10 @@ def concat_outro(
width, height = get_dimensions(input_path)
main_duration = _get_media_duration_seconds(input_path, default=30.0)
- safe_crossfade = _parse_duration_seconds(crossfade_duration) or 0.5
+ if crossfade_duration <= 0:
+ safe_crossfade = 0.0
+ else:
+ safe_crossfade = _parse_duration_seconds(crossfade_duration) or 0.5
# Re-encode outro to match dimensions
outro_scaled = output_path + ".outro_scaled.mp4"
@@ -3048,14 +3052,14 @@ def concat_outro(
# transition-at-t=0 behavior that can make outro appear instantly.
if can_crossfade:
for audio_filter in [
- # Option 1: proper audio crossfade.
+ # Option 1: video transition + audio crossfade.
(
- f"[0:v][1:v]xfade=transition=fade:duration={safe_crossfade}:offset={fade_offset}[v];"
+ f"[0:v][1:v]xfade=transition={transition}:duration={safe_crossfade}:offset={fade_offset}[v];"
f"[0:a][1:a]acrossfade=d={safe_crossfade}[a]"
),
- # Option 2: video xfade + hard audio concat fallback.
+ # Option 2: video transition + hard audio concat fallback.
(
- f"[0:v][1:v]xfade=transition=fade:duration={safe_crossfade}:offset={fade_offset}[v];"
+ f"[0:v][1:v]xfade=transition={transition}:duration={safe_crossfade}:offset={fade_offset}[v];"
f"[0:a][1:a]concat=n=2:v=0:a=1[a]"
),
]:
diff --git a/src/server.ts b/src/server.ts
index cc6b844..6099758 100644
--- a/src/server.ts
+++ b/src/server.ts
@@ -1505,7 +1505,7 @@ export function createServer(): McpServer {
"- Questions that hook the viewer",
"",
"For each moment, note the start/end timestamps and craft a catchy title.",
- "Aim for 30-90 second clips. Then call suggest_clips with your picks.",
+ "Aim for 15-45 second clips (target 20-35s). Then call suggest_clips with your picks.",
"",
"## Step 5: Export",
"Call batch_create_clips(export_selected: true) to render all clips.",
diff --git a/src/ui/public/index.html b/src/ui/public/index.html
index 99ff741..66a6a0b 100644
--- a/src/ui/public/index.html
+++ b/src/ui/public/index.html
@@ -260,7 +260,7 @@
const [quality, setQuality] = useState('max');
const [topClips, setTopClips] = useState(8);
const [minDuration, setMinDuration] = useState(20);
- const [maxDuration, setMaxDuration] = useState(90);
+ const [maxDuration, setMaxDuration] = useState(45);
const [energyBoost, setEnergyBoost] = useState(true);
// Clip editing
@@ -1073,7 +1073,7 @@
<div className="field">
<label className="field-label">Max duration</label>
<div className="field-row">
- <input type="range" min="30" max="180" step="5" value={maxDuration} onChange={e => setMaxDuration(parseInt(e.target.value))} />
+ <input type="range" min="30" max="60" step="5" value={maxDuration} onChange={e => setMaxDuration(parseInt(e.target.value))} />
<span className="range-value">{maxDuration}s</span>
</div>
</div>