fix: trim black frames from video start/end and improve concat

- Add trim_black_frames() utility to detect and remove black intro/outro frames
- Integrate black frame trimming in asset download, AI SDK, and video analysis
- Improve video_renderer vf_filter with consistent properties (setsar, format, crop)
- Use stream copy for concat with +genpts and avoid_negative_ts flags
- Add video_track_timescale for consistent timing across clips

src/asset_manager/asset_downloader.py

@@ -9,7 +9,7 @@ from pathlib import Path
 from typing import Dict, List, Optional, Any
 from urllib.parse import urlparse
 
-from src.utils import logger, is_valid_video, resize_video, remove_black_padding
+from src.utils import logger, is_valid_video, resize_video, remove_black_padding, trim_black_frames
 from file_downloader import get_file_downloader
 from src.config import get_config_value
 from .video_lib import get_video_lib, VideoLib
@@ -125,6 +125,7 @@ class AssetDownloader:
         for video in downloaded_videos:
             local_path = video["local_path"]
             try:
+                trim_black_frames(local_path, overwrite=True)
                 remove_black_padding(local_path, overwrite=True)
                 resize_video(local_path, overwrite=True)
                 videos.append(video)
@@ -237,7 +238,8 @@ class AssetDownloader:
             
             if not local_path:
                 raise Exception(f"Download returned None for {url}")
-            
+
+            trim_black_frames(str(local_path), overwrite=True)
             if remove_padding:
                 remove_black_padding(str(local_path), overwrite=True)
             if resize:

src/google_src/ai_studio_sdk.py

@@ -78,6 +78,7 @@ def generate_video(prompt: str, output_path: str, image: str = None) -> str | No
         client.files.download(file=generated_video.video)
 
         generated_video.video.save(output_path)
+        utils.trim_black_frames(output_path, overwrite=True)
         utils.remove_black_padding(output_path, overwrite=True)
         utils.resize_video(output_path, overwrite=True)
         print(output_path)

src/utils.py

@@ -841,6 +841,206 @@ def remove_black_padding(input_path: str, overwrite: bool = False, threshold_pct
 
     return tmp_output
 
+def trim_black_frames(
+    input_path: str, 
+    overwrite: bool = False, 
+    black_threshold: int = 20,
+    min_frames_to_trim: int = 1,
+    max_frames_to_trim: int = 30
+) -> str:
+    """
+    Detect and remove solid black frames from the start and end of a video.
+    
+    Uses FFmpeg showinfo filter to analyze frame luminance (Y channel mean).
+    A frame is considered black if its Y mean is <= black_threshold.
+    
+    Args:
+        input_path: Path to the input video
+        overwrite: If True, replace the original file
+        black_threshold: Maximum Y luminance value to consider a frame as black (0-255)
+                        Default 20 catches pure black (16) with some tolerance
+        min_frames_to_trim: Minimum black frames at start/end to trigger trimming
+        max_frames_to_trim: Maximum frames to check at start/end
+        
+    Returns:
+        Path to the trimmed video, or original path if no trimming needed
+    """
+    if not os.path.exists(input_path):
+        raise FileNotFoundError(f"Input video not found: {input_path}")
+    
+    # Get video info
+    probe_cmd = [
+        "ffprobe", "-v", "error",
+        "-select_streams", "v:0",
+        "-show_entries", "stream=nb_frames,r_frame_rate,duration",
+        "-show_entries", "format=duration",
+        "-of", "json", input_path
+    ]
+    probe_result = subprocess.run(probe_cmd, capture_output=True, text=True)
+    
+    if probe_result.returncode != 0:
+        logger.warning(f"Failed to probe video: {input_path}")
+        return input_path
+    
+    probe_data = json.loads(probe_result.stdout)
+    
+    # Get FPS
+    fps_str = probe_data.get("streams", [{}])[0].get("r_frame_rate", "25/1")
+    fps_parts = fps_str.split("/")
+    fps = float(fps_parts[0]) / float(fps_parts[1]) if len(fps_parts) == 2 else float(fps_parts[0])
+    
+    # Get total duration
+    duration = float(probe_data.get("format", {}).get("duration", 0))
+    if duration == 0:
+        duration = float(probe_data.get("streams", [{}])[0].get("duration", 0))
+    
+    if duration <= 0:
+        logger.warning(f"Could not determine video duration: {input_path}")
+        return input_path
+    
+    # Analyze first N frames for black frames at start
+    start_black_frames = _count_black_frames_at_position(
+        input_path, "start", max_frames_to_trim, black_threshold, fps
+    )
+    
+    # Analyze last N frames for black frames at end  
+    end_black_frames = _count_black_frames_at_position(
+        input_path, "end", max_frames_to_trim, black_threshold, fps, duration
+    )
+    
+    logger.info(f"🎬 Black frame analysis: start={start_black_frames}, end={end_black_frames}")
+    
+    # Check if trimming is needed
+    if start_black_frames < min_frames_to_trim and end_black_frames < min_frames_to_trim:
+        logger.info(f"✅ No black frames to trim in: {os.path.basename(input_path)}")
+        return input_path
+    
+    # Calculate trim times
+    start_trim_time = start_black_frames / fps if start_black_frames >= min_frames_to_trim else 0
+    end_trim_time = end_black_frames / fps if end_black_frames >= min_frames_to_trim else 0
+    
+    # New duration after trimming
+    new_duration = duration - start_trim_time - end_trim_time
+    
+    if new_duration <= 0.1:
+        logger.warning(f"⚠️ Trimming would remove entire video, skipping: {input_path}")
+        return input_path
+    
+    logger.info(
+        f"✂️ Trimming black frames: {os.path.basename(input_path)} "
+        f"(start: {start_trim_time:.3f}s, end: {end_trim_time:.3f}s)"
+    )
+    
+    # Generate output path
+    temp_output = os.path.join("/tmp", f"{uuid.uuid4().hex}_trimmed.mp4")
+    
+    # Build FFmpeg command
+    cmd = [
+        "ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
+        "-ss", str(start_trim_time),
+        "-i", input_path,
+        "-t", str(new_duration),
+        "-c:v", "libx264", "-preset", "fast", "-crf", "18",
+        "-pix_fmt", "yuv420p",
+        "-c:a", "copy",
+        temp_output
+    ]
+    
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    
+    if result.returncode != 0:
+        logger.error(f"FFmpeg trim failed: {result.stderr}")
+        return input_path
+    
+    logger.info(f"✅ Trimmed video saved: {temp_output}")
+    
+    # Handle overwrite
+    if overwrite:
+        shutil.move(temp_output, input_path)
+        return input_path
+    
+    return temp_output
+
+
+def _count_black_frames_at_position(
+    video_path: str,
+    position: str,  # "start" or "end"
+    max_frames: int,
+    black_threshold: int,
+    fps: float,
+    duration: float = 0
+) -> int:
+    """
+    Count consecutive black frames at the start or end of a video.
+    
+    Args:
+        video_path: Path to video file
+        position: "start" or "end"
+        max_frames: Maximum frames to analyze
+        black_threshold: Y luminance threshold for black detection
+        fps: Video frame rate
+        duration: Video duration (required for "end" position)
+        
+    Returns:
+        Number of consecutive black frames at the specified position
+    """
+    # For start: analyze first max_frames frames
+    # For end: seek to near end and analyze last max_frames frames
+    if position == "end" and duration > 0:
+        seek_time = max(0, duration - (max_frames / fps) - 0.5)
+        ss_arg = ["-ss", str(seek_time)]
+    else:
+        ss_arg = []
+    
+    # Use showinfo filter to get frame luminance
+    cmd = [
+        "ffmpeg", "-hide_banner",
+        *ss_arg,
+        "-i", video_path,
+        "-vf", f"select='lte(n,{max_frames})',showinfo",
+        "-frames:v", str(max_frames + 5),
+        "-f", "null", "-"
+    ]
+    
+    result = subprocess.run(cmd, capture_output=True, text=True, timeout=30)
+    
+    if result.returncode != 0:
+        return 0
+    
+    # Parse showinfo output for mean values
+    # Format: mean:[Y U V] where Y is luminance
+    # A pure black frame has Y=16 in YUV (limited range)
+    frame_means = []
+    for line in result.stderr.split('\n'):
+        match = re.search(r'mean:\[(\d+)\s+\d+\s+\d+\]', line)
+        if match:
+            y_mean = int(match.group(1))
+            frame_means.append(y_mean)
+    
+    if not frame_means:
+        return 0
+    
+    # Count consecutive black frames
+    if position == "start":
+        # Count from beginning
+        black_count = 0
+        for y_mean in frame_means:
+            if y_mean <= black_threshold:
+                black_count += 1
+            else:
+                break
+        return black_count
+    else:
+        # Count from end (reverse)
+        black_count = 0
+        for y_mean in reversed(frame_means):
+            if y_mean <= black_threshold:
+                black_count += 1
+            else:
+                break
+        return black_count
+
+
 def ratio_1x1_to9x16(video_path, overwrite=False):
     """
     Convert a 1:1 video to 9:16 by adding blurred padding using FFmpeg.

src/video_renderer.py

@@ -1162,33 +1162,43 @@ class VideoRenderer:
                     temp_clip_path = os.path.abspath(str(self.temp_dir / f"clip_{video_idx+1:03d}.mp4"))
                     
                     # Determine filter
+                    # IMPORTANT: All clips must have identical properties to avoid black frames during concat
+                    # - setsar=1:1 ensures consistent sample aspect ratio
+                    # - format=yuv420p ensures consistent pixel format  
+                    # - fps=25 ensures consistent frame rate
                     if loop_short_videos and video_duration_src < 4:
+                        # Ping-pong loop (Forward-Reverse-Forward-Reverse) -> 4x duration
                         vf_filter = (
                             "[0:v]split=2[a][b];[b]reverse[br];[a][br]concat=n=2:v=1:a=0[loop1];"
                             "[loop1]split=2[c][d];[d]reverse[dr];[c][dr]concat=n=2:v=1:a=0[looped];"
-                            "[looped]trim=0:3,setpts=PTS-STARTPTS,"
-                            "scale=1080:1920:force_original_aspect_ratio=decrease,"
-                            "pad=1080:1920:(ow-iw)/2:(oh-ih)/2[out]"
+                            "[looped]setpts=PTS-STARTPTS,"
+                            "scale=1080:1920:force_original_aspect_ratio=increase,"
+                            "crop=1080:1920,setsar=1:1,format=yuv420p[out]"
                         )
                         use_filter_complex = True
+                        # Allow utilizing the full 4x duration if needed
+                        max_possible = video_duration_src * 4
+                        trim_duration = min(target_duration, max_possible)
                     elif video_duration_src < target_duration:
                         loop_count = int(target_duration / video_duration_src) + 1
-                        vf_filter = f"loop={loop_count}:size=999:start=0,scale=1080:1920:force_original_aspect_ratio=decrease,pad=1080:1920:(ow-iw)/2:(oh-ih)/2"
+                        vf_filter = f"loop={loop_count}:size=999:start=0,setpts=PTS-STARTPTS,scale=1080:1920:force_original_aspect_ratio=increase,crop=1080:1920,setsar=1:1,format=yuv420p"
                         use_filter_complex = False
+                        trim_duration = target_duration
                     else:
-                        vf_filter = "scale=1080:1920:force_original_aspect_ratio=decrease,pad=1080:1920:(ow-iw)/2:(oh-ih)/2"
+                        vf_filter = "setpts=PTS-STARTPTS,scale=1080:1920:force_original_aspect_ratio=increase,crop=1080:1920,setsar=1:1,format=yuv420p"
                         use_filter_complex = False
-                    
-                    trim_duration = min(target_duration, 3.0 if loop_short_videos and video_duration_src < 4 else video_duration_src)
+                        trim_duration = min(target_duration, video_duration_src)
                     
                     if use_filter_complex:
                         cmd = ["ffmpeg", "-y", "-i", video_path, "-filter_complex", vf_filter,
                                "-map", "[out]", "-t", str(trim_duration), "-c:v", "libx264",
-                               "-preset", "ultrafast", "-r", "25", "-pix_fmt", "yuv420p", "-an", temp_clip_path]
+                               "-preset", "ultrafast", "-r", "25", "-pix_fmt", "yuv420p",
+                               "-video_track_timescale", "12800", "-an", temp_clip_path]
                     else:
                         cmd = ["ffmpeg", "-y", "-i", video_path, "-t", str(trim_duration),
                                "-vf", vf_filter, "-c:v", "libx264", "-preset", "ultrafast",
-                               "-r", "25", "-pix_fmt", "yuv420p", "-an", temp_clip_path]
+                               "-r", "25", "-pix_fmt", "yuv420p", 
+                               "-video_track_timescale", "12800", "-an", temp_clip_path]
                     
                     result = subprocess.run(cmd, capture_output=True, text=True, timeout=60)
                     
@@ -1226,9 +1236,18 @@ class VideoRenderer:
             
             output_path = os.path.abspath(str(self.temp_dir / f"merged_{uuid.uuid4().hex[:8]}.mp4"))
             
-            concat_cmd = ["ffmpeg", "-y", "-f", "concat", "-safe", "0", "-i", concat_file_path,
-                          "-c:v", "libx264", "-preset", "fast", "-crf", "23", "-pix_fmt", "yuv420p",
-                          "-r", "25", "-t", str(music_duration), "-an", output_path]
+            # Use stream copy since all clips are already encoded with identical properties
+            # This avoids re-encoding artifacts and timing issues that cause black frames
+            concat_cmd = [
+                "ffmpeg", "-y", 
+                "-fflags", "+genpts",  # Generate fresh PTS for clean concatenation
+                "-f", "concat", "-safe", "0", "-i", concat_file_path,
+                "-c", "copy",  # Stream copy - no re-encoding
+                "-avoid_negative_ts", "make_zero",  # Fix timestamp issues at clip boundaries
+                "-t", str(music_duration), 
+                "-an", 
+                output_path
+            ]
             
             logger.info(f"🎬 Merging {len(temp_clips)} clips...")
             result = subprocess.run(concat_cmd, capture_output=True, text=True, timeout=120)
@@ -1241,6 +1260,7 @@ class VideoRenderer:
             return output_path
             
         finally:
+            # Clean up temp clips
             for clip_path in temp_clips:
                 try:
                     if os.path.exists(clip_path):

video_analysis/app.py

@@ -204,6 +204,7 @@ def sync_videos_from_drive_recursive(service, downloader, folder_id: str, downlo
             
             # STRICT ENFORCEMENT: Convert to 9:16 immediately (Sequential)
             try:
+                trim_black_frames(str(dest_path), overwrite=True)
                 resize_video(str(dest_path), overwrite=True)
             except Exception as e:
                 print(f"⚠️ Conversion failed for {file_name}: {e}")
@@ -275,6 +276,7 @@ def sync_videos_from_local_recursive(download_path: Path, source_folder: Path):
 
             # STRICT ENFORCEMENT: Convert to 9:16 immediately
             try:
+                trim_black_frames(str(dest_path), overwrite=True)
                 resize_video(str(dest_path), overwrite=True)
             except Exception as e:
                 print(f"⚠️ Conversion failed for {file_name}: {e}")
@@ -406,7 +408,7 @@ def get_uploaded_videos(sheet_id: str = None) -> set:
         print(f"Error getting uploaded videos: {e}")
         return set()
 
-from src.utils import resize_video
+from src.utils import resize_video, trim_black_frames
 from src.google_src.drive_utils import search_file_by_name, get_drive_service, extract_drive_file_id, upload_file_to_drive, update_file_content
 
 def upload_to_video_library(video_path: str, sheet_id: str = None, upload_folder_id: str = None) -> dict:
@@ -419,6 +421,7 @@ def upload_to_video_library(video_path: str, sheet_id: str = None, upload_folder
     # 0. Ensure Local is 9:16 (Strict Enforcement)
     try:
         # This overwrites the local file with 9:16 version if needed
+        trim_black_frames(video_path, overwrite=True)
         video_path = resize_video(video_path, overwrite=True)
     except Exception as e:
         return {"success": False, "uploaded": False, "message": f"Conversion failed: {str(e)}"}