capcut-edit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

capcut-edit

CLI for editing CapCut / JianYing drafts through a version-aware store. v0.11 detects and synchronizes readable timelines across

draft_content.json

draft_info.json

draft_meta_info.json

, and

template-2.tmp

用于通过版本感知存储编辑 CapCut / 剪映草稿的 CLI。v0.11 可检测并同步

draft_content.json

、

draft_info.json

、

draft_meta_info.json

和

template-2.tmp

中的可读时间线。

Project locations

项目位置

macOS:

~/Movies/CapCut/User Data/Projects/com.lveditor.draft/<project>/

Windows:

%LOCALAPPDATA%\CapCut\User Data\Projects\com.lveditor.draft\<project>\

macOS:

~/Movies/CapCut/User Data/Projects/com.lveditor.draft/<project>/

Windows:

%LOCALAPPDATA%\CapCut\User Data\Projects\com.lveditor.draft\<project>\

Core principle — deterministic scripts

核心原则——确定性脚本

Any recipe involving more than one

capcut

call, any arithmetic, or any branching ships as a parameterised shell script in

scripts/

. Claude invokes the script with inputs; the script runs a fixed sequence. If a recipe can be a script, it must be a script — not a narrative in

references/

references/workflows.md

documents which script to call and why, never a reconstructable sequence.

任何涉及多次

capcut

调用、任何算术或任何分支的操作配方，都以参数化 shell 脚本形式放在

scripts/

中。Claude 使用输入调用脚本；脚本按固定顺序执行。如果一个操作配方可以写成脚本，那就必须写成脚本——而不是

references/

中的叙述性文字。

references/workflows.md

记录调用哪个脚本以及为什么，绝不记录可重新构造的操作序列。

Progressive disclosure

渐进式信息展示

Start broad, drill into what you need. Never dump full project JSON.

bash

capcut info <project> -H           # overview
capcut doctor -H                   # installed media/transcription capabilities
capcut diagnose <project> -H       # canonical files, divergence, editor safety
capcut tracks <project> -H         # all tracks
capcut materials <project> -H      # material summary
capcut segments <project> -H       # segments with timing
capcut segment <project> <id>      # one item, full detail

先从概览开始，再深入你需要的部分。绝不导出完整项目 JSON。

bash

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>      # 单个项目，完整详情

Output modes

输出模式

JSON (default): pipe to
```
jq
```
, feed to scripts.
-H
: human-readable tables.
-q
: quiet, exit code only — for write commands in scripts.

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

Batch writes

批量写入

bash

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

Operations:

set-text

shift

shift-all

speed

volume

opacity

trim

Batch is transactional: one failing operation writes nothing. Use

--continue-on-error

only when the user explicitly accepts a partial commit; it still exits non-zero.

bash

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

操作：

set-text

、

shift

、

shift-all

、

speed

、

volume

、

opacity

、

trim

。

批量操作是事务性的：只要有一个操作失败，就不会写入任何内容。仅当用户明确接受部分提交时才使用

--continue-on-error

；它仍然会以非零状态退出。

Where to look

查找指南

references/api-reference.md
— every command, every flag, every value format (time, percentages, degrees), the ID-prefix rule, the
```
.bak
```
invariant.
../../docs/command-reference.md
— generated command-contract v2 with typed positionals/options, mutability, prerequisites, output form, and exit codes.
references/workflows.md
— recipes = which
```
scripts/X.sh
```
to run and why.
references/pitfalls.md
— close-project-first,
```
.bak
```
,
```
clip=null
```
on audio,
```
source_timerange
```
math with
```
speed
```
, alpha-keyframes-don't-render-use-animation-materials, etc.

Enum discovery — call

capcut enums --<category>

(or

-H

for a table) to list every CapCut slug. Categories:

--transitions

--masks

--image-intros

--image-outros

--image-combos

--text-intros

--text-outros

--text-loop-anims

--scene-effects

--character-effects

--audio-effects

--fonts

. Add

--jianying

to switch namespace. The

enums.json

bundle is generated once via

python3 scripts/extract-enums.py

; runtime is Python-free.

scripts/
— the client library. Current:
- ```
anim.sh
```
  — attach any of 9 CapCut intro/outro animations;
```
fade-in.sh
```
  and
```
fade-out.sh
```
  are thin wrappers.
- ```
ken-burns.sh
```
  — scale + pan keyframes via
```
capcut keyframe --batch
```
  (motion properties render; alpha does not — use
```
anim.sh fade-in
```
  instead).
- ```
long-to-short.sh
```
  — cut a range, stamp title + CTA text.
- ```
stamp-cta.sh
```
  — apply a saved text template (see
```
assets/examples/subscribe-cta.json
```
  ).
- ```
_test.sh
```
  — run every wrapper against the fixture; run after any change here.
assets/examples/
— raw JSON snippets for hand-editing.

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
```
计算、alpha 关键帧不渲染需使用动画素材，等等。

枚举发现 — 调用

capcut enums --<category>

（或使用

-H

查看表格）列出所有 CapCut slug。类别：

--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
```
  设置缩放 + 平移关键帧（运动属性可渲染；alpha 不可——请改用
```
anim.sh fade-in
```
  ）。
- ```
long-to-short.sh
```
  — 裁剪一个区间，并添加标题 + CTA 文字。
- ```
stamp-cta.sh
```
  — 应用已保存的文字模板（参见
```
assets/examples/subscribe-cta.json
```
  ）。
- ```
_test.sh
```
  — 针对测试夹具运行所有封装脚本；修改此处后运行。
assets/examples/
— 供手动编辑的原始 JSON 片段。

Invariants

不变量

Close the project in CapCut before editing; reopen after.
Every write is conflict-checked, prepared atomically, and synchronized to every readable timeline target. Every target receives
```
.bak
```
and rolling history snapshots.
Never pass
```
--force-write
```
unless the user explicitly accepts overwriting changed-on-disk state or an open editor.
```
clip
```
is
```
null
```
on audio segments (no opacity/scale).
```
capcut cut
```
writes to
```
--out
```
, never modifies the source.
IDs: first 6+ chars of the UUID match as a prefix.
Time formats:
```
1.5s
```
,
```
500ms
```
,
```
+0.5s
```
,
```
-1s
```
,
```
1:30
```
,
```
0:05.5
```
, bare number = seconds.

编辑前先在 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 high-value paths

v0.11 高价值路径

Whole draft:
```
capcut compile spec.json --check
```
, then
```
capcut compile spec.json --out <dir>
```
. Specs support refs, transforms, decorators, templates, captions, keyframes, and fades.

Karaoke:

capcut caption <project> --audio <path> --whisper-engine <openai|whisper-cpp|faster-whisper> --karaoke

Proxy:

capcut render <project> --all-video-tracks --burn-captions

; run

doctor

first for FFmpeg capability flags.

Automation:
```
capcut serve --workers N --retries N --timeout MS
```
; give jobs stable
```
id
```
fields and let the runner serialize writes per project.
Agent schema:
```
capcut describe
```
is the source of truth. Do not scrape help text or invent flags.

整个草稿：先运行
```
capcut compile spec.json --check
```
，然后运行
```
capcut compile spec.json --out <dir>
```
。规格支持引用、变换、装饰器、模板、字幕、关键帧和淡入淡出。

卡拉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
```
是唯一权威来源。不要抓取帮助文本或编造标志。