ffmpeg

FFmpeg

通过 ffmpeg 和 ffprobe 对本地音视频进行检查和转换的 CLI 技能。调用方式：/ffmpeg。

**范围：**检查元数据、剪辑片段、转码容器/编解码器、拼接片段、提取音频、截取缩略图，以及从磁盘上的文件制作 GIF 预览。不适用于 AI 图像或视频生成（draw-thing）、UI 或布局设计（design）、网络下载（yt-dlp）或广播/流媒体工作流。

---

标准术语

术语	含义	不包括
probe	只读的 ffprobe 检查	转码
trim	按时间范围缩短	裁剪 UI 模型图
transcode	重新封装或重新编码为新的容器/编解码器	生成新图像
concat	按顺序拼接多个输入	合并 git 分支
extract-audio	去除视频，保留音轨	语音转文本
thumbnail	从视频中截取单帧静态图像	设计海报布局
gif	根据视频片段制作 GIF 动图预览	CSS 动画
stream copy	使用 -c copy，不重新编码	对所有剪辑都安全
recipe	references/ 中经批准的命令模板	临时拼凑的滤镜图

---

分发

$ARGUMENTS	模式	操作
doctor / check / preflight	Doctor	运行 PATH 检查；若缺少 ffmpeg/ffprobe，则停止
probe <path> / info <path> / metadata <path>	Probe	运行检查辅助程序；汇总流信息和时长
trim <path> <start> <end> / clip <path> ...	Trim	检查媒体，选择复制或重新编码方案，并指定新的输出路径
transcode <path> / convert <path> to mp4	Transcode	检查编解码器；应用 H.264/AAC 或复制方案
concat <file1> <file2> [...] / join ...	Concat	验证检查结果；使用 concat 解复用器方案并指定新的输出路径
extract-audio <path> / audio <path>	Extract audio	检查音频流；使用 MP3/M4A/复制方案
thumbnail <path> / thumb <path> [timestamp]	Thumbnail	定位视频帧；将 JPG/PNG 写入新路径
gif <path> / animate <path> [start] [duration]	GIF	使用带时长上限的调色板 GIF 方案
媒体路径 + 自然语言编辑意图	Auto	根据意图分类为 trim/transcode/thumbnail/gif
(empty)	Help	显示模式、关键规则、脚本命令和参考资料

自动检测启发式规则

1. 不确定是否已安装/工具是否可用 → Doctor。
2. “metadata”“codec”“duration”“how long”“what format” → Probe。
3. “cut”“clip”“from ... to ...”、时间范围 → Trim。
4. “mp4”“webm”“h264”“aac”“smaller”“compress” → Transcode。
5. “join”“merge clips”“append videos” → Concat。
6. “mp3”“wav”“m4a”“strip video”“audio only” → Extract audio。
7. “poster frame”“screenshot”“still”“thumbnail” → Thumbnail。
8. “gif”“animated preview” → GIF。
9. 生成式图像/视频相关请求 → 拒绝；引导至 draw-thing。
10. UI/页面/布局设计 → 拒绝；引导至 design。
11. 意图不明确 → 询问用户需要哪种模式，并说明复制与重新编码之间的权衡。

---

关键规则

1. 修改前先检查——在 trim、transcode、concat、extract-audio、thumbnail 或 gif 操作前，对每个源文件运行 probe_media.py。使用检查字段选择映射、编解码器和时长边界。参见 references/probe-fields.md。
2. 默认绝不原地覆盖——始终写入新的输出路径。原地替换须经用户明确批准，并先备份或使用临时文件替换。参见 references/safety.md。
3. 仅使用方案进行修改——只能根据 references/recipes-trim-transcode.md 和 references/recipes-thumbnail-gif.md 构建 ffmpeg 命令。未经批准，不得自行编写滤镜链或执行破坏性批处理。

---

前置要求协议

执行任何修改前：

uv run python scripts/doctor.py --format json

如果 JSON 中的 ok 为 false，则停止。安装指引：

brew install ffmpeg

对每个输入文件：

uv run python scripts/probe_media.py /absolute/path/to/input.mp4

选择方案前，解析 summary.duration_seconds、summary.stream_counts 和编解码器字段。

---

模式协议

Doctor

1. 运行 uv run python scripts/doctor.py --format json。
2. 报告 checks 的状态，并说明所有 fail 的修复方法。
3. 如果 ffmpeg-binary 或 ffprobe-binary 失败，不要运行会修改文件的 ffmpeg 操作。

Probe

1. 要求提供可读取的本地文件路径。
2. 运行 uv run python scripts/probe_media.py <path>。
3. 总结：容器、时长、视频／音频编码、分辨率、流数量。
4. 解读旋转、多轨音频或字幕流时，加载 references/probe-fields.md。

Trim

1. 探测源文件；根据 duration_seconds 验证 start／end。
2. 关键帧对齐可接受时，优先使用流复制；否则使用重新编码裁剪方案。
3. 输出到 basename.trim.ext 或用户提供的新路径。
4. 加载 references/recipes-trim-transcode.md。

Transcode

1. 探测源文件；决定使用流复制还是 H.264/AAC 重新编码。
2. 存在多条轨道时，显式映射流。
3. 用于 MP4 网页交付时，加入 -movflags +faststart，除非用户禁止。
4. 加载 references/recipes-trim-transcode.md。

Concat

1. 探测每个片段；确认使用流复制拼接时编码和分辨率兼容。
2. 使用绝对路径构建拼接列表文件；未经警告，不要使用流复制拼接编码不相关的文件。
3. 输出到新的 *.concat.mp4 路径。
4. 加载 references/recipes-trim-transcode.md。

Extract audio

1. 探测源文件；当 stream_counts.audio 为零时，妥善处理并停止。
2. 根据目标格式选择 MP3、M4A 或复制方案。
3. 将 basename.audio.ext 写入新文件。
4. 加载 references/recipes-trim-transcode.md。

Thumbnail

1. 探测源文件；要求至少有一条视频流。
2. 选择时间戳（用户指定的值，或时长的 10%，限制在 1–10 秒）。
3. 将 JPG/PNG 写入 OUTPUT/ 或同级路径——绝不覆盖源文件。
4. 加载 references/recipes-thumbnail-gif.md。

GIF

1. 探测源文件；限制时长（默认最长 5 秒，除非用户要求延长）。
2. 为保证质量，使用两遍调色板方案；仅快速预览时才使用单遍方案。
3. 将 clip.gif 和可选的 palette.png 写入新文件。
4. 加载 references/recipes-thumbnail-gif.md。

Help (empty)

显示分派表、关键规则、doctor/probe 命令、参考资料索引和下方的图库。

Gallery (Empty Arguments)

当 $ARGUMENTS 为空时，展示常见的本地媒体任务：

#	任务	示例
1	预检工具	/ffmpeg doctor
2	检查元数据	/ffmpeg probe ~/Movies/clip.mp4
3	裁剪片段	/ffmpeg trim ~/Movies/clip.mp4 00:00:05 00:00:15
4	转码容器	/ffmpeg transcode ~/Movies/clip.mov
5	拼接片段	/ffmpeg concat part1.mp4 part2.mp4
6	提取音频	/ffmpeg extract-audio ~/Movies/clip.mp4
7	视频海报帧	/ffmpeg thumbnail ~/Movies/clip.mp4 00:00:03
8	GIF 预览	/ffmpeg gif ~/Movies/clip.mp4 00:00:02 4

选择一个编号、分派表中的模式，或粘贴文件路径并描述要进行的编辑。

---

Skill Awareness

信号	转至
“生成图像”、“txt2img”、“AI 视频”、本地 Draw Things	draw-thing
“设计落地页”、“Figma”、“React 布局”	design
“从 YouTube/URL 下载”	yt-dlp
直播、RTMP、OBS 配置	超出范围——建议查阅直播文档

---

Reference Files

文件	加载时机
references/safety.md	任何修改操作；有关原地覆盖的问题
references/probe-fields.md	解读探测 JSON
references/recipes-trim-transcode.md	trim、transcode、concat、extract-audio
references/recipes-thumbnail-gif.md	thumbnail、gif

---

Scripts

脚本	用途
scripts/doctor.py	验证 PATH 中的 ffmpeg/ffprobe（--format json）
scripts/probe_media.py	ffprobe 封装器并提供摘要（使用 --raw 获取完整数据）
scripts/check.py	验证 SKILL.md、evals、软件包试运行和审计

验证：

uv run python scripts/check.py

---

报告模板

每次修改后，报告：

1. Doctor 状态（如果本次会话中运行过）
2. 探测摘要（时长、编解码器、流）
3. 方案名称（复制或重新编码）
4. 执行的确切 ffmpeg 命令
5. 输出路径和大小变化
6. 注意事项（关键帧剪辑、缺少音频、GIF 时长上限）