docs/archive/ffmpeg_clip_methods.md

FFmpeg Clip Generation Methods

This document describes the different FFmpeg methods available for generating video clips from detected plays.

Benchmark Summary

Tested on 20 plays (~3.8 minutes of video) from OSU vs Tennessee 12.21.24:

Method	Time	Speedup	File Size	Accuracy
Parallel Stream Copy	0.8s	77x	132 MB	Keyframe-aligned (~1s variance)
Ultrafast Preset	15.2s	4x	371 MB	Frame-accurate
Baseline (Re-encode)	63.0s	1x	161 MB	Frame-accurate

Available Methods

1. stream_copy (Default)

Command-line: --clip-method stream_copy or omit flag

Uses FFmpeg's stream copy mode (-c copy) to extract clips without re-encoding, then concatenates them. Clips are extracted in parallel for maximum speed.

Pros:

• Extremely fast (77x faster than re-encoding)
• Smallest file size (preserves original encoding)
• No quality loss

Cons:

• Cuts must align to keyframes (typically every 2-5 seconds in broadcast video)
• Each clip may have ~1-2 extra seconds of footage
• Total output may be ~10% longer than expected

Best for: Quick turnaround, highlight reels where extra footage is acceptable

2. ultrafast

Command-line: --clip-method ultrafast

Re-encodes video using libx264 with the ultrafast preset. This is the fastest encoding option while maintaining frame-accurate cuts.

Pros:

• Frame-accurate cuts (exact start/end times)
• 4x faster than baseline encoding
• Good balance of speed and accuracy

Cons:

• Larger file size (2.3x baseline due to less compression)
• Still slower than stream copy

Best for: When frame-accurate cuts are important but speed is still a priority

3. reencode

Command-line: --clip-method reencode

Re-encodes video using libx264 with the fast preset and CRF 23. This is the original method used in main.py.

Pros:

• Frame-accurate cuts
• Best compression ratio (smallest re-encoded file)
• Highest quality per file size

Cons:

• Slowest method
• CPU-intensive

Best for: Final production output where file size and quality matter most

Technical Details

Keyframe Alignment (Stream Copy)

Video files use keyframes (I-frames) as reference points. When using stream copy:

• FFmpeg can only cut cleanly at keyframe boundaries
• Broadcast video typically has keyframes every 2-5 seconds
• The --padding already adds 2 seconds before/after each play, so keyframe variance is usually absorbed

Parallel Processing

The stream_copy method uses Python's concurrent.futures.ThreadPoolExecutor with 4 workers to extract clips simultaneously, providing additional speedup beyond just avoiding re-encoding.

Benchmark Details

Full benchmark results are saved in:

• output/ffmpeg_benchmark/benchmark_results.json

Individual method outputs for comparison:

• output/ffmpeg_benchmark/1_baseline_reencode/output.mp4
• output/ffmpeg_benchmark/2_stream_copy/output.mp4
• output/ffmpeg_benchmark/3_parallel_stream_copy/output.mp4
• output/ffmpeg_benchmark/5_ultrafast/output.mp4

Usage Examples

# Default (fastest - parallel stream copy)
python main.py --video "full_videos/game.mp4"

# Explicit stream copy
python main.py --video "full_videos/game.mp4" --clip-method stream_copy

# Frame-accurate with faster encoding
python main.py --video "full_videos/game.mp4" --clip-method ultrafast

# Original method (best compression)
python main.py --video "full_videos/game.mp4" --clip-method reencode