motion-diorama

Motion Diorama — 教育影片製作技能 (v3.0 · 公開版)

核心原則：在渲染前檢查，而非渲染後。 所有能夠低成本驗證的項目（時間軸、靜止幀、文字寬度）必須先通過。完整解析度渲染僅執行一次，在所有檢查點都通過綠燈後的最後階段。

此檔案為核心內容。各模式的視覺細節位於 references/ 目錄中 — mode-a.md 適用於模式 A，mode-b.md 適用於模式 B，mode-c.md 適用於模式 C（必須根據本影片的對應模式閱讀，然後再建立場景）。測試腳本位於 evals/evals.md。scripts/ 中的腳本必須嚴格按原樣執行 — 請勿重寫其功能。

鎖定決策（來自技能建立者 — 請勿擅自更改；如果你使用此技能並進行更改，請有意識地更改）

• 三種主動模式：模式 A（風景/歷史 + 動態地圖變體），模式 B（拆解物體 — 物體/機器的運作方式），以及模式 C（解剖學 — 人體系列）。使用者透過起始提示為每個影片選擇模式；工作階段在進入第 2 階段之前會讀取該模式的參考檔案。
• 目標：建立觀眾群。 預設結尾 = 結論（模式 A）/ 回呼（模式 C）+ 淡出至黑色。影片中沒有系列卡片/標籤，也沒有階段藥丸/螢幕上的位置指示器（2026年11月13日 v2.8 的使用者決策）— 系列身份僅存在於字幕中。價值呼籲僅偶爾使用，當主題合適且使用者為該影片要求時使用 — 非強制元素。禁止銷售呼籲。
• 數字/數據 = 混合式：螢幕讀出（DOM 覆蓋層）是所有數字的主要系統。例外：每個影片在場景內最多允許一個金色 3D 英雄數字，僅用於該影片的峰值數字 — 並且該數字必須同時作為讀出/字幕出現，因為 3D 版本是視覺強調，而非資訊載體。
• 最終時長 30–60 秒，跟隨音訊。
• 音訊：此技能對音訊不可知論 — 使用使用者在 public/narasi.mp3 提供的任何敘述 MP3。
• 音樂：來自使用者在 public/musik.* 的檔案 — 請勿選擇音樂。
• 事實：使用者提供的事實是主要參考，若有衝突則以此為準。工作階段可以透過網路研究進行補充，條件是：在最終報告中引用來源，優先使用權威來源（期刊、機構、官方），且未經驗證的聲明必須標記為不確定 — 禁止將猜測呈現為事實。
• 單一操作者：一個人。所有結果必須作為檔案出現在工作階段中（靜止幀、預覽、最終版），以便可以下載。
• 目標節奏：1–2 個影片/天。效率是設計要求 — 重複使用模板、基元和組件；請勿重建已存在的內容。
• 閘門 — 即時模式是公開版的預設設定： 工作階段不會停止等待使用者批准。閘門 1（時間軸摘要）和閘門 2（靜止幀聯繫表）在內部執行：工作階段根據此技能的書面標準（驗證器通過 + QC 檢查清單）評估其自身階段的結果，自行修正發現的問題（每個場景最多 2 次修正嘗試），然後繼續。決策遵循提示中的決策區塊（預設：過長的敘述使用 atempo 加速至最多 1.25 倍；未驗證的事實標記在報告中）。該區塊中未回答的問題在建置開始前的單一訊息中一次性提出 — 禁止中途提問。工作階段僅可因硬性阻礙而中途停止：(a) 素材缺失或損壞，(b) 無法建立轉錄稿，(c) 在最大 atempo 後敘述仍超出 30–60 秒。如果提示聲明「即時模式：否」，則適用經典閘門 — 兩次使用者批准（第 1 階段後和第 3 階段後），並根據證據逐步放寬閘門 2：連續 3 次通過無誤 → 每個場景 1 個靜止幀；再 3 次 → 對於已證明的場景類型為可選；閘門 1 永遠不放寬；一次重大的視覺修改會恢復完整格式；每次放寬都會在最終報告中記錄。

嚴格禁止事項

• 禁止使用 AI 圖片/照片/2D 素材/精靈/外部紋理/下載的模型作為場景。所有視覺效果 = Three.js 程式化生成的 3D 幾何圖形。
• 禁止使用信箱模式；原生 9:16 相機。
• 移動僅來自 3D 空間中的相機（真正的視差）。禁止透過縮放/平移 2D 影像來模擬運動。
• 人物僅為沒有臉部特徵的小型黑色剪影。模式 A 中的主要主體不得特寫（風景英雄動物/物體的最小相機距離為 8 公尺）— 在模式 C 中，此距離規則不適用：英雄器官確實填滿畫面；在模式 B 中，此規則僅約束上下文階段的構圖 — 實驗室階段的英雄物體確實填滿畫面（請參閱 references/mode-b.md 和 references/mode-c.md）。
• 所有場景使用一個渲染器、一組材質、一組燈光裝置。
• 禁止根據字數/分鏡圖猜測時長。時間安排僅來自原始音訊（請參閱時間安排）。
• 禁止使用 useFrame()、Math.random()、Date.now() 或幀累積進行動畫製作 — 所有運動均從 useCurrentFrame() 和具有固定種子的隨機常數衍生。

時間安排 — timeline.json 是唯一的事實來源

1. 確保 public/narasi.mp3 存在。如果沒有：停止，通知使用者。在音訊可用之前，請勿確定任何時間安排。
2. 使用此層級結構獲取每個單字的時間戳記： a. TTS 內建時間戳記（例如，帶時間戳記的 ElevenLabs）最準確，如果使用者提供。 b. 備用 Whisper：僅使用大型模型，強制使用 language="id"（請勿自動檢測），並且 Whisper 僅提供時間 — 句子文字必須來自使用者的官方腳本，而非轉錄稿（印尼語 ASR 在數字和名稱上容易出錯）。
3. 完全按照此結構建立 docs/timeline.json：

{
  "fps": 30,
  "audio_duration_s": 40.20,
  "total_duration_s": 41.00,
  "sentences": [
    {"id": 1, "text": "…", "start_s": 0.00, "end_s": 3.68, "scene": 1}
  ],
  "scenes": [
    {"id": 1, "sentence_ids": [1, 2], "start_s": 0.00, "end_s": 6.44}
  ]
}

4. 對應規則：場景邊界 = 下一個場景第一句的開始秒數；根據句子內容進行對應 — 禁止為填滿時長而分組句子；實際剪輯與時間軸的差異 ≤ 0.3 秒。
5. 執行 python3 scripts/validate_timeline.py docs/timeline.json。如果失敗：修正時間軸，重複。禁止在失敗時繼續。
6. 撰寫時間軸摘要（句子數量、場景對應、總時長）並根據這些標準自行評估 — 這是閘門 1。即時模式：不要停止；將摘要保存到最終報告。經典閘門模式：向使用者顯示並等待批准。
7. total_duration_s 必須在 30–60 秒內。超出此範圍：即時模式 — 套用提示策略（對過長內容使用最多 1.25 倍的 atempo；對過短內容拉長結束暫停）並在報告中記錄；如果仍超出範圍，則為硬性阻礙：停止並報告。經典模式：向使用者報告 — 請勿擅自剪裁或修補。禁止無故靜音；結束時允許 0.3–1 秒的回饋暫停，並計入總時長。

風格鎖定（摘要 — 各模式詳情請見 references/）

模式 A（詳情請見 references/mode-a.md）

• 風格化半寫實 3D 立體模型：溫暖電影調色板，一個固定的黃昏燈光裝置，乾淨光滑的表面，簡化背景。調色板可根據主題/季節調整；燈光裝置和材質則不可。
• 主題標題：在移動的開場鏡頭上使用大寫襯線字體。鉤子 = 敘述的第一句話（問題 / 神話反駁 / 悖論），在約 ±1.5 秒內以文字 + 聲音 + 視覺形式出現。
• 字幕：每頁 2–4 個單字（非一個單字）的逐字卡拉 OK，活躍單字粗體，關鍵字以強調色顯示，位於底部安全區域。
• 數據讀出：當敘述準確提到數字時，帶有動畫計數器的讀出 + 小標籤 + 指示線；後續讀出採用相同樣式。唯一允許顯示的 3D 文字：一個用於峰值數字的金色英雄數字（請參閱鎖定決策）。
• 相機：區段內連續移動；變焦步驟作為論證結構；僅在事實區段之間進行硬切，以 ±0.1 秒的黑色淡出形式呈現。
• 敘述結構：對於系統/流程主題，使用「跟隨一個流程」；一個影片可以涵蓋一個主題的兩個事實，並帶有示範區段。
• 結尾：美景鏡頭 + 重複的襯線字體標題/時代 + 結論句。淡出至黑色；影片中無系列標籤/卡片（v2.8）。（僅在為該影片要求時才使用價值呼籲）。

模式 B — 拆解物體（詳情請見 references/mode-b.md）

• 兩個世界階段：類似模式 A 風格的溫暖上下文立體模型（物體完整地出現在其棲息地）→ 實驗室階段，背景為深色技術網格，物體在此被拆解；透過連續變焦過渡（背景淡出/光圈縮小），無硬切。
• 一個英雄物體模型被程式化建立一次；爆炸圖和剖面圖從同一模型衍生。
• 無標題卡片（鉤子 = 上下文鏡頭中敘述的第一句話）和無永久 HUD — 麵包屑導航、變焦計數器和參考小地圖已移除（v2.8 的研究決定 + 方向）。透過連續相機、引導線標籤和瞬時階段標題進行導航。
• 標準階段：上下文 → 變焦 + 物體標籤 → 拆解（雙語 ID + EN 術語的零件標籤，按敘述順序出現）→ 剖面（動畫過程 + 過程讀出）→ 運作中（剖面運作，跟隨一個流程，過程標籤，語義顏色編碼的流程粒子）→ 確定性機制概覽 → 當相機拉遠時，一行原則標籤的收尾。
• 模式 B 結尾：結論/原則句 + 淡出至黑色；無系列卡片/標籤（v2.8）。

模式 C — 解剖學（詳情請見 references/mode-c.md）

• 非立體模型：一個發光的 3D 英雄器官漂浮在散景效果的深紫色虛空中；一個器官模型被建立一次，用於所有場景。預設系列名稱範例：「人體系列」（替換為你的系列名稱）。
• 流程的絕對顏色代碼： 藍色 = 缺氧，亮紅色 = 富氧 — 永遠不可顛倒，無論在本影片還是系列影片之間。細胞粒子在交換點改變顏色，恰好在其對應句子上。
• 必須遵循跟隨一個流程的結構：相機引導一個粒子通過整個電路；變焦步驟：器官 → 系統 → 微觀 → 器官 → 完整身體（剪影）。
• 鉤子 = 觀眾的即時參考 + 一個自第一秒起與器官視覺節拍同步運行的即時計數器。襯線字體標題延遲至約 ±5–8 秒（鉤子之後），然後是事實註釋。
• 無階段藥丸和無 HUD（v2.8）：流程位置透過相機移動讀取；解剖學標籤晶片附著在器官上，並在其部分活躍時發光。
• 模式 C 結尾：帶有動畫的最終計數器 + 反映鉤子的回呼句；淡出至黑色；無系列卡片/標籤（v2.8）。禁止血腥/寫實的醫學圖像。

文字規則（防止裁切 — 修改的首要原因）

• 所有必須閱讀的文字都是 DOM 覆蓋層（Remotion 組件），非 WebGL 畫布內的文字。唯一例外：鎖定決策中的混合式 3D 英雄數字 — 禁止其他 3D 文字。
• 在字體載入後，使用 @remotion/layout-utils 中的 measureText/fitText 測量每個文字；fontSize = min(模式限制，fit 結果)；最大寬度為畫面寬度的 90%；所有邊保留 5% 的安全邊距；尊重平台安全區域（重要文字避開上方 ±250 px 和下方 ±310 px）。
• 如果文字在可讀性底限尺寸仍無法容納：分割成兩頁/行 — 請勿縮小至不可讀，請勿讓文字被裁切。
• 對比度：亮色背景上的亮色文字必須具有深色輪廓/陰影。
• 引導線標籤遵循相同規則。

音訊

• 敘述是主時鐘：所有場景邊界、字幕、計數器和相機都讀取 docs/timeline.json — 沒有第二個時間來源。
• 來自使用者檔案的音樂作為背景放置在敘述下方（簡單 ducking；請勿蓋過單字）。如果沒有來自使用者的音樂檔案：請勿憑空創作音樂 — 通知使用者。
• 最終輸出標準化至 −14 LUFS，峰值 ≤ −1 dB。

生產流程（順序不可跳過）

• 第 0 階段 — 模板： 使用已存在的專案模板；渲染器、相機裝置、風格鎖定和基元不重新編寫。如果儲存庫尚未包含 Remotion 專案（首次生產）：從此技能套件儲存庫中的 starter/ 資料夾建置模板（使用已知可行的精確依賴版本），然後將其視為已存在的模板。
• 第 1 階段 — 時間軸： 按照時間安排部分進行 → 驗證器通過 → 閘門 1（即時模式中為內部；經典模式中需使用者批准）。
• 第 2 階段 — 建立場景 讀取 timeline.json 和本影片模式的參考檔案（references/mode-a.md、references/mode-b.md 或 references/mode-c.md）。
• 第 3 階段 — 靜止幀閘門： 為每個場景渲染 3 個靜止幀（場景開始/中間/結束）+ 聯繫表。即時模式：根據本模式的 QC 檢查清單評估聯繫表，在靜止幀階段修正發現的問題（每個場景最多 2 次嘗試），然後繼續 — 請勿等待使用者；將聯繫表 + 評估清單保存到最終報告。經典模式：顯示並等待使用者批准。在靜止幀階段修正 — 這比在影片中修正便宜得多。
• 第 4 階段 — 預覽 + 自主 QC： 以 0.5 比例渲染預覽，對自己的輸出執行下面的 QC，修正所有發現的問題（僅重新渲染已更改的場景），然後再報告。
• 第 5 階段 — 最終版： 以完整解析度渲染一次；執行 bash scripts/check_output.sh out/<slug>-final.mp4；在工作階段中顯示檔案 + QC 報告。

快速渲染（鎖定管道）

• 按場景渲染：out/scenes/scene-N.mp4；使用 FFmpeg concat 合併 -c copy（場景間的編解碼器/解析度/幀率參數必須相同，否則合併會失敗）。
• --concurrency = 工作階段的 CPU 核心數（檢查 nproc），請勿使用預設值。
• 預覽始終使用 --scale=0.5；僅在第 5 階段使用完整解析度 1080×1920。
• 保持每個幀的低成本：使用基本幾何圖形、實例化處理