python-ffmpeg

Python FFmpeg スキル

エンコード、フィルタリング、音声処理、メタデータの調査、ストリーミング、サムネイル、PyAV によるフレームアクセス、サブプロセス連携、本番環境でのトラブルシューティングなど、Python を使った FFmpeg の作業にこのスキルを使用します。

このスキルを使用する場面

ユーザーから、特にこのドメインでの実装方法の案内、デバッグ、アーキテクチャの選択、本番環境向けの堅牢化、またはパフォーマンスに影響する判断など、フロントマターのトリガーに含まれるタスクを依頼された場合に使用します。このオーケストレーターから始め、求められる詳細度に合ったリファレンスファイルを読み込みます。

基本的なワークフロー

1. まず連携レイヤーを選択します。読みやすいフィルターグラフには ffmpeg-python、CLI と完全に同等の操作には subprocess、フレーム単位のアクセスには PyAV、シンプルな編集には moviepy を使用します。
2. 処理の前に入力を調査し、コーデック、再生時間、解像度、FPS、音声ストリーム、メタデータを確認します。
3. 映像フィルターを適用する際は、音声を明示的に保持します。フィルタリングされた映像ストリームに音声は自動的に引き継がれません。
4. 互換性、圧縮率、デプロイ先のハードウェアに基づいて、出力コーデックとアクセラレーション方式を選択します。
5. 上書きとエラー処理の方法を一貫させます。ffmpeg-python では overwrite_output()、subprocess では -y を使用し、診断のために stderr も取得します。
6. 大容量のメディアでは、すべての stdout やフレームをメモリに読み込むのではなく、フレームをストリーミングするか、一時ファイルを使用します。

主な注意点

• 映像フィルターを使うと、音声ストリームを ffmpeg.output(...) に渡すか、明示的にコピーしない限り、音声が失われることがよくあります。
• stdout/stderr を読み出さなかったり、フレームの読み取りサイズが適切でなかったりすると、サブプロセスのパイプがデッドロックする可能性があります。
• Windows のパスは、手動で引用符を付けたコマンド文字列ではなく、Path(...).as_posix() または subprocess の引数リストとして渡す方法が最も安全です。
• CRF 値はコーデックによって異なります。H.265 の CRF 28 は、H.264 の CRF 23 とおおむね同等です。
• ハードウェアエンコーダーは、圧縮効率と引き換えに速度を向上させます。NVENC、QSV、AMF、VAAPI を選択する前に、利用可能かどうかを確認してください。

リファレンスマップ

• references/ffmpeg-complete-recipes.md - エンコード、ハードウェアアクセラレーション、音声／音声フィルター、映像フィルター、トリミング、連結、ストリーミング、入力の調査、サムネイル、PyAV、subprocess のパターン、一般的な変換、エラー、パフォーマンスのヒントを網羅した完全版のレシピガイドです。
• references/ffmpeg-advanced-patterns.md - このスキル向けに追加で整備された、FFmpeg の高度なパターンをまとめています。

回答の指針

• 互換性やパフォーマンス上の明確な理由がない限り、ユーザーが現在使用しているフレームワーク、ライブラリ、ツールの選択を維持してください。
• その場のタスクに直接使えるコードだけを提示してください。それ以外の場合は、関連するリファレンスの節を案内してください。
• 本番環境でのワークフローについて、トレードオフ、失敗の可能性、検証手順を明示してください。
• 小手先のマイクロ最適化よりも、利用しやすく、保守しやすく、測定可能な解決策を優先してください。