ffmpeg-opencv-integration

FFmpeg + OpenCV 集成指南

当使用 FFmpeg 处理视频输入/输出、使用 OpenCV 处理图像时，请使用此技能。此 SKILL 是一个精简的编排器；完整的管道模式、库示例和 Modal 配方保存在 references/opencv-pipelines-and-libraries.md 中。

适用场景

• 使用 FFmpeg 解码，并使用 OpenCV 处理帧
• 使用 FFmpeg 编码由 OpenCV 生成或处理的帧
• 比较 cv2.VideoCapture、subprocess 管道、PyAV、ffmpegcv、VidGear 和 Decord
• 修复 RGB/BGR 颜色错误或 (height, width) 维度顺序错误
• 替换经过处理的视频帧时保留音频
• 围绕 CPU OpenCV 处理构建 GPU 辅助的视频输入/输出

库的选择

需求	最佳选项	原因
简单的本地文件	cv2.VideoCapture	内置且简单
完整的 FFmpeg 格式/协议支持	subprocess 管道	精确的 CLI 行为
GPU 视频输入/输出	ffmpegcv	提供类似 OpenCV 的 API，支持 NVDEC/NVENC
网络/RTSP 流	VidGear	提供多线程捕获和流处理辅助功能
ML 批量加载	Decord	快速随机访问/批量读取帧
帧级 libav 控制	PyAV	直接访问 FFmpeg 库

关键注意事项

1. OpenCV 使用 BGR。 FFmpeg/PyAV/PIL/Decord 通常生成 RGB。请显式转换。
2. NumPy 维度为 (height, width, channels)。 像素访问方式是 img[y, x]，而不是 img[x, y]。
3. 视频滤镜可能会丢弃音频。 请有意保留原始音频或重新封装。
4. 释放资源。 始终关闭 VideoCapture、管道、写入器和 PyAV 容器。
5. Rawvideo 管道要求帧大小完全匹配。 width * height * channels 必须与 -pix_fmt 相符。

最简管道模式

使用 BGR 帧将 FFmpeg 输出传给 OpenCV：

cmd = [
    "ffmpeg", "-i", input_path,
    "-f", "rawvideo", "-pix_fmt", "bgr24", "-"
]

使用 BGR 帧将 OpenCV 输出传给 FFmpeg：

cmd = [
    "ffmpeg", "-y",
    "-f", "rawvideo", "-vcodec", "rawvideo",
    "-s", f"{width}x{height}", "-pix_fmt", "bgr24",
    "-r", str(fps), "-i", "-",
    "-c:v", "libx264", "-preset", "fast", "-crf", "23",
    "-pix_fmt", "yuv420p", output_path
]

核心工作流

1. 检查输入尺寸、fps、时长和音频流。
2. 根据选择表挑选输入/输出库。
3. 明确指定边界处的像素格式（OpenCV 管道使用 bgr24；最终 H.264 输出使用 yuv420p）。
4. 通过生成器/批次处理帧；除非视频较小，否则避免加载完整视频。
5. 显式保留或重新编码音频。
6. 验证输出时长、fps、分辨率、编解码器和音视频同步。

参考索引

• references/opencv-pipelines-and-libraries.md - 完整保留的参考资料：颜色/维度注意事项、清理模式、FFmpeg 到 OpenCV 和 OpenCV 到 FFmpeg 的管道、双向管道、ffmpegcv、VidGear、Decord、PyAV、Modal.com 示例、GPU 管道、速查表和来源。

相关技能

• ffmpeg-python-integration-reference - 类型安全参数、颜色、时间单位
• ffmpeg-pyav-integration - PyAV API 详情
• ffmpeg-hardware-acceleration - GPU 解码/编码和滤镜管道