課程影片
您將學生的課程教材轉換為學習影片。使這項技能與眾不同的一項規則是：
每個數字、範例和觀點都來自學生的課程教材。不得虛構任何內容。 學生使用這些影片來準備 他們的 教授所出的考試。使用虛構數字的「更好」範例、不同符號的公式，或來自課程外的知識，即使經濟學/物理學等本身是正確的，也屬於錯誤。
0. 需求（只需檢查一次）
python3 -m pip install -r requirements.txt && python3 -m playwright install chromium
ffmpeg -version | head -1 # brew install ffmpeg / apt install ffmpeg
可選：Blender 4.2+ 用於 3D 場景和吉祥物主持人（如果不在 PATH 中，請設定 BLENDER=/path/to/blender），
pdftotext (poppler) 或 pip install pypdf 用於讀取 PDF 投影片，openai-whisper 用於轉錄錄音，
XAI_API_KEY 用於 Grok 語音（否則使用免費的 Microsoft 神經語音）。
1. 收集來源
建立一個資料夾 <course>/sources/，並將 僅限課程教材 放入其中：
課堂逐字稿 (.txt/.srt/.vtt)、投影片 (.pdf 或匯出的文字)、學生的筆記、作業、練習題。
- 有錄音但無逐字稿 →
whisper lecture.mp4 --model base --output_format txt --output_dir sources/ - .docx →
textutil -convert txt file.docx(macOS) 或pandoc file.docx -t plain -o file.txt - 詢問學生影片應涵蓋哪些課程/主題。除非被要求，否則不要用其他週次的教材填充。
在寫任何內容之前，請完整閱讀所有來源。注意教授的確切符號、術語、示範範例和數字。
2. 編寫腳本（內容 JSON）
編寫 <course>/<name>.json，遵循 engine/SCHEMA.md（視覺類型、提示詞、測驗格式、版面限制）。
examples/lemonade/ 是一個完整的簡單範例。
規則：
- 範例：使用課程本身的示範範例，並使用課程本身的數字。如果課程使用「價格 $4，3 個單位」，影片也應使用「價格 $4，3 個單位」，而非「價格 $10，5 個單位」。
- 測驗：從課程的練習題、課堂即時反饋題或示範範例中選取。如果您編寫新題目，只能使用來源中的數字構建，並在測驗標籤中說明（「練習」，而非「考試題目」）。
- 衍生數字（您計算出的總和、差值）是允許的，但必須在頂層的
"derived"映射中宣告每個數字及其運算，且只能使用來源數字："derived": {"16": "4 * 4", "-6": "120 - 126"}。 - 非數據的小計數（「三件要記住的事」、「步驟 2」）放在
"allow": ["3"]中。0 和 1 永遠允許。 - 符號和術語：使用教授使用的（如果課程寫「MR = MC」，不要改成「∂R/∂q」）。
- 如果影片需要的某個事實未出現在來源中，請停下來詢問學生以取得該教材，否則就略過它。 絕不要用一般知識填補這個空白。
- 旁白 (
say) 應為聽覺而寫：使用詞語而非符號（「4 乘以 4 等於 16 元」）。
3. 檢查每個數字是否來自來源（必須在建立前執行）
python3 tools/check_sources.py <course>/<name>.json <course>/sources --report <course>/<name>.sources.md
它會從旁白、螢幕文字、測驗選項和任何 3D 場景標籤中提取每個數字，並在來源中找到每個數字（數字或拼寫的單詞，例如「one hundred twenty」）。衍生數字會重新計算並檢查其運算元。必須以退出碼 0 結束才能繼續建立。 對於每個問題，它會報告：
- 該數字是錯字或虛構 → 修正腳本以使用來源的數字；
- 該數字是真實的計算結果 → 將其加入
"derived"； - 該數字以檢查工具遺漏的形式出現在來源中（例如在圖片中）→ 請學生確認，然後將其加入
"derived"或"allow"，並在您的回覆中附上註記。
然後自行閱讀報告的「證據」部分，抽查每個數字在影片中的用法是否與來源中 意義相同（檢查工具只比對數值，不比較意義：「$40」價格 vs. 「40 單位」數量）。
4. 建立與渲染
cd engine
python3 build.py ../<course>/<name>.json # 語音、時間、字幕、音樂（若要使用 Grok：TTS=xai XAI_API_KEY=...）
python3 lint.py build/<video-id>/spec.json # 檢查延遲出現的視覺元素
python3 qa.py <video-id> # 每個節拍的靜止圖 + 接觸式印樣：請仔細查看
OUT=../out python3 render.py <video-id> --workers 6 # 完整 1080p 渲染 -> ../out/<video-id>.mp4 + .srt
在渲染前請查看 QA 接觸式印樣：確保沒有重疊文字、空白畫面、螢幕上錯誤的數字。
5. 可選：3D 場景、吉祥物、音效
一個帶有 "v": {"type": "clip", "scene": "<name>"} 的節拍會播放來自 engine/blender/scene_defs/<name>.py 的 Blender 場景
（請參閱 engine/blender/scenelib.py 中的文件字串；market.py 和 safe.py 是完整範例，專為經濟學課程編寫，因此它們的標籤帶有該課程的數字。請更改標籤以符合您的來源）。
場景標籤也會被 check_sources.py 檢查。
cd engine
python3 blend.py prep <video-id> # 吉祥物時間線 + 每個場景的輸入
python3 blender/stills.py <scene> --dry # 快速捕捉錯誤，然後不加 --dry 生成靜止圖
python3 blend.py clips <video-id> # 渲染 3D 場景（較慢：每個場景需數分鐘）
python3 blend.py mascot <video-id> && python3 blend.py pack <video-id>
python3 sfx.py mix <video-id> # 在旁白下加入音效
OUT=../out python3 blend.py comp <video-id> # -> ../out/<video-id>-3d.mp4
OUT=../out python3 blend.py site <id1>,<id2> --title "我的課程" --out ../out/site # 一個包含章節的網頁
渲染速度慢且消耗大量磁碟空間（運行期間每個影片產生數 GB 的影格）。首先檢查可用空間，在筆電上每次只渲染一個場景，並保持機器清醒。
6. 交接
告知學生：影片的位置、長度、涵蓋哪些課程，以及來源檢查結果（檢查過的數字、任何衍生或允許的數字）。如果來源中有任何模糊之處，請說明您的假設。提醒他們，該影片是根據他們的教材建構的學習輔助工具，並非課堂的替代品，並且課程教材可能不屬於他們發佈：在公開張貼影片前請先確認。