This is one thing, not a stage of a process. Do it whenever the user calls for it—right after editing, or again after two more sentences were deleted afterward.
It has only one prerequisite:the ledger already exists. Not because it comes after editing, but because without the ledger, it doesn't know which sentences were kept or which second of the final cut each one falls on.
需要 edit-list.json（账本）、transcript.json（逐词稿）
产出 subtitles.json
Stop when done,don't direct the user's next step。
First read and execute the business Skill's stage contract, criteria see subtitle proofreading rules, proper-noun spellings see AI word dictionary。
Whose word counts
This is the foundation of this section; everything else is derived from it.
剪口播 说了算「留哪些话、在什么时候」 ← 时间的唯一真相
字幕 说了算「屏幕上显示什么字」 ← 显示的唯一真相
A subtitle screen stores aword id list + display text，not seconds. Time is computed fresh from the ledger each time. Thus the two ledgers have no second copy of time that can drift, and invalidation can be precise down to the screen: "the words of screens 7 and 12 were cut," rather than that "subtitles may be out of date" line that no one can act on.
Subtitles storing their own text is intentional. The transcript answers "what he said"; the subtitles answer "what to show people"— punctuation, removed filler words, the formal spellings of proper nouns, these were meant to differ. Force one string to do both jobs, and subtitles can never add a comma.
0. Ready
First execute the "readiness check" of check for updates —whether skills are
up to date and whether the Runtime matches;plugin rootis also located there (the <插件根> in commands in this document all substitute
that literal path). Only "ready" continues; for "new session required" or "stop", follow its handling
(including the "no self-made substitute interface" prohibition); the business Skill does not carry its own environment logic.
If the readiness result is runtime.kind=desktop-managed, directly reuse the stable CLI already installed with the desktop App and
the same launchd/windows-task service; do not parse Electron paths, install additional dependencies, or start a second
Runtime.
1. Entry assertions
node "<插件根>/scripts/ensure-running.cjs" --json
node "<插件根>/scripts/videocut-cli.cjs" inspect "<项目目录>" --json
| Assertion | when not satisfied |
|---|---|
edit-list.json exists and has segments |
state clearly that the ledger is missing and have the user first call for talking-head editing.Do not edit it yourself. |
transcript.json exists |
the project is not ready, stop. Do not make one yourself. |
Do not assert source_cut.mp4, and do not transcribe. Subtitles need neither—see the next section.
2. Change text: dictionary first, then manuscript
No re-transcription is needed. The original word-by-word transcript already carries timestamps, and the ledger knows which segments were kept— which second of the final cut each word falls on iscomputed, not heard again by listening:
词在源片的第几秒 转录里就有
哪几段留着 账本里就有
词在成片的第几秒 两者一算就出来
Running ASR again just means hearing the same words again—spending money and time, and hearing them worse—proper nouns have to be corrected all over again.
(transcript retranscribe is leftover from the previous design; back then, subtitles were going to get their timeline from transcribing the edited video.
After subtitles switched to anchor-word IDs, this problem went away.Don't use it for subtitles.）
Two different tools, both needed.
# 词典：这个说话人的固定写法，不需要证据
node "<插件根>/scripts/videocut-cli.cjs" transcript dictionary "<项目目录>" --dictionary "<插件根>/references/ai-term-dictionary.md" --json
# 文稿：作者手上有稿子时才做，逐处要证据
node "<插件根>/scripts/videocut-cli.cjs" transcript align "<项目目录>" --script "<口播稿文件>" --json
词典 永远这么写 不看上下文，直接改，列出改了哪几处
文稿 上下文对得上才这么写 逐处要证据，对不上的报「不敢定」，不猜
Why a dictionary is mandatory; the transcript alone isn't enough: spoken takes get re-recorded. In a real project the same line was recorded four times, so contexts like "连接叉" and "叉是" each appear more than once, and align can only report "can't decide"— by rule it doesn't guess, becausegetting a name wrong is worse than mishearing it. For the three occurrences of "叉" it only dares to fix one. The dictionary doesn't have this problem: in this speaker's work, "叉"is just「X」。
There is only one dictionary, at the plugin level references/ai-term-dictionary.md: it changes the transcription,
and cutting spoken takes and subtitles consume the same transcription. Don't create another one under this skill.
After changes, look at that list. The dictionary doesn't look at context, so it will also make wrong changes—for example, normalizing "Skills" (Claude Skills, a plural proper noun) that the speaker actually said into "Skill". If you see something wrong, change the dictionary; don't patch things on the command side.
transcript align only reports, doesn't change. To apply its proposals, turn corrections into [{wordId, text}] and run again:
node "<插件根>/scripts/videocut-cli.cjs" transcript correct "<项目目录>" --file "<修正文件>" --json
After changing the transcription,subtitle screens that reference these words will be rewritten along with it in the same step, reporting subtitles.updated.
Ones that can't be changed (that line was rewritten by someone) go into needsAttention; report them for a human to look at, don't guess.
When neither the dictionary nor the transcript has any spelling that can confirm what's correct, guessing is not allowed. Report it and have the user add it to the dictionary— once added to the dictionary, the next video gets it right automatically; guess right once and you'll have to guess again next time.
3. Split screens
node "<插件根>/scripts/videocut-cli.cjs" subtitle build "<项目目录>" --json
Four rules, in order:
① 这里删掉过话 删掉的两边在时间轴上挨着，意思上毫无关系。
删掉的是「静音」不算 —— 把句子中间的停顿剪掉，不能把句子劈开。
② 任何标点 火山给的，句号和逗号都算 —— **和剪口播分段是同一个粒度**，
两边断在同一处。标点比任何时间证据都强：说话人可以两句连着
说不喘气，也可以在一句中间停顿。
③ 段落边界 + 停顿 **只在这个词没有标点时才用**。它是「没标点时靠段落猜句子结束了」，
有标点就该由②和逗号那条管 —— 它们会考虑屏够不够长，③ 不会。
（在带标点的边界上也触发③，真实项目从 40 屏变 43 屏，切出更多碎屏）
④ 观众听到长停顿 句子内部要断，得有更长的静音才够格。
Cutting spoken takes and subtitles consume the same punctuation, with the same granularity: one comma, one segment / one screen.
Fragments (one or two characters) get merged away, butdon't merge across periods — "你看" starts a new sentence, not the tail of the previous one; merging it backward gives "…调用Grok CLI你看", smushing the two sentences together.
Short sentences the speaker says quickly will remain (in a real project, "每天早上" and "执行任务" were 0.6 seconds each). That's really how he said it; don't warn about it. One comma per screen inevitably produces this kind of screen; warning about it is like warning about normal speech—too many warnings and no one reads them anymore.
For the rest that are longer than one screen, split evenly into several screens,one line per screen. If you cut out a fragment of one or two characters, it means the boundary in rule ② isn't actually a period; merge the fragment back into the previous screen.
The command reports four things; look at all of them:
stale 被剪辑改动的屏 —— 精确到第几屏、丢了哪几个字
tooFast 字太多、时间不够读
transcriptMoved 转录已经不是当初那一份了
When subtitles already exist — stop here and ask
Without adding --replace it will refuse outright.This is the only place in this skill that requires user consent,
because --replace wipes out screen splits and wording that a person spent time on, and the product can't recover them by itself.
用户想改几个字 不要 build。让他在 Studio 里直接改，或者告诉你改哪几屏。
用户要推倒重来 确认过了再加 --replace。
4. Review: look screen by screen in Studio
node "<插件根>/scripts/videocut-cli.cjs" open "<项目目录>" --json
After opening it, switch to the **"Subtitles" tab** in the left column. One line per screen: on the left are the index and time, on the right is the text; click into it to edit directly.
- Enter = start a new screen from the cursor position
- Backspace at the start of a line = merge into the previous screen
- In the right column, under "Parameters → Subtitles", pick one of the four presets; one style for the whole video
- You can see the subtitles directly on the picture, and the position and font size are proportional to the picture —the preview and the final video use the same set of numbers
During review, have the user confirm at least: whether the proper nouns are correct, whether any text was swallowed, whether the line breaks read smoothly, and whether each screen stays up long enough to finish reading.
5. Until subtitles.json is reached
This section is done. no physical cutting, no shot breakdown, no animation, no rendering the final video,and don't rush the user to the next step。
The report must be written separately: the Product structured readback is API/readback PASS; the real in-project browser frame review is visual frame PASS; whenever no one has actually looked at whether the subtitles match the picture, it is always human listening UNVERIFIED, and DOM, screenshots, or file probing must not be used as a substitute.
Boundary: burning into the picture is not this section's job
What the output method defines isburning into the picture, and the picture is drawn by the export section. The output of the subtitles is just subtitles.json —
the dimensions inside are all percentages of the picture, and the export converts them to pixels according to the output resolution; both sides use the same set of numbers.
Today's exported mp4 has no subtitles, that step hasn't been done yet. The report must clearly state this consequence, and not just say "the subtitles are done" and leave it at that — the user will think they're in the final video.
Recovery and failure
subtitles_exist: subtitles already exist.Ask first, don't just--replace。revision_conflict: something else is also writing. Re-read, don't overwrite automatically.- The dictionary reports "can't parse line N": that's a table row with a broken format. The rules only recognize table rows (
| 正确写法 | 常见误识别 |), and prose and lists are silently ignored. transcript correctreports "must not change any word id, time or gap flag": the word-change proposal has time-changing things mixed into it. Changing words should only change words.runtime_unhealthy: don't reinstall in a loop.- No failure may describe "transcription complete" as "subtitles done".What comes out of ASR is raw material, not the product.