ffmpeg-opencv-integration

FFmpeg + OpenCV 統合ガイド

FFmpeg で動画の入出力を行い、OpenCV で画像処理を行う場合にこのスキルを使用します。この SKILL は最小限のオーケストレーターです。パイプの完全なパターン、ライブラリの使用例、Modal のレシピは references/opencv-pipelines-and-libraries.md に保存されています。

使用する場面

• FFmpeg でデコードし、OpenCV でフレームを処理する
• OpenCV で生成・処理したフレームを FFmpeg でエンコードする
• cv2.VideoCapture、サブプロセスパイプ、PyAV、ffmpegcv、VidGear、Decord を比較する
• RGB/BGR の色の不具合や (height, width) の次元順序の不具合を修正する
• 処理済みの動画フレームを置き換えながら音声を保持する
• CPU での OpenCV 処理を中心に、GPU 支援の動画入出力を構築する

ライブラリの選択

必要な用途	最適な選択肢	理由
シンプルなローカルファイル	cv2.VideoCapture	組み込みでシンプルです
FFmpeg のフォーマット／プロトコルを全面的にサポート	サブプロセスパイプ	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、解像度、コーデック、A/V 同期を確認します。

リファレンス一覧

• 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 デコード／エンコードとフィルターパイプライン