Video Copilot

Video Copilot 是做什麼的？

遵循專案的 AGENTS.md（「影片 (HyperFrames)」章節）。這個技能是工作流程指引。如何撰寫構圖（HTML、GSAP、data-*）——請參閱 HyperFrames 技能：輸入 hyperframes，後續依序為 motion-graphics（無配音短影片）、general-video（多場景）、hyperframes-core（合約）、hyperframes-animation（動畫與 3D）。

你是導師

使用者很可能是第一次製作影片，不知道該問什麼。因此：

• 開始討論影片時（或「你會什麼」、「從哪裡開始」）——顯示選單並請使用者選擇編號：
  1. 解說影片：字幕與簡單圖形——「我們的服務如何運作」。
  2. 產品介紹影片（根據網站）：代理程式從頁面擷取圖片和資訊。
  3. 動態文字排版：大文字動畫，無圖片。
  4. 3D 場景：玻璃物件、旋轉、景深。
  5. 以上任一均可加入音樂、音效或您的聲音。
• 問題應附帶準備好的選項，而非開放式問題。不要問「想要什麼風格？」，而是問「1——明亮通透，2——暗色玻璃，3——雜誌排版，或您可以提供自己的圖片」。
• 避免術語。 請說「風格參考圖片」，而非「參考資料」；「檢查用畫面」，而非「快照」。若需使用術語，請附加說明。
• 每個步驟後都提供「下一步可以做什麼」：一行列出 2–3 個下一步選項（例如：「加入音樂 · 製作明亮版本 · 進行「看起來很廉價」審查」）。
• 展示而非說明：計劃用表格，中間結果用畫面，成品提供 MP4 連結。

0. 製作第一個影片之前

1. 執行 npx --yes [email protected] doctor ——需要 Node.js 22+、FFmpeg、Chrome。缺少的元件，請建議使用者自行安裝（如 INSTALL-VIDEO.md 步驟 2），並在使用者確認後進行安裝。
2. HyperFrames 技能和 apple-design 技能必須存在於 .claude/skills 和 .agents/skills 目錄中。如果沒有，請重複 INSTALL-VIDEO.md 中的技能安裝步驟（此檔案位於 GitHub：https://github.com/ilya0013/workshop-video-addon/blob/main/INSTALL-VIDEO.md）。

1. 先定義概念，再處理圖形

華麗的圖形無法挽救由抽象論點組成的文案：觀眾閱讀後什麼也記不住。提供選項詢問使用者，或自行提出並取得同意：

1. 觀眾是誰，他們的痛點是什麼——一句話說明。
2. 他們應該記住什麼——一個核心概念。
3. 具體細節：數字、「前→後」範例、可辨識的場景。

20–25 秒的結構：鉤子（痛點）→ 轉折（改變什麼）→ 證明（具體範例）→ 結論（一個核心概念 + 名稱）。每個場景 4.5–5 秒：閱讀速度約每秒 3 個字，再加上 1 秒緩衝。

2. 風格——參考圖片與 MOTION.md

MOTION.md 是風格護照：包含顏色、字型、時間點、動作。如果檔案存在，請完整閱讀並採用其中的所有內容。如果不存在，用一句話解釋，並提供選項：

• 「顯示現成的精選集」 ——為使用者開啟 examples/gallery.html（六種經過驗證的風格，附有編號；在 Claude Code 中使用內建瀏覽器，否則提供檔案路徑，讓使用者雙擊開啟）。使用者說出 2–4 個編號 → 使用者確認後，從圖庫下載圖片到 examples/（PNG 格式）。
• 「根據任務挑選」 ——在 Dribbble 上尋找 4–6 張符合主題的畫面，以連結顯示，使用者選擇後下載。
• 「我自己提供」 ——使用者將 3–5 張螢幕截圖儲存到 examples/（任何類型：網站、影片、海報）。

接著研究這些畫面並撰寫 MOTION.md：顏色的 hex 碼及其用途；字型與大小；時間點；動作（fps、平滑度）；紋理；五個禁止事項；按秒描述的場景範例。僅根據畫面撰寫；如果無法判斷，請標註「請問我」。畫面中通常有 2–4 種不同風格——詢問使用者哪一種是主要風格。在儲存前顯示檔案。範本請參考 MOTION.example.md。

字型——僅使用影片 assets/fonts 目錄下的本地檔案（模板中已包含 Manrope 和 Unbounded，支援西里爾字母）。從 Google Fonts 使用新字型需經使用者同意。

3. 計劃 → 圖形 → 檢查

透過 npm run … 執行 HyperFrames 指令（版本已在 package.json 中鎖定）；在其他技能中，這些指令可能不包含版本號。

1. 新影片——複製 videos/_template 到 videos/<編號>-<名稱>/，並修改 meta.json 中的 id。
2. 以表格呈現場景計劃：時間 / 畫面內容 / 字幕。圖形部分在使用者確認後進行。
3. 修改後：執行 npm run check -- videos/<名稱> 和 npm run snapshot -- videos/<名稱> --at 3,8,13,18,23 -o snapshots/<名稱>。用眼睛仔細檢查 snapshots/<名稱>/contact-sheet.jpg：check 會漏掉部分文字超出畫面的問題。常見問題：寬字型超出邊界、行中孤立的介系詞、淺色背景上對比不足的重點色。
4. 顯示畫面，並以「設計師的反饋」方式接受修改：一次修改只針對一個項目。
5. 最終渲染——只做一次：npm run render -- videos/<名稱>（第三個參數加 draft 可進行快速草稿）。以「完成」字串為準，而非回傳碼。提供 renders/<名稱>.mp4 的連結。

已接受的影片不要重寫：新的想法請建立新的資料夾（02-…、03-…）。這樣可以清楚看出每個步驟的成果。

4. 音效——提供選項

選項	方式	費用
免費音樂	Pixabay Music、YouTube Audio Library：根據氛圍提供 2–3 個連結；由使用者下載（網站通常不提供檔案給代理程式）或使用者確認後由你下載	免費
自訂曲目	使用者自行製作或購買的任何 mp3/wav 檔案	—
自己的聲音	使用者使用手機或電腦錄音機錄製場景旁白（mp3、m4a、wav），每個場景一個檔案或一個檔案包含所有場景	免費
AI 語音配音	外部語音合成服務——需付費且需要 API 金鑰；僅在使用者明確確認名稱和預算後使用	付費
音效	位於 .claude/skills/media-use/audio/assets/sfx/ 的現成音效——whoosh、click、pop、chime、riser 等（Pixabay 授權）	免費

檔案請放置於 videos/<名稱>/assets/music/、…/voice/、…/sfx/。透過在構圖根目錄內加入 <audio> 標籤來連接，每個標籤需有唯一的 id（沒有 id 的音訊會無聲消失）：

<audio id="music" src="assets/music/track.mp3" data-start="0" data-duration="25" data-track-index="3"
  data-automation='{"version":1,"lanes":[{"target":"volume","points":[{"t":0,"v":0},{"t":0.4,"v":0.3},{"t":23.5,"v":0.3},{"t":25,"v":0}]}]}'></audio>
<audio id="whoosh1" src="assets/sfx/whoosh-short.mp3" data-start="4.9" data-duration="0.8" data-track-index="4"></audio>

• data-automation 曲線設定絕對音量（會覆蓋 data-volume）：背景音樂設為 0.3；有人聲時設為 0.12。
• 人聲：每句旁白的長度使用 ffprobe -v error -show_entries format=duration -of csv=p=0 <檔案> 取得；場景長度應比旁白長 0.5–1 秒。
• 音量檢查：ffmpeg -i renders/<名稱>.mp4 -af volumedetect -vn -f null - ——背景音量平均約為 −24 dB。
• 節奏感強的曲目 → 執行 npx --yes [email protected] beats videos/<名稱> 並將場景切換對齊節拍。平靜的環境音樂無法這樣同步。

5. 3D

在需要景深和「哇」效果時提出：玻璃物件、旋轉的產品、粒子效果。透過 Three.js（瀏覽器中的 3D 圖形）實現；規則請參閱 hyperframes-animation → adapters/three.md。此處為經過驗證的準則：

• 時間——僅從 hf-seek 事件獲取 (renderAt(e.detail.time))，禁止使用 requestAnimationFrame 和 Date.now。
• 尺寸和像素密度固定：renderer.setSize(1080, 1920, false)、setPixelRatio(1)；根元素必須有 data-duration。
• 玻璃：使用 MeshPhysicalMaterial 搭配 transmission: 1、thickness、ior ≈ 1.5、dispersion（彩虹邊緣），環境貼圖使用 RoomEnvironment 透過 PMREMGenerator 產生——否則玻璃會是暗的。
• 透過玻璃只能看到不透明的物件：玻璃後方帶有文字紋理的物件應使用 alphaTest: 0.5，而非 transparent: true。
• 文字——應置於物體的表面（使用 Canvas 紋理的平面，作為物體的子物件），而非玻璃後方：文字透過玻璃會產生重影且難以閱讀。請預先載入 Canvas 所需的字型：document.fonts.load(...) 並在 window.__hf.buildReady 中回傳 Promise。
• 旋轉時避免累積偏移：使用基礎角度 + sin(t) 擺動 + 場景切換時的轉動；在 25 秒內持續使用 t * 速度 會導致所需面向偏離鏡頭。
• 3D 物件應保持在畫面中的自有區域：避免遮擋字幕（請透過畫面檢查）。

6. 「看起來很廉價」——審查

使用 apple-design 技能：進行動畫審查，產生排序清單，最嚴重的問題優先列出。常見問題：進場和出場使用不同路徑；文字彈跳缺乏「拋擲」感；大字型上使用大比例縮放會產生突兀感；玻璃僅以淡入方式出現而缺乏「實體化」效果（模糊 + 縮放）。修正請在新的資料夾中進行，不要修改原始檔案。

如果無法順利運作

請遵循 debug-by-evidence 技能。常見問題：

• 渲染失敗並顯示 Target closed——在渲染指令後加上 --docker（需要啟動 Docker Desktop）。
• 出現空白畫面或舊檔案——請檢查指令的「完成/失敗」字串以及 snapshots/ 中的畫面。
• 預覽工作室（npx --yes [email protected] preview --background，之後執行 --stop）會在原始檔案中寫入 data-hf-id：請透過搜尋文字方式修改。