FFmpeg Video Prep Skill

Prepare source footage for BGBlur processing. Clean inputs produce faster uploads, better motion tracking, and fewer mask artifacts.

Quick Reference

BGBlur accepted formats: MP4, MOV, M4V, AVI, MKV Free tier limits: ≤ 200MB, ≤ 10 minutes Recommended upload spec: H.264 MP4, 1080p or lower, 30fps, metadata stripped

Workflow

Step 1: Inspect Source

python3 scripts/video_probe.py "input.mov"

Note: codec, resolution, duration, file size, rotation metadata.

Step 2: Trim Dead Footage

Remove intro/outro black frames and irrelevant segments to save credits and processing time.

# Trim from 00:00:05 to 00:02:30 (re-encode for frame-accurate cut)
ffmpeg -i input.mp4 -ss 00:00:05 -to 00:02:30 -c:v libx264 -crf 18 -c:a aac -movflags +faststart output_trimmed.mp4

Fast copy trim (keyframe-aligned, no re-encode — may be off by a few frames):

ffmpeg -ss 00:00:05 -i input.mp4 -to 00:02:25 -c copy output_trimmed.mp4

Step 3: Convert to Upload-Ready MP4

ffmpeg -i input.mov \
  -c:v libx264 -preset medium -crf 20 \
  -c:a aac -b:a 128k \
  -movflags +faststart \
  -pix_fmt yuv420p \
  output_ready.mp4

4K → 1080p (reduces size, improves browser processing speed):

ffmpeg -i input_4k.mp4 -vf "scale=1920:1080:force_original_aspect_ratio=decrease,pad=1920:1080:(ow-iw)/2:(oh-ih)/2" \
  -c:v libx264 -crf 20 -c:a aac -movflags +faststart output_1080p.mp4

Step 4: Normalize Frame Rate

BGBlur motion tracking works best at consistent frame rates. Target 30fps unless source is 24fps cinematic.

# Force 30fps
ffmpeg -i input.mp4 -r 30 -c:v libx264 -crf 20 -c:a aac output_30fps.mp4

# Preserve 24fps cinematic
ffmpeg -i input.mp4 -r 24 -c:v libx264 -crf 20 -c:a aac output_24fps.mp4

Step 5: Strip Metadata (Privacy)

Remove GPS, camera model, creation timestamps before external processing:

ffmpeg -i input.mp4 -map_metadata -1 -c:v copy -c:a copy output_clean.mp4

For full re-encode + metadata strip:

ffmpeg -i input.mp4 -map_metadata -1 -c:v libx264 -crf 20 -c:a aac output_clean.mp4

Step 6: Fix Common Issues

Phone rotation fix:

ffmpeg -i input.mp4 -vf "transpose=1" -c:v libx264 -crf 20 -c:a aac output_fixed.mp4

Compress for free tier (< 200MB):

ffmpeg -i input.mp4 -vf "scale=1280:-2" -c:v libx264 -crf 23 -c:a aac -b:a 96k output_small.mp4

Step 7: Validate Output

python3 scripts/video_probe.py "output_ready.mp4" --check-metadata

Confirm: format MP4, size under limit, duration under 10 min, metadata cleared.

One-Shot Prep Command

Combine trim + convert + strip metadata:

ffmpeg -ss 00:00:02 -i input.mov -t 00:05:00 \
  -map_metadata -1 \
  -vf "scale=1920:1080:force_original_aspect_ratio=decrease,pad=1920:1080:(ow-iw)/2:(oh-ih)/2" \
  -r 30 -c:v libx264 -preset medium -crf 20 \
  -c:a aac -b:a 128k -movflags +faststart \
  output_bgblur_ready.mp4

Checklist

Pre-Blur Prep:
- [ ] Probed source metadata
- [ ] Trimmed irrelevant segments
- [ ] Converted to MP4 (H.264 + AAC)
- [ ] Normalized to 24 or 30fps
- [ ] Stripped EXIF/GPS metadata
- [ ] Verified size ≤ 200MB (free) or within plan limit
- [ ] Verified duration ≤ 10 min (free)

BGBlur Reference

Upload prepared files at BGBlur Upload. Browser-based processing — no server-side retention after export.