系列講解影片全流程製作
把「一個主題」變成「一期成品」：策劃 → 頁面編排（HTML 動畫） → 講解稿 → 配音 → 字幕 → 1080p MP4 → 抖音封面（橫 16:9 + 豎 9:16）。 預設風格檔案沉澱自《道德經》講解影片系列實戰（新中式水墨 / 雲健男聲 / 白字黑發光字幕），整套可複用，逐項可覆蓋。
畫面路線（v2.0 起預設走 HTML 動畫；v2.1 圖文協同）：
- 預設：HTML 動畫頁——基於講解詞產生帶入場動效與頁間交叉淡化的 HTML 展示頁，確定性逐幀渲染成影片，動畫 100% 同步進成品（方案與編排規則見
references/html-animation.md）。 - v2.1 圖文協同：內建水墨 SVG 場景庫（水波孤舟/漣漪/山巒/墨竹/望月/錦鯉）+ 條目圖示 + 外鏈圖片支援，按講解詞自動配對或明確指定，圖形部件錯峰入場與文字動效統一編排。
- 回退：靜態 PPT 幀 + xfade（需要原生 PPT 表格/複雜版式、或用戶點名要 .pptx 時用）。
v2.3 起每期標配抖音封面：橫版 16:9 + 豎版 9:16，按主題 AI 生成成套（橫版錨點→使用者確認→豎版派生），不取影片幀；流程見階段 ⑥ 與 references/douyin-covers.md。
開工五問（每期開工先問；使用者說「按上期來」「老規矩」則全部取預設直接開工）
- 這期講什麼？（主題 / 經文章節）
- 內容深度：詳細講解 / 要點講解？（預設：詳細講解）
- 成品時長目標？（預設 6-7 分鐘）
- PPT 風格沿用新中式水墨？（預設：是）
- 音色沿用雲健、字幕白字黑發光？（預設：是）
風格檔案（使用者未指定時直接採用）
| 項 | 預設值 |
|---|---|
| PPT 風格 | 新中式水墨：宣紙米白 + 墨黑 + 黛青 + 朱砂 |
| 字體 | 標題 SimSun（宋體），正文 Microsoft YaHei（SlideDSL 一律用英文 font-family） |
| 畫面元素 | SVG 水墨插畫（不用 AI 生圖，保真度 100%、可反覆改） |
| 動畫 | HTML 動畫頁：標題 blur-in / 條目錯峰 fade-up / 頁間交叉淡化 / cue 要點強調（原「元素動畫被否」針對 ffmpeg 疊加方案，HTML 確定性渲染路線已於 v2.0 落地驗證） |
| 音色 | zh-CN-YunjianNeural（雲健 · 男 · 渾厚） |
| 語速 | +0%（整篇統一；僅當使用者明確要求才改，不得按內容密度分段變速） |
| 字幕 | 白字 + 黑色外發光（blur 0.8），透明背景，底部居中 |
| 畫幅 | 1920×1080（16:9） |
| 發音修正 | 「老子」→ TTS 讀「老紫」（lǎo zǐ 文讀三聲），字幕仍顯示「老子」 |
| 抖音封面 | 橫版 16:9 + 豎版 9:16；期名四字大字；AI 生成成套（錨點鏈），不取影片幀 |
工作目錄約定
在工作區建 影片工作目錄/，每期一個子目錄（以主題命名）：
影片工作目錄/{期名}/
├── {BASE} 講解稿.json # 單一資料來源：標題/音色/發音修正/每頁講解詞(+頁面文案)
├── {BASE} 講解稿_可編輯.txt # export_txt.py 匯出，供使用者記事本審閱
├── 01_deck/ # deck.html(動畫展示頁,可預覽) + deck.json(時間軸清單)
├── 01_html_frames/ # f_XXXXX.png 逐幀 + frames_manifest.json（HTML 路線）
├── 01_frames/ # frame_01.png ...（靜態 PPT 回退路線）
├── 02_audio/ # slide_01.mp3 ... slide_NN.mp3（逐頁語音）
├── 配音試聽/ # 多音色試聽 mp3 + 配音試聽.html
└── 03_output/ # 成品 {BASE}(帶字幕).mp4
BASE = 期名（若含「講解稿」字樣自動剝除）。講解稿 JSON 用 Python json.dump 程式化生成，禁止手寫含中文引號的 JSON（會跳脫報錯）。
封面畫布 {期名}-抖音封面.miora 按生成媒體交付規範放工作區根，雙尺寸 PNG 在其 _assets/ 目錄。
分階段流程（含 4 道確認關卡，每道關卡拿到使用者答覆再繼續）
開工前（首次或環境異常時）先跑環境體檢：
python scripts/doctor.py，MISSING 補齊再開工。 節奏底線、閘門清單、BGM 與改版範圍表見references/pacing-and-gates.md（融合自 liyupi/ai-promo-video-maker 的方法論：節奏硬標準 / 資料校驗 / 雙閘門 / 改版紀律）。
階段 ① 內容策劃（關卡 1：開工五問）
按五問確定方案後，產出簡短策劃包（文案結構 / 視覺方案 / 音訊方案），使用者認可後進 ②。
階段 ② 頁面編排（HTML 動畫路線 = 預設）
- 不再做 PPT：直接程式化生成
{BASE} 講解稿.json，逐頁寫講解詞text； 每頁可選title（頁面標題）、points（螢幕條目陣列）、layout（title/bullets/quote/end）、cues（要點強調，見下）——缺省時由講解詞自動推導（規則見 references/html-animation.md）， 但正式製作建議明確給出，品質更穩。 - 頁數按內容深度定（詳細講解約 8 頁）；表格/資料仍建議走靜態 PPT 回退路線。
階段 ②′ PPT 製作（靜態回退路線）
- 用 workbuddy-pptx（SlideDSL）製作幻燈片，頁數按內容深度定（詳細講解約 8 頁）。
- 演講者備註（notes）= 逐頁講解詞：一次寫入，多處複用（影片配音 / DOCX 時間軸 / 剪映導入）。
- 字體用英文名（SimSun / Microsoft YaHei），中文名不渲染。
- 配色與元素按風格檔案；表格/資料頁優先原生 PPT 元素。
階段 ③ 講解稿定稿（關卡 2：講解稿審閱）
-
從 PPT notes 提取講解詞，程式化生成
{BASE} 講解稿.json（結構見下）。 -
匯出可編輯文字供審閱：
python scripts/export_txt.py "{BASE} 講解稿.json" -
明確提示使用者用記事本開啟 txt 逐頁審閱；使用者改完返回後同步回 JSON：
python scripts/import_txt.py "{BASE} 講解稿.json" "{BASE} 講解稿_可編輯.txt"使用者僅回覆「文案可以」無修改時跳過同步。
階段 ④ 配音（關卡 3：音色試聽，硬關卡 voice_confirmed）
-
生成試聽頁讓使用者選音色：
python scripts/preview_voices.py 配音試聽 -
使用者選定後寫入 JSON 並置
voice_confirmed=true（缺它 TTS 與合成直接拒絕執行）：python -c "import json;p='{BASE} 講解稿.json';d=json.load(open(p,encoding='utf-8'));d['voice']='zh-CN-YunjianNeural';d['rate']='+0%';d['voice_confirmed']=True;json.dump(d,open(p,'w',encoding='utf-8'),ensure_ascii=False,indent=2)"語速預設
+0%不動；僅當使用者明確要求變速才改，且整篇統一。
階段 ⑤ 成品合成（關卡 4：合成前向使用者確認開工）
順序：合成語音 → 生成動畫頁 → 渲染幀 → 合成影片（HTML 路線）；或 渲染幀 → 語音 → 影片（靜態路線）。
HTML 動畫路線（預設）：
-
合成逐頁語音（必須先做——頁面時長取自真實語音時長）：
python scripts/tts_synth.py --narration "{BASE} 講解稿.json" --out 02_audio -
生成動畫展示頁（deck.html 可用瀏覽器
#preview預覽動畫）：python scripts/gen_html_deck.py --narration "{BASE} 講解稿.json" --audio 02_audio --out 01_deck -
逐幀渲染（只渲染動畫視窗，幾分鐘內完成）：
node scripts/render_html_frames.mjs --deck 01_deck --out 01_html_frames -
合成影片（concat 幀序列 + 逐句字幕，白字黑發光預設樣式）：
python scripts/compose_html_video.py --deck 01_deck --frames 01_html_frames --audio 02_audio --narration "{BASE} 講解稿.json" --out 03_output預設產出
{BASE}(帶字幕).mp4；--also-plain加出無字幕版；--bgm <檔案>加背景音樂（自動 ducking，旁白起時壓低音樂；曲庫 Mixkit 免費可商用，須使用者試聽後定）。
靜態 PPT 回退路線：
-
渲染畫面幀（首選 PowerPoint COM，需本機裝 PowerPoint）：
powershell -ExecutionPolicy Bypass -File scripts/export_frames.ps1 -Pptx "{BASE}.pptx" -OutDir 01_frames已有 PDF 時可用 pymupdf 路徑：
python scripts/pdf_to_frames.py "{BASE}.pdf" 01_frames 1920。 渲染後抽查 3 頁（首頁/內容密的一頁/表格頁）確認無字體異常。 -
合成逐頁語音：同上 tts_synth.py。
-
合成影片（靜態頁 + xfade + 逐句字幕）：
python scripts/compose_video.py --frames 01_frames --audio 02_audio --narration "{BASE} 講解稿.json" --out 03_output -
驗證交付：入場/轉場點抽幀確認動畫正常、無黑閃；頁中段抽幀確認字幕； 跑成品閘門：
python scripts/verify_output.py --video "03_output/{BASE}(帶字幕).mp4" --deck 01_deck（規格/時長/響度/黑幀/靜音全過才交付）；present_files交付。
階段 ⑥ 抖音封面（每期標配：橫版 16:9 + 豎版 9:16）
成品交付時一併給封面，方便直接上傳抖音。不取影片幀——按本期主題 AI 生成成套，交付 .miora 畫布 + 雙尺寸 PNG；
提示詞模板 / 意象對照 / 品檢清單見 references/douyin-covers.md。使用者明說不要封面時跳過。
- 文案：期名四字做圖上唯一大字（如「有無相生」）；不加副題小字（必糊）；除主文案外畫面零文字。
- 成套錨點鏈（硬規則）：橫版錨點（純文生圖 1920×1080）→ 使用者確認 → 豎版以錨點為參考圖派生（1080×1920，豎向三段式）；風格 token 原文複用，禁止兩張盲發。
- 視覺：與成品同風格（宣紙米白 + 墨黑 + 黛青 + 朱砂、水墨暈染、疏朗留白）；意象從本期主題取（如「有無相生」→ 圓月 + 水中月影倒影）。
- 尺寸照實：模型取整可能給 1920×1072 / 1072×1920（差 8px），如實報告；使用者要精確再補邊到標準值。
- 交付：工作區根
{期名}-抖音封面.miora+ 雙尺寸圖卡片；封面文案與尺寸記入需求確認.md。
（需要文字 100% 可控或跨期複用模板時，改走可編輯設計稿排版匯出；預設 AI 生成。）
階段 ⑦ 微調迭代
- 每期目錄維護
需求確認.md：五問答案 + 每輪修改記錄（使用者原話入檔），收到反饋先記後改、 只重做必要步驟（改動範圍→重做步驟對照表見references/pacing-and-gates.md）。 - 字幕樣式/顏色調整 → 見
references/subtitle-style.md（ASS 顏色是 BBGGRR 反序，必讀）。 - 發音問題 → 只改
tts_replacements重跑 TTS + 合成，字幕不動。 - 字幕同步 → compose 優先讀
02_audio/timing_XX.json（TTS 句級真實時間軸，tts_synth 自動產出）。 - 畫面/動畫問題（HTML 路線）→ 改講解稿 JSON 的 title/points/visual/cues 或
gen_html_deck.py編排 → 重跑 生成 deck → 渲染 → 合成（音訊複用，除非講解詞也改了）。 - 畫面問題（靜態路線）→ 改 PPT 重導幀，音訊複用。
- 封面修改 → 文案/意象不對只重出對應件；風格整體不對重出錨點再派生（見
references/douyin-covers.md）。
階段 ⑧ 交付驗收（自檢清單）
- 畫面：字體/配色無異常；表格頁（若有）渲染正確
- 動畫：標題/條目入場自然、頁間轉場平滑、cue 強調與講解對位（HTML 路線）
- 配音：可聽清、無吞字、語速全篇統一
- 發音：文讀詞正確（如「老子」= lǎo zǐ）
- 字幕：與語音逐句同步、樣式統一、無溢出裁切
- 轉場：交叉淡化平滑、無黑閃、無空白幀
- 時長：≈ 目標時長（±10 秒）
- 格式：1920×1080 / H.264 / AAC / .mp4
- 封面：橫豎兩版四字無缺筆、風格成套、尺寸照實（清單見
references/douyin-covers.md）
講解稿 JSON 結構（單一資料來源）
{
"title": "老子今讀-上善若水",
"voice": "zh-CN-YunjianNeural",
"rate": "+0%",
"voice_confirmed": true,
"tts_replacements": { "老子": "老紫" },
"slides": [
{ "idx": 1, "text": "第一頁講解詞……" },
{ "idx": 2, "text": "第二頁講解詞……",
"title": "水的三種品格", "points": ["利他，滋養萬物", "不爭，甘居下位"],
"cues": [ { "t": 4.5, "dur": 0.9, "target": 0 } ] }
]
}
idx從 1 連續編號，與frame_XX.png（靜態路線）/slide_XX.mp3嚴格對應。- HTML 動畫路線每頁可選欄位：
title（頁面標題）、points（螢幕條目陣列）、layout（title/bullets/quote/end）、cues（要點強調：t=頁內相對秒、target=條目序號 0 起、dur=強調時長、action=pulse）；圖文協同（v2.1）：visual（水墨場景 water/ripples/mountain/ bamboo/moon/fish，缺省按講解詞關鍵字自動配對）、icons（條目圖示 droplet/wave/mountain/moon/leaf）、image（外鏈圖片路徑，內嵌右欄）。缺省時由講解詞自動推導，正式製作建議明確給出。 tts_replacements：發音修正表，只作用於 TTS 輸入，字幕與可編輯文字保持原字。通用系列留空{}。voice_confirmed預設 false，關卡 ③ 置 true，否則腳本拒絕合成。
常見失敗速查
| 症狀 | 原因 | 處理 |
|---|---|---|
| 字幕外框顏色和預期不符 | ASS 顏色是 BBGGRR 反序 | 紅=&H000000FF 藍=&H00FF0000 黑=&H00000000 |
| 文讀詞被讀成白話音（如老子 lǎo zi） | TTS 預設取口語讀法 | 加進 tts_replacements 重跑 TTS |
| PPT 字體不渲染 | 中文名無法辨識 | 用 SimSun / Microsoft YaHei |
| 一步合成白屏/濾鏡鏈崩 | xfade 後疊 overlay 覆蓋 | 拆兩步：先底板再疊加；逗號跳脫 \, |
| 幀 |