ffmpeg-opencv-integration

## Quick Reference

| Task | Best Library | Why |
|------|--------------|-----|
| Simple video read | OpenCV `cv2.VideoCapture` | Built-in, easy API |
| GPU video I/O | ffmpegcv | NVDEC/NVENC, OpenCV-compatible API |
| Multi-threaded streaming | VidGear | RTSP/RTMP, camera capture |
| ML batch loading | Decord | 2x faster than OpenCV, batch GPU decode |
| Frame-level precision | PyAV | Direct libav access, precise seeking |
| Complex filter graphs | ffmpeg-python subprocess | Full FFmpeg power |

| Color Format | Library | Conversion |
|--------------|---------|------------|
| BGR | OpenCV (cv2) | `cv2.cvtColor(img, cv2.COLOR_BGR2RGB)` |
| RGB | FFmpeg, PIL, PyAV | `cv2.cvtColor(img, cv2.COLOR_RGB2BGR)` |
| YUV | FFmpeg internal | Convert to RGB/BGR for processing |

## When to Use This Skill

Use for **FFmpeg + OpenCV combined workflows**:
- Reading video with FFmpeg, processing frames with OpenCV
- Piping frames between FFmpeg and OpenCV processes
- GPU-accelerated video I/O with OpenCV processing
- Fixing color format mismatches (BGR vs RGB)
- Memory-efficient processing of large videos
- Parallel frame processing on Modal.com

---

# FFmpeg + OpenCV Integration Guide

Complete guide to combining FFmpeg's video I/O power with OpenCV's image processing capabilities.

## Critical Gotchas (Must Know!)

### 1. Color Format Mismatch (BGR vs RGB)

**The #1 source of bugs in FFmpeg + OpenCV pipelines.**

```python
import cv2
import numpy as np

# OpenCV uses BGR by default
img_bgr = cv2.imread("image.jpg")  # BGR format!

# FFmpeg outputs RGB by default (in most configs)
# PyAV outputs RGB
# PIL/Pillow uses RGB

# WRONG: Using FFmpeg RGB output directly with OpenCV
# Colors will be swapped (red becomes blue)

# CORRECT: Always convert explicitly
def bgr_to_rgb(frame: np.ndarray) -> np.ndarray:
    """Convert OpenCV BGR to RGB for FFmpeg/PIL/ML."""
    return cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)

def rgb_to_bgr(frame: np.ndarray) -> np.ndarray:
    """Convert RGB (FFmp