capcut-cli — 剪映/CapCut 可编辑出片

capcut-edit

一个用于通过版本感知存储编辑 CapCut / 剪映草稿的命令行工具。v0.11 可检测并同步 draft_content.json、draft_info.json、draft_meta_info.json 和 template-2.tmp 文件中的可读时间线。

项目路径

• macOS：~/Movies/CapCut/User Data/Projects/com.lveditor.draft/<project>/
• Windows：%LOCALAPPDATA%\CapCut\User Data\Projects\com.lveditor.draft\<project>\

核心原则 — 确定性脚本

任何涉及多个 capcut 调用、算术运算或条件分支的操作，都以参数化 shell 脚本形式保存在 scripts/ 中。Claude 调用带输入的脚本；脚本执行固定序列。如果某个操作可以写成脚本，则必须写成脚本——而非 references/ 中的叙述性文档。

references/workflows.md 只记录调用哪个脚本及原因，绝不包含可重建的序列。

渐进式信息呈现

从概览开始，根据需要深入。切勿一次性输出整个项目 JSON。

capcut info <project> -H           # 概览
capcut doctor -H                   # 已安装的媒体/转录功能
capcut diagnose <project> -H       # 规范文件、差异、编辑安全性
capcut tracks <project> -H         # 所有轨道
capcut materials <project> -H      # 素材摘要
capcut segments <project> -H       # 带时序的片段
capcut segment <project> <id>      # 单个片段，完整详情

输出模式

• JSON（默认）：通过管道传递给 jq，或提供给脚本使用。
• -H：人类可读的表格。
• -q：安静模式，仅返回退出码——用于脚本中的写入命令。

批量写入

echo '{"cmd":"set-text","id":"a1b2c3","text":"已修复"}
{"cmd":"volume","id":"d4e5f6","volume":0.5}' | capcut batch <project>

支持操作：set-text、shift、shift-all、speed、volume、opacity、trim。

批量操作是事务性的：任何一个操作失败都不会写入任何内容。仅当用户明确接受部分提交时才使用 --continue-on-error；即使部分成功，退出码仍然非零。

参考资料位置

• references/api-reference.md — 每个命令、每个标志、每种值格式（时间、百分比、角度）、ID 前缀规则、.bak 不可变性。
• ../../docs/command-reference.md — 生成的命令约定 v2，包含类型化位置参数/选项、可变性、前置条件、输出格式和退出码。
• references/workflows.md — 操作步骤 = 要运行哪个 scripts/X.sh 及其原因。
• references/pitfalls.md — 先关闭项目、.bak、音频上 clip=null、涉及 speed 的 source_timerange 计算、透明度关键帧不渲染请使用动画素材等。
• 枚举查询 — 调用 capcut enums --<category>（或带 -H 的表格）列出所有 CapCut 标识符。类别：--transitions、--masks、--image-intros、--image-outros、--image-combos、--text-intros、--text-outros、--text-loop-anims、--scene-effects、--character-effects、--audio-effects、--fonts。添加 --jianying 以切换命名空间。enums.json 包通过 python3 scripts/extract-enums.py 一次性生成；运行时无需 Python。
• scripts/ — 客户端库。当前包含：
  • anim.sh — 附加任意 9 种 CapCut 入场/退场动画；fade-in.sh 和 fade-out.sh 是它的轻量封装。
  • ken-burns.sh — 通过 capcut keyframe --batch 实现缩放+平移关键帧（运动属性可渲染；透明度不行——请改用 anim.sh fade-in）。
  • long-to-short.sh — 裁剪范围，添加标题+CTA 文本。
  • stamp-cta.sh — 应用已保存的文本模板（参见 assets/examples/subscribe-cta.json）。
  • _test.sh — 针对测试夹具运行所有封装脚本；更改后务必执行。
• assets/examples/ — 用于手动编辑的原始 JSON 片段。

不可变规则

• 在 CapCut 中关闭项目后再编辑；编辑后重新打开。
• 每次写入都会进行冲突检查、原子化准备，并同步到所有可读时间线目标。每个目标都会获得 .bak 和滚动历史快照。
• 除非用户明确接受覆盖已变更的磁盘状态或打开的编辑器，否则绝不传递 --force-write。
• 音频片段上 clip 为 null（无透明度/缩放属性）。
• capcut cut 写入 --out 指定的位置，永不修改源文件。
• ID：UUID 的前 6 个以上字符可作为前缀匹配。
• 时间格式：1.5s、500ms、+0.5s、-1s、1:30、0:05.5、纯数字=秒。

v0.11 高价值路径

• 完整草稿：capcut compile spec.json --check，然后执行 capcut compile spec.json --out <dir>。Spec 支持引用、变换、装饰器、模板、字幕、关键帧和淡入淡出。
• 卡拉 OK：capcut caption <project> --audio <path> --whisper-engine <openai|whisper-cpp|faster-whisper> --karaoke。
• 代理：capcut render <project> --all-video-tracks --burn-captions；先运行 doctor 检查 FFmpeg 功能标志。
• 自动化：capcut serve --workers N --retries N --timeout MS；为任务提供稳定的 id 字段，让运行器按项目序列化写入。
• Agent 模式：capcut describe 是唯一信息来源。不要抓取帮助文本或发明标志。