ffmpeg-pyav-integration

PyAV 統合ガイド

Python から FFmpeg ライブラリに直接アクセスする必要がある場合は、コンテナ、ストリーム、パケット、フレーム、コーデック、フィルター、シーク、字幕、NumPy 変換に PyAV を使用します。この SKILL は簡潔なオーケストレーターです。完全な API の例は references/pyav-recipes-and-api.md にそのまま保存されています。

PyAV を使用する場面

以下の場合に PyAV を使用します。

• フレーム単位の動画／音声のデコードとエンコード
• 正確なシークとキーフレームの抽出
• フレームごとにシェルコマンドを実行せずに行う NumPy／Pillow／OpenCV フレームへのアクセス
• コンテナの調査、パケット単位のリマックス、字幕の読み取り
• ライブラリレベルで制御する RTSP／ネットワークストリームの処理

単純なトランスコード、本番環境のコマンドとの同等性、または負荷の高いハードウェアアクセラレーションパイプラインには、代わりに FFmpeg CLI／サブプロセスを使用します。

クイックリファレンス

タスク	PyAV のパターン	備考
メディアを開く	av.open(path)	コンテキストマネージャーを推奨
動画をデコード	container.decode(video=0)	VideoFrame を返します
NumPy に変換	frame.to_ndarray(format='rgb24')	OpenCV 用に BGR に変換
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 ビルドが明確に必要な場合を除き、ホイールから av をインストールします。
2. 新しい FFmpeg 8.x の機能に依存する前に、PyAV と FFmpeg ライブラリの互換性を確認します。
3. コンテナはコンテキストマネージャーで開くか、try/finally で確実に閉じます。
4. ストリームを明示的に選択し、必要なものだけをデコードします。
5. フレームのピクセル形式／サンプル形式を意図的に変換します。
6. エンコードでは、コーデック、寸法、ピクセル形式、レート、オプションを明示的に設定し、エンコーダーをフラッシュします。
7. スレッド化されたアプリケーションでは詳細ログを無効にし、Python のファイルオブジェクトよりファイルパスを優先します。

主な注意点

• PyAV のフレームは内部バッファーを参照している場合があります。コンテナを閉じた後も保持する NumPy 配列には .copy() を呼び出してください。
• thread_type='AUTO' によってデコード速度が大幅に向上する場合がありますが、フレーム遅延が増える可能性があります。
• PyAV のハードウェアアクセラレーションは、CLI FFmpeg と比べて制限があります。
• 字幕のトランスコード対応には制限があります。複雑な字幕ワークフローには 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 の基本操作とコーデックの選択