FFmpeg chromakey 绿幕合成踩坑详解

在视频处理领域，FFmpeg 的 chromakey 滤镜是做绿幕抠像的经典方案——比 AI 分割快一个数量级，只要背景足够干净就能出好效果。但在 2026 年 7 月，开源 AI 视频制作系统 OpenMontage 的 green_screen_processor 工具出了一个非常隐蔽的 bug：当用户选择 chromakey 方法时，输出的不是合成好的视频，而是一整块纯色画面——主体完全消失。

更诡异的是，FFmpeg 命令本身不会报错。它正常退出，返回码 0，生成了一个合法的文件。你只是得到一个完全错误的视频。

这个 bug 的根因不是 FFmpeg 本身的缺陷，而是对 overlay 滤镜一个隐式行为的误解——以及 scale=iw:ih 在特定上下文下变成空操作的事实。修复涉及两个独立的 commit，第二个 commit 解决的 alpha 格式可移植性问题甚至比第一个 bug 更有意思。

Bug #1：1×1 像素的背景

有问题的代码

OpenMontage 的 _process_chromakey 方法为每一帧生成合成背景的方式是这样的（简化版）：

# 旧代码 — 有 bug
ffmpeg -y \
  -f lavfi -i "color=c=#0E172A:size=1x1"  \    # ← 1×1 纯色背景
  -i frame_0000.png \                           # ← 绿幕帧（主体在绿幕前）
  -filter_complex \
    "[0:v]scale=iw:ih[bg];\                     # ← 尝试缩放到帧尺寸
     [1:v]chromakey=color=0x00FF00:\
       similarity=0.3:blend=0.08[fg];\          # ← 抠掉绿色
     [bg][fg]overlay=0:0" \                      # ← 合成
  -frames:v 1 output.png

看起来逻辑是对的：先生一个 1×1 的纯色背景，再用 scale=iw:ih 把它缩放到帧的尺寸，然后把抠掉绿色的前景叠上去。

但它生成了一个纯色文件。

逐层拆解

问题要从 FFmpeg filter_complex 的求值规则说起。在这个 filtergraph 里：

第一层：scale=iw:ih 是空操作。

iw 和 ih 是 输入流的宽和高。[0:v] 是那个 color=size=1x1 源，所以 iw=1, ih=1。scale=1:1 等于什么都没做。开发者的意图显然是"缩放到帧的尺寸"，但 iw/ih 引用的是同一个输入，不是另一个输入。没有交叉引用，背景就一直是 1×1。

第二层：overlay 取第一个输入的尺寸。

这是 FFmpeg overlay 的核心语义，也是这个 bug 最致命的部分。overlay 的输出尺寸 = 第一个输入（bottom layer） 的尺寸。合成图的 [bg] 是那个 1×1 的背景——所以整个合成结果就是 1×1 像素。

第三层：_reconstruct_video 把 1×1 放大。

OpenMontage 的帧处理是逐帧的——每帧生成一个 PNG，最后再拼回视频。_reconstruct_video 用的编码器发现输入是 1×1 时会做缩放（FFmpeg 默认行为），所以最终视频不是 1×1——它被放大成目标分辨率，但内容只剩那个 1×1 的纯色像素。

为什么没报错？ 因为每一步都是合法操作。1×1 的 PNG 是有效的文件，FFmpeg 正常处理。fallback 逻辑不会触发，因为主命令以退出码 0 成功完成。这就是静默数据丢失——"method=chromakey" 的每一次调用、以及 "method=auto" 命中 chromakey 时的每一次调用，结果都是错的。

修复

第一个 commit（df8cf21）最初用 scale2ref 来引用帧尺寸。但第二个 commit（fa756fb）重写了方案，改用更直接的方式——直接在生成背景时就指定帧尺寸：

# 修复后代码
ffmpeg -y \
  -f lavfi -i "color=c=#0E172A:size=320x240" \  # ← 直接按帧尺寸生成背景
  -i frame_0000.png \
  -filter_complex \
    "[1:v]chromakey=color=0x00FF00:\
       similarity=0.3:blend=0.08,\
     format=yuva420p[fg];\                       # ← 强制 alpha 格式（见下文）
     [0:v][fg]overlay=0:0:format=auto,\
     format=yuv420p" \                            # ← 输出扁平化为 yuv420p
  -frames:v 1 output.png

scale 滤镜被完全移除了。背景层从一开始就是正确的尺寸，overlay 取第一个输入（已是 320×240）的尺寸，输出正确。同时，_process_chromakey 的函数签名增加了 width 和 height 参数，由 _probe_video 探测到的帧尺寸传入。

Bug #2：alpha 格式可移植性

第一个 bug 修好之后，本地测试全过了——macOS 和 Windows 上。但 CI 跑在 Linux 上，E2E 测试依然失败：角落的像素不是预期的背景色（#0E172A），而是绿色。

现象

chromakey 滤镜的工作原理是：把匹配目标颜色（这里是绿色 0x00FF00）的像素标记为透明，其余像素保留。这就需要帧有一个 alpha 通道（透明度通道）。

问题在于：不同的 FFmpeg 构建对 chromakey 输出的像素格式协商（pixel format negotiation）行为不同。

• macOS（Homebrew）和 Windows 构建通常自动保留 alpha 通道
• CI 上的 Linux 构建在 filter 链传递过程中丢掉了 alpha plane

当 alpha plane 丢失后，overlay 就认为前景是不透明的——于是它直接把整个绿幕帧画在了背景上面，没有合成。抠出来的绿色没变成透明，而是原封不动地覆盖了一切。

修复：显式声明 yuva420p

# 在 chromakey 之后立即强制 alpha 格式
[1:v]chromakey=color=0x00FF00:similarity=0.3:blend=0.08,format=yuva420p[fg]

yuva420p 的 a 就是 alpha。强制这个格式后，无论 FFmpeg 在 filter negotiation 时怎么推断，chromakey 产生的透明度信息都会被保留到一个显式的 alpha plane 里。

合成完成后，再用 format=yuv420p 把输出扁平化回标准的不透明格式（PNG 输出和最终视频编码通常不需要 alpha 通道）：

[0:v][fg]overlay=0:0:format=auto,format=yuv420p

为什么会发生 alpha 丢失

FFmpeg 的 filter 链有一个 自动格式协商（auto-negotiation）机制。当两个 filter 连接时，FFmpeg 会根据输出 filter 的输入约束自动选择一个兼容的像素格式。chromakey 输出的带 alpha 格式（如 yuva420p）在传给 overlay 时，如果 overlay 的构建配置或编译选项不允许带 alpha 的输入，FFmpeg 会自动去掉 alpha plane。

这不是 bug，是 FFmpeg 为保持不同 filter 组合的兼容性而做的权衡。但它意味着：你不能假设 chromakey 的输出格式在所有平台上都一样。

修复前后的完整对比

维度	旧代码（有 bug）	修复后
背景源尺寸	color=c=#0E172A:size=1x1	color=c=#0E172A:size=WxH
缩放策略	scale=iw:ih（空操作）	无需缩放（已按帧尺寸生成）
overlay 输出尺寸	1×1（第一个输入的尺寸）	W×H（第一个输入的尺寸）
alpha 格式	依赖自动协商（不可靠）	显式 format=yuva420p
输出格式	未指定（可能带 alpha）	显式 format=yuv420p
跨平台一致性	macOS/Windows 通过，Linux 失败	所有平台一致
主体是否保留	❌ 完全丢失	✅ 正常合成

完整修复的 FFmpeg filtergraph 如下：

ffmpeg -y \
  -f lavfi -i "color=c=0x0E172A:size=320x240" \
  -i frame_0000.png \
  -filter_complex \
    "[1:v]chromakey=color=0x00FF00:similarity=0.3:blend=0.08,format=yuva420p[fg]; \
     [0:v][fg]overlay=0:0:format=auto,format=yuv420p" \
  -frames:v 1 output.png

测试：如何捕获静默失败

这个 bug 之所以难以发现，是因为它不报错——FFmpeg 优雅退出，生成了合法的文件。OpenMontage 的修复同时引入了回归测试（test_green_screen_chromakey.py，116 行），分两层防护：

单元测试（离线，不需要真实 FFmpeg 处理）——验证 filtergraph 字符串的构建逻辑：

def test_chromakey_filter_scales_background_to_frame():
    # mock run_command，捕获构建的命令
    tool._process_chromakey(fd, pd, "#0E172A", 1, 320, 240)

    cmd = ffmpeg_cmds[0]
    fc = cmd[cmd.index("-filter_complex") + 1]

    # 背景必须按帧尺寸生成，不是旧的 1×1
    assert "size=320x240" in " ".join(cmd)
    assert "size=1x1" not in " ".join(cmd)
    assert "[0:v]scale=iw:ih[bg]" not in fc   # 不再有空操作缩放
    assert "format=yuva420p" in fc             # alpha 必须被强制

E2E 测试（需要 ffmpeg + ffprobe）——验证实际像素，这是捕获静默失败的关键：

def test_chromakey_preserves_frame_size_and_keys(tmp_path):
    # 生成一个 320×240 绿底 + 红色主体的测试帧
    # ... 处理后 ...
    ok = GreenScreenProcessor()._process_chromakey(
        frames_dir, processed_dir, "#0E172A", 1, 320, 240
    )
    assert _size(out) == (320, 240)  # 尺寸不能坍缩

    center = _pixel(out, 160, 120)   # 红色主体 → 保持红色
    corner = _pixel(out, 10, 10)     # 原绿色 → 抠成背景色
    assert center[0] > 150 and center[1] < 80      # 主体没丢
    assert corner[0] < 60 and corner[1] < 60        # 绿色被抠掉

关键在于 _pixel 断言：它检查 具体像素的颜色值。如果 alpha 丢失导致 overlay 直接覆盖，角落会保持绿色——这个断言就会失败。正是因为这个 E2E 测试在 CI 的 Linux 环境里红了，才暴露了 alpha 格式可移植性问题。

AI 视频管线为什么需要关注这些底层细节

OpenMontage 的定位是 Agent 驱动的视频制作系统——我们之前分析过它的架构：52 个工具、500+ Agent 技能，从研究、脚本到剪辑、合成全流程自动化。green_screen_processor 就是这 52 个工具之一。

这类系统的架构假设是：工具层是可靠的。上层 Agent 决定"这一段需要绿幕抠像"，调用 green_screen_processor，然后拿到结果继续后续步骤——配乐、字幕、转场。如果工具层静默返回错误结果（一个纯色视频），Agent 不会知道——它只会继续后续处理，最终产出一个在某个片段突然变成纯色的成品视频。

这个问题在 AI 视频管线中被放大了几个量级：

1. AI Agent 无法感知视觉错误。 与单元测试不同，Agent 不会逐帧检查像素值。如果 chromakey 输出纯色，Agent 看到的是一个"成功生成的视频文件"，会继续合成。
2. 调试链路极长。 从 Agent 调用工具到最终视频成品，中间可能经过 5-10 个处理步骤。纯色视频在中间环节被发现和定位的难度远大于传统管线。
3. FFmpeg 的静默失败模式。 FFmpeg 的设计哲学是"尽力而为"——即使输入有隐含问题，它也尽量生成输出而不是报错。这在交互式使用时是优点，但在自动化管线里就是定时炸弹。

这正是我们在另一篇文章里讨论 AI Agent 测试策略时强调的观点：AI Agent 的工具层必须有像素级的断言，不能只验证"有没有输出文件"。OpenMontage 引入的 _pixel() 测试——检查具体坐标的 RGB 值——正是正确的做法。

回到更广的背景：2026 年 AI 视频生成工具已经百花齐放，但绿幕合成这种经典视频处理技术仍然是管线里不可或缺的一环。理解 FFmpeg 的底层行为——overlay 的尺寸规则、filter negotiation 的格式协商、不同构建之间的差异——在 AI 驱动的自动化管线里不是可选项，而是必须项。

结论

这两个 bug 教给我们三件事：

1. overlay 的输出尺寸 = 第一个输入的尺寸。 这不是文档醒目标注的"陷阱"，而是隐式行为。永远确保你的 bottom layer 是正确的尺寸——最好在生成时就定好，别依赖后置缩放。
2. scale=iw:ih 引用的是当前输入，不是其他输入。 如果需要引用另一个流的尺寸，用 scale2ref 或提前把尺寸参数化。
3. 显式声明像素格式，永远不要依赖自动协商。 format=yuva420p 在 chromakey 之后，format=yuv420p 在 overlay 之后——这让 filtergraph 在所有 FFmpeg 构建上行为一致。

最后一点可能是最有价值的教训：静默失败比崩溃更危险。 崩溃你能立刻知道；静默失败会带着错误数据流过整条管线，直到最终成品上线才被发现。像素级断言——检查输出文件的尺寸和具体坐标的颜色值——是捕获这类问题的唯一可靠手段。

参考资料

1. OpenMontage — green_screen_processor.py — 修复后的完整源码
2. Commit df8cf21 — fix(green_screen): scale chromakey background to frame size, not 1x1
3. Commit fa756fb — fix(green_screen): make chromakey compositing portable across FFmpeg builds
4. FFmpeg — overlay filter 文档 — "The output video size is the same as the input video size of the first (bottom) input"
5. FFmpeg — chromakey filter 文档 — 像素格式与 alpha 行为
6. FFmpeg — scale2ref filter 文档 — 引用另一个流的尺寸进行缩放
7. OpenMontage — test_green_screen_chromakey.py — 回归测试（116 行）