Communitygithub.com

beatcut

从素材夹中按音乐节拍剪辑短视频,支持项目初始化、节拍检测、镜头选择、草稿渲染和最终输出。覆盖从核对缺失文件到用户审核完成的完整工作流。

beatcut 是什么?

beatcut 是一个命令行工具,帮助用户将一段音乐和多个视频片段自动同步到节拍上,生成帧精确的剪辑视频。该技能涵盖了完整的工作流:首先初始化项目(包含剪辑文件夹和音乐文件),然后检测音乐节拍并将节拍网格写入 shots.json。接着,用户可以通过本地浏览器中的镜头选择器手动挑选每个镜头的入/出点和节拍数,或直接编辑 shots.json 文件。完成后,使用 check 命令验证编辑的有效性,然后渲染草稿(draft)视频。用户可以使用 contact sheet 检查视频帧,只有在用户明确批准后,才能进行最终的高质量渲染。该技能支持 Windows 平台,在 Linux 和 macOS 上未经验证。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/faruk76150/beatcut/tree/main

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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 外的所有命令都使用该项目文件夹。

工作流

  1. 询问缺失什么:素材文件夹、音乐文件以及输出尺寸(默认草稿为 1920x1080,最终为 3840x2160;垂直尺寸如 1080x1920 也可以)。
  2. 初始化:beatcut.py init <素材文件夹> --music <音乐文件>。它会打印 created: <文件夹> 并将音乐复制到项目中。如果显示 project.json already exists,表示项目已存在;请使用它,不要重新初始化。如需更改尺寸、fill、fps、encoder、exclude_prefix 或自定义 profiles,请编辑 project.json(参见下方规则)。
  3. 节拍检测:beatcut.py beats <项目>。它会打印 period、t0 和 bpm,并将它们写入 shots.json。检测假设节拍稳定,t0 可能会有百分之几秒的误差。如果退出码为 1 并显示 fewer than 4 beats were detected,则手动设置 period 和 t0(period = 60 / BPM;t0 = 第一个节拍所在的秒数)。告诉用户这些数字,他们可以在选择器中修正。
  4. 选择镜头,两种方式之一:
    • 选择器(默认)。 在后台启动 beatcut.py pick <项目>(它会阻塞直到停止;默认打开浏览器,除非添加 --no-open;默认端口 8765,通过 --port N 修改)。将打印的 URL http://127.0.0.1:<port>/ 告诉用户,并说明页面会自动保存。等待用户表示完成,然后停止服务器(Ctrl+C 或结束后台进程)并读取 shots.json。选择器打开时不要编辑 shots.json,否则页面会覆盖您的更改。
    • 手动编辑,当用户要求您构建剪辑表或给出精确时间时。遵循下方规则,然后运行 check。
  5. 检查:beatcut.py check <项目>。退出码为 0 并显示 ok: <n> shots, <s> s 表示没有错误;同时读取警告(stderr)。修复所有错误后再进行渲染。
  6. 草稿:beatcut.py draft <项目>。它会打印 encoder: ...、segment i/n,最后是 out/<out_name>_draft.mp4 的路径。
  7. 查看草稿:beatcut.py sheet <视频> --out <某个.jpg 路径> 会生成一个 5 行 4 列的联系表;打开该图像并向用户描述结果(镜头顺序、颜色、淡入淡出、黑帧、裁剪错误)。选择素材文件夹外的 --out 路径,例如一个临时文件夹。
  8. 最终渲染,仅需用户批准:展示草稿后,询问是否渲染最终版。只有在用户明确同意后才运行 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 shotsshots 为空。请添加镜头(使用选择器或手动编辑)。
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 是经过测试的平台。

相关技能