用 ffmpeg-skill 把 16:9 视频裁成 1:1 方屏并锁定 CRF 16:一次可复现的 fit.py 实战解析
用 ffmpeg-skill 把 16:9 视频裁成 1:1 方屏并锁定 CRF 16:一次可复现的 fit.py 实战解析
把一个 1280x720 的横屏片段裁成 720x720 的方屏,同时把画质固定在 CRF 16,看起来只是一条 ffmpeg 命令,实际却涉及三个容易出错的判断:裁切中心是否正确、dry-run 与真实执行的滤镜是否一致、以及在"没有交付平台"的前提下该不该继续跑平台检查。本文以仓库中一次真实的 Agent 执行记录 run.md 为主线,完整复盘 probe.py → fit.py --dry-run → fit.py → look.py 四步流程,并结合 scripts/fit.py 与 scripts/_common/decision.py 的源码,解释每一步输出来源与关键参数的边界。
一、任务定义与最终结论
这次任务的原始请求是:把 clip.mp4 裁成方屏,并保持高画质(CRF 16)。在评估集 iteration-24.json 中,该用例编号为 q1,判定为 pass,证据是日志中使用了 fit.py --aspect 1:1 --fit crop --quality 16,且全程没有出现 --crf。
最终产物:
| 项目 | 源文件 clip.mp4 |
输出 clip_square.mp4 |
|---|---|---|
| 时长 | 10.0 s | 10.005 s |
| 分辨率 | 1280x720 | 720x720 |
| 显示宽高比 | 16:9 | 1:1 |
| 帧率 | 30 fps | 30 fps |
| 视频编码 | — | H.264,CRF 16 |
| 音频 | AAC,单声道 | AAC,单声道 |
| 源文件是否被改动 | 否 | 新建文件 |
执行记录中明确写了三条判断依据:没有交付目的地,所以不跑平台检查;画面中心没有偏离的主体,所以采用默认中心裁切;原文件保持不动,结果写入新文件 clip_square.mp4。
二、第一步:用 probe.py 拿到可信输入
任何编辑都不能靠猜。工作流第 1 步要求先用 probe.py 取得时长、帧率、分辨率、编解码器、声道数和 variable_frame_rate_suspected,见 references/workflow.md。本次执行的第一条命令是:
python3 /home/user/ffmpeg-skill/scripts/probe.py clip.mp4 --json
关键输出:
"duration": 10.0,
"video": {"width": 1280, "height": 720, "display_aspect": "16:9", "fps": 30.0, ...},
"audio": {"codec": "aac", "channels": 1}
这几个数字决定了后续所有几何计算:
1280x720是 16:9,目标1:1意味着必须丢弃宽度方向的多余部分,而不是补边;30 fps恒定,说明不需要额外加--fps做 CFR 规整;- 单声道 AAC,说明输出保持一条音轨、用默认 AAC 编码即可,无需
--audio-stream选轨。
probe.py 在这些工具里的角色是"唯一的输入事实来源"。fit.py 内部同样会先调用 probe() 再计算,源码 scripts/fit.py 中 meta = probe(args.input) 之后立刻取 display_size(meta["video"]),而不是直接读容器里的宽高——这一步会把旋转元数据应用上、把非方形像素平方(源码注释指向 #411)。也就是说,即使你不手动 probe,工具也不会基于错误的显示尺寸做裁切。
三、第二步:dry-run 拿命令,但别信汇总行
工作流第 3 步是"用 --dry-run --json 规划,再执行",并且明确要求信任 --json 里的数字而不是汇总行(见 references/workflow.md)。本次执行的第二条命令:
python3 /home/user/ffmpeg-skill/scripts/fit.py clip.mp4 \
--aspect 1:1 --fit crop --quality 16 \
-o clip_square.mp4 --dry-run --json
关键输出:
ffmpeg -vf 'scale=720:720:force_original_aspect_ratio=increase,
crop=720:720:(in_w-out_w)*0.5:(in_h-out_h)*0.5,setsar=1' ... \
-c:v libx264 -preset medium -crf 16 ... clip_square.mp4
[dry-run] would write clip_square.mp4 (0.000s, 0x0)
这里有两点值得注意。
第一,--quality 16 在最终命令行里体现为 -crf 16。这是 2.0 之后的唯一写法:--crf 在 1.8 作为别名引入、1.10 弃用、2.0 移除,--quality 才是跨编码器通用的质量参数名,源码见 scripts/_common/runner.py。同处还定义了取值校验:h264/hevc 的 CRF 上限是 51,AV1 是 63,越界会直接 die() 报错。
第二,would write ... (0.000s, 0x0) 中的 0x0 是占位符,不是真实尺寸。dry-run 阶段没有解码输出,时长和分辨率都无从测得,这正是工作流要求"不要用汇总行的数字做判断"的原因。
四、第三步:真实执行,滤镜会从表达式变成具体数值
去掉 --dry-run 后执行同一条命令:
python3 /home/user/ffmpeg-skill/scripts/fit.py clip.mp4 \
--aspect 1:1 --fit crop --quality 16 \
-o clip_square.mp4 --json
关键输出:
wrote clip_square.mp4 (10.005s, 720x720)
"status": "completed", "verified": true,
"probe": {"duration": 10.005,
"video": {"width": 720, "height": 720, "display_aspect": "1:1",
"fps": 30.0, "codec": "h264"},
"audio": {"codec": "aac", "channels": 1}}
这里的 verified: true 来自工具在写完后重新 probe 自己的输出,而不是"ffmpeg 退出码为 0"就算成功。
为什么真实跑的脚本和 dry-run 打印的不完全一样
dry-run 时源尺寸已知与否决定了 fit.py 走哪条分支。源码 scripts/fit.py 显示:当 sw/sh 已知时,走的是"先算边距、再取偶数偏移"的精确分支:
sc_w = max(out_w, (2 * out_h * sw + sh) // (2 * sh))
sc_h = max(out_h, (2 * out_w * sh + sw) // (2 * sw))
mx, my = (-(-(sc - o) // 4) * 4 for sc, o in ((sc_w, out_w), (sc_h, out_h)))
ox, oy = (int(m * f / 2 + 0.5) * 2 for m, f in ((mx, args.crop_x), (my, args.crop_y)))
vf.append(f"scale={out_w + mx}:{out_h + my}")
vf.append(f"crop={out_w}:{out_h}:{ox}:{oy}")
对 1280x720 → 720x720 代入:缩放后为 1280x720,水平多余 560 px、垂直多余 0 px;560 已是 4 的倍数,--crop-x 默认 0.5 得到偏移 280,且为偶数。于是真实滤镜是 scale=1280:720,crop=720:720:280:0。而 dry-run 打印的 scale=720:720:force_original_aspect_ratio=increase,crop=720:720:(in_w-out_w)*0.5:(in_h-out_h)*0.5 属于"输入尺寸未知(待渲染的中间文件)"分支,它把计算推迟给 ffmpeg 的表达式。
两套写法不是冗余,而是针对不同前提:表达式版本能对任意输入生效,数值版本则能把偏移对齐到色度网格。源码注释解释了为什么必须这么做——crop 会把奇数偏移向下取整到 4:2:0 的色度网格,导致 --crop-x 1 丢掉源画面最后一列、居中裁切偏移一个像素(#512);如果改用 exact=1,色度又会相对亮度偏移半个采样。
输出为什么是 10.005 s 而不是 10.000 s
本次没有传 --duration,所以不存在变速或截断逻辑,整段素材原样保留。0.005 s 的差异来自重新编码后的 AAC 音频帧边界与探针计时,属于编码封装层面的量级;run.md 的最终说明把它表述为"匹配源的时长/帧率/音频,只有画面被裁切",这是准确的表述方式——不要把带小数的时长说成"完全一致",也不要把它当成缺陷去追修。
五、--fit crop 到底做了什么,以及什么时候不该用它
fit.py 的三个 --fit 取值语义完全不同,源码 scripts/fit.py 与 scripts/_common/decision.py 给出了实现:
--fit |
行为 | 代价 |
|---|---|---|
pad(默认) |
等比缩放到框内,剩余区域补 --pad-color(默认黑),或用 --pad-fill blur 填模糊背景 |
不丢画面,但出现黑边/模糊边 |
crop |
等比放大到覆盖目标框,再裁掉多余部分 | 填满画面,但丢边缘内容 |
blur |
整幅画面居中叠在自身模糊压暗的副本上 | 不裁不黑边,但主体变小 |
选择 crop 就是把"丢什么"这个决定显式化。fit.py 的模块文档写得很直白:裁切默认保留中心,而这只是一个猜测;从 16:9 到 9:16 会丢掉大部分宽度,不在中间三分之一的主体(边缘的人、举在一侧的产品)会被切掉;不知道该保留哪边时,--fit pad 永远不会丢东西。
--crop-x / --crop-y 接受 0..1 的归一化锚点(0=左/上,0.5=居中,1=右/下),越界会被 die() 拒绝(源码 scripts/fit.py)。本次执行没有使用它们,理由是第四步的目视检查给出了证据。
另一个容易被忽略的细节:无论哪种 --fit,最后都会追加 setsar=1;如果源本身是非方形像素,square_pixels() 会在滤镜链最前面插入像素平方处理,并在 notes 里说明。这样"按显示宽高比算出来的尺寸"和"写进文件的尺寸"才不会互相矛盾。
六、第四步:用 look.py 做目视确认
工作流第 8 步要求:任何画面变化(裁切、补边、缩放、字幕、叠加、调色、转场)之后都必须跑 look.py 并查看生成的 PNG,见 references/workflow.md。本次命令:
python3 /home/user/ffmpeg-skill/scripts/look.py clip_square.mp4 --tiles 3x2
关键输出:
contact sheet: 6 frames every 1.67s
wrote ./clip_square_sheet.png
look.py 默认是 4x3 的 12 格联系表,--tiles 3x2 表示 3 列 2 行、共 6 帧;它按等分切片并在每片中点取帧(源码 scripts/look.py 中注释说明,这样可以避免首尾的黑场帧),因此 10 s 素材的步长是 1.67 s。
查看 PNG 后的结论是:源画面是合成测试图(彩条、棋盘格、移动斜线),没有可识别的偏心主体,因此中心裁切是正确的,没有切掉有意义的内容。
这条结论的性质很关键。按工作流的划分,目视检查分成两类:
- 机械项(工具自己负责验证并报告):指定文字/logo 是否在指定位置、字幕是否出现在指定时间点、尺寸是否为偶数。
- 判断项(报告,不静默通过或失败):主体或人脸是否被切掉、文字是否压在脸上、颜色是否发灰、转场落点是否合适。
"这个裁切是否切掉了主体"属于判断项,需要先知道"主体是什么"。本次之所以能给出确定结论,是因为源本身就是测试图;如果换成人像素材,正确做法是查看联系表后使用 --crop-x/--crop-y,或者直接问用户要保留哪一边,而不是默认 0.5 就交付。
七、为什么这次没有跑 check.py
这是本次执行里最容易被误判为"漏步骤"的地方。run.md 的 Notes 明确写道:用户没有给交付目的地(没有说"给 Reels/YouTube"等),所以这是一次普通裁切而非导出;按技能工作流,"无目的地 + 普通编辑"意味着保持源格式,因此不跑平台检查。
这条规则来自 references/workflow.md 的 ask/assume 部分:目的地决定宽高比、时长上限、响度和编解码器;没有目的地又只是普通裁切/字幕,就沿用源格式并说明。而 check.py 的平台规格(--platform reels 等)恰恰是在断言"这个文件要投放到某平台",没有目的地却去跑,等于替用户虚构了一个交付约束。
需要区分的是两种场景:
- 有目的地:例如"给 Reels",此时应走
render.py --template reels,模板内部自带检查;或至少执行check.py OUTPUT --platform reels --expect-identity S:M。 - 无目的地但改变了画面:本次属于此类,验证手段是工具的
--json回读 probe 加look.py,不涉及平台规格。
同时要注意,check.py 里 aspect、duration、fps、loudness、resolution 这些行被归为"判断项"(源码 scripts/check.py 附近的 JUDGEMENT 集合),它们变红意味着内容或时长被改变,只有请求本身暗示了这个结果时才应修改。换句话说,即便跑了 check.py,也不能拿它去"自动修正"一次用户只要方屏的裁切。
八、把这次执行抽象成可复用的操作清单
对"把横屏裁成方屏并保持高画质"这一类需求,可以按下面的顺序执行,命令均可直接照搬:
# 1. 读取输入事实
python3 scripts/probe.py clip.mp4 --json
# 2. 规划:看命令与参数,不写文件
python3 scripts/fit.py clip.mp4 --aspect 1:1 --fit crop --quality 16 \
-o clip_square.mp4 --dry-run --json
# 3. 执行
python3 scripts/fit.py clip.mp4 --aspect 1:1 --fit crop --quality 16 \
-o clip_square.mp4 --json
# 4. 目视检查
python3 scripts/look.py clip_square.mp4 --tiles 3x2
其中第 3 步的常用变体:
# 保留右侧主体(例如产品举在画面右方)
python3 scripts/fit.py clip.mp4 --aspect 1:1 --fit crop --crop-x 1 --quality 16 -o out.mp4
# 不确定主体位置时,宁可不裁:补黑边或用模糊背景
python3 scripts/fit.py clip.mp4 --aspect 1:1 --fit pad --quality 16 -o out.mp4
python3 scripts/fit.py clip.mp4 --aspect 1:1 --fit blur --quality 16 -o out.mp4
# 顺带固定到某个精确边长
python3 scripts/fit.py clip.mp4 --aspect 1:1 --fit crop --width 1080 --quality 16 -o out.mp4
关于尺寸推导,源码 scripts/_common/decision.py 中的 frame_size() 是唯一规则,fit.py 与 render.py --export-timeline 写序列帧时共用它:
- 同时给
--width和--height,直接采用两个值(各自取偶); - 只给一个,另一边由宽高比推出;
- 都不给但给了
--aspect,则在不超出源分辨率的前提下套用新比例——源码注释特别指出,从 16:9 源做 9:16 时必须用源高度做上界,否则 1920x1080 会被放大成 1920x3414; - 所有边长都取偶数,避免编码器因奇数尺寸失败。
九、常见坑与规避方式
结合源码与工作流,几个高频错误值得单独列出。
把 --fit crop 当成默认行为。 --fit 的默认值是 pad(源码 scripts/fit.py)。只写 --aspect 1:1 会得到补边的方屏,而不是裁切方屏。本次执行显式写了 --fit crop,这不是冗余参数。
用 --crf 控制质量。 2.0 起 --crf 已移除,应当用 --quality。此外 --quality 的合法区间随编码器变化,h264/hevc 为 0–51、AV1 为 0–63,超范围会被明确拒绝而不是静默截断。
把 CRF 16 理解为"无损"。 帮助文本的表述是"18 在 x264/x265 上视觉无损",16 比 18 更高质量、体积更大,但仍然是 CRF 模式的有损编码。同时 --preset 默认 medium;--fast 会把 preset 覆盖为 veryfast,用于预览而非交付。
忽略偏移的偶数约束。 当 --crop-x/--crop-y 算出的偏移不是偶数时,fit.py 会取最近的偶数并在 notes 里说明实际偏移量与请求值的差距(源码 scripts/fit.py)。看到这类 note 不是报错,而是色度网格约束下的正常行为。
覆盖源文件。 工作流第 7 步明确:永远不要覆盖源文件;已存在的输出路径默认被拒绝(kind: input),只有本次任务自建的文件或用户明确要求替换时才能加 --overwrite。本次输出落在 clip_square.mp4,源文件 clip.mp4 未被触碰。
用汇总行做验收。 dry-run 的 0x0、以及任何未回读的尺寸描述都可能失真。验收依据应是 --json 里的 probe 字段,或独立再跑一次 probe.py。
十、这次执行示范了什么
回到最初的问题:一条"裁成方屏 + CRF 16"的请求,专业做法不是直接拼 ffmpeg,而是把隐性决策显式化——用 probe 确认 16:9 与 30 fps,用 dry-run 看清 scale→crop→setsar=1 的链路和 -crf 16 的落点,用真实执行回读 720x720/10.005 s/H.264/AAC 的事实,用联系表回答"中心裁切是否切掉了主体",最后用"无目的地"这条规则解释为什么没有平台检查。
这四条结论都能在仓库里找到对应证据:scripts/fit.py 定义了几何与编码行为,scripts/_common/decision.py 定义了尺寸与补边规则,references/workflow.md 定义了执行顺序与判断边界,evals/results/iteration-24/q1/with_skill/outputs/run.md 则是这条链路跑在真实素材上的完整记录。照此流程复现,同样的输入与同样的显式参数会得到同样可验证的输出。