ffmpeg-pyav-integration

# PyAV Integration Guide (2025-2026)

Complete reference for PyAV - Pythonic bindings for FFmpeg's libraries.

## Quick Reference

| Task | PyAV Method | Notes |
|------|-------------|-------|
| Open video | `av.open('video.mp4')` | Returns Container |
| Decode frames | `container.decode(video=0)` | Yields VideoFrame |
| Frame to NumPy | `frame.to_ndarray(format='rgb24')` | RGB by default |
| NumPy to Frame | `av.VideoFrame.from_ndarray(arr, format='rgb24')` | For encoding |
| Seek | `container.seek(offset)` | Keyframe-based |
| Encode | `stream.encode(frame)` | Returns packets |
| Close | `container.close()` | ALWAYS do this |

| Version | FFmpeg Requirement | Python Requirement |
|---------|-------------------|-------------------|
| PyAV 16.1.0 (Latest) | FFmpeg 7.0+ | Python 3.10+ |
| PyAV 14.x | FFmpeg 7.0+ | Python 3.9+ |
| PyAV 12.x | FFmpeg 5.0+ | Python 3.8+ |
| PyAV 8.x-10.x | FFmpeg 4.0+ | Python 3.7+ |

---

## What is PyAV?

PyAV provides **Pythonic bindings for FFmpeg's libraries** (libavcodec, libavformat, libavfilter, etc.), offering direct access to:

- **Containers**: Media file handling (MP4, MKV, WebM, etc.)
- **Streams**: Audio, video, and subtitle tracks
- **Packets**: Compressed data units
- **Frames**: Decoded video/audio data
- **Codecs**: Encoding/decoding capabilities
- **Filters**: FFmpeg filter graph access

**Key Features:**
- Direct NumPy/Pillow integration for frame data
- Frame-level precision for seeking and manipulation
- Full codec and filter access
- Lower-level control than ffmpeg-python subprocess

**When to Use PyAV vs FFmpeg CLI:**
- Use **PyAV** when you need programmatic frame-level access
- Use **FFmpeg CLI** for simple transcoding tasks
- PyAV adds complexity - only use when CLI cannot solve your problem

---

## Installation

### Quick Install (Recommended)

Binary wheels include FFmpeg libraries - no separate FFmpeg installation needed:

```bash
pip install av
```

Or with Conda:

```bash
conda install av -c conda-forge