影片引擎
一個經實證的管線，能將腳本轉換為可直接發布的程式碼影片。它與風格無關：引擎（語音、時間、動畫基本元素、品質檢查、渲染）保持不變；外觀、節奏、角色和聲音則根據每個專案的簡報與客戶參考資料量身設計。
如果使用者已擁有以此引擎建立的專案，在製作任何新內容之前，請先閱讀其佈局文件
(VIDEOS.md / SAGAS.md)、引擎合約 (src/engine/video.ts 或 saga.ts)、一個風格 (src/styles/<style>/：
kit.ts、Video.tsx) 以及一個完成的場景。重複使用其引擎，而非重頭開始。有兩種佈局已被證實有效：
- 系列：共用角色、語音和格式的集數（例如，一個使用 TTS 和吉祥物的兒童數學傳奇故事）。
- 獨立影片：一次性解說影片，各有其主題、自備語音、素材，甚至可能有自己的視覺風格 （例如，暗色圖表風格的科技解說，以 16:9 和 9:16 格式渲染）。
不可妥協的原則
- 音訊即時鐘。 先產生/匯入語音，進行逐字對齊，然後依照詞語製作動畫。切勿為了達到特定時長而加速或剪輯語音。
- 每個視覺事件都錨定於一個口說詞語（
at(block, 'exact phrase', {word, n})）。如果該詞語不在對齊結果中，則大聲報錯——切勿憑空捏造時間戳。 - 時間的純函數。 場景狀態 = f(t)。幀與幀之間無狀態 → 預覽即等同於任何幀的渲染結果，品質檢查可以抽樣任何瞬間。
- 確定性材質。 在物件的局部座標中使用種子雜訊 → 無沸騰/閃爍現象。進行測量（靜態區域的幀差異 ≈ 0）。
- 在渲染前驗證；在渲染前後審查畫面。 自動檢查可找出邏輯/時間錯誤；連續靜止畫格可找出構圖錯誤（重疊、擁擠、隱藏元素）。兩者皆為必要。
- 僅在同意後才花錢。 TTS 呼叫會消耗點數：乾執行（區塊 + 字元）→ 詢問 → 產生。根據所有影響音訊的輸入的雜湊值進行快取。
- 誠實回報。 說明哪些項目已自動驗證、哪些已被查看，以及哪些未被查看（例如「我沒有聽過該音訊」）。
- 許多影片，一個引擎——從第一部影片就開始。 共享引擎 + 可重複使用的風格 + 每個影片（或每個系列）一個自包含的資料夾，包含該影片自己的腳本、語音、場景、縮圖、素材和特定影片的元件。引擎絕不會匯入影片或風格；每個指令都指定影片。請參閱
references/project-layout.md。
工作流程
- 將影片置於專案佈局中——新倉儲：在撰寫任何場景之前先設定好多影片佈局；現有倉儲：
npm run video -- new/npm run saga -- new（對客戶已填入音訊+腳本的資料夾運作）。請參閱references/project-layout.md。 - 簡報與格式——目標受眾、目標、平台、時長、長寬比、語言/地區、營利限制（例如 YouTube「為兒童製作」）。請參閱
references/formats-and-niches.md。 - 風格聖經——從客戶參考資料推斷或提出 2–3 個方向；在
style.json/文件中鎖定色板、字體、材質、角色、動作語言、聲音調色板。請參閱references/style-design.md。 - 腳本即資料——包含
tts_text（含語音標籤）、subtitle_text、選擇性問題/等待、視覺指示、預期答案/事實的區塊。使用 JSON schema 進行驗證。 - 語音——ElevenLabs 搭配時間戳（或匯入手動剪輯片段 + 本地強制對齊）。請參閱
references/voice-and-alignment.md。 - 時間軸——放置剪輯片段、測量間隔/等待、標準化的主語音軌、逐幀語音包絡、SRT。請參閱
references/timeline-and-audio.md。 - 場景腳本——每個影片都有一個使用套件（物件、移動、標籤、方程式/文字揭示、姿勢、音效、裝飾）的宣告式建構器。請參閱
references/animation-remotion.md。 - 驗證——schema、等待、未提及前不顯示、計數/答案、無重疊、安全區域、字幕區域無佔用。請參閱
references/qa-and-validation.md。 - 靜止畫面審查——12–15 個關鍵時刻的連續靜止畫格；修正並重複。
- 渲染——背景執行、記錄、記憶體安全的並行；使用 ffprobe + 響度驗證。請參閱
references/render-and-performance.md。 - 產出物——MP4、
<name>.<lang>_<REGION>.srt、縮圖（強制，由管線本身產生——絕非可選的獨立步驟；依格式：16:9 為 1280×720，9:16 為 1080×1920 封面，關鍵內容居中以適應 1:1/3:4 裁切；若缺少則終止執行，在輸出品質檢查中檢查其大小，並查看它）、主音訊、詞語時間、事件時間軸、品質檢查報告、上傳中繼資料（包含真實章節/標籤/主題標籤的標題/描述）。
技術棧（預設；需說明偏離原因）
- Remotion 4 (React + SVG) 用於確定性幀渲染、Studio/Player 預覽、CLI 批次處理。檢查授權（個人或少於等於 3 名員工免費）。
- macOS 上的 Chromium GL
angle（約快 30%）。硬體編碼器鮮少有益（瓶頸在繪圖）——請測量。 - ElevenLabs
POST /v1/text-to-speech/{voice}/with-timestamps（字元對齊）。庫存語音需透過 API 使用付費方案。 - 穩定版-ts (Whisper) 位於 Python 虛擬環境中，用於手動剪輯片段的本地強制對齊；ElevenLabs 強制對齊 API 作為精確替代方案。
- ffmpeg 用於混音、響度標準化 (EBU R128)、重新封裝/faststart、連續靜止畫格、閃爍測量。
- 字體：OFL（Google Fonts）本地儲存並附授權文件。音效/音樂：以程式方式合成或使用授權素材；保留副本 + 授權表格。
容易出錯之處（從慘痛經驗中學到）
ctx.at()預設必須回傳詞語的第一個；重複的詞語需要n（例如說了兩次的「una más」）。- 重疊檢查必須使用物件縮放後的大小；引擎變更後的縮放可能導致驗證失效——在引擎變更後重新驗證所有內容。
- 由「轉移/取出」輔助程式建立的物件在場景變更時也必須設定
remove時間，否則它們會洩漏到後續場景。 - 在問題等待期間移動物件會破壞「等待期間凍結」；請在等待結束後再移動。
- 切勿顯示旁白尚未提及的數字/答案（在場景、標籤、方程式、字幕中）。在數字詞語處分割字幕提示。
- 渲染並行度：每個 Chromium 實例約需 2.6 GB RAM；在 8 GB Mac 上跑 6 個會導致大量交換並使渲染停滯。預設為
floor(totalmem/2.6GB)。 - 內嵌字幕需要保留區域；驗證無物體進入該區域。
- 固定方框內的長標題會溢出——根據長度自動調整大小。
- 在信任匯入的音訊之前，請檢查每個剪輯片段的內容（轉錄 → 與腳本比對，將數字映射到文字）；剪輯片段可能遺失或順序錯誤。對產生的 TTS 也同樣處理（透過代理「聆聽」：Whisper 轉錄 vs 腳本，所有數字都存在）。
- Remotion
bundle()每次呼叫都會將public/（所有語音）複製到作業系統暫存目錄且從不刪除；多次靜止畫面執行可能填滿 460 GB 的磁碟。始終在腳本結束時rm -rf該 bundle。在長時間批次處理期間監控可用磁碟空間。 - SVG 濾鏡使用元素的外框邊界盒：具有濾鏡的完全水平或垂直路徑（零面積邊界盒）會渲染出空白。水平臂、數線刻度與引導線因此消失。筆直的軸對齊筆畫不需要濾鏡。
- 問題的資料可能需要保持可見（價格、資料政策），而答案則不可見。如果價格等於數字答案，請在問題之前移除價格。
- 一個扁平的單一影片倉儲在第二個影片出現時就必須重構。發生此情況時，請先擷取基準線：靜止畫面的 md5、縮圖、JSON/SRT 產出物以及語音 md5。移動後，所有內容必須位元組一致。移動檔案且切勿刪除；將剩餘檔案移至
_legacy/供使用者審查。 staticFile()僅能存取public/：每個影片的媒體檔案位於影片資料夾中，並在每次 bundle 前同步到public/videos/<slug>/。新影片需要一個佔位時間軸（無區塊），以便靜態匯入能編譯成功。- 客戶腳本常將旁白與視覺指示混在一起（例如 NARRACIÓN / REFERENCIA VISUAL — NO NARRAR）。僅對齊旁白，並將每個章節的視覺註記保留在
script.json中，因為它們是場景的精確度規格。 - 提供的音訊可能與提供的腳本內容不符（旁白即興發揮、後續錄製）。在對齊之前，務必先讀取免費轉錄，並根據實際說出的內容在客戶腳本旁建立一個單獨的檔案 (
narracion.md) 進行對齊。對錯誤文字進行強制對齊會悄然產生錯誤的時間。 - 技術解說需要精確度，而非裝飾。可以計算的內容就計算：真正的照片作為張量、真正的卷積、每個像素的真實雜訊公式、真實的取樣器更新。其餘部分標示為示意圖（「esquema didáctico」、「salida ilustrativa」），保留
references/decisiones.md，並在上傳說明中說明相同內容。在繪製之前，請對照主要來源檢查產品聲明。例如，Imagen 是像素空間級聯擴散，而非潛在空間。 - 公式：使用 MathJax 在管線步驟中將客戶的 TeX 渲染為 SVG 路徑（無字體依賴），然後將其作為
formula元素繪製。 - 從左到右建立的圖表永遠不會置中，除非群組隨著增長而滑動。使用自動重新置中功能，在新元素進入之前滑動，在離開元素淡出之後滑動。將標題保持在 CX 固定，且群組進入間隔 ≥ 0.6 秒。對於鏈結，先繪製空插槽。
- 無縫循環：
- 不使用淡入淡出。
- 使開頭+結尾等於一個自然停頓。
- 使用恰好與影片時長一樣長的音樂。
- 以開頭元素的精確副本結束：縮放後的副本會因反鋸齒而產生差異。
- 透過在無字幕情況下比較第一幀與最後一幀的差異來驗證。
- SVG 內的光柵照片應放在
<foreignObject><Img/></foreignObject>中，因為 Remotion 會等待<Img>。裸露的 SVG<image>可能渲染出空白幀。 - 具有關鍵幀參數化數值參數（時鐘分鐘數、傾斜度、亮度、爆炸偏移）的通用屬性分發器可擴展到數十個新物件，而無需接觸渲染器。在編寫場景之前，先建立一個屬性審查表（開發用靜止畫面）。
開始一個新專案
- 在現有引擎倉儲中新增影片或系列（較佳方式）：使用其腳手架指令（例如
npm run video -- new --video <slug>或npm run saga -- new --saga <slug>）。它會從_template/建立資料夾、 註冊它，並可選擇性地將一個基礎風格複製到src/styles/<new-style>作為重新設計風格的起點。 - 新倉儲：在撰寫任何場景之前，先根據
references/project-layout.md設定好多影片佈局：package.json、tsconfig.json、remotion.config.ts、src/engine/（場景模型、詞語提示、格式、字幕、 影片合約）、src/styles/<style>/中的一個風格、scripts/（時間軸、驗證、靜止畫面、渲染、縮圖、檢查、new指令）、tools/（對齊、程序化素材）、一個_template/資料夾、註冊表和Root.tsx。 然後執行npm install，並且僅在需要對齊提供的音訊時才建立包含 stable-ts 的 Python 虛擬環境。 - 根據利基市場的區塊結構（例如鈎子、教學、範例、問題/等待、總結等角色）調整腳本 schema。
- 實作風格聖經：色板、字體（本地、已授權）、濾鏡、背景材質（由腳本產生）、 角色或主持人、音效/音樂。
- 渲染一個 12–15 秒的真實音訊範例 → 使用者核准 → 然後規模化。
- 將專案規則保留在專案的
CLAUDE.md（成本/同意、命名慣例、語言、審查步驟）和VIDEOS.md/SAGAS.md的佈局中。
參考檔案
references/style-design.md— 推斷/提出視覺識別、風格聖經、一致性規則。references/voice-and-alignment.md— ElevenLabs、快取、錯誤、手動剪輯、強制對齊。references/timeline-and-audio.md— 剪輯放置、等待、響度、音樂閃避、音效、字幕。references/animation-remotion.md— 場景資料模型、編寫套件、角色綁定、動作語言、預覽。references/textures-and-rendering-looks.md— 針對多種外觀的種子 SVG 濾鏡配方。references/qa-and-validation.md— 自動規則、視覺審查、輸出檢查。references/render-and-performance.md— 渲染設定、記憶體、佇列、產出物、上傳中繼資料。references/formats-and-niches.md— 長寬比、安全區域、利基市場手冊。references/project-layout.md— 每個倉儲多支影片：每個影片的資料夾、可重複使用的風格、影片合約、素材同步、遷移扁平倉儲。