ffmpeg-skill
脚本位于此文件旁边的 scripts/ 目录中;使用 python3 <skill-dir>/scripts/<name>.py 运行它们,交付模板位于 templates/ 目录中。本文档足以完成工作:下面的表格将路由请求,即将运行的脚本的 --help 是最简单的完整标志列表。参考文件的成本与此文件相同;仅在遇到问题时打开一个:references/scripts.md(所有 42 个脚本的每个标志)、references/devices.md(iPhone HDR、GoPro、DJI、屏幕录制、Zoom)、references/gotchas.md(末尾单行规则的详细形式)。MCP:tools/list 默认仅显示核心的 12 个工具;其他 30 个(根据此表)可通过名称使用 tools/call 调用,由 contract --json 描述;设置 FFMPEG_SKILL_MCP_FULL=1 可看到全部 42 个。
所有脚本共享的标志:--dry-run;--json(输出路径、输出探查、运行的命令);--json-brief(状态/输出/已验证加上 summary;在写入步骤上优先使用);--fast(预览质量);--progress;--timeout SECONDS(kind: timeout,默认 1800);--overwrite(步骤 7);--plan FILE(干运行作为稍后由 render.py FILE 运行的计划;如果输入发生变化则拒绝)。重新编码工具还接受 --codec h264|hevc|av1|prores 和 --quality N:未设置时,SDR 使用 x264,HDR 使用 x265 Main10;prores 需要 -o NAME.mov,h264 拒绝 HDR(首先使用 color.py --to-sdr)。
写入工具在 --dry-run 下不运行任何操作;测量工具(probe、check、sync、multicam、scenes、cropdetect、report、silence、loudness、stabilize)可能仍然运行 ffmpeg/ffprobe,但跳过工件/侧文件(--edl、--sheet、生成的 .ass);verify 忽略该标志。每个工具:contract --json dry_run。
工作流程(按此顺序)
- 仅当失败时,检查环境。 永远不要以
doctor开始一个任务:损坏的机器会以kind: missing_tool或命名过滤器/编码器的 ffmpeg 错误信息失败。在这种失败之后,或者当被问及机器能做什么时,运行python3 <skill-dir>/scripts/_contract.py doctor(或npx ffmpeg-skill doctor):读取ok/usable,报告缺失的能力。contract --json的工具模式是针对规划代理的,而不是此工作流程。 - 探测你需要规划的内容。 在每个你计划使用的输入上运行
probe.py——时长、帧率、分辨率、编解码器、声道、variable_frame_rate_suspected——以及每当用户询问文件时。不要在每次编辑前都单独探测:每个写入工具的--json已经携带了其输入和输出的探查。根据真实数字进行规划,永远不要根据假设。 - 优先无损操作。 如果请求可以在不重新编码的情况下满足(在关键帧上的简单剪切、重新封装、仅音频更改),则不要重新编码。
cut.py和loudness.py默认流复制视频;仅在需要帧精确剪切时才在cut.py上使用--accurate。 - 使用
--dry-run --json进行规划,然后执行。 计划中的任何数字(那里的尺寸可能是占位符)都要相信--json,而不是干运行的摘要行。在长时间编码前使用,以报告事实。--fast是预览质量,--progress在 stderr 上打印百分比/ETA。除非用户要求替换,否则永远不要将-o指向你在此任务中未创建的文件;仅在这种情况下传递--overwrite。 - 按合理顺序链式处理。 一个没有其他编辑的交付请求是一次模板运行(
render.py --template NAME INPUT),而不是手动构建的链。否则:颜色(HDR→SDR / LUT) → 剪切 → 拼接 → 静音 → 适配 → 字幕/叠加 → 同步 → 音频 → 响度 → 导出。在字幕之前进行帧更改,以便文本根据最终帧调整大小。尽可能少地重新编码:中间件使用 CRF 18,export.py最后。三个或更多步骤:使用 project.json 的render.py。 - 检查可交付物。 在报告之前,为目标命名的平台运行
check.py OUTPUT --platform X(模板运行已自动执行)。格式行(编解码器、像素格式、大小、真实峰值、颜色标签、VFR)是可以安全修复的。判断行会改变内容:时长(剪切丢失素材)、宽高比(裁剪丢失边缘)、帧率(丢失动态)、响度(不得提升环境声音)——仅在请求隐含答案时修复,否则说明选择及其代价。提及 WARN;不要追逐它们。 - 验证输出。 从写入工具的
--json/--json-brief探查或probe.py确认时长、分辨率、帧率和音频与请求匹配,并报告这些数字("final.mp4: 59.98 s, 1080x1920, 30 fps, AAC stereo")。只有当脚本以 0 退出并且输出探查符合预期时,该步骤才算完成:非零退出、文件缺失或为空、或与请求矛盾的探查都是失败,需报告脚本的错误信息。 - 保留用户的原始文件。 永远不要覆盖源文件;在输入旁边或用户要求的位置写入新文件。已存在的输出路径将被拒绝(
kind: input);--overwrite是表示“是的,替换它”的唯一方式。 - 查看画面。 每当画面发生变化时(字幕、叠加、图形、裁剪/填充、调整大小、颜色、过渡、
join.py将剪辑缩放到第一个剪辑的帧、color.py --to-sdr),运行look.py OUTPUT --tiles 3x2(或--at T获取一帧)并查看 PNG(整个剪辑布局使用 4x3)。直到Look:命名了该 PNG 才算完成——探查无法看到人脸上的字幕。仅音频:Look: not needed。要查看的内容类似于步骤 5 中check.py的行:- 机械性(此技能自身验证和报告的责任): 指定的文本/Logo 位于指定位置,字幕出现在指定时间戳,尺寸为偶数。来自
fit.py --fit pad的加信箱是正确的该模式结果,绝不是需要标记的缺陷。 - 判断性(报告它,不要静默地通过或失败): 主体或人脸是否被裁剪,文本是否覆盖在人脸上,颜色是否看起来发白,过渡是否着陆。这些需要决定主体是什么,由调用代理决定——用一行描述你看到的;他们来判断。
如果没有视觉能力,写入
Look: PATH (pixels not inspected; agent has no image view)——永远不要声称检查了画面而实际上没有检查,也不要为不存在的能力而停滞。
- 机械性(此技能自身验证和报告的责任): 指定的文本/Logo 位于指定位置,字幕出现在指定时间戳,尺寸为偶数。来自
在运行任何操作之前:问什么,假设什么
仅当答案会实质性地改变输出并且请求没有暗示答案时,才问一个简短的问题。当多个事项同时开放时(模糊的“为社交媒体制作”留下了目标平台、宽高比、长度和字幕),不要每轮问一个:提出一个包含你的默认值的组合包,并让用户更改任何部分("Reels: 9:16 填充, 60 秒, -14 LUFS, 无字幕 — 可以吗?")。一个问题,一个答案,然后运行。永远不要问 probe.py 可以告诉你的内容。
- 目标平台决定了宽高比、长度限制、响度和编解码器;"for Reels" 回答了所有四个问题并命名了一个模板。没有目标平台且是简单的剪切/字幕:保持源格式并说明。如果用户说“导出”、“发布”或“交付”,询问具体平台。
- 时长("make it 60 s")没有指定方法:对于 ≤1.5× 的变化使用加速,否则使用修剪,并说明选择。当内容是演讲(修剪会丢失词语)且变化较大时,需要询问。
- 字幕没有文本来源:如果存在本地的 whisper,使用
--transcribe,否则要求提供文本或带时间的文件;永远不要发明对话。 - 字体和品牌:如果用户提到品牌、颜色或“我们的字体”,要求创建
brand.json一次,然后重复使用。 - CJK / 非拉丁文本:让工具根据文字自动选择字体(
--font会关闭此功能);仅汉字文本使用--lang ja|ko。doctor --json.fonts.scripts会说明此处渲染什么。Tofu(方块字)是失败的任务。 - 裁剪位置用于
--fit crop:默认居中,但当请求或源文本命名了偏离中心的主体时(“保持产品在右侧”,联系表中某人明显偏离中心),使用--crop-x/--crop-y(0=左/顶,1=右/底)而不是猜测中心,或者询问保留哪条边。 - 其他任何内容(过渡类型、字幕样式):选择常规默认值,说明你选择的,用一行提供替代选项。
此技能决定和不决定的内容
此技能剪切、拼接、测量、同步、导出和检查文件——它执行编辑,但不会决定编辑。属于人类、调用代理或另一个技能的内容:
- 哪个剪切是正确的,或者可交付物是否可批准——此技能测量并报告(
check.py的 PASS/WARN/FAIL,cut.py的时长误差);用户或制作代理决定是否交付。 - 什么使一个精彩片段有趣——
scenes.py --highlights通过测量的代理指标(音频能量、时长)进行排名:候选,而不是最终判断。 - 缩略图或封面构图——设计决策,而非测量。
- 理解视频是关于什么的——除了
look.py的联系表供调用代理查看外,这里没有视觉能力让此技能进行解释。 - 判断什么看起来好看——“应用此 LUT”、“将曝光增加 +0.3 档”(
color.py)是机械操作;“将此场景调色成电影感”属于一个调色技能(color-grading-skill)来决定参数,然后调用color.py。 - 字幕中的词语——提示文本原样刻录。对于帧来说太长意味着更小的尺寸、
--max-lines或用户自己的编辑;永远不要重写、缩短或转述它,即使被要求“使其合适”——说明情况,提供更小尺寸的--max-lines 1。 - 挑选未提供给你的主体或区域——“裁剪到 x=200,y=0”一旦知道边界框就是机械操作;“裁剪以将说话者保持在画面中”需要决定说话者是什么,这是调用代理的判断(来自
look.py联系表)。
界线:相同的输入 + 相同的显式参数总是产生相同的可验证输出属于此处;任何取决于品味、理解或看起来/听起来好不好的内容属于做出该判断的人。
如果请求需要 42 个脚本中未公开的 FFmpeg 功能,请说明并提供最近的内置选项——永远不要猜测 scripts/*.py 之外的原始 ffmpeg/ffprobe 调用。这会绕过此技能所做的所有保证,因此永远不要在用脚本的标志无法覆盖某些内容时将其作为后备方案。
请求 → 脚本
此表和 doctor --json 的 tools 列表是存在的工具的真实来源:仅命名你在这两者之一中看到的脚本(没有 doctor.py、没有 trim.py、没有 subtitle.py)。
时间戳标志(--start、--end、--at、--from、--duration、--offset,以及提示和章节文件中的时间)接受秒、mm:ss(.fff)、hh:mm:ss(.fff) 或带 @fps 的 SMPTE hh:mm:ss:ff(00:01:02:[email protected])——按原样粘贴 NLE 提示单;长度标志(--min-silence、--margin、--fade)为简单秒数。
| 用户说 | 操作 |
|---|---|
| "从 1:20 剪到 2:05","剪掉前 10 秒" | cut.py input.mp4 --start 1:20 --end 2:05 |
| "只保留这些部分","删掉中间部分" | cut.py input.mp4 --segments 0-1:00,1:30-2:00 |
| "让它正好 60 秒" | fit.py input.mp4 --duration 60(加速)或 --method trim |
| "剪切这个并转为 HEVC / AV1 / ProRes"(输出编解码器已命名) | cut.py input.mp4 --start 0:10 --end 0:40 --codec hevc(任何重新编码工具上的 --codec/--quality;ProRes 需要 -o NAME.mov) |
| "剪掉停顿","跳剪" | silence.py input.mp4 [--threshold -40 --min-silence 0.8] |
| "剪掉嗯和呃","移除填充词" | silence.py input.mp4 --filler --words words.json(测量的词语时间;--transcribe 生成它们) |
| "不要剪句子内部,只剪真正的停顿" | silence.py input.mp4 --speech-aware——句子内部低于 --min-silence 的气口被保留,只剪切句子边界的停顿;与 --filler 组合成一个列表 |
| "从这个小时的素材中提取一个 60 秒的精彩集锦" | scenes.py long.mp4 --highlights 6 --target 60 --edl picks.txt → cut.py --segments |
| "在节拍上剪辑","让编辑贴合音乐" | scenes.py track.mp4 --beats --json > beats.json,然后 cut.py input.mp4 --segments ... --snap beats --snap-source beats.json(--snap-source 携带测量的网格) |
| "这里加速,那里慢动作"(已知片段) | speedramp.py action.mp4 --segment 0-3:1.0 --segment 3-4:0.25 --segment 4-8:2.0 |
| "保持这一帧","冻结最后一帧" | freeze.py clip.mp4 --hold 2 |
| "平滑慢动作","半速但流畅" | fit.py input.mp4 --duration 2x --smooth interpolate(慢)或 --smooth blend |
| "反转这个片段" | reverse.py input.mp4 |
| "循环这个片段以填满 30 秒" | loop.py bg_loop.mp4 --duration 30 |
| "把它变成竖屏 / 9:16 / 方形" | fit.py input.mp4 --aspect 9:16 --fit pad(或 --fit crop;--pad-fill blur 用于模糊条) |
| "调整尺寸到某个高度/宽度" | fit.py input.mp4 --height 1080(或 --width,或两者都用于精确帧) |
| "裁剪到这个精确的框"(已知 x/y/w/h) | crop.py input.mp4 --x 100 --y 0 --width 1080 --height 1920 |
| "用模糊背景代替黑条" | fit.py input.mp4 --aspect 9:16 --fit blur(保留整个画面,边框为模糊、变暗的副本) |
| "旋转 90 度","镜像它" | fit.py input.mp4 --rotate 90 / fit.py input.mp4 --flip h |
| "地平线歪了"(已知度数) | straighten.py tilted.mp4 --degrees -2.5 |
| "从这个 360 视频中提取平面视图"(已知偏航/俯仰/视场) | sphere.py insta360.mp4 --yaw 90 --pitch 0 --h-fov 100 --v-fov 70 |
| "这段旧素材是隔行扫描的" | deinterlace.py input.mp4 |
| "画面有颗粒感/噪点,清理一下" | denoise.py input.mp4 --strength medium |
| "模糊/马赛克处理这个人脸/车牌"(已知框) | redact.py input.mp4 --x 820 --y 140 --width 240 --height 240 --mode pixelate |
| "稳定这个晃动的素材" | stabilize.py input.mp4 |
| "这个上面有黑条吗?" | cropdetect.py input.mp4 |
| "iPhone Dolby Vision 片段看起来不对" | color.py clip.mov --to-sdr 或 --strip-dovi(保持 HDR,删除 DV 层) |
| "颜色看起来发白 / iPhone HDR" | color.py input.mp4 --to-sdr |