ffmpeg-video-editor

FFmpeg 動画編集エージェントスキル

あなたは FFmpeg のエキスパートです。正しい ffmpeg コマンドラインを組み立てて、あらゆる動画・音声編集のリクエストに対応してください。まず入力ファイルを必ず調査してから、以下の適切な操作カテゴリを選択してください。

入力ファイルの調査

​​scripts/probe.sh <file> を実行する（必要に応じて、まず chmod +x scripts/*.sh で実行可能にする）か、手動で調査してください。

ffprobe -v error -show_streams -show_format -of json input.mp4

トリミング／カット

# Fast stream-copy trim (no re-encode)
ffmpeg -ss 00:01:00 -to 00:02:30 -i input.mp4 -c copy out.mp4

# Precise trim (re-encode around keyframes)
ffmpeg -ss 00:01:00 -i input.mp4 -t 90 -c:v libx264 -crf 18 -c:a aac out.mp4

トランスコード

# H.264 web-safe (pix_fmt ensures broad player compatibility)
ffmpeg -i input.mp4 -c:v libx264 -crf 23 -preset slow \
  -pix_fmt yuv420p -c:a aac -b:a 128k -movflags +faststart out.mp4

# H.265 (smaller files)
ffmpeg -i input.mp4 -c:v libx265 -crf 28 -preset slow \
  -pix_fmt yuv420p -c:a aac -b:a 128k out.mp4

# VP9 for web
ffmpeg -i input.mp4 -c:v libvpx-vp9 -crf 33 -b:v 0 \
  -c:a libopus -b:a 128k out.webm

# AV1 (best compression)
ffmpeg -i input.mp4 -c:v libaom-av1 -crf 35 -cpu-used 4 \
  -c:a libopus -b:a 128k out.mkv

コーデックの詳しい比較については、references/CODECS.md を参照してください。

ファイルの連結

# Using helper script
scripts/concat.sh out.mp4 clip1.mp4 clip2.mp4 clip3.mp4

# Manual concat demuxer
printf "file 'a.mp4'\nfile 'b.mp4'\n" > list.txt
ffmpeg -f concat -safe 0 -i list.txt -c copy out.mp4

スケーリング／サイズ変更

# Scale to 1920×1080, keep aspect ratio, pad to fill
ffmpeg -i in.mp4 -vf "scale=1920:1080:force_original_aspect_ratio=decrease,\
pad=1920:1080:(ow-iw)/2:(oh-ih)/2:black" out.mp4

# Scale by width only (auto height)
ffmpeg -i in.mp4 -vf "scale=1280:-2" out.mp4

クロップ

# Crop 640×360 starting at (100,50)
ffmpeg -i in.mp4 -vf "crop=640:360:100:50" out.mp4

# Center crop to 1:1 square
ffmpeg -i in.mp4 -vf "crop=min(iw\,ih):min(iw\,ih)" out.mp4

オーバーレイ／ウォーターマーク

# Overlay image (top-right, 10px margin)
ffmpeg -i video.mp4 -i logo.png \
  -filter_complex "[0:v][1:v] overlay=W-w-10:10" out.mp4

# PiP: small video on top of main
ffmpeg -i main.mp4 -i pip.mp4 \
  -filter_complex "[1:v]scale=320:-2[small];[0:v][small]overlay=W-w-10:H-h-10" out.mp4

テキスト／タイトルの描画

ffmpeg -i in.mp4 -vf \
  "drawtext=text='My Title':fontfile=/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf\
:fontsize=48:fontcolor=white:x=(w-text_w)/2:y=(h-text_h)/2\
:shadowx=2:shadowy=2" out.mp4

字幕の焼き込み

# SRT subtitles (re-encode required)
ffmpeg -i video.mp4 -vf "subtitles=subs.srt" out.mp4

# ASS/SSA subtitles (preserves styling)
ffmpeg -i video.mp4 -vf "ass=subs.ass" out.mp4

再生速度の変更

# 2× speed (video + audio)
ffmpeg -i in.mp4 -vf "setpts=0.5*PTS" -af "atempo=2.0" out.mp4

# 0.5× speed (half speed)
ffmpeg -i in.mp4 -vf "setpts=2.0*PTS" -af "atempo=0.5" out.mp4

# >4×: chain atempo (max 2.0 per filter)
ffmpeg -i in.mp4 -vf "setpts=0.25*PTS" -af "atempo=2.0,atempo=2.0" out.mp4

# <0.5×: chain atempo (min 0.5 per filter)
ffmpeg -i in.mp4 -vf "setpts=4.0*PTS" -af "atempo=0.5,atempo=0.5" out.mp4

逆再生

ffmpeg -i in.mp4 -vf "reverse" -af "areverse" out.mp4

トランジション（xfade）

# Dissolve between two clips (1s overlap at t=5)
ffmpeg -i a.mp4 -i b.mp4 \
  -filter_complex "[0:v][1:v]xfade=transition=dissolve:duration=1:offset=5[v];\
[0:a][1:a]acrossfade=d=1[a]" \
  -map "[v]" -map "[a]" out.mp4

40 種類以上の xfade トランジションについては、references/TRANSITIONS.md を参照してください。

音声：音量とノーマライズ

# Adjust volume
ffmpeg -i in.mp4 -af "volume=1.5" out.mp4

# EBU R128 normalization (two-pass)
scripts/normalize-audio.sh in.mp4 out.mp4

# One-pass loudnorm
ffmpeg -i in.mp4 -af "loudnorm=I=-16:TP=-1.5:LRA=11" out.mp4

音声：フェードイン／フェードアウト

# Fade in 2s at start, fade out 3s before end (total 60s)
ffmpeg -i in.mp4 -af "afade=t=in:d=2,afade=t=out:st=57:d=3" out.mp4

音声のミックス／結合

# Mix two audio streams
ffmpeg -i video.mp4 -i music.mp3 \
  -filter_complex "[0:a][1:a]amix=inputs=2:duration=first:weights=1 0.3[a]" \
  -map 0:v -map "[a]" -c:v copy out.mp4

カラーグレーディング

# Brightness/Contrast/Saturation
ffmpeg -i in.mp4 -vf "eq=brightness=0.05:contrast=1.2:saturation=1.3" out.mp4

# Hue shift
ffmpeg -i in.mp4 -vf "hue=h=30:s=1.1" out.mp4

# Apply 3D LUT (.cube)
ffmpeg -i in.mp4 -vf "lut3d=file=lut.cube" out.mp4

# Apply Hald CLUT PNG
ffmpeg -i in.mp4 -i lut.png \
  -filter_complex "[0:v][1:v]haldclut" out.mp4

クロマキー／グリーンスクリーン

# chromakey (color + similarity + blend)
ffmpeg -i foreground.mp4 -i background.mp4 \
  -filter_complex "[0:v]chromakey=0x00FF00:0.3:0.2[fg];\
[1:v][fg]overlay" out.mp4

# colorkey (simpler, exact color)
ffmpeg -i in.mp4 -vf "colorkey=green:0.3:0.2" out.mp4

フレームレート変換

# Convert to 30fps
ffmpeg -i in.mp4 -vf "fps=30" out.mp4

# Use motion interpolation (minterpolate)
ffmpeg -i in.mp4 -vf "minterpolate=fps=60:mi_mode=mci" out.mp4

フレームの抽出／スライドショーの作成

# Extract one frame per second as PNG
ffmpeg -i in.mp4 -vf "fps=1" frames/%04d.png

# Slideshow from images (3s per image, 30fps output)
ffmpeg -framerate 1/3 -i frames/%04d.png -c:v libx264 -r 30 out.mp4

スタッキング／グリッドレイアウト

# Side by side (hstack)
ffmpeg -i a.mp4 -i b.mp4 -filter_complex "[0:v][1:v]hstack=inputs=2" out.mp4

# Top-bottom (vstack)
ffmpeg -i a.mp4 -i b.mp4 -filter_complex "[0:v][1:v]vstack=inputs=2" out.mp4

# 2×2 grid (xstack)
ffmpeg -i a.mp4 -i b.mp4 -i c.mp4 -i d.mp4 \
  -filter_complex "[0:v][1:v][2:v][3:v]xstack=inputs=4:layout=0_0|w0_0|0_h0|w0_h0" out.mp4

ハードウェアアクセラレーションエンコード

# NVIDIA NVENC H.264
ffmpeg -hwaccel cuda -i in.mp4 -c:v h264_nvenc -preset p4 -cq 23 out.mp4

# Apple VideoToolbox H.265
ffmpeg -i in.mp4 -c:v hevc_videotoolbox -q:v 60 out.mp4

# Intel QuickSync H.264
ffmpeg -hwaccel qsv -i in.mp4 -c:v h264_qsv -global_quality 23 out.mp4

GPU エンコードの詳しいガイドについては、references/HARDWARE-ACCEL.md を参照してください。

エンコードプリセット（assets/preset-profiles.json）

タスクが以下のユースケース名に該当する場合は、assets/preset-profiles.json を読み込み、既成の ffmpeg コマンドとして example フィールドを使用してください。

プロファイル	コーデック	CRF	用途
web-optimized	H.264	23	ブラウザーでのストリーミング
high-quality	H.264	18	アーカイブ／マスター
social-media-vertical	H.264	23	9:16 TikTok/Reels
social-media-square	H.264	23	1:1 Instagram
fast-preview	H.264	28	プロキシ／レビュー
lossless-intermediate	FFV1	—	ポストプロダクション用保存

マルチストリームフィルターグラフのパターン

ffmpeg \
  -i input_video.mp4 \
  -i overlay.png \
  -i audio_bed.mp3 \
  -filter_complex "
    [0:v]scale=1920:1080,setsar=1[base];
    [1:v]scale=200:-2,format=rgba,colorchannelmixer=aa=0.8[logo];
    [base][logo]overlay=W-w-20:20[composited];
    [0:a][2:a]amix=inputs=2:weights=1 0.2[audio_mix]
  " \
  -map "[composited]" -map "[audio_mix]" \
  -c:v libx264 -crf 18 -preset slow \
  -c:a aac -b:a 192k \
  -movflags +faststart \
  output.mp4

よく使うオプションのリファレンス

フラグ	意味
-ss	シーク／開始時刻（-i の前に指定すると高速シーク）
-to	終了時刻（絶対値）
-t	長さ
-c copy	ストリームコピー（再エンコードなし）
-crf	固定レート係数（値が小さいほど高画質）
-preset	エンコーダーの速度と品質のトレードオフ
-movflags +faststart	moov アトムを先頭に移動（ウェブストリーミング用）
-vf	ビデオフィルターチェーン
-af	オーディオフィルターチェーン
-filter_complex	複数入力／出力のフィルターグラフ
-map	出力ストリームを明示的に選択
-an	音声を除去
-vn	映像を除去
-y	確認なしで出力を上書き

デバッグのヒント

# Dry-run: print filter graph without encoding
ffmpeg -i in.mp4 -vf "scale=1280:-2" -f null -

# Benchmark encode speed
ffmpeg -benchmark -i in.mp4 -c:v libx264 -f null -

# Show available encoders
ffmpeg -encoders | grep -E "^.V|^.A"

# Show filter options
ffmpeg -help filter=loudnorm