製作旁白示範影片
您撰寫一個場景檔案：每個場景包含一段旁白以及播放時觸發的點擊操作。腳本會將旁白轉為語音、在固定 1600×900 解析度的無頭 Chromium 中驅動應用程式並錄製螢幕畫面，最後合成出包含語音與內嵌字幕的 MP4 影片。頁面上會疊加可見游標、點擊波紋、高亮標示環與標題卡。
以下所有指令使用 PY，在 Windows 上代表 python，在 macOS 上代表 python3；以及 DV，代表 "${CLAUDE_SKILL_DIR}/scripts/demo_video.py"。每個指令都會輸出純文字狀態行（SCENE …、RECORDED …、CHECK OK、ERROR …）；請閱讀這些訊息，而非自行猜測。
1. 安裝設定（每台機器僅需執行一次）
PY "${CLAUDE_SKILL_DIR}/scripts/setup_env.py"
此指令會在 ~/.claude-demo-video 建立一個私有環境，內含 Playwright、Chromium 與 edge-tts，然後檢查 ffmpeg。結束時會顯示 READY，或明確指出缺少的項目。ffmpeg 是系統工具：請先詢問使用者再進行安裝（Windows 上使用 winget install --id Gyan.FFmpeg -e，macOS 上使用 brew install ffmpeg）。腳本也會在常見的安裝目錄（WinGet、Chocolatey、Scoop、Homebrew）中搜尋。若 ffmpeg 安裝於其他位置，請在每個指令前設定 DEMO_VIDEO_FFMPEG_DIR 為其所在資料夾。
2. 在開始撰寫任何內容前，先與使用者確認影片規劃
請詢問或從對話情境中確認：
- 觀看對象與目的（審查功能的主管、客戶、新進員工）。這將決定影片語氣與解說重點。
- 要展示的內容與順序。 提出一個場景列表（每行一個場景），並獲得同意。目標長度為 3 到 8 分鐘。
- 語音。 預設為自然的英文神經網路語音（edge-tts）。請告知使用者旁白文字會傳送至 Microsoft 的語音服務以產生音訊。 旁白應僅包含功能說明，絕不能包含資料。替代方案為離線系統語音（
--offline）：不會離開本機，但聽起來較為機械。 - 資料。 僅錄製示範資料：虛構人物、
@example.com電子郵件、明顯虛構的專案。切勿錄製真實客戶或員工紀錄，也切勿將錄製器指向正式環境。
3. 準備應用程式
- 應用程式必須正在執行中，且可從本機存取，通常為本機建置版本。
- 若畫面需要資料，請撰寫一個資料植入腳本以及對應的示範資料清除腳本，並執行植入。請為示範資料列加上標記（例如 ID 開頭為
DEMO-），使清除腳本不會誤刪其他資料。 - 確保外寄郵件與通知功能已關閉，或僅傳送至假地址，因為示範操作會點擊真實按鈕（提交、核准…）。
- 會修改資料的場景（核准、刪除）僅能對每次植入錄製一次。每次重錄前都需要重新植入資料。
4. 撰寫場景檔案
請將場景檔案建立在使用者的專案中，例如 demo-videos/<name>.py，絕對不要放在技能資料夾內。請從 ${CLAUDE_SKILL_DIR}/reference/scenes-template.py 開始。完整的實際範例請參閱 ${CLAUDE_SKILL_DIR}/reference/zentrio-timesheet-example.py，該範例製作了 6 分鐘的核准影片。
CONFIG = {'url': 'https://localhost:7101/MyTimesheet', 'ready': '#tsCards .tsw-card', 'sign_in': True}
async def week(r):
await r.click('.tsw-row:has-text("Approval screen")')
await r.spot('.tsw-panel', 3)
SCENES = [
('week', "點擊任務列，記錄面板會在其下方展開。", week),
]
CONFIG['url']是第一個頁面。ready是一個選擇器，僅在該頁面載入且登入完成後才可見。記錄器藉此判斷登入是否成功。- 旁白：每個場景一至三句簡短的對話。解釋某個功能為何重要，而非只是描述畫面上有什麼。請按照實際發音方式書寫數字與符號（例如「二點三零」）。旁白中不要包含資料。
- 動作會在其旁白播放的同時執行。請確保動作時間短於旁白時間；記錄器會等待旁白播放完畢再開始下一個場景。
場景輔助函式（r 是記錄器；其他內容可透過 r.page 存取 Playwright 頁面）：
| 輔助函式 | 功能 |
|---|---|
await r.goto('/path', wait_for=sel) | 開啟頁面（相對於 CONFIG['url']） |
await r.click(target, dx=.5, dy=.5) | 將可見游標移至該處並點擊；dx/dy 選取元素內部的點位 |
await r.move_to(target) | 移動游標但不點擊 |
await r.type(target, 'text') | 點擊欄位並以可見方式輸入文字 |
await r.select(target, value) | 選擇下拉選單選項 |
await r.press('ControlOrMeta+K') | 鍵盤快捷鍵（Windows 上為 Ctrl，macOS 上為 Cmd） |
await r.spot(target, seconds, pad) | 橘色高亮標示環 |
await r.card(kicker, title, lines, bullets) / await r.uncard() | 全螢幕標題卡（介紹、摘要、結尾） |
await r.confirm_click(target, show=4) | 用於呼叫 confirm() 的按鈕：顯示一個仿製對話框，然後接受 |
await r.download(target) | 點擊下載並回傳儲存的檔案路徑 |
await r.show_file(path) | 顯示本機檔案，例如您為下載的報表製作的 HTML 預覽 |
await r.scroll_top()、await r.scroll_x(selector, px) | 平滑捲動 |
await r.clear_toasts(selector) | 移除遮擋按鈕的通知提示 |
await r.wait(seconds) | 暫停 |
target 可以是 CSS 或 Playwright 選擇器字串（'button:has-text("Approve")'），或是 Locator（r.page.locator('tr', has_text='Aarav').first）。
5. 製作旁白、錄製與審查
PY DV voice demo-videos/<name>.py # 每個場景的音訊；印出每個場景的長度
PY DV record demo-videos/<name>.py # 驅動應用程式並擷取畫面
PY DV stills demo-videos/<name>.py # 每個場景兩張靜態截圖，儲存在 <name>-video/stills/
登入。 若 'sign_in': True 且應用程式尚未登入，則會開啟一個瀏覽器視窗，記錄器會顯示 SIGN_IN_NEEDED。請要求使用者在該視窗中登入。絕對不要輸入憑證或要求密碼。 工作階段會儲存在 <name>-video/.profile 中，因此重錄時無需再次登入。
在合成影片之前，務必審查每一張靜態截圖，檢查：
- 正確頁面、面板已開啟、游標位於旁白所指的位置；
- 沒有遮擋操作的元素（通知訊息、Cookie 橫幅、個人檔案選單）；
- 圖片沒有被拉伸或裁切；
- 畫面上沒有真實的個人資料。
出現 SCENE_ERROR 訊息或截圖有誤，表示需要修正該場景函式並重新錄製（若場景修改了資料，請先重新植入）。reference/lessons.md 列出了目前已發生的失敗情況與解決方法。當發現異常時請閱讀該文件。
6. 合成、檢查與交付
PY DV build demo-videos/<name>.py [--out "path/Name.mp4"]
PY DV check "path/Name.mp4" --size 1600x900
run 指令在場景已確定可正常運作後，會依序執行語音、錄製、截圖、合成與檢查。請告知使用者影片的路徑、長度以及內容。除非使用者要求，否則請勿上傳或分享影片。
7. 清理
PY DV clean demo-videos/<name>.py會刪除已儲存的登入資訊。完成後務必執行此動作，因為其中包含真實的工作階段。加上--all參數還會移除畫面影格、靜態截圖與音訊。- 執行示範資料的清除腳本，並停止您啟動的任何應用程式程序。
平台注意事項
- macOS：請使用
python3。字幕由 Chromium 繪製並疊加在影片上，因此在所有平台上看起來一致，無需使用內建 libass 的 ffmpeg（Homebrew 的 ffmpeg 預設不包含 libass）。錄製為無頭模式，因此 Retina 螢幕不會影響影片尺寸。 --headed參數會在可見視窗中錄製。僅在應用程式拒絕無頭瀏覽器時使用，並請使用者不要在錄製期間觸碰或調整視窗大小。DEMO_VIDEO_HOME可變更私有環境的路徑；DEMO_VIDEO_FFMPEG_DIR可指定 ffmpeg 資料夾。