ffmpeg-pipeline 是做什么的？
胶水技能。它将生成的（或提供的）静态图片转变为带有旁白的动态 MP4，并处理 Agent 经常遇到的那些琐碎的媒体任务。
需要系统安装 ffmpeg + ffprobe。在提示模式下需要 anon-image，使用 --narration 时需要 anon-audio；两者都会作为同级技能自动发现，如果你使用 --images / --audio 参数传递文件，则两者都是可选的。
命令
| 命令 | 功能说明 |
|---|---|
video | 静态图片（生成或来自 --images）→ MP4，包含缩放平移运动 + 交叉淡入淡出，可选的旁白和背景音乐 |
slideshow | 现有图片 → MP4 |
mux | 将音频轨道附加到视频，循环或填充以匹配时长 |
frames | 每隔 N 秒提取静态帧 |
sheet | 联系表（N 个均匀分布的帧，带时间戳） |
gif | 从任意片段生成裁剪后经调色板优化的 GIF |
normalize | 将音频响度归一化至 −16 LUFS |
speed | 改变音频速度且不改变音高（链式 atempo） |
info | 单行 ffprobe 摘要 |
probe | 依赖检查 |
快速开始
# 一步完成完整流水线：3 张生成图片，每张 4 秒，带旁白
vidkit.py video "暮色中玄武岩悬崖上的灯塔，电影感" -o story.mp4 \
--shots 3 --seconds 4 --ratio 16:9 \
--narration "在一片寒冷的海岸上，一座灯塔坚守着它的守望。" \
--voice en-GB-RyanNeural
# 复用已有的图片
vidkit.py video --images shots/ -o out.mp4 --seconds 3 --music bed.mp3
# 媒体处理
vidkit.py mux clip.mp4 voiceover.mp3 -o final.mp4
vidkit.py sheet final.mp4 -o preview.jpg --cols 4 --count 8
vidkit.py gif final.mp4 -o teaser.gif --start 1 --dur 2.5 --width 480
vidkit.py normalize voiceover.mp3 -o clean.mp3
vidkit.py info final.mp4
时长计算（以便你能预测输出）
设 N 张图片，每张 S 秒，交叉淡入淡出 0.8 秒：
时长 = N*S - (N-1)*0.8
3 × 4 秒 → 10.4 秒。如果旁白长于视频画面，视频会循环以覆盖旁白（-stream_loop）。如果旁白短于视频画面，音频会填充静音，这样你永远不会丢失结尾。两种情况都已处理——不要自己添加 -shortest。
决策规则
- 比例：YouTube/网页用
16:9，Shorts/Reels/TikTok 用9:16，信息流和缩略图用1:1。所有内容都会先缩放填充再裁剪，因此任何形状的源图片都不会出现黑边。 - 每张图片时长：静态图片以 3–4 秒为宜；超过 6 秒的静态图像会显得死板。如果需要更长的播放时间，应增加图片数量而非时长。
- 背景音乐：传入
--music，它会以 12% 的音量混合在语音之下。不要将两个大音量音源混在一起；请先进行归一化。 - GIF：保持宽度 ≤ 480 且时长 ≤ 3 秒，否则文件会超出聊天限制。
失败模式
| 症状 | 原因 | 修复方法 |
|---|---|---|
missing dependency: ffmpeg | 未安装 | apt install ffmpeg（或 brew install ffmpeg） |
ffmpeg failed: … Invalid argument 出现在 zoompan | 源图像尺寸为奇数 | 滤镜已自动缩放到 W*2；如果你修改了它，请保持偶数尺寸 |
| 输出无声 | 旁白文件缺失/为空 | 检查路径；--narration 接受文本或音频文件路径 |
| 输出远短于预期 | 音频比视频短，且某处添加了 -shortest | 移除它；vidkit.py 使用填充方式 |
contact sheet needs Pillow | 缺少 Pillow 库 | pip install pillow，或使用 frames 命令再加自己的联系表工具 |
给 Agent 的提示
- 除非用户明确要求更高分辨率，否则以 720p 渲染。这样速度快 4 倍，且在笔记本电脑屏幕上无人能察觉差异。
- 始终对最终产物运行
info命令，并将实际的时长、分辨率和大小反馈给用户——这能捕捉到静默失败。 - 交付 MP4 文件路径；不要将其嵌入。文件本身即是产物。