應用程式訓練影片
製作一支專業的實際應用程式訓練影片。影片解析度為 1920 × 1080，採用 H.264 編碼，並包含 AAC 旁白。每個口語句子都附有字幕，每個章節都以卡片開頭，並會剪掉冗長的等待時間。影片具有可重複性：當使用者介面變更時，只需重新執行捕捉與渲染，影片就會立即更新。
運作方式：
- 故事板 包含旁白文字、章節和品牌資訊。
narrate.py使用離線的 Kokoro 語音引擎朗讀每個段落：無需雲端服務、無需帳號、無需費用。- 捕捉腳本 使用 Playwright 驅動真實的應用程式（真實滑鼠移動、看得見的游標和點擊漣漪效果）。它會錄製 Chrome 的螢幕畫面影格，並讓每個段落的畫面長度與其旁白同步。
render.py將各個片段、卡片、字幕帶和經過音量正規化的旁白音軌組合在一起。review.py檢查結果，並建立一個連環圖片（contact sheet），以便在發布前進行審查。
腳本位於此檔案旁的 scripts/ 目錄中。在撰寫旁白前，請先閱讀 references/storyboard.md；在撰寫捕捉腳本前，請先閱讀 references/capture-guide.md。這兩份文件都包含有助於避免常見重錄情況的經驗教訓。
0. 一次性設定
bash <skill>/scripts/setup.sh
這會在 ~/.cache/app-training-video/ 目錄下建立（可透過環境變數 TRAINING_VIDEO_HOME 覆蓋）以下內容：
- 一個獨立的 Python 3.10–3.13 環境，包含固定版本的套件；
- Kokoro 語音模型（約 350 MB）和 Inter 字型，並經過 SHA-256 檢查；
- Chromium 瀏覽器。
所有的腳本都應使用該環境的 Python 直譯器（PY=~/.cache/app-training-video/venv/bin/python）來執行，並傳入故事板的路徑。如果模型檔案已存在於某處，可先設定 MODEL_SOURCE=<dir> 以重複使用這些檔案。ffmpeg 會隨附在內（透過 imageio-ffmpeg）；不會在系統範圍內安裝任何東西。
1. 了解應用程式與目標觀眾
在開始撰寫任何內容之前，請親自使用該應用程式（或閱讀其使用者指南），並了解以下事項：
- 觀看對象： 新客戶、現場工作人員、內部使用者。
- 他們必須掌握的一個工作流程： 從輸入到產出結果的完整過程。
- 可以展示的示範資料： 需確認哪些資料是安全的。
- 如何以乾淨狀態啟動應用程式： URL 或啟動指令，以及需要準備的空白資料夾或示範帳號。
- 品牌資訊： 公司名稱、產品名稱、版本、Logo PNG 檔案、強調色、用於片尾的聯絡資訊。
對於任何你找不到的資訊，請向使用者提問。完整的操作流程影片長度以 6 到 7 分鐘為佳，單一功能的介紹影片則以 60 到 90 秒為宜。
2. 撰寫故事板
將 assets/storyboard.example.json 複製到專案目錄旁，並命名為 storyboard.json，然後依照 references/storyboard.md 的指示進行撰寫。簡而言之：
- 每個段落的旁白長度在 10 到 35 秒之間；
- 章節命名格式為
"n · Title"，並且在每個章節的第一個段落設定card: "chapter"； - 包含
intro和outro卡片； - 為語音引擎拼寫出縮寫詞的發音，並使用
caption_replacements規則將其恢復為書面形式。
在開始錄製前，先將旁白展示給使用者確認：此時修改的成本很低，但之後修改的代價會很高。
3. 產生旁白
$PY <skill>/scripts/narrate.py storyboard.json
此指令會印出每個段落的長度。它只會對文字有變更的段落重新產生語音。如果發音很重要，請聆聽 video-build/audio/ 中的一兩個 WAV 檔案，調整拼寫後再次執行。
4. 撰寫與執行捕捉腳本
將 scripts/capture_template.py 複製到故事板旁，並命名為 capture.py，設定好技能 scripts/ 目錄的路徑，然後按照故事板的順序，為每個要錄製的段落撰寫一個 with rec.segment('<id>'): 區塊。在區塊內部，精確執行旁白所描述的動作：
rec.click,rec.hover,rec.type,rec.drag,rec.scroll,rec.park；- 在需要等待的地方使用
rec.cut()來剪掉等待時間，並等待可見的結果出現。
錄製器會拒絕在非空的 frames/ 資料夾中執行，因此不會混入舊的畫面影格。
$PY capture.py storyboard.json
每個段落都會印出其錄製長度與旁白長度的比較。如果第一個失敗的步驟、任何頁面錯誤或任何未錄製的段落發生，執行會失敗（狀態為 incomplete）。修正步驟、清空 video-build/frames/ 資料夾，然後再次執行。
5. 渲染與審查
$PY <skill>/scripts/render.py storyboard.json
$PY <skill>/scripts/review.py storyboard.json
輸出檔案位於建置資料夾中：
<output_name>.mp4.srt字幕檔-chapters.txt（可貼入 YouTube 影片描述）-poster.jpg-timeline.json-review.jpg：每個段落一張靜態截圖。
請打開連環圖片仔細檢視，並抽樣檢查 MP4 檔案本身。請檢查：
- 每個段落是否顯示正確的畫面；
- 沒有錯誤橫幅、空白圖表或遺留的對話框；
- 游標沒有遮擋正在說明的內容；
- 字幕文字正確可讀。
選取器（Selector）可能在畫面錯誤時仍匹配成功，因此這個檢查步驟是必要的，在確認影片完成前一定要執行。
6. 交付
提供使用者 MP4 檔案、SRT 檔案（大多數播放器在檔名相同時會自動載入）以及章節列表。告知影片長度與檔案大小。發布時，請將 MP4 和 SRT 檔案一起上傳。請妥善保存 storyboard.json 和 capture.py 檔案：下次使用者介面變更時，只需重新執行步驟 4 和 5（如果文字有變動則包含步驟 3）。
疑難排解
| 症狀 | 解決方法 |
|---|---|
Need Python 3.10–3.13 | 安裝 python3.12，或在執行 setup.sh 前設定 PYTHON= |
launch() 雖然應用程式已啟動但逾時 | 應用程式會緩衝輸出：請使用 python -u 執行 Python 伺服器，或檢查 ready 正規表示式 |
| Chromium 在 Linux 上啟動失敗 | $PY -m playwright install --with-deps chromium |
| 定位器（Locator）逾時或匹配到兩個元素 | 將其範圍限制在一個區域內，或使用帶有 exact=True 參數的 get_by_role（請參閱捕捉指南） |
| 段落長度遠長於旁白長度 | 有某些緩慢的操作沒有被包在 rec.cut() 中 |
| 發音錯誤 | 在 speech 中重新拼寫，加入 caption_replacements 規則，然後重新執行 narrate.py |
| 字幕不同步 | 字幕時間是根據旁白長度決定的：請縮短過長的句子，或分割該段落 |