This is the last link in the chain, and the only place in the whole product that actually draws pixels.
Everything before it is annotation: the ledger records "which words play", subtitles record "what appears on screen", visuals record "what layers get overlaid", and preview stitches these three together in real time for a human to see,without writing to disk. Export burns them into a single file.
需要 edit-list.json（必须）、subtitles.json、visuals.json + modules/
产出 成片.mp4
Prerequisite tools: the machine has Google Chrome(used to render subtitles and animations into images). For desktop-install sources,
FFmpeg / FFprobe have already entered the Product-managed directory along with the App; a pure CLI installation still requires the system
ffmpeg ≥ 6. If Chrome is missing it will report a clear error, do not try to work around it—without it there is no subtitle layer and no animation layer.
First read and execute the business Skill's stage contract the "Conclusion Levels" section in it.Export does not enter the editing state machine: it does not modify any project files, does not perform CAS writes, does not advance the stage, its output is a new file, and re-running it overwrites. So it does not need a confirmation card.
0. Ready
First execute Check for updates 's "Readiness Check"—whether skills are
up to date and whether the Runtime matches;plugin rootis also located there (in the commands in this document, <插件根> all substitute
that literal path). Continue only if it is "Ready"; for "Needs New Session" or "Stop", execute according to its disposition
(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 by the desktop App,
the media tools, and the same launchd/windows-task service; do not parse the Electron path, install
FFmpeg/Bun separately, or start a second Runtime.
Command
node "<插件根>/scripts/ensure-running.cjs" --json
node "<插件根>/scripts/videocut-cli.cjs" export <project> --dry-run --json # 先看计划，不编码
node "<插件根>/scripts/videocut-cli.cjs" export <project> --json # 出成片（默认 2 倍、源帧率）
node "<插件根>/scripts/videocut-cli.cjs" export <project> --out /path/成片.mp4 --json
node "<插件根>/scripts/videocut-cli.cjs" export <project> --scale 1 --json # 只要源尺寸
node "<插件根>/scripts/videocut-cli.cjs" export <project> --keep-work --json # 留下中间片和逐帧 PNG，供排查
ensure-running when there is an identity mismatch, port conflict, or unhealthy service, stop immediately; it is not allowed to substitute a temporary foreground
process and continue exporting.
Two steps, don't just run the second step
① --dry-run 先报计划 片长、帧数、字幕屏数、画面层数、推近段数、输出尺寸
念给用户听。数字不对就是上游不对，编码十分钟不会修好它
② 真跑 assemble → overlay → compose → verify 四段进度
--dry-run the warnings in it must be relayed verbatim. It reports only one kind of thing:words for certain subtitle screens or visual layers
have already been cut out, so they will not appear in the finished video. This is something upstream must decide, not something export should swallow on someone's behalf.
Clarity: the source footage is the ceiling, look at the source first before talking about upscaling
Before exporting, take a look at the source resolution (--dry-run the source field is enough):
源宽 ≥2560（Retina 原生录屏） → --scale 1，输出就是原生像素，这是最好的情况
源宽 <1920（如 960×720） → 先停一下：问用户有没有同一次录制的高清导出。
录屏工具常常能把同一次录制重新导出成 3 倍分辨率，
换源比任何后期都管用（见下节）。确实没有 → --scale 2
--scale 2 Why it is useful for low-definition sources: upscaling the base footage will not make it clearer, butsubtitles and animations are redrawn at the output size—these are the two things the viewer is actually reading; and when the platform compresses it again, the larger image gets a higher bitrate.
Do not adjust --fps。 for "more clarity"; frame rate follows the source footage; changing it will only make the animation's sampling and the screen recording not line up.
Switching source: when the user brings out a high-definition version of the same recording
This is not part of the export flow—export itself is always read-only. Switching source is an independent media operation after the user explicitly agrees; when it is done, come back and export normally.
First determine whether it is the same take(the first two are hard enough):
ffprobe -v error -show_entries format=duration -of csv=p=0 <两个文件> # 时长精确到毫秒相同
ffmpeg -v error -i <文件> -map 0:a:0 -c copy -f md5 - # 音频流逐位相同
# 再抽两三帧对比画面内容，眼睛确认
Bit-identical audio = identical timeline: the word-by-word script, ledger, subtitles, and visual layers are all bound to word ids, and not a single one needs to change. This is exactly the payoff of "bind to words, not seconds" when it comes to swapping sources.
Four steps to swap the source(actually walked through once on 2026-07-29; step ③ was missed at the time, and the edit preview immediately reported "generation failed"—fingerprint records are in more than one place, so grep for the old fingerprint, find them all, and then act):
① 换文件 input/source.mp4 和 uploads/source.mp4 是硬链接对 ——
删两个，拷新文件到 input/，再建硬链接回 uploads/
（macOS 用 ln；Windows 用 New-Item -ItemType HardLink）
② 更新指纹 project.json 的 source.sha256 改成新文件的
③ 再查一处 workbench.json 的 sourceSha256 也记着源片指纹，
剪辑预览管道校验的恰恰是这本 —— 漏了它，预览拒绝生成
（这是产品的正确行为：指纹对不上宁可失败，不拿旧预览冒充）
④ 重导 --scale 1 —— 换源就是为了原生像素，别再放大
Safe approach: use your search tool to look for the first 8 digits of the old fingerprint in all *.json under <project directory>, and handle every occurrence it lists (cache records such as preview-edited/current.json are recalculated automatically, no need to change them by hand).
If the audio is different (re-recorded, edited, different length), itis not a source swap, it's a new project: the word-by-word script has to be re-transcribed, and all annotations are void. Don't force it.
Acceptance: three things; miss one and the export doesn't count as complete
① 命令成功返回 产品自己数成片的尺寸、帧数、音轨，和计划逐项比。
对不上就是 readback_mismatch 报错，文件留在盘上当证据，
不算导出完成
② 抽帧看像素 从成片里抽帧，用眼睛看。至少覆盖：一个推近段、
一个整屏动画段、一个只有字幕的段、一个层与层的边界
③ 人耳听感 没人真的听过，一律记 human listening UNVERIFIED
② You may not substitute preview screenshots.Preview and final render are two rendering paths, and what acceptance needs to check is precisely whether they match— using a preview image as evidence for the final render is treating the very thing to be verified as a premise.
To judge a push-in, look for discriminating landmarks; overall impression can deceive(actually tripped over on 2026-07-29): after a 1.6x push-in, the on-screen page still looks like "a whole page," and in the thumbnail it's almost indistinguishable from the wide shot—once misjudged a correct push-in frame as "the push-in was lost," wasting half an hour and re-exporting twice. The correct way to judge is to look forevidence that only cropping can cause: half-cropped elements (a speech bubble broken in the middle), vanished edge elements (sidebar, title bar). Compare with the same-instant frame from the source video and it's settled at a glance.
For frame extraction, just use ffmpeg:
ffmpeg -v error -ss 8.84 -i 成片.mp4 -frames:v 1 -y frame.png
Where to look when something goes wrong
--keep-work will leave three things under the project's .chengfeng-videocut/export/ ,
and they directly separate "which half is wrong":
assembled.mkv 只有剪辑，没有任何盖的东西。它错 = 账本或切片错
overlay/*.png 只有盖的东西，透明底。它错 = 字幕样式或模块错
spans/*.mp4 合成后的分段。它错 = 推近或对齐错
Comparison table:
成片没有字幕/动画 overlay PNG 是不是全透明？模块是不是没答应 seek？
动画停在第一帧 模块没实现 seek，或者 GSAP 时间线没 paused
画面整块白 模块少了 `:root { color-scheme: dark }`
推近的框歪了 模块的 viewBox 和层的 zoom 不是同一组数
成片比计划短 某个 span 帧数不够，看 compose 阶段的报错
层边界闪一小段原片 overlay 截图陈旧（帧标记验证失效）。产品靠页面顶部的
帧标记条自证每张截图属于哪一帧；若复发，先确认 overlay
PNG 顶部有标记条、compose 有裁掉它的 crop
找不到 Chrome 装 Google Chrome，别改成别的渲染路径
What is not allowed
- You may not call "export succeeded" "acceptance passed"—a command returning success only means the product matches itself, not that the picture matches
- You may not substitute preview screenshots, DOM, or logs for frame extraction from the final render
- You may not report human listening PASS when nobody has listened
- You may not modify project files (change subtitles, delete layers, touch the ledger) just to make the export run. Export is read-only, it does not write
- You may not do upstream work inside the export: if subtitles are missing, go write subtitles; if visuals are missing, go make visuals; don't slap together a temporary fix in this section