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