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

```bash
# 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
```