Communitygithub.com

澄風匯出 — 剪切、推近、字幕、畫面層一次燒成 mp4

算繪口播成片:把刪詞帳本、推近、字幕與 HTML 畫面層一次全部燒進 mp4。先 dry-run 核對片長、影格數、字幕屏數與畫面層,再依拼接 → 疊層 → 合成 → 校驗四段出片。需要 Google Chrome 與 ffmpeg 6 以上。

澄風匯出 — 剪切、推近、字幕、畫面層一次燒成 mp4 是什麼?

短影音剪輯配方第 3 步(匯出):video-skill-ku-chengfeng-export。整條流程中唯一真正繪製像素的一步,前面都是即時預覽的標註。字幕或畫面層引用了被剪掉的詞時會原樣回報警告,預設 2 倍尺寸、來源影格率,可保留中間影格以利除錯。

相容平台✓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

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

匯出(成片)

這是鏈條最後一段,也是整個產品裡唯一一個真正畫出像素的地方。

在它之前全部是標註:帳本記「播哪些詞」,字幕記「螢幕上寫什麼」,畫面記「蓋什麼層」, 預覽把這三樣即時拼給人看,不落盤。匯出把它們燒成一個檔案。

需要   edit-list.json(必須)、subtitles.json、visuals.json + modules/
產出   成片.mp4

前提工具:機器上有 Google Chrome(用來把字幕和動畫畫成圖)。桌面安裝來源的 FFmpeg / FFprobe 已隨 App 進入 Product 受管目錄;純 CLI 安裝仍要求系統 ffmpeg ≥ 6。缺 Chrome 會明確報錯,不要試圖繞過——沒有它就沒有字幕層和動畫層。

先讀取並執行 業務 Skill 的階段合同 裡的「結論等級」一節。匯出不進剪輯狀態機:它不改任何專案檔案、不做 CAS 寫入、 不推進 stage,產出是一個新檔案,重跑一次就覆蓋。所以它不需要確認卡。

0. 就緒

先執行 檢查更新 的「就緒檢查」——skills 是否 最新、Runtime 是否配套;插件根也在那裡定位(本文命令裡的 <插件根> 都代入 那個字面路徑)。只有「就緒」才繼續;「需新會話」或「停」按它的處置執行 (含「禁止自製替代介面」禁令),業務 Skill 不自帶環境邏輯。

若就緒結果為 runtime.kind=desktop-managed,直接複用桌面 App 已安裝的穩定 CLI、 媒體工具與同一 launchd/windows-task 服務;不要解析 Electron 路徑、另裝 FFmpeg/Bun 或起第二個 Runtime。

命令

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 身份不匹配、埠衝突或服務不健康時立即停止;不允許用 foreground 臨時頂替後繼續匯出。

兩步,別只跑第二步

① --dry-run 先報計劃    片長、幀數、字幕屏數、畫面層數、推近段數、輸出尺寸
                       唸給用戶聽。數字不對就是上游不對,編碼十分鐘不會修好它
② 真跑                 assemble → overlay → compose → verify 四段進度

--dry-run 裡的 warnings 必須原樣轉述。它只報一類事:某些字幕屏或畫面層的詞 已經被剪掉了,所以它們不會出現在成片裡。這是上游要決定的事,不是匯出該替人吞掉的。

清晰度:來源片是天花板,先看來源再談放大

匯出前看一眼來源解析度(--dry-run 的 source 字段就有):

來源寬 ≥2560(Retina 原生錄屏)  → --scale 1,輸出就是原生像素,這是最好的情況
來源寬 <1920(如 960×720)      → 先停一下:問用戶有沒有同一次錄製的高清匯出。
                              錄屏工具常常能把同一次錄製重新匯出成 3 倍解析度,
                              換來源比任何後期都管用(見下節)。確實沒有 → --scale 2

--scale 2 對低清來源有用的原因:底片放大不會變清楚,但字幕和動畫是按輸出尺寸 重畫的——觀眾真正在讀的就是這兩樣;平台再壓一次時,大圖分到的碼率也更高。

不要為了「更清晰」去調 --fps。 幀率跟著來源片走;改它只會讓動畫的取樣和錄屏對不上。

換來源:用戶拿出同一次錄製的高清版時

這不是匯出流程的一部分——匯出本身永遠唯讀。換來源是用戶明確點頭後的獨立素材操作, 做完再回來正常匯出。

先判定是不是同一條(前兩條就足夠硬):

ffprobe -v error -show_entries format=duration -of csv=p=0 <兩個檔案>   # 時長精確到毫秒相同
ffmpeg -v error -i <檔案> -map 0:a:0 -c copy -f md5 -                  # 音訊流逐位相同
# 再抽兩三幀比對畫面內容,眼睛確認

音訊逐位相同 = 時間線相同:逐詞稿、帳本、字幕、畫面層全綁詞 id,一個不用動。 這正是「綁詞不綁秒」在換來源這件事上的兌現。

換來源四步(2026-07-29 真實走過一次;第 ③ 步當時漏了,剪輯預覽當場報 「生成失敗」——指紋記錄不止一處,grep 舊指紋找全再動手):

① 換檔案      input/source.mp4 和 uploads/source.mp4 是硬連結對 ——
              刪兩個,拷新檔案到 input/,再建硬連結回 uploads/
              (macOS 用 ln;Windows 用 New-Item -ItemType HardLink)
② 更新指紋    project.json 的 source.sha256 改成新檔案的
③ 再查一處    workbench.json 的 sourceSha256 也記著來源片指紋,
              剪輯預覽管道校驗的恰恰是這本 —— 漏了它,預覽拒絕生成
              (這是產品的正確行為:指紋對不上寧可失敗,不拿舊預覽冒充)
④ 重導        --scale 1 —— 換來源就是為了原生像素,不要再放大

保險做法:用你的搜尋工具在 <專案目錄> 的全部 *.json 裡找舊指紋前 8 位, 列出來的每一處都要處理(快取記錄如 preview-edited/current.json 會自動重算,不用手動改)。

音訊不同(重新錄了一遍、剪過、時長不一樣)就不是換來源,是新專案: 逐詞稿要重新轉,所有標註作廢。別硬套。

驗收:三件事,缺一件就不算匯出完成

① 命令成功返回        產品自己數成片的尺寸、幀數、音軌,和計劃逐項比。
                     對不上就是 readback_mismatch 報錯,檔案留在盤上當證據,
                     不算匯出完成
② 抽幀看像素          從成片裡抽幀,用眼睛看。至少覆蓋:一個推近段、
                     一個整螢幕動畫段、一個只有字幕的段、一個層與層的邊界
③ 人耳聽感            沒人真的聽過,一律記 human listening UNVERIFIED

② 不許用預覽截圖代替。預覽和成片是兩條渲染路徑,驗收要看的正是它們對不對得上—— 拿預覽的圖當成片的證據,等於把要驗的那件事當成了前提。

判推近要找判別性地標,整體印象會騙人(2026-07-29 真踩過):1.6 倍推近後的 螢幕頁面看起來仍像"一整頁",縮圖上和全景幾乎沒差別——曾把正確的推近幀誤判成 "推近丟了",白追半小時、重導兩次。正確判法是找只有裁切才能造成的證據: 被裁掉一半的元素(氣泡從中間斷開)、消失的邊緣元素(側欄、標題欄)。 和來源片同刻幀比對一眼定案。

抽幀就用 ffmpeg:

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

出問題往哪查

--keep-work 會在專案的 .chengfeng-videocut/export/ 下留三樣東西, 它們把「哪一半錯了」直接分開:

assembled.mkv    只有剪輯,沒有任何蓋的東西。它錯 = 帳本或切片錯
overlay/*.png    只有蓋的東西,透明底。它錯 = 字幕樣式或模組錯
spans/*.mp4      合成後的分段。它錯 = 推近或對齊錯

對照表:

成片沒有字幕/動畫       overlay PNG 是不是全透明?模組是不是沒答應 seek?
動畫停在第一幀          模組沒實現 seek,或者 GSAP 時間線沒 paused
畫面整塊白             模組少了 `:root { color-scheme: dark }`
推近的框歪了            模組的 viewBox 和層的 zoom 不是同一組數
成片比計劃短            某個 span 幀數不夠,看 compose 階段的報錯
層邊界閃一小段原片      overlay 截圖陳舊(幀標記驗證失效)。產品靠頁面頂部的
                      幀標記條自證每張截圖屬於哪一幀;若復發,先確認 overlay
                      PNG 頂部有標記條、compose 有裁掉它的 crop
找不到 Chrome          裝 Google Chrome,別改成別的渲染路徑

不許做什麼

  • 不許把「匯出成功」說成「驗收通過」——命令返回成功只是產品自己對得上,不是畫面對
  • 不許用預覽截圖、DOM、日誌代替成片抽幀
  • 不許沒人聽過就報 human listening PASS
  • 不許為了讓匯出跑通去改專案檔案(改字幕、刪層、動帳本)。匯出唯讀,不寫
  • 不許在匯出裡補做上游的活:缺字幕就去寫字幕,缺畫面就去做畫面,別在這一段臨時糊一個

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

相關技能