beatcut 是做什么的?
beatcut 可以将一个素材夹中的视频片段和一个音乐文件,转换为帧精确地落在节拍上的视频。项目状态保存在项目文件夹下的两个文件中:project.json(设置)和 shots.json(剪辑表)。命令行工具是 beatcut.py。
路径
使用已安装依赖的 Python 运行命令(pip install -r requirements.txt;ffmpeg 和 ffprobe 必须在 PATH 中)。将本 skill 所在的文件夹作为仓库文件夹:
python <skill 文件夹>/beatcut.py <命令> ...
下文中的 beatcut.py 即指该完整路径。素材和项目的路径可以是任意位置;如果包含空格,请用引号括起来。项目始终位于 <素材文件夹>/beatcut;除 init 和 sheet 外的所有命令都使用该项目文件夹。
工作流
- 询问缺失什么:素材文件夹、音乐文件以及输出尺寸(默认草稿为 1920x1080,最终为 3840x2160;垂直尺寸如 1080x1920 也可以)。
- 初始化:
beatcut.py init <素材文件夹> --music <音乐文件>。它会打印created: <文件夹>并将音乐复制到项目中。如果显示project.json already exists,表示项目已存在;请使用它,不要重新初始化。如需更改尺寸、fill、fps、encoder、exclude_prefix或自定义profiles,请编辑project.json(参见下方规则)。 - 节拍检测:
beatcut.py beats <项目>。它会打印period、t0和bpm,并将它们写入shots.json。检测假设节拍稳定,t0可能会有百分之几秒的误差。如果退出码为 1 并显示fewer than 4 beats were detected,则手动设置period和t0(period = 60 / BPM;t0 = 第一个节拍所在的秒数)。告诉用户这些数字,他们可以在选择器中修正。 - 选择镜头,两种方式之一:
- 选择器(默认)。 在后台启动
beatcut.py pick <项目>(它会阻塞直到停止;默认打开浏览器,除非添加--no-open;默认端口 8765,通过--port N修改)。将打印的 URLhttp://127.0.0.1:<port>/告诉用户,并说明页面会自动保存。等待用户表示完成,然后停止服务器(Ctrl+C 或结束后台进程)并读取shots.json。选择器打开时不要编辑shots.json,否则页面会覆盖您的更改。 - 手动编辑,当用户要求您构建剪辑表或给出精确时间时。遵循下方规则,然后运行
check。
- 选择器(默认)。 在后台启动
- 检查:
beatcut.py check <项目>。退出码为 0 并显示ok: <n> shots, <s> s表示没有错误;同时读取警告(stderr)。修复所有错误后再进行渲染。 - 草稿:
beatcut.py draft <项目>。它会打印encoder: ...、segment i/n,最后是out/<out_name>_draft.mp4的路径。 - 查看草稿:
beatcut.py sheet <视频> --out <某个.jpg 路径>会生成一个 5 行 4 列的联系表;打开该图像并向用户描述结果(镜头顺序、颜色、淡入淡出、黑帧、裁剪错误)。选择素材文件夹外的--out路径,例如一个临时文件夹。 - 最终渲染,仅需用户批准:展示草稿后,询问是否渲染最终版。只有在用户明确同意后才运行
beatcut.py final <项目>。最终版更慢、文件更大。报告输出路径。
如果用户之后修改了剪辑表,请回到步骤 4。渲染会复用缓存的片段,因此第二次草稿会更快。
手动编辑 shots.json
确保文件是有效的 JSON(UTF-8 编码)。check 会报告所有违反以下规则的情况。
顶层结构:
version:1。period:数字,大于 0.05 且小于 10。t0:数字,大于等于 0。tail:0 到 30(默认 1.5)。shots:列表,最多 2000 个。- 可选:
bad(剪辑名称到{"a": s, "b": s, "note": ""}的列表,要求b > a >= 0)、clipnotes(剪辑名称到文本)、markers({"beat": int >= 0, "title": text};仅在选择器中显示)。保留您不知道的键;工具会保留它们。
每个镜头:
clip:文件名(含扩展名),与素材文件夹中的名称一致。不能包含/、\或:。必须是clips_dir下的直接文件,且匹配extensions。in(大于等于 0)和out(大于in):源剪辑中的秒数。beats:1 到 512 之间的整数。- 可选字段及默认值:
fit(fit或cut;默认fit)、interp(oflow、blend、none;不设置则自动)、prof(内置名称neutral、warm、cool、contrast、golden,或project.json中profiles定义的名称;默认neutral)、tin(cut、fade、fadewhite;默认cut)、tdur(0 到 5 秒,默认 0.5)、note(文本,最多 2000 字符)。
数字的使用方式:
- 镜头依次播放;第 N 个镜头占据从
t0 + period * (前面所有镜头的节拍之和)开始的beats个节拍。第一个镜头从视频帧 0 开始,对应其in点,因此它也覆盖了第一个节拍之前的时间,并会读取到其out之后。 fit:速度 =(out - in) / (beats * period)。速度在 0.015 以内接近 1 则视为 1。check会拒绝速度超出 0.1x 到 8x 范围的镜头。若要使镜头在fit模式下保持正常速度,设置out = in + beats * period。cut:以 1x 速度播放;out不用于计算速度(选择器会写入out = in + beats * period)。请同样处理。- 最后一个镜头会延长
tail秒,画面在tail时间内淡出。整个剪辑表不能长于音乐。 - 每个镜头需要足够的源素材直到其结束(包括
tail和第一个镜头的超前量),且源素材结尾前要有 0.1 秒的余量。fade或fadewhite转场从相邻镜头各借用一半长度,因此前面的镜头需要超过其out的源素材,后面的镜头需要在其in之前的源素材。 - 转场必须短于其两侧的镜头。
tdur会四舍五入为偶数帧;少于 2 帧则视为普通硬切。 - 慢动作:仅当镜头播放速度低于 0.97x 且源帧率乘以速度低于输出帧率时,才会自动进行插帧(草稿中为
blend,最终版中为oflow)。除非用户要求,否则不要设置interp。 - 选择
in/out时,确保范围不与bad范围重叠;check会在重叠时发出警告。
project.json 规则(当您修改它时):
- 未知键会报错。
music相对于项目文件夹,不能包含..,不是绝对路径。draft和final为{"width": n, "height": n},其中 n 为正偶数。fps为字符串,例如"25"或"30000/1001"。fill:cover或blur。encoder:auto、cpu或nvenc。loudness:-40 到 -5。 profiles:名称([a-z0-9_-],1 到 32 个字符)对应一条 ffmpeg 滤镜链,不能包含;、[或]。镜头仅通过名称引用配置文件。
消息及处理方式
警告以 warning: 开头,不会阻止渲染。错误以 error: 开头,输出到 stderr。
| 消息 | 含义与操作 |
|---|---|
ffmpeg was not found on PATH; install FFmpeg and try again (exit 2) | ffmpeg 或 ffprobe 不在 PATH 中。请用户安装 FFmpeg;除非用户要求,否则不要自行安装。 |
no project.json in <folder> (did you mean <folder>\beatcut?) (exit 1) | 您传入了素材文件夹。请使用其内部的 beatcut 文件夹。 |
unknown key(s): ...、<field>: must be ... | project.json 中的字段无效。请修正该字段。 |
<path>: invalid JSON (...)(<path> 是 shots.json 的完整路径) | 文件存在语法错误。请修正;之前的版本可能在 shots.json.bak 中。 |
shots[i].<field>: must be ... | 镜头违反了上述规则(i 从 0 开始计数)。请修正。 |
no shots | shots 为空。请添加镜头(使用选择器或手动编辑)。 |
shot N (clip): clip not found in the clips folder | 文件名错误、文件缺失,或被 extensions 或 exclude_prefix 排除。请检查拼写;切勿创建或复制文件到素材文件夹来解决问题。 |
shot N (clip): needs source up to X s but the clip is Y s long | 范围加上超前量、尾部或转场超出了剪辑的时长。请将 in 提前、减少节拍数、使用 fit 并缩短 out,或缩短转场。 |
shot N (clip): needs X s before the start of the clip; move `in` later | 第一个镜头的超前量或转场到达了 0 秒之前。请增大 in 或缩短转场。 |
shot N (clip): shorter than its transitions; ... | 转场比镜头本身还长。请减小 tdur 或增加节拍数。 |
shot N (clip): speed X is outside 0.1x-8.0x | 范围与节拍数不匹配。请修改 beats 或范围。 |
the edit is X s long but the music is only Y s | 剪辑表比音乐长。请移除节拍或镜头、减小 tail,或使用更长的音乐文件。 |
warning: shot N (clip): uses a range marked bad (...) | 镜头与 bad 范围重叠。请移动镜头,或告知用户。 |
warning: <clip>: HDR source (...); colours will look washed out ... | HDR 素材;beatcut 无法进行色调映射。请告知用户并建议使用 SDR 素材。 |
warning: <clip>: cannot be read (...) | ffprobe 无法读取该素材。请告知用户。 |
music file not found: <name> | music 文件在项目文件夹中缺失。 |
profile <name>: ffmpeg rejects the filter chain | 自定义配置文件错误。请修正 project.json 中的滤镜链。 |
too many shots to assemble in one pass (N); split the edit | 剪辑表太长,无法一次渲染。请告知用户,将其拆分为多个项目或减少镜头数量。 |
another render is already running for this project (exit 2) | 渲染正在进行中(可能从选择器启动)。请等待,不要删除 work/ 目录。 |
cannot write <file>; close it in any player and try again | 输出文件正在其他地方打开。请用户关闭它。 |
fewer than 4 beats were detected; set period and t0 by hand (exit 1) | 参见步骤 3。 |
退出码:0 成功,1 用户输入问题(修正后重新运行),2 环境或运行时错误。
禁止操作
- 不要修改、移动、重命名或删除源素材,也不要向素材文件夹中写入除
init创建的beatcut项目文件夹外的任何内容。工具写入的所有内容都在项目文件夹内。 - 不要删除
project.json、shots.json或音乐文件。不要在已有项目上再次运行init。 - 不要在用户查看草稿并批准前运行
final。 - 不要将选择器暴露到网络:不要进行端口转发、隧道、反向代理,也不要尝试将其绑定到其他地址。它仅监听
127.0.0.1,且对同一台计算机上的其他程序没有保护。 - 不要将滤镜链放入
shots.json,也不要在选择器运行时编辑shots.json。 - 在未查看草稿(联系表或视频本身)之前,不要声称结果良好。
- 不要承诺工具不具备的功能:不支持 HDR 色调映射、人脸检测、CapCut 导出、音效。Linux 和 macOS 未经过测试;Windows 是经过测试的平台。