Motion video
製作 10–30 秒的動態圖形短片，完全使用真實程式碼：Swift 合成器編寫樂譜，Swift CoreGraphics/CoreImage 渲染器在相同的節拍網格上繪製每一幀（支援子幀動態模糊、真實高斯模糊、磨砂玻璃效果、底片顆粒感），並由 AVFoundation 編碼為 H.264 + AAC。此技能資料夾內包含所有必要元件；僅需 macOS + Xcode 命令列工具。
目標是達到「動態設計師的作品集」水準，而非簡單的展示：每個畫面都與音樂節拍同步，螢幕上沒有任何純裝飾性的內容，且每個宣稱都真實有據。
資料夾結構
engine/—audio_core.swift+audio_main.swift（樂譜引擎），video_core.swift+video_main.swift（渲染引擎）。請勿針對每個專案進行修改；專案程式碼應放在專案資料夾中。scripts/mv.sh— 建置與執行腳本：audio、stills <beats>、video [out]。levels.py、sheet.py、probe.swift由它調用。- 完整的運作專案位於配套技能
app-3d-video（template/：score.swift、scenes.swift、project.env，以及 SceneKit 層s3d.swift）。對於僅 2D 的影片，請複製其project.env與score.swift，並參考references/engine-api.md撰寫全新的scenes.swift。 examples/scores/energetic-128bpm.swift— 高能量發表樂譜（包含 Drop、填充、淡出）。references/motion-direction.md— 根據語氣調整節奏、緩動函數、轉場、佈局、說故事模式、審查清單。在規劃場景前先閱讀。references/score-guide.md— 節奏/調性/編曲配方，匹配品牌聲音的調性、響度目標。在編寫樂譜前先閱讀。references/engine-api.md— 每個繪圖/音訊函數及其簽名。在撰寫程式碼時閱讀。
工作流程
1. 簡報（只問能改變結果的問題）
確定：目的與目標受眾、影片長度、長寬比例（預設 1080×1920 直立；可透過 W/H 設定為 1920×1080 或 1080×1350）、語氣、螢幕文案語言。如果使用者不在乎，則使用預設值：15 秒、直立、英文文案、語氣與產品領域相符。如果要求的內容在符合目標語氣的節奏下無法容納於指定長度，請告知並詢問要捨棄哪一項——長度或內容——而不是硬塞。例如：一個健康應用程式想要平靜的節奏同時又是 15 秒；正確的答案是減少場景，而非加快節奏。
2. 研究什麼是真實的
螢幕上的一切必須有憑有據：
- 已發佈的內容：自最近幾個版本更新以來的
git log、CHANGELOG、發行說明。 - 確切的產品文案：閱讀程式碼以取得通知標題/內容、按鈕標籤、Siri/意圖對話字串、片段標題、引導文案。直接引用；不要將其改寫為承諾。
- 標記任何說明性內容（範例名稱、計數、時間），並在交付時告知使用者。
- 保持故事內部一致性：如果場景 1 在 9:41 記錄了 Metformin，場景 2 就不能詢問上次服用 Metformin 是什麼時候並回答「13 小時前」——請改用另一種藥物。
3. 素材
收集真實的品牌素材：應用程式圖示（最大 PNG）、標誌、品牌顏色（設計 Token / 素材目錄）、產品已使用的官方徽章（例如「Works with Apple Health」），以及產品自身的音效（通知/音效標誌 WAV）。使用 afconvert -f WAVE -d LEF32@48000 -c 1 in.wav assets/name.wav 將單次音效轉換給合成器使用；如果儲存庫中有 SVG，則使用 sharp/resvg 轉換為 PNG，或使用 qlmanage -t -s 1024。
優先使用帶有一組資料（一個桌布、一個時鐘時間、一組名稱）的重新創建向量 UI，而非原始螢幕截圖。來自不同來源（不同時間、設備、資料、幀）的螢幕截圖並列在一起看起來很奇怪；觀眾會立即注意到。如果你確實使用螢幕截圖，請在單一會話中使用 xcrun simctl status_bar booted override --time 9:41 … 擷取，之後清除覆蓋，並且切勿擷取恰好開啟的其他應用程式。
4. 在節拍網格上規劃
影片長度 = 小節數 × 4 × 60 / BPM，因此一起選擇 BPM 和小節數（15 秒 = 6 小節 @ 96 BPM，8 小節 @ 128 BPM）。在專案中撰寫 plan.md：一個表格，列出小節 → 場景 → 每個節拍上的提示（文字揭示、卡片落地、勾選符號出現、轉場）。每個小節一個想法；重要時刻（標誌、關鍵功能、結束卡）位於強拍上。請參閱 references/motion-direction.md 以了解語氣預設值與模式。
5. 專案資料夾
在 ~/Movies/MotionVideo/<slug>/ 中工作（此路徑會保留以供後續修改）：
mkdir -p ~/Movies/MotionVideo/<slug> && cp ~/.claude/skills/app-3d-video/template/{project.env,score.swift} ~/Movies/MotionVideo/<slug>/
編輯 project.env（BPM、DURATION、W、H、FPS），將品牌素材放入 assets/，然後改寫 score.swift 並撰寫 scenes.swift。在 scenes.swift 頂部為該品牌重新指派調色盤變數（INK、TEAL、MINT、GREEN、GLOW、PAPER、DARKTEXT、ORANGE、DARK_MID、LIGHT_GLOW_A/B）。
6. 先做配樂
撰寫 score.swift（配方請參考 references/score-guide.md），然後執行 mv.sh <dir> audio。你無法聽到它——請讀取音量輸出：RMS 在目標語氣範圍內、無削波、段落對比符合你的意圖（安靜的開頭、Drop 處的提升、淡出前的下降）。影片會讀取 music.wav 用於音訊反應元素，因此在靜止畫面前渲染音訊。
7. 場景，然後靜止畫面審查——至少兩輪
撰寫 scenes.swift，定義 func render(_ t: Double, frame: Int)，然後執行：
~/.claude/skills/motion-video/scripts/mv.sh <dir> stills 0.5,2,4.25,6,8.5,10,13,16,20,22.5
使用 Read 開啟 <dir>/sheet.png 並檢查 references/motion-direction.md 中的清單（彈簧過衝處的重疊、被截斷的下沉部分、文字太小、模糊的交叉淡變、不一致的 UI、空白區域）。也要挑選轉場中間的節拍，而不僅僅是靜止狀態。修正並重新渲染，直到一輪檢查完全乾淨。靜止畫面渲染速度約為 0.1 秒/幀，因此可以自由迭代。
8. 最終渲染與驗證
mv.sh <dir> video <dir>/out.mp4 — 在 SUB=5 動態模糊設定下約 0.3–0.5 秒/幀（15 秒 @ 60 fps 約需 5–8 分鐘），因此在背景執行。探測工具會印出持續時間和音軌；此外，可以提取幾幀（.build/probe out.mp4 <dir> 2,5,9,12）並查看它們。
9. 交付
複製到 ~/Downloads/<Product>_<Topic>_<duration>s[_vN].mp4，使用 SendUserFile 發送，並報告：逐拍的故事（秒數）、哪些素材和字串是真實的、哪些是說明性的、你僅透過測量來判斷音訊，以及給使用者的簡短檢查清單（以合適音量聆聽、在手機上檢查可讀性、品牌/徽章使用情況）。修改時保留先前的版本（v1/）。
修改
大多數反饋可以對應到一個調整旋鈕：更慢/更平靜 → 降低 BPM + 減少場景 + 阻尼彈簧（k≈5, w≈6）+ 更長的揭示時間（0.9–1 拍）+ 使用焦點轉移/虹膜轉場而非快速甩鏡；更多能量 → 使用充滿活力的配樂、帶過衝的彈簧、快速甩鏡、Drop 處的閃爍；「我不理解功能 X」 → 在一個設備上展示完整的因果關係（請求 → 回應 → 結果），使用產品真實的回應文案，並以價值而非功能名稱作為標題。