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 与混合滤镜流程
  6. 06滤镜图排错指南

适用场景

  1. 01将多个视频输入合成为一种布局
  2. 02添加转场、文字或水印
  3. 03混合音轨或路由媒体流
  4. 04从一个视频生成多个分辨率版本

安装

复制下面的命令，在终端中运行。

$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]"

何时使用此技能

适用于复杂滤镜图操作：

  • 多输入合成（画中画、网格、叠加）
  • 视频转场和特效
  • 音频混合和路由
  • 拆分流以输出多个结果
  • 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 的视频流第二个输入的视频
[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]第二个输入的第二个音频流
默认标签
  • 未标记的第一个滤镜输入使用 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 混合流程

需要使用仅限 CPU 的滤镜（drawtext、字幕）时，请使用 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. 使用有意义的标签 - 使用 [scaled] 而不是 [v1]，以便于理解
  2. 使用短片段测试 - 使用 -t 5 测试前 5 秒
  3. 检查所有流 - 使用 -map 验证音频映射
  4. 规范化输入 - 拼接或转场前统一帧率和分辨率
  5. 为滤镜图加引号 - 在整个 -filter_complex 两侧使用双引号
  6. 单独处理音频 - 视频和音频通常需要不同的处理方式

本指南介绍了 2025 年的 filter_complex 模式。有关硬件加速的详细信息，请参阅 ffmpeg-hardware-acceleration。有关基本滤镜语法，请参阅 ffmpeg-fundamentals-2025。

评论

支持 Markdown