ffmpeg-pipeline は何をしますか？
接着剤のようなスキル。生成（または提供）された静止画をナレーション付きのMP4に変換したり、エージェントが繰り返し直面する平凡なメディア処理ジョブを実行します。
ffmpeg + ffprobe が必要です。プロンプトモードには anon-image が、--narration には anon-audio が必要です。これらは兄弟スキルとして自動検出され、--images / --audio を指定した場合はどちらもオプションです。
コマンド
| コマンド | 機能 |
|---|---|
video | 静止画（生成または--imagesで指定）→ zoompanモーション＋クロスフェード付きMP4、オプションでナレーションとBGM |
slideshow | 既存画像 → MP4 |
mux | 動画に音声トラックを追加、ループ/パディングで長さを調整 |
frames | N秒ごとに静止フレームを抽出 |
sheet | コンタクトシート（タイムスタンプ付きで均等にN枚のフレーム） |
gif | 任意の区間からクロップ済みパレット最適化GIF |
normalize | 音声を−16 LUFSにラウドネス正規化 |
speed | ピッチを変えずに音声速度を変更（連鎖atempo） |
info | ffprobeの一行サマリー |
probe | 依存関係チェック |
クイックスタート
# すべてを一度に：3枚の生成ショット、各4秒、ナレーション付き
vidkit.py video "夕暮れの玄武岩の崖にある灯台、映画的" -o story.mp4 \
--shots 3 --seconds 4 --ratio 16:9 \
--narration "冷たい海岸のどこかで、灯台がその見張りを続けている。" \
--voice en-GB-RyanNeural
# 既存の画像を再利用
vidkit.py video --images shots/ -o out.mp4 --seconds 3 --music bed.mp3
# メディア手術
vidkit.py mux clip.mp4 voiceover.mp3 -o final.mp4
vidkit.py sheet final.mp4 -o preview.jpg --cols 4 --count 8
vidkit.py gif final.mp4 -o teaser.gif --start 1 --dur 2.5 --width 480
vidkit.py normalize voiceover.mp3 -o clean.mp3
vidkit.py info final.mp4
時間計算（出力を予測するため）
N枚のショット、各S秒、クロスフェード0.8秒の場合：
duration = N*S - (N-1)*0.8
3×4秒 → 10.4秒。ナレーションが画像よりも長い場合、動画はループしてカバーします（-stream_loop）。短い場合、音声は無音でパディングされ、末尾が欠けることはありません。両方のケースを自動処理するため、-shortest を自分で追加しないでください。
判断ルール
- アスペクト比：YouTube/Webには
16:9、Shorts/Reels/TikTokには9:16、フィードやサムネイルには1:1。すべてスケール・トゥ・カバー後にクロップされるため、どんな形状のソース画像でもレターボックスなしで表示されます。 - ショットあたりの秒数：静止画は3～4秒が適切。6秒を超えると静的な画像が死んでいるように感じられます。実行時間を長くしたい場合は秒数ではなくショット数を増やしてください。
- BGM：
--musicを指定すると、音声の12%の音量でミックスされます。2つの大きな音源をミックスしないでください。まず正規化してください。 - GIF：幅は480以下、長さは3秒以下に抑えないと、ファイルがチャットの制限を超えます。
障害モード
| 症状 | 原因 | 解決策 |
|---|---|---|
missing dependency: ffmpeg | 未インストール | apt install ffmpeg（または brew install ffmpeg） |
ffmpeg failed: … Invalid argument（zoompan時） | ソース次元が奇数 | このフィルターはすでに W*2 にスケールします。編集した場合は偶数にしてください |
| 出力が無音 | ナレーションファイルが存在しない/空 | パスを確認。--narration はテキストか音声ファイルパスの両方を受け付けます |
| 出力が予想より大幅に短い | 音声が動画より短く、-shortest が追加された | 削除。vidkit.py はパディングします |
contact sheet needs Pillow | Pillowがない | pip install pillow、または frames と独自のシートを使用 |
エージェント向け注意事項
- ユーザーが特別に要求しない限り、720pでレンダリングします。4倍高速で、ラップトップの画面では誰も違いがわかりません。
- 最終成果物に対して常に
infoを実行し、実際の長さ、解像度、サイズをユーザーに報告してください。これにより、サイレント障害を検出できます。 - MP4のパスを提供してください。埋め込まないでください。ファイルが成果物です。