Communitygithub.com

Chengfeng Subtitle — Captions Timed from the Cut Ledger

Caption an edited talking-head video straight from the existing word-level transcript plus the cut ledger: post-cut timings are computed, misheard names are fixed from your dictionary and script, lines are split into screens, and every screen is reviewed in Studio.

What is Chengfeng Subtitle — Captions Timed from the Cut Ledger?

Short-form Editing Step 2 (caption): video-skill-ku-chengfeng-subtitle. Subtitles store word IDs and display text, never seconds, so timing is recalculated from the ledger every time and stale screens are flagged precisely. Rerun it whenever you trim another line; then hand off to export.

Works with✓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-subtitle

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

Subtitles

This is a standalone task, not a step in a workflow. It runs whenever the user calls for it—right after editing, or after deleting two sentences and needing it again.

It has only one prerequisite: the ledger already exists. Not because it comes after editing in sequence, but because without the ledger, it doesn't know which sentences remain or at which second they appear in the final cut.

Needs   edit-list.json (ledger), transcript.json (word-level transcript)
Produces   subtitles.json

Stop when done—do not instruct the user on next steps.

First, read and execute the Business Skill Stage Contract, criteria in Subtitle Correction Rules, proper noun conventions in AI Term Dictionary.

Who Decides What

This is the foundation; everything else follows from it.

Editing decides "what words to keep, at what time" ← sole source of time truth
Subtitles decides "what words appear on screen" ← sole source of display truth

Each subtitle screen stores a list of word IDs + displayed text, not seconds. Timing is calculated from the ledger each time. Thus the two ledgers have no second timing source that could drift, and invalidation is precise to the screen: "words on screens 7 and 12 were cut," not the unactionable "subtitles may be outdated".

Subtitles deliberately store their own text. Transcription answers "what did they say," subtitles answer "what to show people"—punctuation, removed filler words, proper formal names are inherently different. Forcing one string to do both means you can never add a comma.

0. Readiness

First execute the "Readiness Check" in Check Updates—whether skills are up-to-date, Runtime is compatible; the plugin root is also located there (all <pluginRoot> in this command should be substituted with that literal path). Only continue if "Ready"; for "New Session Needed" or "Stop" follow its handling (including the "no custom replacement UI" prohibition). The Business Skill itself does not contain environment logic.

If the readiness result is runtime.kind=desktop-managed, directly reuse the stable CLI already installed by the Desktop App and the same launchd/windows-task service; do not parse Electron paths, install additional dependencies, or spawn a second Runtime.

1. Entry Assertions

node "<pluginRoot>/scripts/ensure-running.cjs" --json
node "<pluginRoot>/scripts/videocut-cli.cjs" inspect "<projectDirectory>" --json
AssertionIf not met
edit-list.json exists and has segmentsExplain the ledger is missing and ask the user to call Editing first. Do not edit yourself.
transcript.json existsProject not ready, stop. Do not create one yourself.

Do not assert source_cut.mp4, and do not transcribe. Subtitles need neither—see next section.

2. Correct Words: Dictionary First, Script Later

No need for re-transcription. The existing word-level transcript already carries timestamps; the ledger knows which segments remain—each word's timing in the final cut is calculated, not re-heard:

Word's second in source clip → already in transcript
Which segments remain → already in ledger
Word's second in final cut → calculated from both

Re-running ASR just re-listens to the same speech, costs money, takes time, and performs worse—proper nouns would need re-correction. (transcript retranscribe is a legacy of an older design where subtitles intended to get timelines by transcribing post-edit video. Since subtitles switched to anchoring by word IDs, this problem is gone. Do not use it for subtitles.)

Two different tools, both required.

# Dictionary: fixed convention for this speaker, no evidence needed
node "<pluginRoot>/scripts/videocut-cli.cjs" transcript dictionary "<projectDirectory>" --dictionary "<pluginRoot>/references/ai-term-dictionary.md" --json

# Script: only if the author has a script; each change requires evidence
node "<pluginRoot>/scripts/videocut-cli.cjs" transcript align "<projectDirectory>" --script "<scriptFile>" --json
Dictionary    Always write this way          Ignores context, changes directly, lists which changes
Script        Only write this if context matches   Each change needs evidence; reports "unsure" if mismatch, never guesses

Why the dictionary is necessary, and script alone isn't enough: voiceovers get retaken. In a real project, the same sentence was recorded four times, so contexts like "the connector fork" and "fork is" appear multiple times—align can only report "unsure" because it follows the rule of not guessing, since a wrong name is worse than a missed one. With three instances of "fork" it only dares to change one. The dictionary has no such issue: for this speaker's work, "fork" is "X".

There is only one dictionary, at the plugin-level references/ai-term-dictionary.md: it corrects the transcript, which both Editing and Subtitles consume. Do not create another copy under this skill.

Review the change list after correction. The dictionary doesn't check context, so it can correct incorrectly—for example, normalizing a speaker actually saying "Skills" (Claude Skills, plural proper noun) to "Skill". If you see an error, fix the dictionary, don't patch around the command.

transcript align only reports, does not apply. To apply its proposals, convert corrections to [{wordId, text}] and run:

node "<pluginRoot>/scripts/videocut-cli.cjs" transcript correct "<projectDirectory>" --file "<correctionsFile>" --json

After correcting the transcript, subtitle screens that reference these words will be updated in the same step, returning subtitles.updated. Unmodifiable ones (lines manually rewritten by the user) go into needsAttention—report them for review, don't guess.

When neither the dictionary nor the script can confirm the correct spelling, do not guess. Report it for the user to add to the dictionary—once added, the next video will be automatically correct; guessing correctly once means guessing again next time anyway.

3. Screen Splitting

node "<pluginRoot>/scripts/videocut-cli.cjs" subtitle build "<projectDirectory>" --json

Four rules, in order:

① Words have been deleted here   The deletions are adjacent in the timeline but semantically unrelated.
                                 Deleting "silence" doesn't count—removing a pause within a sentence shouldn't split it.
② Any punctuation mark           Periods and commas from the ASR—**same granularity as editing segments**.
                                 Both break at the same point. Punctuation beats any time-based evidence: a speaker can say two sentences without pausing for breath or pause in the middle of a sentence.
③ Paragraph boundary + pause     **Only use when the word lacks punctuation.** It's "guess sentence end by paragraph when there's no punctuation".
                                 If punctuation exists, rule ② and the comma rule should handle it—they consider whether the screen is long enough; rule ③ does not.
                                 (Triggering rule ③ even on punctuated boundaries increased real project from 40 to 43 screens, creating more fragments.)
④ Audience hears long pause      To split within a sentence, a longer silence is needed.

Editing and subtitles use the same punctuation granularity: one comma = one segment / one screen.

Short fragments (1-2 characters) are merged, but never merged across periods—"You see" starts a new sentence, it's not a tail of the previous one. Merging forward would produce "…call Grok CLI you see", blurring two sentences together.

Fast-spoken short phrases stay as separate screens (e.g., in a real project, "Every morning" and "Execute task" each last 0.6 seconds). That's how the speaker said it; no warning. One comma per screen inevitably produces such screens—warning about them means warning about normal speech, and nobody reads warnings after the first few.

Screens longer than one subtitle line are evenly split into multiple screens, one line per screen. If splitting produces a 1-2 character fragment, rule ②'s boundary probably wasn't a real period—merge the fragment back into the previous screen.

The command reports four things, all must be reviewed:

stale              Screens affected by editing changes—precise screen numbers, which words lost
tooFast            Too many characters, not enough time to read
transcriptMoved    Transcript is no longer the original version

When subtitles already exist—stop and ask

Without --replace it will directly refuse. This is the only place in this skill that requires user consent, because --replace discards manually crafted screen splits and wording that the product cannot recover by itself.

User wants to change a few words      Don't `build`. Let them edit directly in Studio, or tell you which screens to change.
User wants to start over              Get confirmation, then add `--replace`.

4. Review: Screen by Screen in Studio

node "<pluginRoot>/scripts/videocut-cli.cjs" open "<projectDirectory>" --json

After opening, switch to the "Subtitles" tab in the left panel. One row per screen: left side shows sequence number and timing, right side shows the text; click to edit directly.

  • Enter = split current screen at cursor position
  • Backspace at line start = merge into previous screen
  • Right panel "Parameters → Subtitles" has four presets; choose one for the entire video
  • Subtitles appear directly on the preview canvas, position and font size proportional to the video—preview and final render use the same numbers

During review, at minimum have the user confirm: proper nouns are correct, no swallowed characters, line breaks read naturally, each screen stays long enough to read.

5. Stops at subtitles.json

This segment is done. No physical cutting, no shot breakdown, no animation, no rendering, and don't push the user to the next step.

The report must be written separately: Product structured readback as API/readback PASS; real project browser frame review as visual frame PASS; if no human has actually verified subtitles against video, always mark as human listening UNVERIFIED—do not substitute with DOM, screenshots, or file probing.

Boundary: Burning into the video is not this segment's job

The delivery format is burned into the video, and the video is rendered during export. The output of subtitles is subtitles.json—all dimensions are percentages of the video frame; during export, convert to pixels based on output resolution. Both sides use the same numbers.

Today's exported mp4 does not contain subtitles—that step hasn't been done yet. The report should clearly state this consequence; don't just say "subtitles are done"—the user will assume the final video has them.

Recovery and Failure

  • subtitles_exist: Subtitles already exist. Ask first, don't go straight to --replace.
  • revision_conflict: Another process is also writing. Re-read, don't auto-overwrite.
  • Dictionary reports "Line N unreadable": That line is a malformed table row. The parser only recognizes table rows (| Correct form | Common misrecognition |); prose and lists are silently ignored.
  • transcript correct reports "must not change any word id, time or gap flag": The correction proposal includes changes to timing. Word correction only.
  • runtime_unhealthy: Do not loop reinstallation.
  • Under no circumstances should "transcription complete" be reported as "subtitles done". ASR output is raw material, not the final product.

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

剪辑中文口播原素材:逐词转录、词典修字出修字表、五轮扫描找口误与重复、汇总表与重复句子表、打开 Studio 让用户复核、复盘沉淀用户偏好与词典。只产出一份已复核的删词账本,不切媒体、不做字幕、不做分镜动画。用户说剪口播、处理口误、生成口播基础素材、继续剪口播,或确认卡回传 action=return_cut_review 时使用。不要用于执行物理剪切、导出剪后视频、单独安装、单独打开工作台或口播分镜成片。

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

操作 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) 架构、工程自修复、智能配音字幕及录屏变焦。

Related Skills