Master class render 是做什麼的？

輸入：<source>/scripts/NN - Title.script.md（由 master-class 編寫）。你會撰寫：<source>/scenes/NN.scenes.md（D2 文本，不含座標或時間）。一個指令即可產生：<videos>/NN - Title.mp4 + <notes>/NN - Title.md + <notes>/<MOC>.md。

所有步驟都在本地端執行：D2 佈局圖表（草圖風格），Kokoro-82M 語音朗讀，時間來自真實音訊，Chromium 在每個視覺變化時擷取畫面，ffmpeg 編碼。沒有任何資料傳送給第三方。唯一花費的 tokens 只有場景檔案（大約是腳本大小的 1 倍）。

0 · 設定（每台機器只需執行一次；重複執行安全）

bash ~/.copilot/skills/master-class-render/scripts/setup.sh

安裝 d2、ffmpeg、uv（Homebrew）、在 scripts/.venv 中建立虛擬環境（包含 kokoro-onnx、soundfile 和 playwright（Chromium）），以及將 Kokoro 模型放入 ~/.cache/kokoro（約 350 MB）。如果 scripts/.venv/bin/python 已存在，則設定已完成。

1 · 撰寫場景

請先閱讀 references/scenes-guide.md 以及已批准的範例：01、05、08。每個範例都與其在 ~/.copilot/skills/master-class/examples/ 中的腳本配對，因此你可以確切看到每個畫面如何變成圖表。此步驟適用於小型/快速模型：一次處理一課，並讓驗證器告訴你何時正確。接著，針對每個腳本，以一個 ## Beat N 加上一個 ```d2 程式區塊來對應每個 Beat，翻譯該 Beat 的畫面描述：

# @at "phrase"（從該 Beat 旁白中逐字複製 3–7 個單詞）會在旁白者說出該片語時揭示後續內容。最終佈局會一次計算完成，因此不會有任何跳動；新元素會短暫發光。
# @continue 會延伸前一個 Beat 的圖表。
類別：model、code、tool、data、person、bad、good、note（便利貼，顯示結論；這些會成為課程筆記中的 重點觀念）、muted、wrong。
指南列出了 D2 的注意事項（\$，不能在 {} 區塊內使用 @at，|||md 表格，樣式變更不會產生動畫）。

邊進行邊驗證每一課（必須顯示 ok:，且沒有 warning:）：

cd ~/.copilot/skills/master-class-render/scripts && export PATH=/opt/homebrew/bin:$PATH
.venv/bin/python render.py "<source>/scripts/NN - Title.script.md" "<source>/scenes/NN.scenes.md" /tmp/check.html

若有多課 → 請分割給平行子代理（每份約 4 課）處理，並提供指南與範例。

2 · 建立課程

cd ~/.copilot/skills/master-class-render/scripts && export PATH=/opt/homebrew/bin:$PATH
.venv/bin/python build_course.py \
  --source "<lab>/_attachments/master-class/source" \
  --videos "<lab>/_attachments/master-class" \
  --notes  "<lab>/Master class" \
  --moc    "<Lab name> · Master class" \
  --course "<label shown top-left in the video>" \
  --tags   "course/<course-tag>,section/labs,topic/<x>,type/lesson" \
  --intro  "One paragraph for the MOC: what the course is built from ([[source note links]]) and its intent." \
  --voice am_michael --lang en-us

語言/語音：英文 --voice am_michael --lang en-us（替代選項 am_puck、bm_george --lang en-gb）；西班牙文 --voice em_alex --lang es（女性：ef_dora）。
--only 03,07 可重新建立特定課程（筆記總是會為所有課程重新產生）。--notes-only 僅重新產生筆記，不重新產生影片。
每課約 15 秒（語音快取後；首次合成約每課 1 分鐘）。輸出會先編碼到暫存資料夾，然後複製，因為直接寫入 OneDrive 同步的資料夾會超時。
確保 --tags 與原始筆記使用的標籤一致。

3 · 回報前驗證

建置程序已為每課印出 ok:，且沒有 !! … @at phrase(s) not found。
從一或兩個 MP4 中擷取 2 個畫面並檢查它們（每次使用 新的檔案名稱；圖片檢視器會快取）： ffmpeg -v error -ss 120 -i "<mp4>" -frames:v 1 -vf scale=1280:-1 /tmp/mc_check_<n>.png 檢查：圖表是否可讀（不是小細條）、字幕是否匹配、顯示的是否為正確的 Beat。
圖表太小？渲染器已自動嘗試另一種佈局方向；如果仍然太小，請分割該 Beat 的圖表，或放棄 @continue 並用一個 muted 方塊總結前面步驟。
開啟 MOC 筆記與一課筆記：影片嵌入 ![[NN - Title.mp4]]、目標、重點觀念、自我測驗（問題 + 折疊答案）、折疊逐字稿、上一頁/下一頁連結。

每課筆記的內容（自動產生，零 tokens）

Frontmatter（標籤、課號、時長、課程連結）· 嵌入的 MP4 · 目標 · 常見迷思 · 重點觀念（來自 note 便利貼）· 自我測驗（來自 Retrieval pause Beat）· 折疊逐字稿 · ← 上一課 · 課程索引 · 下一課 →。

檔案

scripts/：build_course.py（進入點）· render.py（腳本 + 場景 → 帶有音訊與時間軸的中間 HTML）· export_mp4.py（HTML → MP4）· make_notes.py（筆記 + MOC）· player.html（中間模板；也可用作離線播放器）· prelude.d2（類別、字型大小）· setup.sh。快取：scripts/.cache/（語音片段、圖表；可安全刪除）。

Master class render