課程生成器:手繪解說影片 是做什麼的?
輸出:一或多個 1920x1080 30fps H.264+AAC MP4 檔案,內嵌字幕與 .srt 檔案,風格如同有人在黑色 iPad 上以霓虹螢光筆教學(Caleb Eom 風格)。每堂課以緊湊的 spec.js(旁白與視覺整合在一起)撰寫;引擎負責佈局、將每個繪圖動作與語音同步,並進行渲染。
research → spec.js per lecture → build.sh (extract → TTS → scenes.js) → qa.sh (stills) → fix → render_lecture.sh → zip + deliver
風格規則(不可協商)
- 語速 ≈ 1.2 倍,絕不更快。 API 語音:先修剪靜音,再
ATEMPO=1.05(富有表現力的語音)到1.12(較慢的語音)。節拍之間間隔 0.2 秒。1.25 倍以上聽起來會很急促。 - 手工感。 使用 Reenie Beanie 字體,每個字母帶有隨機抖動;使用 rough.js 線條(粗糙度 ≥1.4)加上 SVG 湍流搖晃效果。只有「印刷」的證據卡片(表格、真實數字)使用乾淨的無襯線字體。
- 黑色背景,霓虹角色:
w主要,g好/有效,p問題/警告,v概念,o動作/類比,y強調/數字,b次要,gr引用/旁白。
教學結構(每堂課)
- 鉤子(20–40 秒): 一個 relatable 的情境,接著一個令人驚訝的事實,然後一個問題。接著是一個標題節拍,預覽整個框架。
- 框架(
LAYERS,3–7 個項目): 主幹。每個區段在右上角顯示一個小型副本,並用括號標示其層級。 - 區段: 每個區段 1–3 個節拍。每個節拍一個想法和一個視覺元素。在旁白中說出資料來源,並在螢幕上以灰色顯示。
- 直覺: 每個區段至少有一個
類比,用於任何抽象概念(「它是煙霧偵測器,不是消防隊」)。立即用白話解釋專業術語。 - 總結與預告: 顯示框架,勾選已完成的項目,然後顯示下一堂課的標題,使整個課程連貫銜接。
語音:像同儕在喝咖啡時解釋。使用短句,「所以說,」、「重點是這個。」、「還記得 X 嗎?」。按照口語方式書寫數字(「二零二六」、「一點七秒」)。在 say 中避免使用符號。
初學者友善模式(當要求讓新手易懂時):用自己的網路研究補充來源,每個概念加入一個類比,並降低想法密度(每 3–4 分鐘的課程約 500–650 字)。
準確性
對每個數字、日期和名稱進行網路搜尋。優先使用第一手來源。將同一實驗的數字放在一起。標示廠商的主張(「廠商數據:請驗證」)。絕不虛構書中未提供的範例;引用書中原有的範例。提交一份來源列表。
設定
在 ~/course 中工作,這是此技能的 engine/ 資料夾的副本,因此音訊和影片會保留在技能資料夾之外。如果 ~/course 已存在,則跳過複製步驟。
cp -r <此技能資料夾>/engine ~/course && cd ~/course # 例如 ~/.claude/skills/course-generator-handwritten/engine
npm i && npm run browsers # Playwright + Chromium(需要 Node 20+)
pip install --break-system-packages soundfile numpy
cp .env.example .env # 在 .env 中填入 TTS_*(切勿提交它)
必須安裝 ffmpeg。課程資料夾(~/course/L02_Architecture/spec.js)與腳本放在同一層;可以從任何目錄呼叫腳本。
TTS 是可插拔的(tts.py):任何相容 OpenAI 的 POST /audio/speech,且回傳 response_format: "pcm"(24 kHz s16le)。透過環境變數或 .env 設定 TTS_URL、TTS_API_KEY、TTS_MODEL 和 TTS_VOICE。挑選語音時,先用 2–3 種語音測試同一個節拍,選擇最具表現力(音高變化最大)的語音,而不是第一個。音訊會依節拍快取,並附帶文字側車檔案,因此只有編輯過的節拍會重新生成語音。絕不可在提交的檔案中硬編碼金鑰或模型名稱。
撰寫一堂課:<Dir>/spec.js
const LECT = { label: 'Lecture 2 · behind the scenes', title: 'The Seven-Layer Architecture' };
const LAYERS = ['Channels + triggers', 'Gateway', 'Durable orchestrator', 'Agent loop'];
say({ hook: "…", title: "…", recap: "…", outro: "Next, …" }); // 註冊 intro/recap 節拍
intro('S01_Intro', 'hook', 'title', [ items… ]);
section('S02_Gateway', 1 /*layer idx*/, 'v' /*colour*/, [
{ b: 'ga1', t: 'The front door', cite: 'Source, 2026', say: "Narration…", v: [ items… ] },
]);
recap('S06_Recap', 'recap', 'outro', ['line', 'line'], 'Next lecture title');
每個節拍都有自己的面板,攝影機在面板之間移動。佈局會自動縮放以適應。
項目 [type, ...args, opts?]:
| type | args |
|---|---|
big / text | str, colour, size |
note | str, colour(箭頭前綴的旁白) |
analogy | null, str, 'o'(帶框的「把它想成…」) |
list | `[lines], colour, {num |
col | title, colour, [lines](在 row 內部使用) |
row | [[item],[item]…], {vs, gap}(並排) |
flow | [labels], [colours](帶箭頭的方框) |
stack | [labels], {rh,size,w,cols,step} |
tokens | [words], colour, {step, cols}(自動換行) |
bars / hbars | `[[label, value, colour, valueLabel]…], {h |
eq | str, colour(加底線的標題數字) |
card | title, rows[][], {w, hi:[rowIdx], hit:[time]}(印刷表格;第 0 列是標題) |
chart | [[[x,y]…], colour, label]…], {h, xl, yl} |
timeline / grid / gpus / people / down | 請參閱 dsl.js |
時間選項(最後一個物件):at: 'word' 表示在說出該單字時啟動該項目(occ: 2 表示第二次出現);times: [[beat, frac, 'f'], …] 設定每個部分的時間,作為節拍的分數;step 則錯開各個部分。開始時間會被限制,確保繪圖在節拍結束前 ≥2.6 秒完成。允許的選項金鑰在 dsl.js(OPTK)中定義;未知的金鑰會被視為資料,因此請在那裡新增新的金鑰。
建置、品質檢查、渲染
./build.sh L02_Architecture # beats.json, TTS, scenes.js;輸出語音分鐘數
./qa.sh L02_Architecture # 將節拍結束時的靜態畫面拼貼成 L02_Architecture/qa/sheet*.jpg
./render_lecture.sh L02_Architecture "02 - The Seven-Layer Architecture" # 2 條平行通道 → out/*.mp4 + .srt
在渲染之前對每堂課執行 QA,並檢查每個畫面。修正:
- 標籤溢出方框(引擎會縮小字型,但長標籤仍需縮短);
- 卡片反白標示在錯誤的列上(將標題列計為第 0 列);
- 內容超出畫面邊框;
- 不存在的
at單字(記錄中會出現WORDMISS)。
對於多堂課,使用佇列:每個目錄有一個 READY 標記,一次渲染一堂課,當 scenes.js 比 MP4 新時重新渲染。在雲端,完成一堂課大約需要 3–4 分鐘的渲染時間。背景工作必須由 harness 追蹤(不要在可能休眠的 VM 上使用 nohup)。
交付
壓縮 out/*.mp4 + *.srt,使用帶編號和標籤的檔案名稱(「00 - Title.mp4」)。在回覆中提供執行時間表、一行方法說明,以及來源列表。
範例
examples/agents-L00-spec.js(概念課程)和 examples/inference-B4-spec.js(重證據課程)是完整的、已渲染的規格,可供複製參考。