Voice-over Editing
From one video to a manually reviewed word-deletion ledger (Cuts + EDL), without touching media files. Seven steps in a line:
0 Ready Reference the readiness check from "Check for Updates" (this Skill has no environment logic)
1 Setup Real video → cloud word-by-word transcription → product project creation → start service → read back status
2 Fix Words Use dictionaries to correct words (one general + one user) → output word correction table
3 Delete Words Read preferences and rules → five rounds of scanning, each round finds only one type, records only rows
4 Summarize Summary table of deletions + table of repeated sentences → self-read verification based on tables
5 Review Submit all → present both tables to user → open Studio for manual review
6 Retrospect & Handoff Compare proposal with final version → archive three drawers → report four things
No media cutting: Modifying the ledger takes tens of milliseconds; cutting creates an irreversible file. By the end of this Skill, no new videos exist on disk. The Skill performs semantic judgment and orchestration; the Product Runtime is the sole writer of project, Cuts, and Studio states.
User only speaks in three places: choose continue or restart from the same source project (only when previously cut), review in Studio, and confirm completion. Everything else is one-way reporting, without stopping to wait for a reply. The completion criterion for each step is its deliverable: no table, not complete.
First read and execute the Skill’s phase contract. This document’s steps correspond to contract phases: 1=preflight+Product state readback, 5=proposal+Product CAS, review=project-level review binding. The three phases after the contract (confirmation, execution, verification) belong to the export Skill.
The incident origins of each rule are in the Lessons Log — rules are in the main text; stories are there.
0. Ready
First execute the "readiness check" from Check for Updates — whether skills are up-to-date and Runtime is compatible; the plug-in root is also located there (all instances of <plug-in root> in this document substitute that literal path). Only proceed if the result is "ready"; if "needs new session" or "stop", follow its directives (including the "no custom replacement UI" prohibition).
If the readiness result is runtime.kind=desktop-managed, it shares the same stable entry point and launchd/windows-task service with the CLI installation; proceed directly. Do not look for the Electron installation directory, install Bun/FFmpeg separately, or start a second Runtime.
1. Setup: Real Input → Transcription → Product Project Creation
What to do: Submit the user’s local real video and cloud word-by-word transcript to the product, atomically create the project, start the service, and read back the status.
# After cloud word-by-word transcription (generates a transcript candidate in the task directory):
node "<plug-in root>/scripts/videocut-cli.cjs" project create "<project directory>" --video "<video file in task directory>" --transcript "<word-by-word transcript in task directory>" --json
node "<plug-in root>/scripts/ensure-running.cjs" --json # Product declarative service (5190)
node "<plug-in root>/scripts/videocut-cli.cjs" workflow get "<project directory>" --json # Product state readback
node "<plug-in root>/scripts/videocut-cli.cjs" cuts get "<project directory>" --json
Rules:
- Only accept the user’s provided real voice-over video or an existing real project; stop if there’s no real media. Do not use samples or placeholder videos as substitutes.
- Transcription must use the currently authorized cloud ASR; no fallback to local ASR. If no cloud ASR is available, report
missing_cloud_transcription_adapter; do not open Studio or fabricate a transcript. --video/--transcriptmust be real files within the task directory. Do not pass aspect ratio — the product will derive it automatically from the video’s actual dimensions (Runtime 0.4.4+). Only add--aspect-ratio W:Hif the user explicitly requests a specific aspect ratio.- For existing standard projects, first
inspectto confirm and reuse; do not create a duplicateprojectId. If the same video has been cut before, ask the user: continue from last time or start over (this is one of the three speaking points).project prepareis an idempotent compiler; use only for restoring interrupted sessions or explicit refreshes; in case of interruption, just rerun. project createis the sole entry point: do not go through media libraries, upload sessions, or additional Skills. The Skill must not writeproject.jsonbeforehand.- The service must be confirmed by the script as
healthy=true, withruntimeMode=launchd(macOS) orruntimeMode=windows-task(Windows), compatible version, and URL as canonical 5190 before proceeding. Failure must pass through a structured error and stop; do not fallback to foreground mode, change ports, or kill unknown processes. - Both readback results must point to the same
projectId; save the workflow stage and the three revisions (Project / Cuts / EditList). Stop if missing or inconsistent.
2. Fix Words: Correct Words, Output Correction Table
What to do: Before any deletion judgment, use the dictionary to correct words misheard by ASR — wrong words make all subsequent judgments incorrect; misheard words are not superfluous phrases, and deletion cannot fix them.
node "<plug-in root>/scripts/videocut-cli.cjs" transcript dictionary "<project directory>" --dictionary "<plug-in root>/references/ai-term-dictionary.md" --json
Check with your file tool whether $HOME/.chengfeng-videocut/dictionary.md exists; if so, run it through again (transitional approach: CLI currently only accepts a single file, so run twice; it can only add, not undo the previous run — a complete multi-dictionary merge with user priority will be released later):
node "<plug-in root>/scripts/videocut-cli.cjs" transcript dictionary "<project directory>" --dictionary "$HOME/.chengfeng-videocut/dictionary.md" --json
Deliverable: Correction table — merge the applied lists from both calls into a small table (original word → corrected to → context) and report to user. After correction, you must review this table — dictionaries can also make mistakes without context; if you see an error, correct the dictionary, not apply a patch elsewhere.
Only if the dictionary cannot resolve the issue and the author has a script in hand, proceed with an additional context alignment:
node "<plug-in root>/scripts/videocut-cli.cjs" transcript align "<project directory>" --script "<script file>" --json # report only, no changes
node "<plug-in root>/scripts/videocut-cli.cjs" transcript correct "<project directory>" --file "<correction file>" --json
Rules:
- Only change text, not timestamps, word count, or wordId — the product compares timestamps word by word; changes are directly rejected.
- Only change spelling, not meaning — true corrections and restarts (incomplete sentences) are for deletion management.
- If the dictionary doesn’t have it and the script can’t confirm, do not guess: report it and leave it for the user to add to the dictionary. Inserting a made-up name is worse than leaving a misheard name.
- Keep Chinese colloquial speech as originally spoken: if they say "叉" or "大模型", that’s what they said.
- The dictionary is a pass to be applied every time transcription is run (the same audio transcribed twice yields different results; see the lessons log).
Segment the script by punctuation: each word in the transcript carries punctuation; a comma breaks a paragraph, a period breaks a line. Subtitles use the same punctuation, ensuring consistent breaks. For projects from before 2026-07-28 without punctuation, run node "<plug-in root>/scripts/videocut-cli.cjs" transcript regroup "<project directory>" --json to re-segment (the word-level check id/time/text remains unchanged; safe for previously cut projects). To truly add punctuation, retranscription is needed — punctuation didn’t exist in old transcripts.
3. Delete Words: Five Rounds, Each Round Finds Only One Type
What to do: Read the materials, then read the playback order completely five times, each time with only one criterion. Reading with one criterion at a time yields much higher judgment quality than reading with six at once; each round produces small, checkable output.
First read the materials:
node "<plug-in root>/scripts/videocut-cli.cjs" transcript playback "<project directory>" --json
Then use your file reading tool to read $HOME/.chengfeng-videocut/cut-preferences.md (user preferences; what they said counts; if the file doesn’t exist, it’s a new user, skip).
Criteria are in Semantic Deletion Rules (principles + cases). Priority: user preferences > user cases > general cases.
Round 1 Repetition Between-sentence, within-sentence repetition (most objective: two identical expressions)
Round 2 Incomplete sentences & reformulations Half-started sentences, then rephrased
Round 3 Slip of the tongue & retries Incorrect numbers, names, words, then corrected
Round 4 English hesitations Prefix / letter / syllable repetition
Round 5 Filler words & interjections Most subjective, based on user preference density and tolerance
Each round has a fixed action: search for cases based on the round type → for each found instance, record a row (wordIds + type + risk) → do not decide on other types. Skip words already marked in later rounds; resolve conflicts in the summary.
Rules:
- Use only the playback order from
transcript playbackfor judgment; do not reconstruct fromtranscript.jsonyourself — "said twice" depends on adjacent utterances; reconstructing on your own can misread skip numbers as missing content (see lessons log). - Deletion has only two states: "deleted / not deleted"; AI reasons do not form a third "suggested deletion" state.
- For errors, repetitions, and incomplete sentences, default to deleting before and keeping after; long sentences, full sentences, and branching reformulations must be high-risk reviewed.
- Normal pauses are not calculated by the Skill: adjacent silence merging and
natural-pause-v2are executed deterministically by the product.
4. Summarize: Two Tables, Tables Must Be Produced Before Action
What to do: Merge the rows from the five rounds into two tables — this is the step’s deliverable, also what the user sees.
Summary Table of Deletions (per-item deletion decision):
| # | Time | Type | Deleted | Remaining read as | Risk | Basis |
|---|-------|--------|------------------|-------------------|-----|----------|
| 1 | 00:12 | Repeat | 这个功能呢 | 这个功能它其实 | Low | Case R2 |
| 2 | 02:31 | Reformulation | 比如我就让他跟踪 | 比如我让grok跟踪 | High | Case R5 |
Table of Repeated Sentences (sentences said multiple times; a word-by-word table cannot show "how many takes there were, which take was kept" which is exactly what the user most needs to check):
| Sentence (start) | Times said | Which take kept | Which takes deleted | Risk |
|---------------------|--------|--------------|-----------------|-----------------|
| 因为今天有什么… | 3 | Take 3 00:08 | Takes 1, 2 | Low — three takes basically identical |
| 多数Agent能搜… | 2 | Take 2 04:40 | Take 1 | High — two takes differ; listen carefully |
Then self-read: based on the tables, read the full post-deletion text in playback order; undo any rows that don’t read smoothly. This is the definition of review: the AI checks itself again, not asking the user. If unsure = don’t list (two states).
5. Review: Open Studio Only for Manual Review
What to do: Submit all candidates, present both tables to the user, then open the product review page for the user to manually review.
node "<plug-in root>/scripts/videocut-cli.cjs" cuts get "<project directory>" --json # Get Cuts’ own revision
node "<plug-in root>/scripts/videocut-cli.cjs" cuts set "<project directory>" --file "<proposal file>" --expected-revision "<Cuts current revision>" --json
Candidates only reference stable wordIds:
{
"schemaVersion": 1,
"cutWordIds": ["word-12", "word-13"],
"reasons": [
{ "wordIds": ["word-12", "word-13"], "kind": "repeat", "risk": "low" }
]
}
Submission rules:
- The candidate is the complete conclusion of this round, not an increment —
cuts setis a replace semantic; submitting an increment would silently discard the previous round’s semantic deletions (see lessons log). When submitting the candidate, do not read or manually mergeinitialization.baselineCutWordIds(the product automatically incorporates pause baselines). reasonsare persisted as written; the product will trim parts that refer to undeleted words.- Do not directly write
cut-selection.json,project.json, or event logs. cuts get.data.revisionis the Cuts revision;workflow get.data.revisionis the project’s; do not mix them.- After successful submission, you must check
noLongerCut(number of words no longer deleted this time): if non-zero and not an intentional undo = incremental submission was made, go back and resubmit the full set. Also note if it reads"unknown". - Immediately after, run
workflow get+cuts getagain, confirmingcut_review_readyand the three revisions; stop if inconsistent; never write JSON directly or auto-overwrite. - Keep the
<proposal file>in the task directory after submission — the retrospection step (step 6) needs it (reasons are trimmed by the product after user editing; reverse-engineering from the ledger afterwards is unreliable).
Then present the tables first, then open the page: send both tables to the user, letting them enter Studio with the tables.
node "<plug-in root>/scripts/ensure-running.cjs" --json # Ensure again before opening
node "<plug-in root>/scripts/videocut-cli.cjs" open "<project directory>" --json # Get the project URL from the product
node "<plug-in root>/scripts/ensure-studio.cjs" --url "<product project URL>" --view koubo --json # Capability gate: confirm 5190 has registered the koubo view
Rules:
- Only if the gate returns
ok=true, use the Codex built-in browser to openstudio.url, then stop automatic progression; wait for the user to highlight, restore, and save. - Before opening, strictly compare the
productUrl’s#project/<projectId>with the readback’sprojectId, and bindstage=cut_review_readywith the three revisions — the gateok=trueonly proves the product surface capability, not the project-level binding. If any inconsistency, re-readback. studio_capability_missing: stop and explain version incompatibility; can suggest$chengfeng-report-bug. Do not assume the new interface exists just because the URL contains?view=koubo; do not fallback to old task panels.- Do not make "open the workbench" the first step of the task; do not access old
review.html, 8898/8899; do not control Studio DOM or directly modify media elements; do not create independent audio tracks or placeholder subtitle tracks.
6. Retrospect & Handoff: User’s Corrected Work Must Not Be Discarded
After the user completes review, first read back:
node "<plug-in root>/scripts/videocut-cli.cjs" workflow get "<project directory>" --json
node "<plug-in root>/scripts/videocut-cli.cjs" cuts get "<project directory>" --json
Retrospect (transitional approach; will be replaced when the product’s cuts diff command is released): Compare the <proposal file> saved from step 5 with the final cutWordIds from the readback —
- User restored (proposal has it, final doesn’t) = AI deleted incorrectly. Against the reason you wrote in the proposal, ask: what type was the error?
- User added deletion (final has it, proposal doesn’t, and it’s not in
initialization.baselineCutWordIdspause baseline) = AI missed it. Ask: which type does this belong to, and why wasn’t it identified? (The baseline is only used here to exclude pause words; still prohibited from merging it into submissions.)
Archive three drawers:
- Preference differences → append to
~/.chengfeng-videocut/cut-preferences.md(Agent-managed markdown; only append and rewrite its own section; create file if it doesn’t exist) - Proper name errors → append to
~/.chengfeng-videocut/dictionary.md(two-column table; check for duplicates before appending) - Rule gaps → record one line under the "pending upgrade cases" section in the preferences file; when the same case appears a third time, report to the user and suggest upgrading to general cases (skills repository is only modified after human review)
- Even zero differences: record one line per project in the preferences file with "fully adopted".
Report four things: how many words deleted, how many seconds saved; current stage (should be cut_review_ready); three revisions (Project / Cuts / EDL); retrospect summary (N proposals, X adopted Y restored Z added deletion, main divergence in one sentence). Then tell the user to run the export.
Do not show a confirmation card, do not execute cutting — the physical cutting confirmation card belongs to the export Skill; that card must freeze the revision at the moment the user presses confirm.
return_cut_review: First run node "<plug-in root>/scripts/ensure-running.cjs" --json again, then return to the same Studio to continue review; does not trigger retrospect. Retrospect is only done once at the final handoff.
Report levels: Product structured revisions as API/readback PASS; real browser frame review as visual frame PASS; no one actually listening to audio is always human listening UNVERIFIED; do not substitute with playback, DOM, screenshots, or media detection.
Recovery and Failure
revision_conflict: Re-read the state, explain the user’s edits, do not auto-overwrite.runtime_unhealthy: Do not loop reinstall.service_identity_mismatch/service_port_conflict: Stop; do not fallback to foreground mode, change ports, or kill unknown processes.- Page closed but service still running: Read the workflow and continue from current state; do not create a new project.
- Any failure must not state "ledger written" as "already cut" — up to this point, no media files have been generated.
Note: This Skill accepts local real video and cloud word-by-word transcript directly into the product; this is a requirement of the contract preflight. Both must truly exist for all judgments to proceed.