HTML 影片與本地旁白
交付可播放的 MP4、字幕、可繼續修改的 HTML 分鏡和生成配置。以使用者目前的專案、素材、音色與風格為準；這些腳本不綁定任何 AI Agent、帳號或模型服務 API。
開始前
- 讀取目標專案說明、既有成片與本地工作約定，確認實際功能和示範範圍。不要把計劃中的能力展示成已實現的介面。
- 指定獨立的影片專案目錄，保持原始程式碼、生產資料和舊版成片可回復。修改現有影片時先讀取最新配置和備份相關輸出。
- 已確認的音色直接沿用。選擇新音色時，優先使用同一段短稿做等響度試聽；無需重複要求使用者確認已選定的方案。
- 初次執行或更換機器時讀 環境與命令。本套件的配音實作要求 Apple Silicon / MLX；Node 渲染入口獨立於配音實作。
製作流程
- 確定內容。 把觀眾需要理解的操作串成因—果明確的分鏡。每幕一個主要資訊，旁白口語化，畫面保留關鍵文字。根據內容決定幕數與總時長，不套用固定九幕或兩分鐘模板。
- 準備真實素材。 用示範資料擷取介面、局部截圖或實際操作。瀏覽器控制方式遵循當前 Agent 和專案要求。讀 畫面與素材，不要複用其他專案的截圖、人員資訊或內部地址。
- 確定聲音。 在
project.json配置音色、風格和語言；先聽新音色的短樣，再批次生成。用相鄰語義段落組成有界講述組，沿用同一音色、風格和取樣參數。不要逐句隨機換種子，也不要預設整篇無限長合成。分組原則見 旁白與對齊。 - 核對內容與時序。 用獨立 ASR 找漏句或重複，再用強制對齊定位原稿。兩者作用不同：對齊能給出時間，不能證明實際說對了所有文字。檢查同音字、英文術語和最後幾個字。
- 按聲音安排畫面。 在實際停頓處切章，保證最後一個字完整結束，並留出適合內容的收尾時間。預設約一秒可作為技術講解的起點。局部強調與操作錄影跟隨語音標記，而不是沿用舊版固定秒數。
- 用 html-video 渲染。 先檢查 HTML 抽幀，再透過 ContentGraph、ProjectOrchestrator 和 Hyperframes 匯出。外部資源應本地化或嵌入；動畫使用
window.__hvPlayAll()，避免字型載入期間提前播放。協議見 畫面與素材。 - 檢查成片。 完整解碼 MP4，核對音影片時長和每個切幕點的音軌，再檢查瀏覽器播放、跳轉和畫面。只檢查 WAV 或字幕檔案不足以證明最終影片正確。通過後提供本地預覽、MP4、字幕和原始檔案。
可執行入口
所有路徑由參數提供。完整欄位見 專案格式。下面的 SKILL_DIR 指本技能目錄，DEMO_PROJECT 指獨立的影片專案：
python "$SKILL_DIR/scripts/audio.py" init --project "$DEMO_PROJECT"
# 編輯 project.json，準備 assets/；必要時先執行 audition。
python "$SKILL_DIR/scripts/audio.py" validate --project "$DEMO_PROJECT"
python "$SKILL_DIR/scripts/audio.py" synthesize --project "$DEMO_PROJECT"
python "$SKILL_DIR/scripts/audio.py" check-text --project "$DEMO_PROJECT"
python "$SKILL_DIR/scripts/audio.py" align --project "$DEMO_PROJECT"
node "$SKILL_DIR/scripts/compose.mjs" --project "$DEMO_PROJECT"
node "$SKILL_DIR/scripts/verify.mjs" --project "$DEMO_PROJECT" --stage scenes
node "$SKILL_DIR/scripts/render.mjs" --project "$DEMO_PROJECT"
node "$SKILL_DIR/scripts/verify.mjs" --project "$DEMO_PROJECT" --stage export
node "$SKILL_DIR/scripts/serve.mjs" --project "$DEMO_PROJECT"
Node 的渲染、瀏覽器檢查和截圖命令透過 HTML_VIDEO_ROOT 或 --html-video 定位已安裝的 html-video。使用隔離環境裡的 Python，不要把相依套件裝進系統 Python。
修改和排錯
- 文案變更：重新合成受影響的組、核對、對齊、建構和渲染。圖片或佈局變更：重新建構、檢查畫面、渲染。音色變更：重新走聲音與時序流程。
- 語音達到 token 上限或輸出重複：縮短出問題的組，優先保留已驗證的其餘組。不要把不完整結果當成功交付；連續失敗時保留診斷與可用素材，說明具體阻塞。
- 尾字不完整：按「原始合成 → 解碼長度 → 歸一化 → 拼接 → MP4」排查。追加靜音無法補回已經被裁掉的音節。 當前腳本只在偵測到 Qwen3-12Hz 無 padding 長度異常時啟用局部修正，不改第三方安裝目錄。讀 字尾回歸與音訊排錯。
- 不要把這次的音色、配色、組數或某版庫的缺陷變成對所有任務的固定要求。若使用另一種 TTS 或既有配音，保留同樣的時間、樣本與匯出校驗約束。
- 成片發佈到外部平台、上傳業務資料或通知他人，不屬於預設的本地製作步驟；按使用者實際授權執行。