瀏覽器展示影片
您以程式碼方式編寫影片腳本,因此每次錄製皆可重複:更換聲音或修正一個標籤就能自動重新錄製,無需手動重錄。管線如下:
script.cjs ──tts.cjs──▶ audio/*.wav + durations.json
│ │
└──────────record.cjs◀───────────┘ Chrome + overlay, CDP screencast → takes/<target>/frames + timeline.json
│
post.py ──▶ MP4 (cuts removed, narration + click sounds, −16 LUFS, chapters)
│
review.py ──▶ contact sheets + loudness/chapter check → you inspect, then deliver
引擎:此技能中的 scripts/ 目錄。每個影片專案位於 ~/Movies/Demos/<slug>/(絕不使用會被清除的 /tmp),內含 video.config.cjs、script.cjs、audio/ 與 takes/。可運行的範例:examples/hello-orders/(一個嵌入在主機 shell 中的小型頁面,可用於檢查您的設定)。在首次錄製前,請先閱讀 references/lessons.md。
需求:Chrome、Node(含 Playwright,record.cjs 會自動尋找,或可在設定檔中設定 playwright)、ffmpeg/ffprobe、Python 3 以及用於 Polly 的 AWS CLI。
1. 確認影片內容(在任何程式碼之前)
請確認並提出一份大綱供使用者回饋:
- 觀眾對象。 內部影片需涵蓋角色、權限、控制項與已知限制,並以「須知事項」章節結尾。主管與客戶影片則僅涵蓋成果與順利路徑。
- 端到端流程, 以章節劃分,並設定目標長度。內部深度探討影片約 10–12 分鐘較為合適。
- 錄製地點(需決策)。 逐步導覽會點擊真實按鈕並寫入真實狀態,因此絕不能在真實的共享資料上執行。建議使用複本、測試工作區或含有真實資料的開發環境,並能於每次錄製之間重設。若製作複本會寫入生產環境,則需要明確的同意。
- 身份(需決策)。 若流程需要兩個人(例如建立者與審核者),可由一位真實團隊成員在第二個視窗中登入,或由同一人扮演兩個角色並在影片中標示。絕不建立使用者或處理密碼;如果需要測試帳號,請由使用者建立。
- 聲音(需決策)。 預設為 Polly 生成式「Amy」(en-GB),在真實觀眾測試中表現良好。在產生所有內容前,請提供每個候選聲音約 30 秒的樣本:
aws polly synthesize-speech --profile <dev profile> --region eu-west-2 --engine generative --voice-id Amy --output-format mp3 --text "<passage with the product's jargon>" sample-Amy.mp3請使用非生產環境的 AWS 帳號。macOSsay可離線運作,但聽起來較為合成。使用者的真實聲音則是最自然的選擇。 - 畫面構圖。 僅顯示產品本身:不含主機側邊面板、清單或橫幅。請在設定檔的
setuphook 中配置此項。
2. 設定專案
P=~/Movies/Demos/<slug>; K=~/.claude/skills/browser-demo-video
mkdir -p "$P" && cp $K/templates/video.config.cjs $K/templates/script.cjs "$P"/
在 video.config.cjs 中,填入下列項目:可拋棄環境的 url、若產品在 iframe 中執行則設定 frame、ready、setup(畫面構圖)、theme(產品強調色與頁尾)、voice 以及 helpers.waitLoaded(產品的載入完成訊號)。
在編寫步驟之前,先對 UI 進行對映。開啟它,列出穩定的選取器(id、角色、data-*、顯示的文字),並注意較慢的載入。偏好使用基於顯示文字的選取器(例如 tr:has-text("-1,250.00") [data-resolve]),而非自動產生的鍵。
3. 編寫場景腳本
每個步驟包含 { id, chapter?, pre?, say?, act?, gap? }。h API 的詳細說明位於 templates/script.cjs 頂端。
- 旁白驅動時間點。
act在片段播放時執行,h.at(0.6)可將第二個動作與話語對齊。每個say維持一到兩句口語句子。 - 按照口語方式撰寫數字(例如 "ninety-seven percent"、"the fourteenth of September")。
- 若存在真實使用者的真實決策,請使用它們,以確保畫面中的數字與團隊所知一致。
- 在每個章節前放置章節卡片(
h.card), 並加入 3–6 個單字的標籤醒目環。僅在需要強調某個觀點時使用note(),例如安全性屬性、注意事項或「在實際使用中…」。 - 將每個慢速載入包裹在
h.cut(() => h.waitLoaded(), 'Loading …')中。 該段時間會在後製中被移除。 - 在畫面上和旁白中都說明每個簡化處理。 例如,一人扮演兩個角色:顯示阻止它的控制項、顯示「僅為此錄製」而變更的設定,然後解釋實際使用中的情況。
- 指向下載內容,不要點擊它們(請參閱 lessons)。
4. 產生語音旁白
node $K/scripts/tts.cjs "$P"。僅重新產生已變更的台詞。Claude 無法聆聽結果,因此請指出有風險的詞彙(縮寫、名稱),並請使用者檢查。若使用 macOS say,請將縮寫拼成字母(例如 "S A P")。
5. 試運行,然後登入,最後錄製
- 試運行。 將
TARGET=preview搭配previewUrl指向本地建置版本(如果有的話)。否則在可拋棄環境上執行短片段:ONLY='^(c1|load0|where1)$' node $K/scripts/record.cjs "$P" record。使用 Read 工具檢查數個影格(takes/prod/frames/*.jpg,錯誤時檢查failure.png),並使用 ffprobe 確認影格為 1920×1080。之後重設環境。 - 登入。 使用
run_in_background執行node $K/scripts/record.cjs "$P" login。使用者在開啟的視窗中登入,然後關閉視窗。如果他們說已完成但視窗仍開啟,請執行pkill -INT -f "record.cjs.* login"。 - 完整錄製。 重設環境,然後使用
run_in_background執行node $K/scripts/record.cjs "$P" record。開始前,告知使用者此過程大約需要旁白長度再加三分之一的時間,並且會顯示一個他們不得點擊的可見 Chrome 視窗。等待完成通知,不要使用 sleep 輪詢。檢查日誌,確認每個步驟都顯示ok且沒有FAILED或CRASHED行。
6. 組裝與審閱
python3 $K/scripts/post.py "$P/takes/prod" "$P/takes/prod/walkthrough.mp4" # run_in_background; 對於 10 分鐘的影片約需 10 分鐘
python3 $K/scripts/review.py "$P/takes/prod" "$P/takes/prod/walkthrough.mp4" "$P/review" # 可選:使用 step_id:0.8 挑選影格
閱讀每個 review/s*.jpg 連絡表。檢查是否有裁剪或重疊的標籤、出現在錯誤元素上的醒目環、未被裁切的載入狀態,以及殘留的覆蓋層。響度應約為 −16 LUFS,章節數量應與腳本相符。在腳本中修正問題,重設環境,然後重新錄製。重新錄製的成本很低。
7. 交付與清理
- 交付。 將影片複製到
$P/<slug>.mp4,然後open它。如果存在舊版本,請保留它並重新命名(例如old-<voice>-<slug>.mp4),不要覆蓋。 - 報告。 提供影片長度、解析度、章節、聲音、錄製地點、所有顯示的簡化處理、您無法驗證的部分(音訊),以及任何遺留的視覺瑕疵。
- 清理前先詢問。 在獲得使用者同意前,不要移除可拋棄的複本或環境,也不要刪除
takes/(影格佔用數 GB)。保留script.cjs、設定檔和audio/,以便日後可以重新錄製影片。 - 記錄下來。 如果這項工作屬於某個票證或筆記檔案,請在該處記下影片的位置,並標明複本的刪除尚待處理。僅提交該檔案。