ffmpegパイプライン
ヘルパースクリプトはこのファイルの隣の scripts/ にあります。以下のコマンドで実行します: python <skill_dir>/scripts/<name>.py
probe.py IN...— ファイルごとの1行サマリー（サイズ、fps、回転、HDR、長さ、音声）export.py IN OUT --preset instagram|tiktok|shorts|youtube|master|preview— 適切な設定で最終エンコードframes.py IN OUTDIR --times 0.5,3,7.2または--every 1— チェック用フレームを抽出
1. まずはプローブと補正
スマートフォン映像の落とし穴:
- 回転: iPhoneは横長ピクセルと回転フラグを保存。ffmpegはデコード時に自動回転（
-noautorotateで無効化）。OpenCVVideoCaptureは自動回転 しない 場合がある —frame.shapeを確認し、自分で回転させること。 - VFR（可変フレームレート）: スマートフォンは可変フレームレートで録画。抽出時にCFRに変換:
-vf fps=30（または出力に-r 30）でフレーム計算を正確にする。 - HDR:
color_transfer=arib-std-b67（HLG）またはsmpte2084（PQ）。そのままではSDRで見ると色あせて見える。トーンマップを適用:
# HDR（HLGまたはPQ）→ SDR Rec.709、CPU zscaleパス
-vf "zscale=t=linear:npl=100,format=gbrpf32le,zscale=p=bt709,tonemap=tonemap=hable:desat=0,zscale=t=bt709:m=bt709:r=tv,format=yuv420p"
hable = フィルム調; mobius は彩度をより保持。zscaleがない場合は libplacebo を使用（-vf libplacebo=tonemapping=bt.2390:colorspace=bt709:color_primaries=bt709:color_trc=bt709）。
- Apple Log / カメラログ: 最初にメーカーのLog→Rec.709 LUTを適用（
lut3d=AppleLog_to_Rec709.cube）、その後グレーディング。 - 10ビットソース: 中間工程では10ビットを維持（
-pix_fmt yuv422p10leProRes またはyuv420p10lex265）。ソーシャル向け最終エクスポート時のみ8ビットyuv420pに変換。
2. ビルドスクリプトのアーキテクチャ
sources/ （決して変更しない）
edit/
build.py # sources + データファイルからすべてを再生成
edl.json # [{src, in, out, speed, grade, transition}]
segments/ # EDLエントリごとにグレーディング・補正されたファイル（ほぼロスレス）
overlays/ # PNG / PNGシーケンス / ProRes 4444 / WebM アルファ
preview.mp4, final.mp4
ルール:
- セグメントごとに抽出：すべてのクリップ単位の作業（トリム、速度、スケール/クロップ、グレーディング、fps）を1パスで行い、中間ファイルを
-crf 10（x264）またはProRes 422 HQで出力。 - 結合：トランジション不要の場合はconcatデマルチプレクサと
-c copyを使用（すべてのセグメントでコーデック、解像度、fps、pix_fmt、タイムベースが同一である必要あり）。 - オーバーレイとテキスト：結合後の動画に1パスで適用し、配信仕様に合わせて1回エンコード。
- 音声：別途ビルド（音楽+効果音+台詞→1つのWAV）、最終パスで多重化。
正確なトリム
# 再エンコード時、-ss を -i の前に置くと高速かつフレーム正確（ffmpeg >= 2.1）
ffmpeg -ss 12.40 -i IN.mov -t 2.333 -vf "fps=30,scale=1080:1920:force_original_aspect_ratio=increase,crop=1080:1920" \
-c:v libx264 -crf 10 -preset medium -pix_fmt yuv420p -an seg_003.mp4
フレーム正確なトリムには -c copy を使用しないこと（キーフレームにスナップするため）。
16:9から9:16への変換
- クロップ（カバー）:
scale=-2:1920,crop=1080:1920:(iw-1080)*X:0（Xは0〜1で被写体の位置を指定、動く場合はトラッキング） - ぼかし背景（コンテイン）:
split[a][b];[a]scale=1080:1920:force_original_aspect_ratio=increase,crop=1080:1920,boxblur=40:2[bg];[b]scale=1080:-2[fg];[bg][fg]overlay=(W-w)/2:(H-h)/2
結合
# list.txt: file 'segments/seg_001.mp4' （1行に1ファイル）
ffmpeg -f concat -safe 0 -i list.txt -c copy joined.mp4
xfadeトランジション
ffmpeg -i a.mp4 -i b.mp4 -filter_complex \
"[0:v][1:v]xfade=transition=fade:duration=0.5:offset=4.5,format=yuv420p[v]; \
[0:a][1:a]acrossfade=d=0.5[a]" -map "[v]" -map "[a]" out.mp4
offset = 最初のクリップの長さ − トランジションの長さ。タイプ: fade、fadeblack、fadewhite、wipeleft、slideup、smoothleft、circleopen、radial、zoomin、hblur、pixelize、dissolve… 複数のクリップではオフセットを累積的に計算（各xfadeはその長さだけ合計を短縮）。
オーバーレイ
# 動画全体に静的なPNG（全画面、透明）— -loop 不要
[0:v][1:v]overlay=0:0:format=auto
# 時間制限
overlay=0:0:enable='between(t,2.0,5.5)'
# 出力のT秒から開始するアニメーションオーバーレイクリップ
[1:v]setpts=PTS-STARTPTS+T/TB[ov];[0:v][ov]overlay=0:0:eof_action=pass
アルファオーバーレイ: PNGシーケンス（-framerate 30 -i ov/%04d.png）、ProRes 4444（-c:v prores_ks -profile:v 4444 -pix_fmt yuva444p10le）、またはVP9 WebM（-c:v libvpx-vp9 -pix_fmt yuva420p）。
長時間の動画で4K RGBA PNGを -loop 1 しないこと（RAMを消費）。単一画像の入力はオーバーレイが自動的に繰り返す。
Python（PIL/OpenCV）からの生フレームをffmpegにパイプ:
p = subprocess.Popen(["ffmpeg","-y","-f","rawvideo","-pix_fmt","rgb24","-s",f"{W}x{H}","-r","30","-i","-",
"-c:v","libx264","-crf","12","-pix_fmt","yuv420p","out.mp4"], stdin=subprocess.PIPE)
p.stdin.write(frame.tobytes()) # numpy uint8 HxWx3、フレームごと
ソースフレームも同様に読み取る（-f rawvideo -pix_fmt rgb24 -）。これによりOpenCVの回転やコーデックの問題を回避。
速度変更
- 一定速度:
setpts=PTS/2（2倍速）+atempo=2.0（atempo範囲0.5-100; さらに高速にするにはチェーン） - 30fpsからのスムーズなスローモーション:
minterpolate=fps=60:mi_mode=mci:mc_mode=aobmc:vsbmc=1その後setpts=2*PTS。エッジや手の部分の歪みを確認。 - 可変速度ランプ: タイムマップからフレームごとにレンダリング（
beat-sync参照）。複数のsetpts式を重ねないこと。
字幕（最後に）
-vf "subtitles=captions.ass:fontsdir=fonts" # ASSは完全なスタイル制御を提供
3. エクスポートプリセット
| ターゲット | 動画 | 音声 | 備考 |
|---|---|---|---|
| Instagram Reels / TikTok / Shorts | 1080x1920（または2160x3840）H.264 High、30 fps、CRF 16-18、-maxrate 25M -bufsize 50M、yuv420p | AAC 48 kHz 256-320k | -movflags +faststart; プラットフォームが再エンコードするので高品質ファイルを供給 |
| YouTube 16:9 | 3840x2160または1920x1080、H.264 CRF 16またはHEVC CRF 18、ソースfps | AAC 48 kHz 320k | 1080pコンテンツでも4Kでアップロードするとより良いVP9/AV1エンコードになる |
| マスター | ProRes 422 HQまたはx264 CRF 10 / x265 CRF 14 -tag:v hvc1 | PCM 24-bit 48 kHz | アーカイブ用 |
| プレビュー | 720p、CRF 28、-preset veryfast | AAC 128k | 高速イテレーション用 |
ソーシャル向けには常に -pix_fmt yuv420p を追加（10ビットや4:2:2はアップロード後に失敗したり見た目がおかしくなることがある）し、-color_primaries bt709 -color_trc bt709 -colorspace bt709 でSDRを正しくタグ付け。
4. 確認
ffprobe -v error -show_entries stream=codec_name,width,height,r_frame_rate,pix_fmt -show_entries format=duration -of compact out.mp4
ffmpeg -i out.mp4 -af ebur128=peak=true -f null - 2>&1 | tail -12
ffmpeg -i out.mp4 -vf "select='gt(scene,0.3)',showinfo" -f null - 2>&1 | grep pts_time # 実際のカット位置