Communitygithub.com

澄风剪口播 — 口误删词 + 人工复核

剪中文口播原素材但不动媒体文件:逐词转录、词典修字、五轮扫描口误与重复句、出汇总表,再在 Studio 里人工复核。最终只产出一份已复核的删词账本(Cuts + EDL),供字幕和导出步骤使用。

澄风剪口播 — 口误删词 + 人工复核 是什么?

短视频剪辑配方第 1 步(剪):video-skill-ku-chengfeng-cut,来自 chengfeng-videocut Codex 插件。转录 → 修专名 → 五轮单一目的扫描(口误、重说、重复)→ 汇总表 + 重复句表 → 打开 Studio 复核 → 沉淀个人偏好与词典。导出之前不切任何文件,所有决定都能撤回。

兼容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/2789927464king-jpg/video-skill-ku/tree/HEAD/chengfeng-videocut-skills/plugins/chengfeng-videocut/skills/chengfeng-cut

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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 / --transcript must 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:H if the user explicitly requests a specific aspect ratio.
  • For existing standard projects, first inspect to confirm and reuse; do not create a duplicate projectId. 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 prepare is an idempotent compiler; use only for restoring interrupted sessions or explicit refreshes; in case of interruption, just rerun.
  • project create is the sole entry point: do not go through media libraries, upload sessions, or additional Skills. The Skill must not write project.json beforehand.
  • The service must be confirmed by the script as healthy=true, with runtimeMode=launchd (macOS) or runtimeMode=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 playback for judgment; do not reconstruct from transcript.json yourself — "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-v2 are 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 set is 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 merge initialization.baselineCutWordIds (the product automatically incorporates pause baselines).
  • reasons are 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.revision is the Cuts revision; workflow get.data.revision is 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 get again, confirming cut_review_ready and 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 open studio.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’s projectId, and bind stage=cut_review_ready with the three revisions — the gate ok=true only 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.baselineCutWordIds pause 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.

Individual skills in this repo

This repo contains 8 individual skills — each has its own dedicated page.

2789927464king-jpg/video-skill-ku

剪辑环境的唯一管理者:就绪检查(skills 是否最新 → Runtime 是否配套)、Skills 更新激活、Runtime 安装与体检。用户说检查更新、安装剪辑环境、装播放器、检查剪辑环境、剪辑环境就绪了吗、配置转录凭证时使用;业务 Skill(剪口播/字幕/画面/导出)第 0 步也引用本 Skill 的就绪检查。不用于剪辑、字幕、画面、导出本身或项目数据迁移。

2789927464king-jpg/video-skill-ku

把剪好的口播烧成一个成片文件:账本切片段、推近、字幕、HTML 画面层,一次全部烧进 mp4。用户说导出、出成片、烧字幕、渲染、导出视频、生成最终文件时使用。不要用于生成删词候选、写字幕、做画面动画。

2789927464king-jpg/video-skill-ku

整理、脱敏并上报 chengfeng-videocut 的 GitHub Bug。用户说上报 Bug、反馈剪口播问题、提交 GitHub Issue、这个问题告诉开发者,或要求继续提交已预览的 Bug 草稿时使用。不要用于功能建议、普通排错、代码提交或未获用户确认的自动上报。

2789927464king-jpg/video-skill-ku

给剪好的口播做字幕:直接用已有的逐词稿加账本算出剪后时间(不必导出、不必重新转录)、用词典和作者文稿改写听错的专名、按句子分屏、在 Studio 里逐屏复核。用户说做字幕、加字幕、改字幕、重新分屏、字幕不对时使用。不要用于删词剪辑、物理剪切、分镜动画或成片渲染。

2789927464king-jpg/video-skill-ku

操作 chengfeng-videocut 剪辑工作台的已有工程,通过 Runtime CLI 查工程与词句位置、添加或替换画面覆盖层、移除画面、删除明确指定的词句或片段、拆分裁剪移动已有片段、调整画布比例并回读核验。用户说插入片段、删掉这句、移除动画、换个画面、调整顺序或管理时间线时使用;先区分画面覆盖与主轨顺延插入,不负责自动判断口误、创作动画、制作字幕、导出或排查安装故障。

2789927464king-jpg/video-skill-ku

Create Ian Xiaohei-style HTML/SVG motion illustrations for Chinese articles, scripts, storyboard scenes, workflow explanations, concept metaphors, and short video visual aids. Use when the user asks for 小黑 SVG、漫画感 HTML、分层 SVG 动效、把小黑生图做成 HTML/SVG、可编辑矢量动效、口播流程动画、手绘漫画动效、正文配图动画, or wants a Xiaohei illustration style adapted into controllable HTML/SVG/GSAP output instead of raster image generation.

2789927464king-jpg/video-skill-ku

给剪好的口播配画面:在录屏上盖 HTML 层(圈重点标注 / 小黑整屏动画 / 推近),层绑字幕屏、由播放器逐帧驱动、直接在预览里看。用户说做分镜、配画面、加动画、圈重点、B-roll、做 storyboard 时使用。不要用于删词剪辑、字幕、物理剪切或成片渲染。

2789927464king-jpg/video-skill-ku

剪映 (JianYing) AI自动化剪辑的高级封装 API (JyWrapper),提供开箱即用的 Python 接口,支持录屏、素材导入、字幕生成、Web 动效合成及项目导出。全面适配 MacOS (Apple Silicon/Intel) 与 Windows,支持 v5.9+ (draft_info.json) 架构、工程自修复、智能配音字幕及录屏变焦。

相关技能