往视频中叠加动图的实现过程与踩坑记录
背景
在线编辑功能需要支持将用户上传的贴纸（包括静态图片和动态贴纸）叠加到视频指定时间段的指定位置。静态图片（PNG/JPG/静态WebP）处理比较顺畅，但动态贴纸（Animated WebP/GIF）在实现过程中遇到了多个坑，本文记录完整的踩坑与解决过程。
基本思路
使用 FFmpeg 的overlayfilter 将图片叠加到视频上，enable='between(t,startTime,endTime)'控制显示时间段，scalefilter 控制尺寸，format=auto保留透明通道。
基本命令结构如下：
ffmpeg-ivideo.mp4\-isticker.png\-filter_complex"[1:v]scale=W:H[img0];[0:v][img0]overlay=X:Y:format=auto:enable='between(t,S,E)'[v0]"\-map"[v0]"-map0:a-c:acopy-b:v6000k\-youtput.mp4坑一：Animated WebP 无法被 FFmpeg 解码
现象
下载的贴纸文件后缀是.webp，FFmpeg 执行时报错：
[webp @ 0x...] skipping unsupported chunk: ANIM [webp @ 0x...] skipping unsupported chunk: ANMF [webp @ 0x...] image data not found [webp_pipe @ 0x...] Could not find codec parameters for stream 0: unspecified size Conversion failed!原因分析
WebP 分为两种格式：
- 静态 WebP：单帧，FFmpeg 的
webp_pipe解复用器可以正常处理。 - Animated WebP：多帧动画，包含
ANIM和ANMFchunk，webp_pipe解复用器不支持，无法读取。
ANIM 和 ANMF chunk 是什么
WebP 基于RIFF 容器格式，整个文件由多个 chunk 组成，每个 chunk 有4字节标识符 + 4字节长度 + 数据内容。
RIFF....WEBP ├── VP8 / VP8L / VP8X ← 静态 WebP 的图像数据 ├── ANIM ← 动画全局配置（仅 Animated WebP 有） ├── ANMF ← 第1帧 ├── ANMF ← 第2帧 └── ANMF ← 第N帧ANIM chunk（Animation）：整个动画的全局配置块，只出现一次，包含背景色和循环次数（0表示无限循环）。静态 WebP 没有此 chunk，因此扫描到 ANIM 即可确认是动态 WebP。
ANMF chunk（Animation Frame）：每一帧的数据块，每帧对应一个，包含该帧的坐标偏移、宽高、显示时长（毫秒）、混合方式以及实际图像数据。
webp_pipe解复用器只认VP8 / VP8L / VP8Xchunk，遇到ANIM和ANMF直接跳过，最终找不到图像数据报错。要正确解码 Animated WebP 需要能理解ANIM/ANMF结构、逐帧读取并按Frame Duration控制帧率的解复用器，而该版本 FFmpeg 静态构建未实现这部分。
尝试方案一：使用-f webp解复用器
查阅资料发现可以用-f webp替代默认的webp_pipe来支持动态 WebP。在输入前加-f webp -stream_loop -1。
结果：依然失败，报错：
[in#2 @ 0x...] Unknown input format: 'webp'该版本的 FFmpeg 静态构建根本没有独立的webpdemuxer，此路不通。
解决方案：预转换为 GIF
FFmpeg 无法解码 Animated WebP，但ImageMagick原生支持。思路是：先检测文件是否为 Animated WebP，若是则用 ImageMagick 的convert命令将其转换为 GIF，再交给 FFmpeg 处理。
检测 Animated WebP 的方法：读取文件二进制头，在 RIFF/WEBP 结构内搜索ANIMchunk（最多扫描前 64KB）来判断。
# 安装 ImageMagick（需含 WebP 支持）aptinstall-yimagemagick-6.q16 webp# 验证 WebP 支持convert-listformat|grep-iwebp# 输出应包含 WEBP rw+# 转换命令convert input.webp output.gif坑二：GIF 叠加后 FFmpeg 无限循环，任务永不结束
现象
转换成 GIF 后，用以下命令叠加：
ffmpeg-ivideo.mp4\-ignore_loop0-stream_loop-1-isticker.gif\-filter_complex"..."\-youtput.mp4FFmpeg 开始正常处理，但在源视频（72秒）结束后并没有停止，而是继续疯狂生成帧，time 一直增长到几小时，dup（重复帧计数）不断攀升：
frame=10767 ... time=01:01:10 ... dup=10005 drop=0 frame=282734 ... time=03:08:26 ... dup=31215 drop=0原因分析
-stream_loop -1：让 GIF 输入无限循环读取。-ignore_loop 0：忽略 GIF 自身的循环次数限制，强制无限播放。- 两者叠加后，GIF 输入流变成了无限长的流。
- FFmpeg 默认以最长输入流作为输出时长，导致输出永远不会结束。
尝试方案：加-shortest
加-shortest可以让 FFmpeg 以最短的有限流（源视频72秒）为准结束处理。
但这个方案有缺陷：-shortest会影响所有输出，如果贴纸的endTimeS比视频短，可能导致输出视频被截断。
最终解决方案：用-t endTimeS限制 GIF 输入时长
在 animated GIF 的-i参数之前加上-t endTimeS，直接限制该输入流只读取到贴纸结束时间：
ffmpeg-ivideo.mp4\-ignore_loop0-stream_loop-1-t20.0-isticker.gif\-filter_complex"[1:v]scale=W:H[img0];[0:v][img0]overlay=X:Y:format=auto:enable='between(t,10.0,20.0)'[v0]"\-map"[v0]"-map0:a-c:acopy-b:v6000k\-youtput.mp4-t 20.0表示 GIF 输入只读取20秒，FFmpeg 不再无限循环，GIF 在between(t,10,20)区间内循环播放动画，整个源视频完整输出。
最终完整方案总结
| 步骤 | 操作 |
|---|---|
| 1. 检测文件类型 | 读取文件头，检查 RIFF/WEBP 结构中是否包含ANIMchunk |
| 2. 格式转换 | 若为 Animated WebP，用convert input.webp output.gif转为 GIF |
| 3. 构建 FFmpeg 命令 | 对 GIF 输入加-ignore_loop 0 -stream_loop -1 -t endTimeS |
| 4. overlay filter | 加format=auto保留透明通道，enable='between(t,...)'控制显示区间 |
完整命令示例（一个静态 WebP + 一个动态 GIF）：
ffmpeg\-ivideo.mp4\-ilogo.webp\-ignore_loop0-stream_loop-1-t20.0-isticker.gif\-filter_complex" [1:v]scale=450:102[img0]; [0:v][img0]overlay=267:120:format=auto:enable='between(t,0.0,10.0)'[v0]; [2:v]scale=450:450[img1]; [v0][img1]overlay=735:315:format=auto:enable='between(t,10.0,20.0)'[v1] "\-map"[v1]"-map0:a-c:acopy\-b:v6000k\-youtput.mp4注意事项
- ImageMagick 必须含 WebP 支持：安装后用
convert -list format | grep -i webp验证，输出需包含rw（可读写）。 -t参数位置必须在-i之前：-t是输入参数，写在-i后面会变成输出时长限制，语义完全不同。- 静态 WebP 不受影响：只有检测到包含
ANIMchunk 的动态 WebP 才走转换流程，静态图片仍按原流程处理。 - GIF 色彩限制：GIF 最多支持 256 色且不支持半透明（只有全透明/全不透明），转换后颜色可能有损失，这是 GIF 格式本身的局限。若对画质要求高，可考虑将 Animated WebP 转为带透明通道的 WebM（需 FFmpeg 版本支持）。
