/pitch-deck-video

從正在運行的本地網頁應用程式生成帶旁白的產品示範影片。剪輯是衍生而來、從不手動計時，因此當前端變動時，您重新錄製，剪輯便會隨之調整——無需修復任何影格編號。

專為實際發生的情況而設計：當您需要影片時，UI仍在變動中。

使用方式

/pitch-deck-video                          # 拍攝當前目錄中的應用程式
/pitch-deck-video <path-to-app>            # 拍攝特定應用程式
/pitch-deck-video --rebuild                # 重新錄製並重新剪輯現有影片專案
/pitch-deck-video --script                 # 僅旁白變更；重複使用上一次的錄製
/pitch-deck-video --render                 # 僅卡片/字幕變更；重新渲染

結構

四個生成的檔案驅動一切。只有第一個是由人類編寫。

檔案	內容	編寫者
`shots.json`	旁白內容、語音、音樂、主題以及瀏覽器執行的動作	您
`src/vo-durations.json`	每句台詞實際所需的時間	`scripts/tts.mjs`
`capture/marks.json`	每次拍攝的開始時間點，以及搜尋位置	`scripts/record.mjs`
`src/frames.json`	拍攝中輸出的影格數量	`scripts/frames.mjs`

src/timeline.ts 從這些檔案中推導出整個剪輯。場景長度來自實際測量的旁白音訊。影片素材會拉伸以符合旁白長度。鏡頭移動來自錄製期間即時測量的元素邊界框，因此移動的按鈕會帶動鏡頭移動，而不是破壞它。

工作流程

1 · 建立專案結構

將此技能的 template/ 複製到應用程式旁邊的 <app-name>-video/ 目錄中，然後執行 npm install。範本包含種子 JSON，以便在首次錄製前進行型別檢查和渲染。

切勿為單一專案編輯 ~/.claude/skills/pitch-deck-video/template/ 下的檔案——這是共用範本。請編輯副本。

2 · 先檢查是否已有儲存的登入狀態

如果應用程式有身份驗證，請尋找儲存庫為其自身端到端測試保存的 Playwright 儲存狀態 (。auth/*.json, storageState, playwright/.auth/)。將 app.storageState指向該檔案，則錄製將從已登入狀態開始，無需在鏡頭中顯示登入流程。只有在沒有此類檔案時，才建立登入拍攝——然後使用{"type": {"sel": "…", "env": "DEMO_PASSWORD"}}，這樣密碼永遠不會寫入 shots.json`。

3 · 在編寫任何文字前先了解應用程式

啟動應用程式的開發伺服器，並以 1920×1080 解析度對每個路由進行截圖，然後閱讀這些圖片。不要根據原始碼編寫旁白。您編寫的是評審將會看到的內容，只有螢幕截圖能告訴您這些。

// 一次性腳本；Playwright 隨範本提供
for (const r of routes) {
  await p.goto(base + r, { waitUntil: 'networkidle' });
  await p.waitForTimeout(700);
  await p.screenshot({ path: `/tmp/shots/${r}.png` });
  console.log(r, await p.evaluate(() => document.documentElement.scrollHeight));
}

注意滾動高度：任何超過 1080 的內容都需要 scroll 動作，否則它永遠不會出現在鏡頭中。

4 · 編寫 `shots.json`

從 template/shots.example.json 開始。參閱 references/shots-reference.md 以了解每個欄位和動作。

從應用程式的設計標記中提取 theme.colors，使卡片和影片素材看起來像一體。用真實的架構填充 cards.arch.nodes——哪些盒子是模型呼叫，哪些是確定性程式碼。這個關鍵點區分了示範和單純的包裝，而評審會關注這一點。

重要的旁白規則：

12–16 個節拍，總時長 1:30–1:50。 在 2:00 的限制內，保留 10 秒的空間。
每個節拍一個想法。 當想法結束時，節拍結束。
說出數字。「六個人評分，Priya 獲勝」優於「它選了一個人」。
永遠不要描述 UI。 不要說「這裡我們點擊核准」——而是要說出它的意義。
以使用者的話語開始，描述問題，在產品名稱出現之前。
以一個句子結束，希望它留在畫面上。

5 · 建置

APP_DIR=/path/to/app npm run all

旁白 → 錄製 → 影格 → 渲染。如果沒有服務提供 app.url，它會啟動開發伺服器，並讀取應用程式自己的 dev 腳本來了解該框架如何使用連接埠。如果需要特定設定，請設定 app.devCommand。典型的完整重建：約 2 分鐘。

shots.json 首先被驗證，因此重複的 id 或未知的動作會在兩秒內失敗，而不是在兩分鐘後生成令人困惑的影片。

6 · 透過查看來進行品質檢查——這是不可省略的

npm run qa          # 每個拍攝一個靜止影格，堆疊成聯絡表
npm run qa 3        # 每個拍攝三個靜止影格，當您想檢查轉場時使用

然後將這些表格作為圖片閱讀。快速瀏覽影片很慢，並且您會錯過一些東西；聯絡表只需幾秒鐘，並能準確捕捉到重要的失敗。

檢查：capture/marks.json → warnings 是否為空（缺少選擇器是警告，不是崩潰——您仍然會得到一部影片，以及一份故障清單）。然後：每個字幕是否落在支援它的影格上？是否有任何空白或白色的影格？小字體是否清晰可讀，還是需要 focus？

references/troubleshooting.md 包含此流程實際遇到的所有失敗以及每個失敗的修復方法。在從頭除錯之前，請先閱讀它。

在 UI 變更後重新剪輯

這就是整個系統的價值所在。

APP_DIR=/path/to/app npm run all

大多數變更無需任何其他操作——移動的元素、重新設計的頁面、新的文案。仍然需要判斷的情況：

頁面被刪除或重新命名 → 重新指向或替換該拍攝。
功能被重寫 → 該節拍的旁白現在是關於已不存在事物的陳述。重寫該行。
選擇器確實消失了 → 檢查警告清單並在那裡修復它。

旁白會按行快取，因此只有編輯過的台詞會重新合成。

語音

語音是完成影片中最大的品質差異，而預設的語音確實很差。 在首次建置前就坦白說明，而不是事後才說。

tts.provider: "minimax" — 良好。詢問使用者他們的 MiniMax 金鑰存放位置，並將 tts.envFile 指向該檔案。語音 ID 來自 MiniMax 的系統語音清單；語音上的語言標籤是提示，而不是限制（帶有烏克蘭語標籤的語音，使用 languageBoost: "English" 可以很好地朗讀英文）。
tts.provider: "say" — macOS 內建的合成器，通常只安裝了舊版的語音。它很機械化，會念錯產品名稱，而且對任何觀看者來說都很明顯。可用於檢查時間，但對於評審或客戶會看到的影片來說很弱。
真人錄音勝過任何合成器。 將 <id>.wav 檔案放入 public/vo/ 中，然後執行 npm run script；系統會重新測量持續時間，整個影片會自行重新調整時間，無需其他編輯。

如果沒有金鑰，仍然建置影片——但要事先告訴使用者，語音部分是弱項，而擁有金鑰或用麥克風錄製十分鐘可以解決這個問題。不要默默地提供一個 say 語音旁白，好像它已經完成了一樣。

如果 API 無法連線，MiniMax 會逐行回退到 say，因此執行永遠不會完全失敗。

切勿將 API 金鑰複製到專案中。 scripts/tts.mjs 從環境變數中讀取 MINIMAX_API_KEY / MINIMAX_GROUP_ID，否則會從 tts.envFile 指定的任何檔案中解析它們。詢問使用者他們的金鑰存放位置，並將 envFile 指向它。

真人錄音勝過任何合成器：將 <id>.wav 檔案放入 public/vo/ 中，然後執行 npm run script——它會重新測量它們並重新調整整個影片的時間。

音樂

scripts/music.mjs 使用 yt-dlp 擷取 music.url 中命名的曲目，並根據當前影片長度剪輯背景音樂。告知使用者在發布前檢查曲目的授權——庫存曲目通常在使用說明中標明出處即可免費使用，而無需出處則需付費。標題和 URL 會儲存到 public/music/SOURCE.txt，以便於複製致謝資訊。

禁忌

不要手動調整時間。如果某個節拍感覺太趕，表示旁白對該拍攝而言太長——請修正 shots.json，而不是時間軸。
不要將 <Screen /> 放在 <Sequence> 內部。它設計上會讀取絕對時間；而在 Sequence 內部使用 useCurrentFrame() 會傳回 Sequence 本地的影格。這曾經導致影片出問題，症狀（影片與語音微妙地不同步）很難發現。
不要讓設定時間出現在鏡頭中。導航、資料載入和關閉橫幅都發生在拍攝的捕捉視窗內，並會在旁白下被拉伸。在設定步驟後放置 {"cut": true}；影片素材將從該點開始。
不要拍攝任何存根（stubbed）功能。如果按鈕返回「連接後端」，請將其排除，並告知使用者在功能連接後應加入哪個拍攝。
在檢查警告清單之前，不要發布。
不要描述您看到在不同執行之間會漂移的數字，並且永遠不要將螢幕描述為已滿，而此帳戶的版本是空的。如果評審發現一個虛假陳述，他們會對其餘內容大打折扣。

Pitch Deck 真機示範片（真實應用）