Communitygithub.com

Chengfeng Export — Cuts, Zooms, Captions Burned into One MP4

Render the finished talking-head video: applies the cut ledger, punch-in zooms, subtitles and HTML visual layers in a single burn to mp4. Dry-run first to check duration, frame count, caption screens and overlays, then assemble → overlay → compose → verify. Needs Google Chrome and ffmpeg 6+.

What is Chengfeng Export — Cuts, Zooms, Captions Burned into One MP4?

Short-form Editing Step 3 (export): video-skill-ku-chengfeng-export. The only step that actually draws pixels; everything before it is annotation previewed live. Reports warnings verbatim when captions or overlays point at words that were cut, defaults to 2x scale at source frame rate, and can keep intermediate frames for debugging.

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-export

Ask in your favorite AI

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

Documentation

Export (Final Video)

This is the last segment of the pipeline, and the only place in the entire product where actual pixels are rendered.

Everything before this is annotation: the ledger records "which words to speak," the subtitles record "what to display on screen," the visuals record "which layers to overlay," and the preview stitches them together in real-time for human review—without writing to disk. Export bakes them into a single file.

Requires: edit-list.json (mandatory), subtitles.json, visuals.json + modules/
Produces: final_video.mp4

Prerequisites: Google Chrome (used to render subtitles and animations as images). A desktop-installed FFmpeg / FFprobe is already in the product-managed directory with the App; pure CLI installations still require system ffmpeg ≥ 6. Missing Chrome will result in a clear error—do not attempt to bypass it; without Chrome, there is no subtitle layer or animation layer.

First read and execute the "Conclusion Level" section of the Business Skill Phase Contract. Export does not enter the editing state machine: it does not modify any project files, perform CAS writes, or advance stages. The output is a new file; re-running overwrites it. Therefore, no confirmation card is needed.

0. Readiness

First execute the Readiness Check — whether skills are up-to-date and the Runtime is compatible; the plugin root is also located there (all <plugin_root> commands in this document substitute the literal path). Proceed only if "ready"; for "new session required" or "stop," follow its directives (including the prohibition on self-made alternative interfaces). The Business Skill does not incorporate environment logic itself.

If the readiness result is runtime.kind=desktop-managed, directly reuse the stable CLI, media tools, and the same launchd/windows-task service already installed by the desktop App; do not resolve Electron paths, install FFmpeg/Bun separately, or start a second Runtime.

Commands

node "<plugin_root>/scripts/ensure-running.cjs" --json
node "<plugin_root>/scripts/videocut-cli.cjs" export <project> --dry-run --json          # Preview plan without encoding
node "<plugin_root>/scripts/videocut-cli.cjs" export <project> --json                    # Final export (default 2x, source framerate)
node "<plugin_root>/scripts/videocut-cli.cjs" export <project> --out /path/final_video.mp4 --json
node "<plugin_root>/scripts/videocut-cli.cjs" export <project> --scale 1 --json          # Source dimensions only
node "<plugin_root>/scripts/videocut-cli.cjs" export <project> --keep-work --json        # Keep intermediate files and per-frame PNGs for debugging

Stop immediately if ensure-running detects identity mismatch, port conflicts, or unhealthy services; do not temporarily substitute with a foreground process and continue exporting.

Two Steps, Don't Skip to Step Two

① --dry-run first reports the plan    Duration, frames, subtitle screens, visual layers, zoom segments, output dimensions
                                       Read it to the user. If numbers are wrong, it's an upstream issue; ten minutes of encoding won't fix it
② Actual run                           assemble → overlay → compose → verify (four progress stages)

The warnings in --dry-run must be relayed verbatim. They only report one thing: certain subtitle screens or visual words have already been trimmed and thus will not appear in the final video. This is an upstream decision, not something export should silently ignore.

Resolution: Source is the ceiling; inspect the source before upscaling

Before exporting, check the source resolution (the source field in --dry-run provides it):

Source width ≥2560 (Retina native screen recording)  → --scale 1, output is native pixels; this is the best case
Source width <1920 (e.g., 960×720)      → Pause first: ask the user if there is a high-definition export from the same recording.
                                          Screen recording tools can often re-export the same recording at 3x resolution;
                                          replacing the source is more effective than any post-processing (see next section). If not available → --scale 2

--scale 2 works for low-resolution sources because: enlarging the source footage doesn't make it clearer, but subtitles and animations are redrawn at the output size—viewers are reading these. Additionally, when the platform re-encodes, a larger image receives a higher bitrate.

Do not adjust --fps in an attempt to make things "clearer." The framerate follows the source; changing it will cause animation sampling and screen recording to become out of sync.

Source Replacement: When the User Provides a High-Definition Version of the Same Recording

This is not part of the export workflow—export itself is read-only. Source replacement is an independent material operation after the user explicitly agrees; after completion, return to normal export.

First determine if it's the same recording (the first two checks are sufficient):

ffprobe -v error -show_entries format=duration -of csv=p=0 <file1> <file2>   # Duration identical to the millisecond
ffmpeg -v error -i <file1> -map 0:a:0 -c copy -f md5 -                  # Audio stream bit-identical
# Then extract 2-3 frames to visually compare content

Bit-identical audio = identical timeline: all word-level scripts, ledgers, subtitles, and visual layers are bound to word IDs—not a single change needed. This is precisely how "binding words, not seconds" pays off when replacing the source.

Four Steps for Source Replacement (real event on 2026-07-29; step ③ was missed at the time, causing immediate "generation failed" error from the editing preview—fingerprint records are stored in multiple locations; grep all instances of the old fingerprint before proceeding):

① Replace Files        input/source.mp4 and uploads/source.mp4 are hardlinked pairs —
                        Delete both, copy the new file to input/, then create a hardlink back to uploads/
                        (macOS: ln; Windows: New-Item -ItemType HardLink)
② Update Fingerprint    Change source.sha256 in project.json to the new file's hash
③ Check Another Location   workbench.json also records the source fingerprint in sourceSha256;
                        the editing preview pipeline validates against *this*—miss it, and preview refuses to generate
                        (This is the product's correct behavior: fingerprint mismatch means failure, not serving an old preview)
④ Re-export            --scale 1 — replacement is for native pixels; do not upscale again

Safe practice: use your search tool to find the first 8 characters of the old fingerprint in all *.json files within , and handle every occurrence (cache records like preview-edited/current.json will be auto-recalculated, no manual changes needed).

If the audio is different (re-recorded, edited, different duration), it is not source replacement but a new project: the word-level script must be re-transcribed, and all annotations are invalidated. Do not force it.

Verification: Three Items—Missing Any Means Export Not Complete

① Command returns successfully         The product compares the output's dimensions, frames, audio tracks against the plan item by item.
                                        Mismatch triggers a readback_mismatch error; the file remains on disk as evidence,
                                        and export is not considered complete
② Extract frames and check pixels       Extract frames from the final video and visually inspect. Cover at minimum: one zoom segment,
                                        one full-screen animation segment, one subtitle-only segment, one boundary between layers
③ Human listening check                 Since no one has actually listened, always record as human listening UNVERIFIED

② Do not substitute with preview screenshots. Preview and final export are two different rendering paths; verification must check if they match— using a preview image as evidence for the final video assumes the thing being verified.

When judging a zoom segment, find discriminative landmarks; overall impression can be misleading (real event on 2026-07-29). At 1.6x zoom, the on-screen page still looks "like a full page" and is nearly indistinguishable from the overview in thumbnails—a correct zoom frame was once misjudged as "zoom lost," wasting half an hour and exporting twice. The correct method is to look for evidence that only cropping can create: half-cut elements (e.g., a speech bubble sliced in the middle), disappearing marginal elements (sidebar, title bar). Compare with the same frame from the source to reach a definitive conclusion.

Extract frames using ffmpeg:

ffmpeg -v error -ss 8.84 -i final_video.mp4 -frames:v 1 -y frame.png

Troubleshooting

When using --keep-work, three items are left in the project's .chengfeng-videocut/export/ directory, clearly separating which half went wrong:

assembled.mkv    Only the edit, nothing overlaid. If wrong = ledger or segment error
overlay/*.png    Only overlaid content, transparent background. If wrong = subtitle style or module error
spans/*.mp4      Composite segments after merging. If wrong = zoom or alignment error

Troubleshooting Reference Table:

Final video missing subtitles/animations          Are overlay PNGs fully transparent? Did the module not agree to seek?
Animation stuck on first frame                    Module didn't implement seek, or GSAP timeline isn't paused
Entirely white frame                              Module missing `:root { color-scheme: dark }`
Zoom rectangle misaligned                         Module's viewBox and layer's zoom aren't the same set of numbers
Final video shorter than planned                  A span has fewer frames than expected; check compose stage errors
Layer boundary shows a brief flash of original footage   Outdated overlay screenshot (frame marker validation failed). The product relies on a frame marker bar at the top of each overlay frame to self-verify which frame it belongs to; if this recurs, first ensure the overlay PNG has the marker bar at the top and that compose crops it out
Chrome not found                                  Install Google Chrome; do not use an alternative rendering path

Prohibitions

  • Do not say "export succeeded" as "verification passed"—command success only means the product's internal checks match, not that the visuals are correct
  • Do not substitute final video frame extraction with preview screenshots, DOM, or logs
  • Do not report human listening PASS if nobody has listened
  • Do not modify project files (edit subtitles, delete layers, alter ledger) just to make export work. Export is read-only
  • Do not perform upstream tasks during export: if subtitles are missing, go create them; if visuals are missing, go create them; do not patch things together temporarily

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

整理、脱敏并上报 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) 架构、工程自修复、智能配音字幕及录屏变焦。

Related Skills