ffmpeg-python-integration-reference

Python-FFmpeg 統合リファレンス

Python コードで FFmpeg コマンド、フィルター、ASS 字幕、または生フレームのパイプを構築しており、型、単位、色、ストリームマッピングに関する不具合のリスクがある場合に、このスキルを使用してください。この SKILL は簡潔なオーケストレーターであり、詳細な表や完全なコード例は references/python-ffmpeg-reference.md にあります。

使用する場面

• ffmpeg-python のストリームグラフとフィルター引数
• FFmpeg を呼び出す Python の subprocess
• drawtext、ASS/SSA、カラオケ、アニメーション付きキャプションのパラメータマッピング
• RGB/BGR/ASS の色変換に関する不具合
• 秒、センチ秒、ミリ秒の混同
• NumPy/OpenCV による生フレームのパイプ入出力
• コマンド実行前の範囲・型の検証

重要なルール

1. パラメータを渡す前に型を検証してください。 fontsize と crf は整数です。ビットレートは 5M や 192k などの単位を含む文字列で、FFmpeg の式は文字列です。
2. FFmpeg の式は Python で引用符で囲んでください。 Python 変数名に w や tw を使うのではなく、x="(w-tw)/2" のようにします。
3. 音声を明示的に処理してください。 ffmpeg-python では、出力に input_file.audio をマッピングしないと、通常、動画フィルターチェーンで音声が破棄されます。
4. 色のコンテキストを把握してください。 FFmpeg の drawtext の色は RGB または名前付き文字列、OpenCV の配列は BGR、ASS の色は &HAABBGGRR です。
5. 時間のコンテキストを把握してください。 FFmpeg のフィルターでは秒、ASS のカラオケタグではセンチ秒、ASS のアニメーションタグではミリ秒を使用します。

クイックリファレンス

FFmpeg / ASS パラメータ	Python の型	形式 / 範囲	よくある失敗
-crf	int または str	H.264/H.265 0-51	18.5 を渡す
-b:v、-b:a	str	5M、1000k、192k	単位のない整数を渡す
fontsize	int	実用範囲 12-200	'24' を渡す
fontcolor	str	white、#FFFFFF、0xFFFFFF	RGB のタプルやリストを渡す
ASS の色	str	&HAABBGGRR	RGB のバイト順を使用する
x、y、alpha、enable	式の場合は str	'(w-tw)/2、between(t,1,5)	式を引用符で囲まない

基本的なワークフロー

1. 入力またはメタデータソースを調べ、幅、高さ、fps、長さ、利用可能なストリームを確認します。
2. 統合レイヤーを選択します。コマンドグラフには ffmpeg-python、完全な CLI 互換性とパイプには subprocess、フレーム単位のライブラリアクセスには PyAV を使用します。
3. Python との境界で色と時間の単位を正規化します。
4. コマンドを組み立てる前に、パラメータと範囲を検証します。
5. 音声・字幕ストリームを意図的にマッピングします。
6. まず短いサンプルで実行し、原因の特定に役立つ FFmpeg エラーを得るために stderr を取得します。

リファレンス一覧

• references/python-ffmpeg-reference.md - 色変換関数、ASS スタイル構造、カラオケ／アニメーション用ヘルパー、drawtext パラメータ表、ffmpeg-python の例、subprocess のパイプパターン、注意点、検証ヘルパー、完全な動作例を含む、完全版のリファレンスです。

関連スキル

• ffmpeg-opencv-integration - OpenCV/NumPy のフレームパイプラインと BGR/RGB の受け渡し
• ffmpeg-pyav-integration - PyAV のフレーム単位 API パターン
• ffmpeg-captions-subtitles - 字幕の抽出、映像への焼き込み、スタイル設定
• ffmpeg-animation-timing-reference - 時間単位、読みやすさ、イージング、同期