口播成片
官方來源
本 Skill 由 chengfeng / AI產品自由 原創並維護。
https://github.com/Agentchengfeng/chengfeng-videocut-skills
官方帳號:GitHub @Agentchengfeng;X @chengfeng240928;小紅書 / 公眾號 / B站 / 抖音 / 影片號 AI產品自由。
核心流程
這個 Skill 只解決一件事:把一條口播影片做成完整成片;成片比例和動畫風格由用戶配置決定。
+-----------------------------+
| 輸入 |
| 影片 + 字幕 + 可選素材 |
+--------------+--------------+
|
v
+-----------------------------+
| 1. 分鏡稿 |
| 概念分段 + 類型判定 + 畫面來源 |
+--------------+--------------+
|
v
+-----------------------------+
| 2. 時間軸預覽 |
| 原影片/截圖/HTML 與口播對齊 |
+--------------+--------------+
|
v
+-----------------------------+
| 3. 合成 |
| 按用戶配置比例匯出最終 MP4 |
+--------------+--------------+
|
v
+-----------------------------+
| 驗收 |
| ffprobe + 抽關鍵幀檢查 |
+-----------------------------+
不要把 cue 表、HTML 模組、review player、final player、匯出腳本單獨講成用戶流程。它們只是「時間軸預覽」和「合成」裡的實作細節。
用戶配置
每次執行本 Skill,先讀取:
用戶配置/default.json
配置項只負責定義用戶當前選擇:
{
"aspectRatio": "3:4",
"animationStyle": "xiaohei"
}
支援值:
3:4:預設直式高畫質,邏輯畫布1080x1440,預設用 DPR1.5匯出1620x2160。16:9:橫式,邏輯畫布和匯出畫布1920x1080。4:3:橫式,邏輯畫布和匯出畫布1440x1080。animationStyle:預設xiaohei,可選項來自動畫/styles.json。
命令列參數優先級高於用戶配置;沒有明確參數時,匯出腳本讀取 aspectRatio,動畫腳本讀取 animationStyle。比例臨時覆蓋可用:
--config /path/to/config.json
--ratio 16:9
--aspect-ratio 16:9
--width 1920 --height 1080
--dpr 1.5
不要把視覺偏好、模板、編碼品質、輸出目錄、字幕邊距等七七八八的設定寫進 用戶配置/default.json。用戶配置只放當前選擇;動畫目錄只放可選項註冊表和具體風格實作。
動畫風格
動畫風格的當前選擇放在 用戶配置/default.json:
animationStyle
動畫目錄只註冊可選項:
動畫/styles.json
xiaohei 對應:
動畫/ian-xiaohei-svg-motion/
當分鏡或 HTML 模組需要做解釋動畫、流程動畫、手繪感高亮時,預設先用小黑漫畫感 SVG 動效。除非用戶明確指定其他動畫風格,否則不要臨時發明新風格。
輸入
先定位這些檔案:
- 主影片:
source_cut.mp4、*_cut.mp4或用戶指定的剪後影片。 - 字幕:
subtitles.srt、video.srt或subtitles_with_time.json。 - 可選文稿:文章、口播稿、正文草稿,只用於理解意圖。
- 可選素材:
assets/裡的截圖、產品頁、評論圖、結果頁、證明頁。 - 專案規則:如果當前專案有
AGENTS.md或README.md,先讀。
真相源優先級:
實際音訊 / 字幕 > 剪後影片畫面 > 素材檔案 > 文稿草稿
如果文稿和實際字幕不一致,以字幕和音訊為準。
第 1 步:分鏡稿
預設先做 HTML 分鏡核對頁,不先寫 Markdown 表格。
分鏡的前置流程必須按這個順序執行:
- 先按口播語意分段:把講同一個概念、同一個動作、同一個證據的一句、兩句或三句合成一段;不要按字幕編號機械切分。
- 再判斷每段的畫面任務:這是操作演示、原圖講解、結果證明、概念梳理,還是純文字表達。
- 再決定畫面來源:能用真實錄影、原始截圖、原始圖片證明的段落,優先使用原素材;只有概念性講解且當前螢幕主要是文字、空白或弱相關畫面時,才設計 HTML / 小黑動畫。
- 最後才進入具體視覺設計:每個 HTML / 小黑動畫段都要先寫清它的獨立隱喻和動作,再實作模組。
常見路徑:
review/storyboard-audit-vN.html
預設基於這個模板:
templates/storyboard-audit.html
分鏡稿要讓用戶回答:
這句話說到這裡,觀眾眼前該看到什麼?
每段至少寫清楚:
- 時間範圍
- 字幕編號
- 完整口播
- 語意分段依據
- 畫面任務
- 畫面類型:
原影片、操作錄影、原始截圖、原始圖片、資訊圖聚焦、HTML 動畫、文字 + 動畫 - 素材來源
- 鏡頭動作
畫面選擇規則:
- 操作演示:使用原影片 / 原錄影,不要改成抽象動畫。
- 講圖片內容、圖表內容、報錯截圖、產品截圖:直接使用原始圖片或原始截圖,動畫只做圈選、標註、局部聚焦。
- 真實操作、證明頁、結果頁、需要可信度的片段:保留原影片或原始截圖。
- 錄影 / 原影片片段預設按原畫面展示;只有明確需要避開後續統一字幕時,才把該段標記為錄影小窗,並在底部留出字幕安全區。不要把小窗規則批量套到所有錄片段。
- 概念梳理、機制關係、系統分工、觀點歸納,並且當前螢幕主要是文字、空白或弱相關畫面:做 HTML / 小黑動畫。
- 可以用簡短文字輔助理解的抽象段:使用文字 + 動畫;文字負責命名,動畫負責關係和動作。
- 已有截圖或資訊圖:優先復用,不要重畫。
- 同一張圖多次出現時,每次必須承擔不同任務:全貌、局部聚焦、對比、結果復看。
- 不要把所有動畫做成同一套動態。每個動畫段必須先單獨設計動作隱喻,再實作。
分鏡設計硬標準:
- 一頁只講一個概念、一個動作或一個案例。同一段口播裡如果出現兩個獨立案例,必須拆成兩個頁面;不要為了少做頁面把兩個案例擠進同一張表或同一個動畫。
- 每個 HTML / 小黑動畫段必須先寫清楚「這句話說到這裡,畫面發生什麼變化」,再實作。動作要綁定具體口播句或字幕,不要把同一套入場 / 閃爍 / 放大平均套給所有段落。
- 講原圖、截圖、結果頁時,主視覺必須是原素材。HTML 只負責裁切、放大、圈選、標註和焦點切換;不要用錄影抽幀或重畫圖替代原圖。
- 長圖和網頁結果頁預設裁掉無資訊的空白區域,優先露出觀眾正在聽到的區域;口播說到對應對象時,可以放大對應圖片或局部,其餘內容退後。
- 影片畫面裡不要出現素材路徑、內部說明、動作解釋或「原圖素材 · img/xxx.png」這類工作台文字。分鏡稿可以寫來源,成片畫面只保留觀眾需要看的內容。
- 沒有必要的標題就不放標題。結果頁、表格頁、原圖對比頁優先讓主視覺自己說話,只保留短標籤、模型名、指標名或必要的標註。
- 數據對比頁優先使用清晰的表格、列對齊、短標籤和少量高亮。字型大小要服務閱讀,不要把字塞進小方塊;能用簡單表格講清楚,就不要做複雜卡片堆疊。
- 直式短影片裡的表格不能只做成中間一條橫向小表。數據階段要把表格作為主視覺,佔據主要安全區;前置任務說明、案例標籤、總結句只在對應口播階段出現,進入最終數據對比階段後要消失或退到不佔空間的位置。
- 評價詞只寫口播明確說到或剪輯需要強調的正向 / 中性結果。對照項可以留空或只展示數據;不要額外加「慢且貴」等負面用詞,除非口播原句就是這個判斷。
- 圖示必須從動畫庫索引裡找。ChatGPT、Claude、Flash 閃電、Step、DeepSeek、Qwen 等已有圖示不得用抽象形狀替代;新增用戶給的 SVG,要先存入動畫庫並更新索引。
分鏡方向確認前,不要進入時間軸預覽。
第 2 步:時間軸預覽
分鏡方向確認後,再做時間軸預覽。
常見路徑:
review/timeline-preview.html
預設基於這個模板:
templates/timeline-preview.html
時間軸預覽要檢查:
- 畫面切換是否跟口播句子對齊。
- 原影片有沒有被誤換成 HTML。
- 被標記為錄影小窗的段落是否避開底部字幕安全區;未標記的錄片段不要被自動縮窗。
- 截圖、頁面、證明素材有沒有用錯。
- 圖片素材預設保留左右邊距,不要貼滿當前畫面;需要強調完整截圖時再單獨縮小。
- 畫面有沒有擋字、裁切、留黑邊。
- HTML 模組單獨看沒問題,但放進整條時間軸後是否仍然成立。
預覽頁裡有來源影片時,必須用支援 HTTP Range 的服務打開頁面,否則瀏覽器不能隨機 seek,進度條會被拉回開頭。不要用普通 python -m http.server 預覽 MP4 時間軸。預設使用:
node ~/.Codex/skills/chengfeng-videocut-skills/口播成片/scripts/serve_range_preview.cjs \
--project-dir /absolute/path/to/project \
--port 8767
必要時生成:
docs/08-動畫cue表-vN.md
html-modules/module-*.html
html-modules/xiaohei-*.html
如果要新做解釋動畫,先讀 用戶配置/default.json 的 animationStyle,再到 動畫/styles.json 找對應的動畫子 Skill。
每個動畫動作必須綁定到具體口播句,不要平均分配時間。多階段 HTML 動畫必須明確管理顯示隱藏狀態:下一階段出現時,上一階段不再承擔資訊任務的說明卡、標籤和註釋要隱藏;不要讓前一階段繼續佔用主視覺空間,尤其是直式數據表、截圖聚焦和結果頁。
第 3 步:合成
只有用戶確認時間軸預覽後,才能合成。
合成前建立或確認:
final-player.html
新寫 final-player.html 或 HTML 模組前,讀取:
references/artifact-contracts.md
如果專案裡有 HTML 模組,先注入 render mode:
node ~/.claude/skills/chengfeng-videocut-skills/口播成片/scripts/write_render_mode.cjs \
--project-dir /absolute/path/to/project
時間軸預覽和最終匯出必須使用同一套 HTML 渲染上下文。HTML 模組在預覽頁和 final-player.html 裡都要帶 ?timeline=1&render=1,預覽頁只負責把最終畫布等比例縮放放進視窗,不能讓模組按預覽視窗重新響應式排版。
高畫質交付不能把 CSS 邏輯畫布直接放大。預設 3:4 必須保持 1080x1440 邏輯畫布,再用截圖 DPR 1.5 輸出 1620x2160;否則表格、CSS 卡片、截圖標註會在匯出裡相對變小,和預覽不一致。
如果預覽和匯出出現大小不一致,先檢查 HTML 模組內部 CSS、render-mode.js 和匯出 DPR,確認預覽頁與 final-player 的邏輯畫布相同,不要先重導整條影片。常見原因是預覽 iframe 較小,看起來正常;最終高畫質畫布觸發了 .photo-frame { max-width: ... }、.stage { width: min(...) }、.wrap { max-height: ... }、clamp(...) 這類預覽尺寸上限,導致匯出變成「小圖」。修復順序:
- 用
write_render_mode.cjs重新生成html-modules/render-mode.js。 - 在時間軸預覽裡確認 HTML 模組 URL 已經變成
?timeline=1&render=1。 - 確認
export_final_video.cjs的viewport是邏輯畫布尺寸,dpr才是高畫質倍數。 - 用 final-player 在實際匯出 viewport 下抽該模組的關鍵幀,必要時用
getBoundingClientRect()比對主視覺容器尺寸。
直式裡處理橫向小黑 SVG / 16:9 SVG 模組時,禁止用 .wrap { transform: scale(...) } 這類整體放大來解決「小橫條」問題。整體縮放會在 3:4 畫布裡裁掉左右邊緣,尤其是左右分布的模型卡、箭頭、說明標籤。要嘛重排成直式構圖,要嘛保持完整安全區;改完必須抽該模組的左右邊界幀檢查,不能只看中心關鍵幀。
匯出最終影片:
node ~/.claude/skills/chengfeng-videocut-skills/口播成片/scripts/export_final_video.cjs \
--project-dir /absolute/path/to/project \
--input-video /absolute/path/to/source_cut.mp4 \
--duration 173.03
預設按高畫質交付匯出:無損 PNG 中間幀、H.264 crf=14、preset=slow。這樣可以避免瀏覽器預覽清楚、匯出後小字和細線發軟:
node ~/.claude/skills/chengfeng-videocut-skills/口播成片/scripts/export_final_video.cjs \
--project-dir /absolute/path/to/project \
--input-video /absolute/path/to/source_cut.mp4 \
--duration 173.03 \
--frame-format png \
--crf 14 \
--preset slow
只有臨時看節奏、需要快速出草稿時,才明確降級:
node ~/.claude/skills/chengfeng-videocut-skills/口播成片/scripts/export_final_video.cjs \
--project-dir /absolute/path/to/project \
--input-video /absolute/path/to/source_cut.mp4 \
--duration 173.03 \
--frame-format jpeg \
--quality 92 \
--crf 18 \
--preset medium
比例讀取規則見「用戶配置」。專案與用戶配置不同時,可傳:
--config
--ratio
--aspect-ratio
--fps
--player
--stage
--frames-dir
--width
--height
--frame-format png|jpeg
--quality 100
--crf 14
--dpr 1.5
--device-scale-factor 1.5
驗收
匯出成功不等於成片正確。必須做兩步:
- 用
ffprobe檢查解析度、幀率、時長和音訊。 - 抽 3 張以上關鍵幀,人工看畫面是否正確。
- 對每個 HTML 模組,至少抽 1 張對應口播時間點的 final-player 幀,和時間軸預覽的同一時間點對照;大小、位置、裁切和顯示隱藏必須一致,不能只用
ffprobe作為完成依據。
按當前比例檢查解析度,其他期望來自腳本預設值和專案實際輸入。當前預設配置為:
1620x2160
邏輯畫布 1080x1440,DPR 1.5
3:4
30fps
時長和剪後來源影片一致
有音訊
無 HUD、按鈕、審核時間軸、瀏覽器 UI
邊界
適合:
- 中文口播
- 教學、產品演示、結果展示、知識講解
- 已有剪後影片和字幕,素材可後補
- 原影片 + 截圖 + HTML 解釋畫面混合成片
不優先解決:
- 沒有影片,直接憑文稿生成成片
- 複雜多機位真人剪輯
- 需要剪輯軟體工程檔案的精細調色和多軌混音
- 用戶沒看分鏡稿和時間軸預覽就直接要求最終發布
專案衛生
如果在用戶寫作工作區內新增或修改檔案,必須同步更新專案 README 索引。
本地活動日誌統一放在:
log/
log/ 只記錄本機試驗、用戶偏好、臨時結論和未發布的工作過程,禁止上傳 GitHub。該目錄已被 .claude/skills/.gitignore 忽略。
不要在這個 Skill 目錄裡新增 README。這個 Skill 的核心檔案只保留:
SKILL.md
templates/
references/
scripts/
用戶配置/
動畫/
動畫/ 用於沉澱口播成片可復用的 HTML/SVG/GSAP 動畫子 Skill、模板和規則;可選風格見 動畫/styles.json,當前選擇見 用戶配置/default.json。