Innate-Labs/product-demo-video

Product Demo Video（產品展示片）

把一個真實 Web 產品做成有調性的展示片：真實頁面截圖 + 程式碼重建的介面，組裝進瀏覽器視窗 Mockup，配字幕、Logo、音樂，渲染成直式/方型短影片。

它是自動的——你只給一個能跑起來的專案，Claude 會：

• 自動理解產品：讀 CLAUDE.md / README / 路由，搞清每個頁面是做什麼的、產品的調性。
• 自動讀程式碼生成文案：根據每個頁面的真實功能，自動寫出對應場景的標題 / 副標題字幕與網址列，不用你手寫。
• 自動定位 Logo：在 public/ 裡找到你專案的真實向量 Logo，用在片頭與收尾。

你只在幾個關鍵點做選擇題（畫布比例、納入哪些頁面、節奏、聲音）。

前置 Skill：本技能依賴 [remotion-best-practices]（影片框架）和 [agent-browser]（截圖）。處理 Remotion 程式碼前先載入 remotion-best-practices 取得領域知識。

何時用

使用者要把一個跑得起來的 Web 產品（自己的專案 / 給定目錄）做成產品展示 / 宣傳短片。典型：「幫我們的產品做個展示影片」、「把這個頁面做成直式宣傳片」。

產物型態

一個 Remotion 專案，渲染出 mp4：

• 畫布：直版 1280×1706（3:4，預設，適合社群媒體）/ 方版 1080×1080 / 橫版 1920×1080
• 結構：N 個場景，每個場景 = 一張產品頁面（真實截圖或程式碼重建）放進瀏覽器視窗 Mockup，配底部字幕；場景間 crossfade + 整窗緩慢 Ken Burns；收尾落到品牌 Logo + 標語
• 聲音：免版權 BGM（預設）或 TTS 旁白（可選）

完整流程（5 階段）

階段 1 — 摸清產品 & 規劃敘事

1. 讀專案 CLAUDE.md / README.md / DESIGN.md，搞清：產品是什麼、有哪些核心頁面/功能、調性規範（配色/字體/禁忌——見 reference/tone.md，必須遵守專案自己的 DESIGN.md）。
2. 列出頁面路由（find app -name page.tsx），讀懂每個頁面的功能，自動歸納一條「使用者旅程」敘事線（如「核心功能 A → B → C → 結果頁」），並為每段自動擬好字幕文案。
3. 跟使用者確認：畫布比例、納入哪些環節、節奏、聲音方案。截不到真實圖的頁面要提前標註風險（即時/需特殊資料的頁面）。

階段 2 — 截真實頁面（能截的優先）

用 agent-browser。詳見 scripts/capture-pages.md。要點：

• 啟動目標專案前後端（後台），等就緒。
• 設標準視口 agent-browser set viewport 1440 900 2（@2x retina，16:10 正常瀏覽器比例，截圖清晰）。
• 處理登入：多數 (app) 頁面要登入。從 dev.db 找測試帳號；密碼是 hash，經使用者授權後用專案自己的 hash 函數臨時重設（截完必須還原，見教訓）。
• 去掉 dev 角標：agent-browser eval "document.querySelectorAll('nextjs-portal').forEach(e=>e.remove())"。
• 每個目標頁面截一張乾淨圖，存進 Remotion 專案 public/<brand>/。

階段 3 — 程式碼重建截不到的頁面（關鍵品質點）

有些頁面截不到真實圖（即時語音面試間 headless 無麥克風、報告頁依賴後端生成、資料缺失）。不要憑想像畫——

1. 去讀真實元件程式碼（components/.../XxxLayout.tsx 等），看清真實的佈局/元素/資料結構。
2. 按真實結構在 Remotion 裡 1:1 重建成一個 React 元件，渲染進視窗內容區（尺寸 = 視窗內容區 W×H）。
3. 範例見 templates/screens/InterviewScreen.tsx（對話型介面）、templates/screens/ReportScreen.tsx（報告型介面）——它們是「照真實程式碼重建」的中性樣板，換產品時照搬手法、重寫成你產品的真實內容。

階段 4 — 組裝展示片

用 templates/PromoVideo.tsx 作骨架（瀏覽器 Mockup + 場景 crossfade + Ken Burns + 字幕 + Outro + 音訊），templates/PromoRoot.tsx 註冊 composition。

• 每個場景配置 { type: 'image'|'<custom>', src?, addr, title, sub }。
• 網址列隨場景變（提升真實感）。
• 頂部 + 收尾自動定位並使用專案真實 Logo（在 public/ 裡找 icons/logo.svg 之類的向量字標，別用純文字假冒）。
• 嚴格遵守調性規範（見下）。

階段 5 — 聲音 & 渲染

• BGM（預設）：Mixkit 免版權可商用音樂，scripts/get-bgm.sh 下載+試聽讓使用者選。整片鋪底，首尾淡入淡出。
• TTS 旁白（可選）：scripts/gen-tts.sh，走 AiHubMix/OpenAI 相容 /audio/speech（gpt-4o-mini-tts 真人級，需使用者 key）。每句對齊場景，場景時長按旁白長度。別用 macOS say（機械音，品質差）。
• 渲染：npx remotion render <id> out/<name>.mp4，驗證含 audio 軌 + 時長，拷到 ~/Desktop/。

Tone — 調性規範（這是「terminal」質感的關鍵，詳見 reference/tone.md）

預設調性 = 克制、專業、真實。除非專案 DESIGN.md 另有要求：

• 配色：白底（#F4F4F6 畫布 / #FFF 視窗）+ 黑白灰文字（#141414 / #8A8A90），不引彩色；功能性紅點（錄製/連接）等照真實保留。
• 字體：中英文統一 PingFang（"PingFang SC","Heiti SC",sans-serif），渲染機為 macOS 直接可用；不引 Inter 等（中文 fallback 不一致）。
• 瀏覽器 Mockup：圓角 18 白窗 + 頂部 chrome bar（三個灰色圓點，不用紅綠燈彩色 + 網址列 pill），柔和投影。
• 運鏡：緩動統一 Easing.bezier(0.16,1,0.3,1)；視窗浮入用 spring；整窗緩慢 Ken Burns scale 1→1.03（作用在視窗不是內部圖片，否則裁內容）。
• 節奏：場景統一長度（預設每段 60 幀/2s @30fps），整齊；想卡點可測 BGM 的 BPM 對齊小節。
• 字幕：底部居中，標題 PingFang Semibold 大字 + 副標題灰色小字，crossfade。
• 無 emoji。

反面清單（別做）：彩色亂用、紅綠燈彩點、Inter 配中文、objectFit cover 放大裁掉頁面內容、憑想像畫截不到的頁面、機械音 TTS、節奏忽快忽慢、純文字假 Logo。

踩坑教訓（必看）

• headless 瀏覽器沒有麥克風/攝影機：即時語音 / 影片類頁面會卡在「準備 / 裝置不可用」，截不到——直接走程式碼重建，別死磕。
• 本地 dev 資料庫 schema 漂移：程式碼加了 migration 但本地庫沒跑，會 500（如 no such column: xxx）。為截圖 / 填資料，可 ALTER TABLE ADD COLUMN 補缺失的欄位（安全，不刪資料），但要說明。
• 改本地資料庫必須還原：重設的測試密碼、臨時填入的範例資料，截完一律還原原值（先備份原 hash/JSON）。補的欄位可保留（本就是程式碼預期的）。
• objectFit 別裁內容：截圖放進視窗用 objectFit:"contain" 完整顯示；Ken Burns 放大要作用在外層視窗，不是圖片，否則頁面底部被裁。
• 填入範例資料時欄位名要去程式碼確認：前端讀的欄位名常與直覺不同（複數 / 底線命名等），必須讀渲染元件確認，別猜。
• 中文文案含 ASCII 雙引號 → 整個 string 用 backtick（全域 CLAUDE.md 規則）。
• Bash cwd 跨呼叫持久：用絕對路徑，別重複 cd 子目錄。

快速校驗

改完 Remotion 程式碼：npx tsc --noEmit；渲染關鍵幀 npx remotion still <id> out/check.png --frame=N --scale=0.5 自檢視覺；終渲染後 ffprobe 確認音軌+時長。