ffmpeg-pyav-integration

PyAV 集成指南

当 Python 需要直接访问 FFmpeg 库时，请使用 PyAV：容器、流、数据包、帧、编解码器、滤镜、定位、字幕和 NumPy 转换。此 SKILL 是一个精简的协调器；完整的 API 示例保存在 references/pyav-recipes-and-api.md 中。

何时使用 PyAV

以下场景适合使用 PyAV：

• 逐帧解码和编码视频／音频
• 精确定位和关键帧提取
• 访问 NumPy/Pillow/OpenCV 帧，无需为每一帧调用 shell 命令
• 容器检查、数据包级重封装、读取字幕
• 通过库级控制处理 RTSP／网络流

对于简单转码、要求与生产环境命令保持一致，或大量使用硬件加速的管线，请改用 FFmpeg CLI／子进程。

快速参考

任务	PyAV 模式	说明
打开媒体	av.open(path)	优先使用上下文管理器
解码视频	container.decode(video=0)	生成 VideoFrame
转为 NumPy	frame.to_ndarray(format='rgb24')	转为 BGR 以供 OpenCV 使用
从 NumPy 转换	av.VideoFrame.from_ndarray(arr, format='rgb24')	编码生成的帧
定位	container.seek(offset)	通常基于关键帧
编码	stream.encode(frame)，然后调用 container.mux(packet)	结束时刷新编码器
关闭	container.close()	在循环中至关重要

最简模式

import av

with av.open("input.mp4") as container:
    stream = container.streams.video[0]
    stream.thread_type = "AUTO"
    for frame in container.decode(stream):
        rgb = frame.to_ndarray(format="rgb24")
        break

import av

with av.open("input.mp4") as container:
    stream = container.streams.video[0]
    container.seek(int(10.0 * av.time_base), backward=True)
    for frame in container.decode(stream):
        if frame.time >= 10.0:
            image = frame.to_ndarray(format="rgb24")
            break

核心工作流

1. 除非明确需要自定义 FFmpeg 构建，否则请从 wheel 安装 av。
2. 使用新的 FFmpeg 8.x 功能前，请检查 PyAV 与 FFmpeg 库的兼容性。
3. 使用上下文管理器打开容器，或通过 try/finally 确保关闭。
4. 明确选择流；只解码所需内容。
5. 有意转换帧的像素／采样格式。
6. 编码时，请明确设置编解码器、尺寸、像素格式、速率和选项；并刷新编码器。
7. 在线程化应用中禁用详细日志，并优先使用文件路径而非 Python 文件对象。

主要注意事项

• PyAV 帧可能引用底层缓冲区；容器关闭后若仍要保留 NumPy 数组，请调用 .copy()。
• thread_type='AUTO' 可显著提高解码速度，但可能增加帧延迟。
• 与 CLI FFmpeg 相比，PyAV 对硬件加速的支持有限。
• 字幕转码支持有限；对于复杂的字幕工作流，请使用 FFmpeg CLI。

参考索引

• references/pyav-recipes-and-api.md - 完整保留的参考资料：安装、自定义 FFmpeg 构建、FFmpeg 8 兼容性、解码、NumPy 转换、编码、音频、滤镜、定位、重封装、字幕、RTSP、错误、内存、线程、性能、硬件注意事项和常见模式。

相关技能

• ffmpeg-python-integration-reference - 类型安全的 FFmpeg 参数映射
• ffmpeg-opencv-integration - OpenCV 管线和颜色转换
• ffmpeg-fundamentals-2025 - FFmpeg 核心操作和编解码器选择