product-video
真實畫面 + 事件記錄 → 宣告式計劃 (YAML) → pvk render → 連絡表 → 最終作品。
腳本負責處理時間、縮放、疊加與音訊；你負責分鏡、撰寫計劃與檢視影格。
PVK=~/.claude/skills/product-video/bin/pvk # 或安裝後使用 `pvk`（執行 `pip install -e ~/.claude/skills/product-video`）
使用時機
| 使用者想要 | 製作 | 優先閱讀 |
|---|---|---|
| 讓使用者學習某項功能或整個應用程式（"video hướng dẫn"、教學、入門） | tutorial：每章 1-3 分鐘，然後 pvk join | references/storyboard.md |
| 為產品或版本吸引注意（"video quảng cáo"、宣傳、上市、預告） | promo：一個 30-45 秒的 16:9 剪輯，對準節拍 | references/storyboard.md |
| 簡短的網路應用程式示範或錯誤重現片段 | 僅使用 web-video 技能 | - |
嚴格規定
- 真實應用程式，使用樣本資料。 錄製真實產品，並使用逼真但虛構的樣本資料。不得使用 mockups，絕不能使用真實客戶資料、機密或生產帳號（
references/privacy.md）。 - 先寫分鏡表，獲得同意後再行動。 以口語文字撰寫分鏡表，在開始任何錄影前取得核准。
- 遵循專案的設計。 在專案上執行
theme init，並比對其設計指南檢查結果。 - 音樂與音效是強制性的。 每支影片都需有背景音樂與 UI 音效；總音量調整至 -16 LUFS。
- 先草稿、檢視、再最終版。 使用
--draft --check渲染，開啟每一張連絡表，修正後才使用--final。 - 資料不得離開本機（上傳、貼文、問題附件）除非得到擁有者的同意。
- 絕不操作安全、鑰匙圈或登入對話框。 將這些交給使用者處理。
步驟 0. 設定（每台機器一次）
$PVK doctor # 檢查 ffmpeg、Python 3.11+、套件、Chromium、字型、選用工具
python3 -m pip install -r ~/.claude/skills/product-video/requirements.txt && python3 -m playwright install chromium
$PVK fonts # 下載 Inter、Playfair Display、JetBrains Mono（OFL 授權）至 ~/.cache/product-video
$PVK sfx gen && $PVK music beds
$PVK selftest # 使用內建示範檔渲染一個短章節與宣傳片（約 1 分鐘）
缺少工具：請顯示安裝指令並詢問；不要靜默安裝。
步驟 1. 從專案建立主題
cd <video-folder> # 例如 <project>/video（將輸出檔保留在 git 之外）
$PVK theme init --repo <project> --out theme.json
$PVK fonts --theme theme.json
$PVK overlay chapter title="Preview" --theme theme.json --out preview.png # 查看效果
針對 theme.json 中的顏色、字型、brand 與 logo，根據設計指南的說明手動調整（references/theme.md）。
步驟 2. 分鏡表
教學影片：每個使用者需要學習的任務為一個章節；每個章節包含章節卡、帶有 3-8 個編號字幕的畫面、回顧卡。宣傳短片：5-8 個亮點，每個亮點為一個簡短標題卡加上 2-4 秒的畫面瞬間，以及結尾卡。以表格形式撰寫（時間、畫面、字幕、聲音）並取得同意。詳細說明請見 references/storyboard.md。
步驟 3. 錄製
| 產品 | 方法 |
|---|---|
| 原生 macOS 應用程式 | 撰寫 scene.py（參考 examples/scene_native.py），然後使用 $PVK capture native scene.py --app "App" --out takes/s1 --rehearse 排練，再移除 --rehearse 正式錄製 |
| 網頁應用程式 | 使用 web-video 錄製（record.py --slug x），然後使用 $PVK capture import video-out/x/v1 --name w1 匯入 |
| 其他情況 | 將 raw.mp4 和 events.json（格式請見 references/plan-format.md）放入 takes/<name>/ 目錄 |
| 尚無應用程式 / 僅測試 | 使用 $PVK demo --out takes/demo |
每次錄製前：載入樣本資料、關閉通知（請勿打擾）、關閉舊的 toast 提示、固定視窗大小。
每次錄製後：執行 $PVK check popups takes/s1 與 $PVK check grab takes/s1 grab.png 1 5 9 檢視畫面。
macOS 常見問題（Mission Control 按鍵、Cmd 與 Ctrl 差異、真實滑鼠游標、HUD）：references/pitfalls.md。
步驟 4. 計劃
將 examples/tutorial.yaml 或 examples/promo.yaml 複製到錄製資料夾旁並進行編輯。畫面片段中的時間為來源秒數（來自錄製的 events.json）；框線為來源像素。完整格式請見 references/plan-format.md。
$PVK render ch01.yaml --only-plan # 快速：out/plan/ch01.md 列出每個片段、字幕、縮放、聲音、警告
修正所有警告（字幕過短、重疊、跨縮放的 callout、兩位數的步驟編號）。
步驟 5. 草稿與檢查
$PVK render ch01.yaml --draft --check # 720p；輸出至 out/drafts/ch01.mp4 + out/check/ch01/contact-*.png
$PVK render ch01.yaml --frames 3.2,7.5 # 在指定輸出時間點產生靜態圖，以便更仔細查看
$PVK promo promo.yaml --draft --check # 宣傳片：使用相同引擎，剪輯對齊節拍網格
開啟每一張連絡表（讀取 PNG 檔案）。檢查項目：字幕可讀且不遮蓋動作、縮放位置正確、沒有作業系統彈出視窗或殘留的 toast、游標位於點擊位置、卡片拼寫正確、音量約 -16 LUFS。最多進行 3 次修正，然後向使用者展示草稿與連絡表。
步驟 6. 最終版與完整剪輯
$PVK render ch01.yaml --final # 1080p，輸出至 out/final/ch01.mp4
$PVK join out/final/tutorial.mp4 out/final/ch0*.mp4
$PVK check out/final/tutorial.mp4
報告：檔案路徑、長度、音量、無法檢查的項目（例如無法聽到混音效果：請明確說明）。
音樂與音效
music: bed:soft-piano | bed:ambient | bed:promo 為合成背景音樂（原創作品，免費使用）。對於有授權的曲目：執行 $PVK music fetch（取得來源），然後執行 $PVK music add track.mp3 --title ... --author ... --source URL --license ...（會正規化至 -20 LUFS 並記錄於 music/LICENSES.md）。絕不提交第三方曲目至版本庫。
音效對應、音量壓縮與響度：references/audio.md。
參考資料
references/storyboard.md：教學 vs 宣傳、章節結構、字幕寫法、節拍剪接references/plan-format.md：所有計劃鍵、events.json 格式、時間軸計算references/theme.md：theme.json、theme init、字型（OFL）、標誌references/audio.md：背景音樂、授權音樂、音效對應、響度目標references/capture.md：原生 macOS 錄製、web-video 匯入、錄製資料夾結構references/pitfalls.md：真實專案中發生過的所有問題與解決方法references/privacy.md：資料與分享規則