mcpField
F
ffmpeg-filter-complex-patterns

ffmpeg-filter-complex-patterns

github.com/josiahsiegelクリエイティブ・メディア5997 回インストール19 週間前に更新
リポジトリ

ffmpeg-filter-complex-patterns について

FFmpegの複雑なフィルターグラフを扱うリファレンススキルです。動画編集者やメディア処理開発者向けに、複数ストリームの合成、フィルター連結、音声ミックス、CPU・GPU処理の例を示します。

主な機能

  1. 01フィルターグラフのラベルと連結
  2. 02ピクチャーインピクチャーとグリッド配置
  3. 03トランジションと音声ミックス
  4. 04出力用ストリーム分割
  5. 05GPUとCPUのハイブリッド処理
  6. 06フィルターグラフのデバッグ

活用シーン

  1. 01複数の動画入力をレイアウトに合成
  2. 02トランジション、テキスト、透かしを追加
  3. 03音声トラックをミックスまたは振り分け
  4. 041本の動画から複数解像度を作成

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/josiahsiegel/claude-plugin-marketplace --skill ffmpeg-filter-complex-patterns

インストール後、Claude Code で/ffmpeg-filter-complex-patternsを入力して読み込まれたか確認します。

詳細

重要なガイドライン

Windows のファイルパス要件

必須：Windows のファイルパスには必ずバックスラッシュを使用してください

Windows で Edit または Write ツールを使用する場合、ファイルパスにはスラッシュ（/）ではなく、必ずバックスラッシュ（\）を使用してください。

クイックリファレンス

タスクコマンドパターン
基本的な filter_complex-filter_complex "[0:v][1:v]overlay"
名前付きラベル[input]filter[output]
フィルターの連結filter1,filter2,filter3
チェーンの分離chain1;chain2
出力のマッピング-map "[label]"

このスキルを使用する場面

複雑なフィルターグラフ操作に使用します：

  • 複数入力の合成（PiP、グリッド、オーバーレイ）
  • 動画のトランジションとエフェクト
  • 音声のミキシングとルーティング
  • 複数出力向けのストリーム分割
  • GPU と CPU のハイブリッド処理

基本的なフィルターの場合：ffmpeg-fundamentals-2025 を使用してください ハードウェアアクセラレーションの場合：ffmpeg-hardware-acceleration を使用してください

FFmpeg filter_complex リファレンス（2025）

複雑なフィルターグラフ、複数入力の合成、高度なフィルターチェーンに関する包括的なガイドです。

filter_complex の構文

基本構造
-filter_complex "filterchain1;filterchain2;..."

各フィルターチェーンは、次の要素で構成されます：

  • 入力ラベル：[input_label]
  • フィルター：filter1,filter2,...（カンマ区切り）
  • 出力ラベル：[output_label]
完全な構文
[input_label1][input_label2]filter=param1=value1:param2=value2[output_label]
構文要素
要素説明例
[0:v]入力 0 の動画ストリーム最初の入力動画
[0:a]入力 0 の音声ストリーム最初の入力音声
[1:v]入力 1 の動画ストリーム2 番目の入力動画
[label]カスタムの名前付きラベルユーザー定義
,フィルターを順番に連結scale,fps
;独立したチェーンを分離chain1;chain2
=パラメーターの割り当てscale=1280:720
:パラメーターの区切りw=1280:h=720
ストリーム参照
参照意味
[0]最初の入力（すべてのストリーム）
[0:v]最初の入力の動画ストリーム
[0:a]最初の入力の音声ストリーム
[0:s]最初の入力の字幕ストリーム
[0:v:0]最初の入力の最初の動画ストリーム
[1:a:1]2 番目の入力の 2 番目の音声ストリーム
デフォルトのラベル
  • ラベルのない最初のフィルター入力には in が使用されます
  • ラベルのない最後のフィルター出力には out が使用されます
  • ラベルのないパッドは順番に接続されます
エスケープ規則
# Wrap filtergraph in double quotes
ffmpeg -i input.mp4 \
  -filter_complex "[0:v]drawtext=text='Hello World':fontsize=24[out]" \
  -map "[out]" output.mp4

# Using shell variables
text="Dynamic Text"
ffmpeg -i input.mp4 \
  -filter_complex "[0:v]drawtext=text='$text':fontsize=24[out]" \
  -map "[out]" output.mp4

# Escaping special characters (colons in timestamps)
ffmpeg -i input.mp4 \
  -filter_complex "[0:v]drawtext=text='Time\: %{pts\:hms}':fontsize=24[out]" \
  -map "[out]" output.mp4

一般的な合成パターン

1. ピクチャーインピクチャー（PiP）
# Basic PiP - small video in bottom-right corner
ffmpeg -i main.mp4 -i pip.mp4 \
  -filter_complex "\
    [1:v]scale=320:240[pip];\
    [0:v][pip]overlay=W-w-10:H-h-10" \
  -c:v libx264 -c:a copy output.mp4

# PiP with border
ffmpeg -i main.mp4 -i pip.mp4 \
  -filter_complex "\
    [1:v]scale=320:240,drawbox=x=0:y=0:w=iw:h=ih:c=white:t=3[pip];\
    [0:v][pip]overlay=W-w-10:H-h-10" \
  output.mp4

# Animated PiP (moving)
ffmpeg -i main.mp4 -i pip.mp4 \
  -filter_complex "\
    [1:v]scale=320:240[pip];\
    [0:v][pip]overlay='W-w-10-sin(t)*20':'H-h-10-cos(t)*20'" \
  output.mp4

# PiP with fade-in
ffmpeg -i main.mp4 -i pip.mp4 \
  -filter_complex "\
    [1:v]scale=320:240,fade=in:st=2:d=1[pip];\
    [0:v][pip]overlay=W-w-10:H-h-10:enable='gte(t,2)'" \
  output.mp4
2. 動画のグリッドレイアウト

hstack/vstack を使用（高速、シンプル）：

# 2x2 Grid
ffmpeg -i 1.mp4 -i 2.mp4 -i 3.mp4 -i 4.mp4 \
  -filter_complex "\
    [0:v]scale=640:360[v0];\
    [1:v]scale=640:360[v1];\
    [2:v]scale=640:360[v2];\
    [3:v]scale=640:360[v3];\
    [v0][v1]hstack=inputs=2[top];\
    [v2][v3]hstack=inputs=2[bottom];\
    [top][bottom]vstack=inputs=2[out]" \
  -map "[out]" output.mp4

# 3x2 Grid
ffmpeg -i 1.mp4 -i 2.mp4 -i 3.mp4 -i 4.mp4 -i 5.mp4 -i 6.mp4 \
  -filter_complex "\
    [0:v]scale=426:240[v0];\
    [1:v]scale=426:240[v1];\
    [2:v]scale=426:240[v2];\
    [3:v]scale=426:240[v3];\
    [4:v]scale=426:240[v4];\
    [5:v]scale=426:240[v5];\
    [v0][v1][v2]hstack=inputs=3[top];\
    [v3][v4][v5]hstack=inputs=3[bottom];\
    [top][bottom]vstack=inputs=2[out]" \
  -map "[out]" output.mp4

xstack を使用（より柔軟な配置）：

# 2x2 Grid with xstack
ffmpeg -i 1.mp4 -i 2.mp4 -i 3.mp4 -i 4.mp4 \
  -filter_complex "\
    [0:v]scale=640:360[v0];\
    [1:v]scale=640:360[v1];\
    [2:v]scale=640:360[v2];\
    [3:v]scale=640:360[v3];\
    [v0][v1][v2][v3]xstack=inputs=4:layout=0_0|640_0|0_360|640_360[out]" \
  -map "[out]" output.mp4

# L-shaped layout
ffmpeg -i main.mp4 -i side1.mp4 -i side2.mp4 \
  -filter_complex "\
    [0:v]scale=960:720[main];\
    [1:v]scale=320:360[s1];\
    [2:v]scale=320:360[s2];\
    [main][s1][s2]xstack=inputs=3:layout=0_0|960_0|960_360[out]" \
  -map "[out]" output.mp4
3. 動画のトランジション（xfade）
# Simple fade transition
ffmpeg -i first.mp4 -i second.mp4 \
  -filter_complex "\
    [0:v][1:v]xfade=transition=fade:duration=1:offset=4[v];\
    [0:a][1:a]acrossfade=d=1[a]" \
  -map "[v]" -map "[a]" output.mp4

# Dissolve transition
ffmpeg -i first.mp4 -i second.mp4 \
  -filter_complex "\
    [0:v][1:v]xfade=transition=dissolve:duration=2:offset=3[v]" \
  -map "[v]" output.mp4

# Wipe transitions
ffmpeg -i first.mp4 -i second.mp4 \
  -filter_complex "[0:v][1:v]xfade=transition=wipeleft:duration=1:offset=4[v]" \
  -map "[v]" output.mp4

# Multiple transitions (3+ clips)
ffmpeg -i 1.mp4 -i 2.mp4 -i 3.mp4 \
  -filter_complex "\
    [0:v]settb=AVTB,fps=30[v0];\
    [1:v]settb=AVTB,fps=30[v1];\
    [2:v]settb=AVTB,fps=30[v2];\
    [v0][v1]xfade=transition=fade:duration=1:offset=4[xf1];\
    [xf1][v2]xfade=transition=dissolve:duration=1:offset=8[out]" \
  -map "[out]" output.mp4

利用可能な xfade トランジション：

  • fade、fadeblack、fadewhite
  • wipeleft、wiperight、wipeup、wipedown
  • slideleft、slideright、slideup、slidedown
  • circlecrop、rectcrop、distance
  • radial、smoothleft、smoothright
  • dissolve、pixelize、diagtl、diagtr、diagbl、diagbr
  • hlslice、hrslice、vuslice、vdslice
  • hblur、fadegrays、squeezev、squeezeh
4. 音声ミキシング
# Mix two audio tracks
ffmpeg -i video.mp4 -i music.mp3 \
  -filter_complex "\
    [0:a][1:a]amix=inputs=2:duration=first:dropout_transition=2[aout]" \
  -map 0:v -map "[aout]" output.mp4

# Mix with volume control
ffmpeg -i vocals.mp4 -i music.mp3 \
  -filter_complex "\
    [0:a]volume=1.0[v0];\
    [1:a]volume=0.3[v1];\
    [v0][v1]amix=inputs=2:duration=first[aout]" \
  -map 0:v -map "[aout]" output.mp4

# Audio with delay (ducking)
ffmpeg -i main.mp4 -i effect.mp3 \
  -filter_complex "\
    [1:a]adelay=2000|2000[delayed];\
    [0:a][delayed]amix=inputs=2:duration=first[aout]" \
  -map 0:v -map "[aout]" output.mp4

# Merge channels (stereo from two mono)
ffmpeg -i left.wav -i right.wav \
  -filter_complex "[0:a][1:a]amerge=inputs=2[aout]" \
  -map "[aout]" stereo.wav

# Audio crossfade between tracks
ffmpeg -i track1.mp3 -i track2.mp3 \
  -filter_complex "[0:a][1:a]acrossfade=d=3:c1=tri:c2=tri[out]" \
  -map "[out]" mixed.mp3
5. テキストとウォーターマークのオーバーレイ
# Static text overlay
ffmpeg -i input.mp4 \
  -filter_complex "\
    [0:v]drawtext=text='Watermark':\
    fontsize=48:[email protected]:\
    x=10:y=H-th-10[out]" \
  -map "[out]" output.mp4

# Fade-in text
ffmpeg -i input.mp4 \
  -filter_complex "\
    [0:v]drawtext=text='Hello':\
    fontsize=64:fontcolor=white:\
    x=(w-text_w)/2:y=(h-text_h)/2:\
    alpha='if(lt(t,1),t,1)'[out]" \
  -map "[out]" output.mp4

# Scrolling credits
ffmpeg -i input.mp4 \
  -filter_complex "\
    [0:v]drawtext=textfile=credits.txt:\
    fontsize=32:fontcolor=white:\
    x=(w-text_w)/2:y=h-t*50[out]" \
  -map "[out]" output.mp4

# Timed text (appear/disappear)
ffmpeg -i input.mp4 \
  -filter_complex "\
    [0:v]drawtext=text='Show at 2s':\
    fontsize=48:fontcolor=yellow:\
    x=100:y=100:\
    enable='between(t,2,5)'[out]" \
  -map "[out]" output.mp4

# Logo/image watermark
ffmpeg -i video.mp4 -i logo.png \
  -filter_complex "\
    [1:v]scale=150:-1[logo];\
    [0:v][logo]overlay=W-w-20:20[out]" \
  -map "[out]" -map 0:a output.mp4
6. ストリームの分割と複数の出力
# Split for multiple resolutions
ffmpeg -i input.mp4 \
  -filter_complex "\
    [0:v]split=3[v1][v2][v3];\
    [v1]scale=1920:1080[hd];\
    [v2]scale=1280:720[sd];\
    [v3]scale=640:360[mobile]" \
  -map "[hd]" hd.mp4 \
  -map "[sd]" sd.mp4 \
  -map "[mobile]" mobile.mp4

# Split video and audio separately
ffmpeg -i input.mp4 \
  -filter_complex "\
    [0:v]split=2[v1][v2];\
    [0:a]asplit=2[a1][a2];\
    [v1]scale=1280:720[vout1];\
    [v2]scale=640:360[vout2]" \
  -map "[vout1]" -map "[a1]" output1.mp4 \
  -map "[vout2]" -map "[a2]" output2.mp4
7. フィルターを使用した動画の連結
# Concatenate with format normalization
ffmpeg -i 1.mp4 -i 2.mp4 -i 3.mp4 \
  -filter_complex "\
    [0:v]scale=1920:1080,fps=30,setpts=PTS-STARTPTS[v0];\
    [1:v]scale=1920:1080,fps=30,setpts=PTS-STARTPTS[v1];\
    [2:v]scale=1920:1080,fps=30,setpts=PTS-STARTPTS[v2];\
    [0:a]aformat=sample_rates=48000:channel_layouts=stereo[a0];\
    [1:a]aformat=sample_rates=48000:channel_layouts=stereo[a1];\
    [2:a]aformat=sample_rates=48000:channel_layouts=stereo[a2];\
    [v0][a0][v1][a1][v2][a2]concat=n=3:v=1:a=1[outv][outa]" \
  -map "[outv]" -map "[outa]" output.mp4

GPU アクセラレーション対応のフィルターグラフ

CUDA のフルパイプライン
# GPU decode -> GPU filter -> GPU encode
ffmpeg -hwaccel cuda -hwaccel_output_format cuda -i main.mp4 \
  -hwaccel cuda -hwaccel_output_format cuda -i overlay.mp4 \
  -filter_complex "\
    [0:v]scale_cuda=1920:1080[main];\
    [1:v]scale_cuda=320:180[pip];\
    [main][pip]overlay_cuda=W-w-10:H-h-10[out]" \
  -map "[out]" -map 0:a \
  -c:v h264_nvenc -preset p4 output.mp4
GPU と CPU のハイブリッドパイプライン

drawtext や字幕など、CPU 専用のフィルターが必要な場合は、hwdownload/hwupload を使用します：

# GPU scale -> CPU text -> GPU encode
ffmpeg -hwaccel cuda -hwaccel_output_format cuda -i input.mp4 \
  -filter_complex "\
    [0:v]scale_cuda=1920:1080[scaled];\
    [scaled]hwdownload,format=nv12[cpu];\
    [cpu]drawtext=text='Watermark':fontsize=48:x=10:y=10[text];\
    [text]hwupload_cuda[out]" \
  -map "[out]" \
  -c:v h264_nvenc output.mp4
GPU を使用した ABR ラダー
# Generate multiple resolutions on GPU
ffmpeg -y -vsync 0 \
  -hwaccel cuda \
  -hwaccel_output_format cuda \
  -i input.mp4 \
  -filter_complex "[0:v]split=3[v1][v2][v3];\
    [v1]scale_cuda=1920:1080[hd];\
    [v2]scale_cuda=1280:720[sd];\
    [v3]scale_cuda=640:360[mobile]" \
  -map "[hd]" -c:v h264_nvenc -b:v 5M output_1080p.mp4 \
  -map "[sd]" -c:v h264_nvenc -b:v 2M output_720p.mp4 \
  -map "[mobile]" -c:v h264_nvenc -b:v 500k output_360p.mp4

高度なパターン

マルチレイヤー合成
# Video with lower third, logo, and timecode
ffmpeg -i main.mp4 -i logo.png -i lower_third.png \
  -filter_complex "\
    [1:v]scale=150:-1[logo];\
    [2:v]scale=400:-1[third];\
    [0:v][logo]overlay=W-w-20:20[step1];\
    [step1][third]overlay=50:H-h-80:enable='between(t,5,55)'[step2];\
    [step2]drawtext=text='%{pts\\:hms}':\
      fontsize=32:fontcolor=white:\
      x=W-tw-20:y=H-th-20[out]" \
  -map "[out]" -map 0:a output.mp4
音声の可視化オーバーレイ
# Waveform overlay on video
ffmpeg -i video.mp4 -i audio.mp3 \
  -filter_complex "\
    [1:a]showwaves=s=1920x200:mode=cline:[email protected][wave];\
    [0:v][wave]overlay=0:H-h-50[out]" \
  -map "[out]" -map 1:a output.mp4

# Spectrum analyzer
ffmpeg -i video.mp4 \
  -filter_complex "\
    [0:a]showspectrum=s=1920x200:legend=0:color=rainbow[spec];\
    [0:v][spec]overlay=0:H-h[out]" \
  -map "[out]" -map 0:a output.mp4
時間ベースのエフェクト
# Different effects at different times
ffmpeg -i input.mp4 \
  -filter_complex "\
    [0:v]split=3[v1][v2][v3];\
    [v1]trim=0:5,setpts=PTS-STARTPTS[part1];\
    [v2]trim=5:10,setpts=PTS-STARTPTS,eq=brightness=0.2:saturation=2.0[part2];\
    [v3]trim=10,setpts=PTS-STARTPTS[part3];\
    [part1][part2][part3]concat=n=3:v=1:a=0[out]" \
  -map "[out]" -map 0:a output.mp4

フィルターグラフのデバッグ

詳細ログ
# Enable debug logging
ffmpeg -loglevel debug -i input.mp4 -filter_complex "..." output.mp4

# Show filter graph info
ffmpeg -filter_complex_script script.txt -lavfi "..." 2>&1 | grep -i filter
フィルターグラフの検証
# Test filtergraph without encoding (null output)
ffmpeg -i input.mp4 -filter_complex "..." -f null -

# Check specific filter options
ffmpeg -h filter=overlay
ffmpeg -h filter=xfade
ffmpeg -h filter=amix
よくあるエラー
エラー原因解決策
"Input pad not connected"入力ラベルがありません[0:v] を追加するか、ラベルを修正します
"Output pad not connected"フィルター出力が未使用です-map を追加するか、次のフィルターに接続します
"Stream specifier not found"ストリーム参照が無効です入力にそのストリームタイプがあるか確認します
"Filter not found"FFmpeg のビルドにフィルターがありませんffmpeg -filters を確認します
"Discarding frame"タイムスタンプが不連続ですsetpts=PTS-STARTPTS を追加します
パフォーマンスのヒント
  1. 順序が重要です - 負荷の高いフィルターはチェーンの後半に配置します
  2. 利用可能な場合は GPU フィルターを使います（scale_cuda、overlay_cuda）
  3. 不要なフォーマット変換を避けます - 同じピクセルフォーマットを維持します
  4. 複数の出力を作成する場合は、フィルターの前に分割します
  5. -threads 0 を使います - スレッド数を自動検出します

ベストプラクティス

  1. 意味のあるラベルを使います - わかりやすさのため、[v1] ではなく [scaled] を使います
  2. 短いクリップでテストします - -t 5 を使って最初の 5 秒をテストします
  3. すべてのストリームを確認します - -map で音声のマッピングを確認します
  4. 入力を正規化します - 連結やトランジションの前に FPS と解像度をそろえます
  5. フィルターグラフを引用符で囲みます - -filter_complex 全体を二重引用符で囲みます
  6. 音声は別途処理します - 映像と音声では異なる処理が必要になることがよくあります

このガイドでは、2025 年向けの filter_complex のパターンを説明します。ハードウェアアクセラレーションの詳細については、ffmpeg-hardware-acceleration をご覧ください。基本的なフィルター構文については、ffmpeg-fundamentals-2025 をご覧ください。

コメント

Markdown 対応