mathruffian-dot / claude-motion-explainer

# claude-motion-explainer
**用一句話，讓 coding agent 做出一支「原理解說動畫」。** 上網查資料、寫腳本、中文旁白、一格一格做動畫、字幕、三色配色、自我審查，最後輸出可以直接上課投影或上傳 YouTube 的 MP4。
這是一組給 Claude Code（以及 Codex、Gemini CLI 等讀得懂 `SKILL.md` 的 agent）用的 skills，建立在 HeyGen 開源的 HyperFrames（HTML + GSAP → MP4）之上。
> 與 Anthropic 官方的 Claude Motion 無關。這是社群做的開源工作流。
## 你會得到什麼
用這套技能做出來的第一支片：〈Tesla Roadster 的三個神奇配備〉，105 秒、9 格。
- 用國中理化解釋三件事：倒掛靠壓力差，滯空靠作用力與反作用力，超快加速靠突破輪胎摩擦力的上限。
- 繁體中文旁白，字幕逐句高亮。
- 黑底、白線稿，橘色只標重點。
- 每個數字都在畫面上標「宣稱」或「估算」。
## 包含的 skills
| Skill | 做什麼 |
|---|---|
| `motion-explainer` | **主流程**：研究 → 需求訪談（含三個顏色）→ 分鏡與子句化旁白 → TTS → 每格派一個 sub-agent 平行製作 → 字幕 → 套色 → 審查 → 輸出 |
| `motion-design` | 品味規則：緩動、節奏、閱讀停留、繁體中文排版、三色配色，全部附具體數字 |
| `review-loop` | 自我審查：在每個旁白子句截一格拼成 contact sheet，逐張對照檢查表 |
`motion-explainer/references/lessons.md` 收錄第一支片實際踩過的 26 個坑：整格樣式消失、遮罩漏字、數字和長條不同步、字型不一致……每一條都附解法。
唸錯字也有工具：整支片做完才發現某個字唸錯（例如英文品牌名、破音字），用 `fix_voice.py` 產生試聽檔，讓你用耳朵從幾個候選裡挑一個，再把那一句**整句等比伸縮回原本的長度**換進去。每一格的長度都不變，動畫不用重做。
## 需要的環境
先跑 `python skills/motion-explainer/scripts/hw_check.py`：它會檢查你的 CPU、記憶體、GPU 和硬碟，建議要用哪個旁白引擎、輸出時同時開幾個 worker。各步驟吃多少資源，見 `hardware.md`。
- Node.js 22+、ffmpeg、Python 3 + Pillow + fonttools（`pip install pillow fonttools`；另外裝 `brotli` 的話，瘦身後的字型會是 woff2）
- HyperFrames：`npm install -g hyperframes`，再跑 `hyperframes skills update` 和 `hyperframes skills update faceless-explainer`
- 旁白（擇一，詳見 `tts-setup.md`）：
 - **edge-tts（預設，大多數人用這個）**：`pip install edge-tts`。不需要 GPU，產生時要連網，有台灣口音的男聲和女聲。
 - **Breeze TTS 2（進階）**：本機 NVIDIA GPU（建議 12 GB 以上），可以用文字描述來設計聲音。模型和產生的聲音**只限研究與非商業用途**。想用的話，請 agent 照 `tts-setup.md` 一步一步帶你安裝。
## 安裝
 [code] 
**給其他 agent（Codex、Gemini CLI 等）**：這些 skill 只用到終端機指令和一般的讀寫檔案，沒有 Claude 專屬的工具。兩個要注意的地方，`SKILL.md` 開頭都有寫：
- 工具和 HyperFrames 官方 skill 的位置用代號 ` `、` ` 表示，開工前先用一行指令找出實際路徑。
- 「每格派一個 sub-agent 平行做」在沒有 sub-agent 的 agent 上改成一格一格依序做，結果一樣，只是比較慢。
字型（開源 OFL）不放在 repo 裡，每個專案要用時，跑一次 `bash skills/motion-explainer/scripts/fetch_fonts.sh ` 就會放好。預設全片使用 **源石黑體 粗體**（GenSeki Gothic Bold），中文、英文、數字、字幕都是它。影片做完、正式輸出前，`subset_fonts.py` 會把字型瘦身成只含片中用到的字（源石黑體從 15 MB 降到約 140 KB）。
## 怎麼用
在 Claude Code 裡直接說：
 [code] 
Agent 會先問你播放平台、長度、旁白聲音和**三個顏色**（背景色、主色、強調色，預設是黑底、白字、橘色重點），確認後才開始做。做完會交給你 MP4 和一張總覽圖。
## 三色主題與字型
像簡報版型一樣，由你決定三個顏色和一個字型：
 [code] 
強調色只給「答案、結論、關鍵數字、章節卡」。想換顏色或字型，改 `theme.json` 再跑 `python skills/motion-explainer/scripts/theme.py --project `，然後重新輸出就好，不用重做動畫。
## 延伸：動畫教學簡報
soil-motion-deck 把這套技能和 SOIL Teaching Deck 接在一起，一次做出兩樣東西：一份 .pptx 教學簡報，關鍵頁嵌入動畫片段；以及同一份內容的配音字幕解說影片。
## English
A set of agent skills that turn one sentence into a narrated, captioned explainer animation (MP4) on top of HyperFrames: web research → brief (incl. a three-color theme) → clause-cued storyboard → TTS (edge-tts by default, Breeze TTS 2 optional) → parallel per-frame sub-agents → captions → theming → contact-sheet self-review → render. Written in Traditional Chinese; the workflow itself is language-agnostic. See `skills/motion-explainer/SKILL.md`.
## 授權
程式碼與文件採 MIT。`motion-design` 和 `review-loop` 改編自 whaleyxbt/claude-motion（MIT），其他第三方元件見 NOTICE.md。