python-video-pipeline

Python Video Pipeline Skill

デコード、OpenCV／PyAV／フレーム処理、FFmpeg エンコード、サーバーレス実行、GPU アクセラレーション、HLS 出力、大容量ファイルのオーケストレーションを組み合わせた、エンドツーエンドの Python 動画パイプラインにこのスキルを使用します。

このスキルを使用するタイミング

ユーザーがフロントマターのトリガーに該当するタスクを依頼したときに使用します。特に、この分野における実装のガイダンス、デバッグ、アーキテクチャの選択、本番環境向けの堅牢化、パフォーマンス重視の判断に適しています。このオーケストレーターを起点にしてから、求められる詳細度に合ったリファレンスファイルを読み込みます。

基本的なワークフロー

1. まず、パイプラインのアーキテクチャを選択します。シンプルな OpenCV、FFmpeg と OpenCV のパイプ、PyAV によるフレーム処理、ffmpegcv／Decord／VidGear、またはスケーラブルな実行のための Modal から選びます。
2. ライブラリ間の境界ごとに、色と形状の規約を統一します。OpenCV の BGR／HWC、PIL の RGB、PyAV の RGB、FFmpeg のピクセル形式、ML の CHW テンソルを考慮します。
3. 処理前にメディアのメタデータを調べ、FPS、解像度、フレーム数、音声の有無、コーデックに関する前提を明確にします。
4. 長い動画はストリーム、バッチ、またはチャンクとして処理します。入力が小さく、サイズが限定されている場合を除き、すべてのフレームを蓄積しないでください。
5. フレーム単位の処理後は、音声を再多重化するか保持します。OpenCV のみのワークフローでは、通常、音声のない出力が生成されるためです。
6. Modal または GPU インフラストラクチャでは、バッチサイズ、ピクセル形式、デコード／エンコードのアクセラレーション、ボリュームの使用方法、タイムアウトの境界を調整します。

主な注意点

• BGR／RGB の不一致は、OpenCV、FFmpeg、PyAV、PIL、ML フレームワーク間で色を意図せず誤らせます。
• NumPy／OpenCV では通常、フレームの次元は HWC ですが、ディープラーニングフレームワークでは CHW が必要な場合があります。
• OpenCV の VideoWriter 出力では、元の音声が保持されないことがあります。FFmpeg で音声を再多重化する手順を明示的に計画してください。
• 並列フレーム処理では、再構成の前にフレームの順序を元に戻す必要があります。
• チャンク処理では、タイムスタンプと連結の処理が必要です。通常、音声はチャンクを再結合した後に処理します。

リファレンスマップ

• references/video-pipeline-complete-patterns.md - ライブラリの選定、統合時の注意点、FFmpeg／OpenCV のパイプ、ffmpegcv、VidGear、Decord、Modal の GPU ワークフロー、チャンク処理、トランスコード、HLS、エンドツーエンドのワークフロー、最適化のヒントを網羅した、元のパイプラインガイド全体です。
• references/modal-video-patterns.md - このスキルで管理している、Modal 固有の動画パターンの追加資料です。

応答ガイダンス

• 互換性またはパフォーマンス上の明確な理由がない限り、ユーザーが現在使用しているフレームワーク、ライブラリ、ツールの選択を維持します。
• コピーしてそのまま使えるコードは、依頼されたタスクに必要なものだけを提示します。それ以外の場合は、関連するリファレンスのセクションを案内します。
• 本番環境のワークフローでは、トレードオフ、障害モード、検証手順を明示します。
• 気の利いたマイクロ最適化よりも、利用しやすく、保守しやすく、測定可能なソリューションを優先します。