cut

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cut

剪切

Paths:

${CLAUDE_SKILL_DIR}

means the folder containing this SKILL.md, and

${CLAUDE_PLUGIN_ROOT}

the plugin folder two levels above it.

Read

${CLAUDE_PLUGIN_ROOT}/PRINCIPLES.md

first: the rules every video in this plugin follows.

Every question goes in the question box: the AskUserQuestion tool (2-4 options, recommended first). Only in an agent without it, ask numbered questions in text.

edits/<name>/  transcript.txt (read this, never words.raw.json), spans.json (what to remove, quoted),
  candidates.md (what code flagged), paper-edit.md (the cut as text), cut-check.html (the
  transcript), review.json (notes), cut.mp4 + words.json (the render and its words).

<name>

is a slug of the file name (

IMG_1234.MOV

img-1234

), in the library (PRINCIPLES.md "Where"). Never modify, move or copy the source file: pass its path.

PY="${CLAUDE_PLUGIN_ROOT}/lib/ai_editor/run.py"

;

python3 "$PY"

runs the tool venv. On Windows, use

py

wherever these commands say

python3

. No venv yet: run the

setup

skill first.

S="${CLAUDE_SKILL_DIR}/scripts"

路径：

${CLAUDE_SKILL_DIR}

表示包含此 SKILL.md 的文件夹，

${CLAUDE_PLUGIN_ROOT}

表示其上两级的插件文件夹。

先阅读

${CLAUDE_PLUGIN_ROOT}/PRINCIPLES.md

：这是插件中每个视频都必须遵循的规则。

每个问题都应通过问题框提出：使用 AskUserQuestion 工具（2–4 个选项，推荐项放在首位）。只有在没有该工具的 Agent 中，才用文本提出编号问题。

edits/<name>/  transcript.txt (read this, never words.raw.json), spans.json (what to remove, quoted),
  candidates.md (what code flagged), paper-edit.md (the cut as text), cut-check.html (the
  transcript), review.json (notes), cut.mp4 + words.json (the render and its words).

<name>

是文件名的 slug（

IMG_1234.MOV

img-1234

），存放在文件库中（PRINCIPLES.md 中的“Where”）。绝不修改、移动或复制源文件；只需传入其路径。

PY="${CLAUDE_PLUGIN_ROOT}/lib/ai_editor/run.py"

；运行

python3 "$PY"

会使用工具的虚拟环境。在 Windows 上，所有命令中提到

python3

的位置都改用

py

。如果尚未创建虚拟环境，请先运行

setup

skill。

S="${CLAUDE_SKILL_DIR}/scripts"

。

No video yet?

还没有视频？

Ask for their take's path. Several files:

references/takes.md

. None: offer the sample take (raw, vertical, retakes, false starts and pauses kept) and download it to their folder:

bash

curl -L -o sample-take.mp4 https://github.com/nextwork-projects/ai-video-editor-cooked/releases/download/sample-video/sample-take.mp4

询问用户其拍摄素材的路径。存在多个文件时：参见

references/takes.md

。没有文件时：提供示例素材（包含原始画面、竖屏、重拍、说错后重来和停顿），并将其下载到用户的文件夹：

bash

curl -L -o sample-take.mp4 https://github.com/nextwork-projects/ai-video-editor-cooked/releases/download/sample-video/sample-take.mp4

0. Ask: the cut first, or everything at once

0. 询问：仅先剪切，还是一次完成全部

Before anything else, ask one question in the question box (start decides this for a whole edit):

Do you want just the cut first, or the cut and the styled edit in one go?

Just the cut first (Recommended). You approve the cut before I add captions, zooms or visuals, so a changed cut never rebuilds the visuals (fewer tokens).

Everything at once. I cut, then style without waiting. You still see the cut page and the stills sheet before anything renders.

Skip it only when the user already answered ("just cut it", "cut and style it in one go") or start or clips called this skill. Just the cut first: steps 1-6, then stop until the user approves the cut and asks for the style. Everything at once: steps 1-5, open the cut page, go straight on to style-edit; a later cut change re-runs style-edit from its plan step.

开始任何操作前，先在问题框中提出以下问题（完整编辑由 start 决定）：

你想先只完成剪切，还是一次完成剪切和风格化编辑？

仅先剪切（推荐）。 你先确认剪切，我再添加字幕、缩放或视觉效果，这样剪切发生变化时无需重新构建视觉效果（可节省 token）。

一次完成全部。 我先剪切，然后不等待确认就继续进行风格化。你仍会在任何内容渲染前看到剪切页面和静帧表。

仅当用户已经回答（"just cut it"、"cut and style it in one go"），或 start、clips 调用了本 skill 时跳过此步骤。仅先剪切：执行第 1–6 步，然后停止，直到用户批准剪切并且要求进行风格化处理。**一次完成全部：**执行第 1–5 步，打开剪切页面，然后直接进入 style-edit；之后若剪切发生变化，则从 style-edit 的计划步骤重新运行。

0b. Read the user's taste

0b. 读取用户偏好

bash

python3 "${CLAUDE_PLUGIN_ROOT}/skills/taste/scripts/taste.py" show --edit edits/<name>

Follow every rule in it. Save a reaction to a result ("too slow") with the taste skill before redoing.

bash

python3 "${CLAUDE_PLUGIN_ROOT}/skills/taste/scripts/taste.py" show --edit edits/<name>

遵守其中每条规则。重做前，使用 taste skill 保存对结果的反应（"too slow"）。

1. Transcribe

1. 转录

bash

python3 "$PY" "$S/transcribe.py" <source> edits/<name>/words.raw.json [--script <their script>]

A script (or

--keyterm Name

, repeatable) gets names and jargon right (+20% on Scribe).

Say the time first: Whisper 1-4 min for a 3-min take, CrisperWhisper about the take's length. It picks Scribe when a key is saved, else CrisperWhisper if installed, else the free local Whisper (

--engine whisper|crisper|scribe

overrides), which drops some ums and false starts. With neither, say once that setup can add one (CrisperWhisper's weights are non-commercial only). Never download a model mid-edit: a re-check needing one not installed (exit 4) is skipped and said in the round's note.

Never read
words.raw.json
: step 2 writes

transcript.txt

, 1/12 the size.

bash

python3 "$PY" "$S/transcribe.py" <source> edits/<name>/words.raw.json [--script <their script>]

提供脚本（或可重复使用的

--keyterm Name

）有助于正确识别人名和术语（在 Scribe 上提升约 20%）。

开头先说明预计耗时：Whisper 处理 3 分钟的素材需要 1–4 分钟；CrisperWhisper 的耗时大致等于素材长度。已保存 key 时会选用 Scribe；否则，如果已安装 CrisperWhisper，则使用它；再否则使用免费的本地 Whisper（

--engine whisper|crisper|scribe

可覆盖此选择），它会去掉部分含糊语气词和说错后重来的内容。如果两者都不可用，只说明一次可以通过 setup 添加一个（CrisperWhisper 的权重仅限非商业用途）。编辑过程中绝不要下载模型：如果复查时发现所需模型未安装（退出码 4），则跳过该复查，并在本轮备注中说明。

绝不读取
words.raw.json
：第 2 步会写入

transcript.txt

，大小仅为前者的 1/12。

2. Decide what to cut

2. 确定剪切内容

bash

python3 "$S/retakes.py" propose edits/<name>

Code finds every possible cut (a repeated line, an unfinished sentence, "wait, sorry", fillers) into

candidates.md

. Each is a place to look, not a decision. Read

transcript.txt

and

candidates.md

, follow

references/retake-detection.md

, and write

spans.json

(

references/shapes.md

With a

script.md

python3 "$S/script_match.py" edits/<name>

, read

script-match.md

(

references/script.md

Last take wins, except alternate hooks. Never type a timestamp or span a pause.

Only if the user wants it shorter (or their taste says to run the editorial pass), also read

references/editorial-rules.md

and add

redundant

cuts (content calls).

A misheard name is one command, never a JSON rewrite:

python3 "$S/retakes.py" fix edits/<name> cloud=Claude jiv=Jev

(whole words, kept in

fixes.json

for the captions).

bash

python3 "$S/retakes.py" propose edits/<name>

程序会把所有潜在剪切点（重复台词、未说完的句子、"wait, sorry"、语气词）汇总到

candidates.md

。每个候选都只是需要查看的位置，而不是最终决定。阅读

transcript.txt

和

candidates.md

，遵循

references/retake-detection.md

，并编写

spans.json

（

references/shapes.md

）。

存在

script.md

时：

python3 "$S/script_match.py" edits/<name>

，然后读取

script-match.md

（

references/script.md

）。

通常采用最后一次拍摄，但备选开场钩子除外。不要手动输入时间戳，也不要将停顿作为剪切区间。

仅当用户希望素材更短（或其 taste 偏好要求执行编辑处理）时，才另外阅读

references/editorial-rules.md

，并添加标记为

redundant

的剪切（内容重复）。

识别错的人名只需执行一条命令，绝不要直接改写 JSON：

python3 "$S/retakes.py" fix edits/<name> cloud=Claude jiv=Jev

（使用完整单词，并保存在

fixes.json

中，供字幕使用）。

3. Build

3. 构建

bash

python3 "$S/build_timeline.py" <source> edits/<name> && python3 "$PY" "$S/mirror.py" <source> edits/<name>

Every pause (breaths too) over

--max-pause

(0.15 s) becomes 0.10 s; under music only word gaps are trimmed. A build

ERROR

writes nothing: fix that span and run it again.

mirror.py

says

mirrored

when a book, shirt or sign reads backwards (a front-camera take): ask once, Keep it as shot (Recommended) (most creators post it that way) / Flip it so the text reads; on a flip add

--flip

to every render.py below.

In one message, start the spans encoding in the background (

run_in_background

) and the paper checks; step 4 then encodes only what changed:

bash

python3 "$S/render.py" <source> edits/<name> --segments-only

The

cut-judge

agent grades

paper-edit.md

(a flub left in, a bad join, a good line lost) and fixes

spans.json

. Readers for takes over 5 min go first, the judge after:

references/judge.md

. Never read

paper-edit.md

yourself.

```
CLIPPED
```
in
```
paper-edit.md
```
: a pause cut ate a word. Raise
```
--pad
```
. Still there: a label is off.
Joins inside speech move to a quiet frame. Any
```
still in speech
```
: listen in step 5.

bash

python3 "$S/build_timeline.py" <source> edits/<name> && python3 "$PY" "$S/mirror.py" <source> edits/<name>

所有超过

--max-pause

（0.15 秒）的停顿（包括呼吸停顿）都会缩短至 0.10 秒；在音乐铺底的情况下，只修剪词语之间的空隙。构建时出现

ERROR

不会写入任何内容：修正该区间后重新运行。

当书、衣服或标牌上的文字显示为反向时，

mirror.py

会输出

mirrored

（使用前置摄像头拍摄）：询问一次，保持原样（推荐）（大多数创作者都会这样发布）/ 翻转，让文字正向显示；选择翻转时，在下面的每个

render.py

命令中添加

--flip

。

在同一条消息中，后台启动区间编码（

run_in_background

）并运行纸面剪辑检查；第 4 步随后只编码发生变化的部分：

bash

python3 "$S/render.py" <source> edits/<name> --segments-only

cut-judge

Agent 会对

paper-edit.md

评分（是否残留口误、是否有糟糕拼接、是否遗漏好台词），并修正

spans.json

。对于超过 5 分钟的拍摄，先运行

readers

，再运行

judge

：参见

references/judge.md

。不要亲自读取

paper-edit.md

。

```
paper-edit.md
```
中出现
```
CLIPPED
```
：剪切停顿时误删了一个词。提高
```
--pad
```
；如果问题仍存在，说明标签有误。
语音内部的拼接点会移到安静的帧。若仍有拼接点位于语音中：在第 5 步中进行听音检查。

4-5. Render and verify

4–5. 渲染并验证

Foreground (render.py waits for the background encode):

bash

R="${CLAUDE_PLUGIN_ROOT}/lib/ai_editor/review.py"
python3 "$S/build_timeline.py" <source> edits/<name> && \
python3 "$S/render.py" <source> edits/<name> && \
python3 "$PY" "$S/verify_cut.py" edits/<name> --engine <same engine as step 1> && \
python3 "$S/preview_cut.py" edits/<name> --no-open && \
python3 "$R" edits/<name> start --video edits/<name>/cut.mp4 --stage cut --transcript edits/<name>/words.json

Verify clean: the cut page is ready. Verify diffs the cut's transcript with the kept words (exit 1 stops the chain):

MISSING: a kept word is not in the render. Raise
```
--pad
```
(or narrow the span), rebuild, re-render.
SURVIVED: a span to add for a real repeat or stumble, never one that cuts a kept line.
HEARD DIFFERENTLY ("jev -> jeff") and filler notes are transcriber variance: no rebuild.
DOUBLED: words said twice in a row. Natural ("very, very"): keep. A stumble: add its span.
N join(s) in speech: listen. Clipped:
```
splice_check.py edits/<name> --fix
```
, re-render.

One fix cycle (the same chain), then show the user what is left.

在前台执行（

render.py

会等待后台编码完成）：

bash

R="${CLAUDE_PLUGIN_ROOT}/lib/ai_editor/review.py"
python3 "$S/build_timeline.py" <source> edits/<name> && \
python3 "$S/render.py" <source> edits/<name> && \
python3 "$PY" "$S/verify_cut.py" edits/<name> --engine <same engine as step 1> && \
python3 "$S/preview_cut.py" edits/<name> --no-open && \
python3 "$R" edits/<name> start --video edits/<name>/cut.mp4 --stage cut --transcript edits/<name>/words.json

verify

检查通过：剪切页面已就绪。

verify

会把剪切后的转录与保留词进行差异比对（退出码 1 会中止整条命令链）：

MISSING：某个保留词未出现在渲染结果中。提高
```
--pad
```
（或缩小剪切区间），然后重新构建并渲染。
SURVIVED：为真实的重复或口误添加剪切区间，但绝不能添加会剪掉保留台词的区间。
HEARD DIFFERENTLY（"jev -> jeff"）和语气词备注属于转录器差异：无需重新构建。
DOUBLED：词语连续说了两遍。自然重复（"very, very"）应保留；若为口误，则添加剪切区间。
```
N join(s) in speech
```
：进行听音检查。若词被截断：运行
```
splice_check.py edits/<name> --fix
```
，然后重新渲染。

执行一轮修复（使用同一条命令链），然后向用户展示仍然保留的内容。

6. The user approves

6. 用户批准

The chain opened the review page (

../style-edit/references/review.md

serve

and

wait

in the background. Say the seconds cut. Notes: "keep <line>": narrow or delete that span; "cut <line>": add one; pauses off:

--max-pause

. Then steps 4-5,

resolve

each note (

--reply

: what changed), last

round --video edits/<name>/cut.mp4

(never a second

start

), then ask any learn question.

After approval, one Bash call:

python3 "$S/trend.py" log edits/<name>

(

tally

: trend), the hook check. Then hook variants if

hooks.json

exists (

references/retake-detection.md

); called by start, ask that in the same question box as style-edit's stills approval, not before it.

Only approval finishes the cut;

cut.mp4

words.json

go to style-edit. On "just the cut first", say they can ask for the style. Never start style-edit on your own. Called by start: as the page opens, start

visual-prep

in the background; its

motion_briefs

: a background

clip-builder

each at once; say a

motion_note

once.

上述命令链已打开审阅页面（

../style-edit/references/review.md

）。让

serve

和

wait

在后台运行。告知总共剪掉了多少秒。处理备注："keep <line>" 表示缩小或删除该区间；"cut <line>" 表示添加一个区间；暂停剪切不合适时使用

--max-pause

。然后执行第 4–5 步，用

resolve

处理每条备注（

--reply

：说明改动内容），最后执行

round --video edits/<name>/cut.mp4

（绝不能第二次执行

start

），再询问是否有 learn 问题。

批准后，执行一次 Bash 调用：

python3 "$S/trend.py" log edits/<name>

（

tally

：趋势分析），并完成 hook 检查。若存在

hooks.json

，则处理 hook 变体（

references/retake-detection.md

）；当 start 调用本 skill 时，在与 style-edit 静帧审批相同的问题框中询问，不要提前询问。

只有获得批准才视为剪切完成；

cut.mp4

和

words.json

将移交给 style-edit。对于 "just the cut first"，告知用户之后可以要求风格化处理。绝不自行启动 style-edit。被 start 调用时，在页面打开后于后台启动

visual-prep

；针对其

motion_briefs

，每个都在后台同时启动一个

clip-builder

；只说明一次

motion_note

。

If a script stops

如果脚本停止

message	do
`no such file` / `ffmpeg could not read audio`	ask for the right path; never copy or convert the source
`faster-whisper missing` / `CrisperWhisper missing`	run with `python3 "$PY"` , or the setup skill's step 3
`no ElevenLabs key` (exit 2) / `HTTP 4xx` , `unreachable` (3)	drop `--engine scribe` , or re-save the key with the setup skill
build `ERROR` on a quote	fix that span's quote or add `occurrence` , build again
`cannot derive a silence threshold` / `marked no silence`	speech and background are under 10 dB apart: `ffmpeg -i <source> -af volumedetect -vn -f null -` , pass `--noise` about 10 dB above the mean
render `ERROR ...`	say it; re-run render once

消息	处理方式
`no such file` / `ffmpeg could not read audio`	询问正确的路径；绝不复制或转换源文件
`faster-whisper missing` / `CrisperWhisper missing`	使用 `python3 "$PY"` 运行，或执行 setup skill 的第 3 步
`no ElevenLabs key` （退出码 2）/ `HTTP 4xx` 、 `unreachable` （3）	移除 `--engine scribe` ，或使用 setup skill 重新保存 key
构建时在引文处出现 `ERROR`	修正该区间的引文或添加 `occurrence` ，然后再次构建
`cannot derive a silence threshold` / `marked no silence`	语音和背景音之间的电平差不足 10 dB：运行 `ffmpeg -i <source> -af volumedetect -vn -f null -` ，然后传入比平均值高约 10 dB 的 `--noise`
渲染时出现 `ERROR ...`	报告该错误；重新运行 render 一次

Rules

规则

Every cut quotes the transcript. No quote, no cut.
A script breaks ties between takes and keeps every take of a line it says twice. Nothing is cut for being off-script.
Never stream-copy (
```
-c copy
```
) across cuts: it lands up to 2 s off.
Never hand over a render that has not been verified and approved.

每次剪切都必须引用转录文本。没有引文，就不能剪切。
脚本会在不同拍摄版本之间打破平局，并保留一句被说了两次的每个拍摄版本。不得仅因内容偏离脚本而将其剪切。
跨剪切点时绝不能使用流复制（
```
-c copy
```
），否则最多会产生 2 秒的偏移。
不得交付未经验证和用户批准的渲染结果。

Self-check

自检

test_build_timeline.py

test_retakes.py

test_media.py

(ffmpeg);

demo

transcribe.py

trend.py

splice_check.py

script_match.py

mirror.py

test_build_timeline.py

、

test_retakes.py

、

test_media.py

（ffmpeg）；在

transcribe.py

、

trend.py

、

splice_check.py

、

script_match.py

、

mirror.py

上运行

demo

。