卡通 3D 故事短片 (three.js + Remotion)

卡通 3D 故事短片 (three.js + Remotion) 是做什麼的？

已驗證範例：為歌而傾的橋。這是一部原創的 67 秒短片，講述了 1831 年布勞頓橋和 74 名士兵齊步走的故事。

• 程式碼：Remotion 專案的 src/videos/bridge/ (構圖 BridgeShort，1080x1920，30 fps)。
• 劇本、語音和音效：~/bridge-short/。
• 風格研究：references/。

此風格參考來源為私下研究的頻道 (references/：STYLE_BIBLE.md、reports/*.md、frames/)。

• 那些影片是私人學習資料。切勿上傳、發布或發送它們。
• 切勿複製其劇本、角色或鏡頭。故事、角色和語音始終是我們的原創。
• 切勿在旁白或描述中提及該頻道的名稱。

適用的使用者規則：

• 影片中無字幕或標籤。
• 僅限英文。
• 語音：語調平穩一致。
• 笑話需基於研究過的真實事實。
• 標準混音：音樂 +3 dB，音效 -6 dB，語音保持不變。
• 最終輸出為 2K 豎版：1440x2560，--scale 1.3333。
• Opus max 驗證每個步驟。
• 每一步後都儲存。
• 劇本獲批後「直接執行」。

管道

1. 主題與事實。 挑選一個令人驚訝的真實故事，具有物理因果關係（並且應該是視覺化的），再加上一個簡單的日常類比來解釋它。
   • 在 SCRIPT.md 頂部寫下事實及其來源。
2. 劇本 (~3.7 字/秒，55-70 秒)。橋樑短片的節奏公式：
   • 鉤子： 用一句話表達荒謬的事實（「七十四名士兵僅僅是走過一座鐵橋就把它震垮了。」）。
   • 背景： 年份、地點、驕傲。
   • 行動： 三到四個節拍的升級，每個節拍都稍微更大。
   • 斷裂點： 它斷裂的瞬間。
   • 面無表情的雙行： 「幸運的是... / 不幸的是...」。
   • 解釋： 透過一個日常類比（盪鞦韆的小孩）來說明一個物理概念。
   • 後果： 它所創造的規則。
   • 回調轉折： 結局。
   • 切勿在螢幕上描述觀眾已經看到的內容。
3. 語音。 錄製或生成 voice.wav，然後製作其單字時間戳 words.json（任何能提供單字時間的語音轉文字工具）。
   • 將它們放在專案資料夾中，例如 ~/bridge-short/voice/。
   • 手動修正單字時間戳。所有時間都對齊 words.json。
4. 鏡頭計劃 在 story.ts 中：複製 templates/bridge/（最終的橋樑原始碼，與 Remotion 專案的 src/videos/bridge/ 相同）到 src/videos/<name>/，在 src/Root.tsx 中的 BridgeShort 旁邊註冊一個新的構圖，並重新命名。
   • SHOTS：id、a/b 幀、光線白天/金色、人群模式、tau 故事時間。
   • XFADE：地點/時間變更時的交叉淡入淡出。
   • FLASH_AT：鉤子之後的白色閃光。
   • CAMS：每個鏡頭的關鍵幀 {f, dur?, cut?, s: f => {pos, look, fov, roll}}。
   • KICKS：衝擊翻轉震動。
   • DOF/dofAt：每個節拍的鏡頭模糊。
   • FOREGROUND：近距離構圖道具。
   • 每個視覺反應都在其對應單字之前 0-3 幀處出現。
5. 世界。
   • lights.ts：LIGHTS 加上每個光線的 LOOK 天空/河流/雲彩調色板。
   • shade.ts：雙色調陰影和 untone()。
   • build.ts：城鎮、房屋和 Kenney CC0 套件道具，重新著色，並帶有視線剔除功能，以移除任何阻擋攝影機視線的物體。
   • paint.ts：HD Canvas2D 繪畫紋理，接縫處以深色調繪製。
   • world.ts：天空著色器、霧 = 地平線顏色、河流、逐幀姿態、太陽凍結在每個鏡頭中並相對於攝影機。
6. 角色。
   • toon.ts：Canvas2D Pen 繪圖 API，600x1000 設計畫布，腳底在 y = 975，豆形頭，棍狀四肢，李子色可變寬度輪廓，臉部庫。
   • cast.ts：面向攝影機的公告板、人群、效果卡、眨眼、行走循環。所有公告板都放在 NOINK 圖層上。
   • cardshade.ts：卡片由場景光線照明，無自發光。
7. 後期 (Bridge.tsx + ink.ts + lensblur.ts + grade.ts)。
   • 合成器順序：墨水 → 鏡頭預處理 → 鏡頭主體 → 綻放 → NEUTRAL 色調映射 → 調色 (MSAA 4)。
   • 每個像素參數都隨輸出高度 / 1920 縮放。
8. 音效 (~/bridge-short/audio/：timeline.py、sfx_gen.py、sfx.py、music.py、instruments.py、dsp.py、mix.py)。
   • 事件表 → 合成的音效加上在語音下方閃避的原創配樂。
   • 輸出：mix.wav (48 kHz，精確長度)、分軌和 cues.md。
   • 在製作音效之前鎖定畫面的時間常數。之後任何時間變更都意味著重新執行音效。
9. 外觀檢查。 執行 node scripts/bridge-stills.mjs out/<name>/x_ 100,400 0.5。
   • 設定 BRIDGE_ENTRY=src/sandboxes/<n>/index.tsx 以渲染沙盒副本。
   • 使用 python scripts/sbs_sheet.py out.jpg --ours ... --ref ... 製作與參考幀的並排比較圖。
   • 將其發送給 Opus max 驗證器：1-3 張圖片，一份 ≤200 字的判斷。
10. 最終渲染。
    • npx remotion render src/index.ts <Comp> out/<name>/video.mp4 --codec h264 --crf 16 --scale 1.3333
    • 使用 -map 0:v:0 -map 1:a:0 進行混流 (Remotion 會寫入一條無聲的音軌)。
    • QA：python scripts/short_qa.py final.mp4 out/<name>/qa shots.json 檢查每一幀是否有黑場、白場、凍結和跳幀，以及響度和圖表。
    • 修正它發現的任何問題，然後執行深入的 Opus 審計。
11. 交付。 發送最終的 mp4 檔案給使用者，更新記憶，撰寫筆記。

最終外觀數值 (橋樑經過 4 輪驗證器後的結果；全部在 templates/bridge/ 中)

每個新短片都從 templates/bridge/ 開始 (複製到 src/videos/<name>/)：外觀存在於這些數值中，故事存在於 story.ts / build.ts 佈局 / cast.ts 角色中。Opus max 最終分數：色彩白天 7、金色 5-6、燈光 5-6、墨水 6、紋理 5-6、角色 7、深度 6-7、構圖 6-7 (起始為 5/3/4/5/4/7/4/6)。

• 光線預設 (lights.ts，太陽相對於攝影機並在每個鏡頭中凍結)：
  • 白天：方位角 75 / 仰角 48，照明 [1.58,1.5,1.33]，陰影 [.30,.29,.36]，提亮 [.05,.06,.11] (僅在陰影中使用冷色調)，天空頂部 #3e7fd2 → 地平線 #b8d0ec，霧 = 地平線顏色，25→300 米，uSat 1.08，超過 60 米後約 15% 的藍色霧氣。
  • 金色：方位角 6 / 仰角 7 (背光低角度太陽)，主光趨向 #FFB36B ×1.5，紫藍色陰影 (建築物正面 ≈ #444380)，天空 #ffc47c → #8a6f8a，僅在超過 50 米處有桃色霧氣，太陽光盤 #ffcf9e + 綻放，接觸點斑塊 + 真實卡片陰影。
• 反照率 (paint.ts/build.ts)：柔和的磚紅色 / 奶油色 / 赭色 / 陶土色房屋，帶有基座、檐口、窗台、門罩、門階、煙囪 + 煙囪帽，高度 7 / 8.4 / 9.8 米；暖灰色/米色石材 (飽和度與「故事書」風格相比降低 −35%)；赭色木甲板 C* 約 51-58，帶有近黑色接縫；鐵材質深色且去飽和。切勿使用檸檬色、薰衣草色照明的人臉。
• 墨水 (ink.ts)：#030303，近距離 (6 米) 5.1 像素 → 遠距離 (90 米) 3.3 像素，在 1080x1920 解析度下，折痕從 35° 開始 ×0.8，深度跳變從 1% 開始，僅在遠處有 0.3 的霧氣色調；角色卡片位於圖層 NOINK 上 (它們自帶李子色墨水)。
• 鏡頭 (lensblur.ts + story.ts 中的 dofAt)：在 1080 解析度下 cInf 像素：鉤子/河流特寫 15-16，近景 12-14，中景 10-12，公園 7，金色搖擺 5，廣角/航拍 0。對焦在前排角色的眼睛上。
• 後期 (Bridge.tsx)：墨水 → 鏡頭預處理 → 鏡頭主體 → 綻放 (閾值 1.0，強度 .5，6 級，半徑 .6) → NEUTRAL 色調映射 → 調色；MSAA 4。有膠片顆粒但已關閉 (參考素材測量無顆粒；它會使檔案大小增加四倍)。
• 角色 (toon.ts/cast.ts/cardshade.ts)：豆形頭高/寬比 .94，李子色墨水 #241726，眼睛間距 .26 倍頭寬，無腮紅，14 種表情；成人 3.5 倍頭高；行走上下浮動 5%，傾斜 1-7°，著地步幅 0.8 米；眨眼 0.5-2.3 秒；白天在腳下約 .5 處有緊密接觸陰影 + 朝向太陽的尾巴；金色輪廓僅在內側 (絕非偏移的外側複製)。
• 攝影機 (story.ts)：在較大跳躍時切換，平滑步進滑行 18-40 幀，每個靜止畫面都有微動 (無 ≥4 幀的完全靜止)，衝擊翻轉震動在 7 幀內衰減，4-4.6° 的滾轉，前景道具 (FOREGROUND) 出現在約 1/3 的鏡頭中。

外觀目標 (根據參考素材測量；參見 references/reports/)

• 墨水：
  • 世界線條：在 1080 寬度下約 3 像素，近黑色 #0b0a0c，隨距離幾乎恆定。僅有輪廓、深度跳變和法線折痕。牆壁/地板接縫或地平線上無線條。角色卡片絕不會被世界墨水勾勒。
  • 角色墨水：深李子色 #201628-#2f1d28，在底部/陰影側較粗。
• 色彩：
  • 白天中位亮度約 .57。非墨水區域的第 5 百分位亮度約 .23 (無死黑)。照明區域的第 90 百分位彩度 C* 約 55。白天天空頂部約 #5e93d9，地平線亮度為其 1.28 倍。
  • 金色：桃色地平線 #ffd08a，紫藍色陰影 (從不含棕色)，背光太陽。
• 深度：
  • 景深約佔螢幕時間的 1/3 (特寫、中景、插入鏡頭)，在 1080 解析度下 cInf 10-16 像素，對焦在眼睛上。建立鏡頭和廣角鏡頭保持清晰。
  • 霧 = 地平線顏色，白天 25→420 米，金色 20→360 米。
  • 綻放僅作用於 HDR 自發光物體：閾值 1.0。
• 攝影機：
  • 在較大跳躍時硬切。其他所有運動都是 18-40 幀的平滑步進滑行，在 720p 下峰值速度 ≤ 25 像素/幀。
  • 每個靜止畫面都推近 0.15-0.35%/幀，在強調詞上達到 0.6%/幀。
  • 滾轉 4-5°。
  • 無手持晃動。衝擊震動每幀翻轉符號並在 7 幀內衰減。
• 角色：
  • 約 3.5 倍頭高，腿部 1.4 倍頭高。
  • 棍狀四肢約為頭寬的 0.055，墨水點狀手掌。
  • 豆形頭 (高/寬比約 0.93，下巴較窄，頭頂較尖)。
  • 無腮紅或眼睛高光。臉部亮度約 .93。
  • 行走上下浮動 3-7%，傾斜 1-7°，腳步著地。
  • 每 0.5-2.3 秒眨眼一次，持續 4 幀。

外觀匹配循環 (橋樑外觀的達成方式；任何「讓它看起來像 X」的流程都可重複使用)

1. 首先測量參考素材。 每個主題 (運動、深度、紋理、角色、燈光、輪廓、調色) 由一個分析代理負責，每個代理將數字而非形容詞寫入 references/reports/<topic>.md。共享簡報：compare/CONTEXT.md。報告是之後所有代理的事實依據。
2. 沙盒，每個檔案一個所有者。 將專案資料夾複製到 src/videos/<name>_{cam,world,mat,char,post}，並帶有入口 src/sandboxes/<n>/index.tsx (與主專案相同的 index.tsx，僅更改導入路徑)。橋樑專案的所有權分配：
   • cam：story.ts (攝影機關鍵幀、切換、震動、景深表、前景道具)
   • world：world.ts、lights.ts、shade.ts、grade.ts (太陽、天空、霧、河流、色彩、調色)
   • mat：paint.ts、build.ts (繪畫紋理、建築物、道具)
   • char：toon.ts、cast.ts、cardshade.ts (角色繪製、姿勢、卡片照明、特效卡)
   • post：ink.ts、Bridge.tsx、lensblur.ts (輪廓通道、合成器、鏡頭模糊、綻放) 代理僅在其自己的沙盒中編輯自己的檔案，並使用 BRIDGE_ENTRY=src/sandboxes/<n>/index.tsx node scripts/bridge-stills.mjs out/<name>/<n>/x_ <frames> 0.5 渲染靜止幀。
3. 合併 使用 python scripts/bridge_merge.py [cam,world,mat,char,post] (將主專案備份到 backup/bridge_<time>/，僅複製所擁有檔案)。然後執行 npx tsc --noEmit (過濾到專案資料夾)，然後在下輪開始前重新同步每個沙盒與主專案 (cp -f src/videos/<name>/* src/videos/<name>_<n>/)。
4. 驗證 使用一個全新的 Opus max 代理：並排比較圖 (python scripts/sbs_sheet.py out.jpg --ours a b --ref r1 r2)，每個項目以 10 分制評分 (色彩白天/金色、燈光、墨水、紋理、角色、深度、構圖)，並附帶帶有幀編號的編號修正列表。將每個修正映射到檔案所有者，並使用 SendMessage 恢復該所有者的代理 (以保持其上下文)。橋樑分數：第 1 輪 5/3/4/5/4/7/4/6 → 第 2 輪 5/4/5/6/4/7/6/6 → 第 3 輪參閱筆記。
5. 所有權之間的契約存在於導出的常數中 (例如 ink.ts 中的 NOINK 圖層、story.ts 中的 dofAt/FOREGROUND、lights.ts 中的 LIGHTS/LOOK)。更改契約意味著要通知每個讀取其內容的所有者。

注意事項

• Kenney 自然素材套件的材質是青色：在 build.ts 中按材質名稱重新著色。
• 攝影機最終可能會進入房屋內部：build.ts/world.ts 中的視線剔除器會移除任何阻擋攝影機視線的物體。
• 墨水如果與景深在同一個合併效果通道中會被覆蓋。墨水必須在模糊之前作為其自己的通道。
• 像素級別的後期參數必須隨解析度縮放：靜止幀是 0.5，最終是 1.333。R3F 會將 dpr 限制為 ≥ 1，因此 --scale 0.5 的靜止幀仍然會渲染一個 1080x1920 的緩衝區。
• 磁碟： 每個 Remotion 套裝會將 public/ (~1.3 GB) 複製到 臨時資料夾\remotion-webpack-bundle-* 並且從不刪除。在橋樑測試期間，60+ GB 填滿了系統磁碟，導致渲染因 ENOSPC 而失敗。始終使用 export TEMP='<大容量磁碟>/remotion-tmp' TMP='<大容量磁碟>/remotion-tmp' 渲染 (bridge-stills.mjs 會自行設定)，並在使用者刪除共用臨時資料夾中的舊套裝資料夾之前詢問使用者 (自動模式會阻止清理)。<大容量磁碟>/remotion-tmp 也會被填滿 (~在 4 輪橋樑處理後有 500 個資料夾 / 110 GB)：當專案完成且沒有正在渲染的任務時，刪除其中的 remotion-webpack-bundle-* 和 puppeteer_dev_chrome_profile-* 資料夾。
• 在 JS 字串中寫入 "<大容量磁碟>/remotion-tmp"，切勿寫入 "<大容量磁碟>\remotion-tmp" (\r 會變成回車符)。
• Remotion 會寫入一條無聲的音軌：使用 -map 0:v:0 -map 1:a:0 進行混流。
• 在此框架中子代理無法寫入報告檔案：要求它們提供一份 ≤150 字的最終訊息，並自行將其儲存到 out/<name>/<n>/REPORT.md。
• out/ 內部的暫存 .ts 檔案會破壞 tsc：將它們命名為 .txt。
• 2K 渲染約 4 fps (67 秒約需 10 分鐘)。0.5 解析度的靜止幀在約 40 秒的套裝後每個需要 3-8 秒。
• 2.5% 的膠片顆粒會使 2K 檔案達到 910 MB 而非約 250 MB，並且在 YouTube 上會變得模糊；參考素材中沒有顆粒。保持關閉。

驗證器發現的可讀性陷阱 (檢查每個新道具/鏡頭是否有這些問題)

• 畫成一根繩子並消失在小孩後面的鞦韆看起來像是上吊。 始終使用兩根繩子連接到一個寬木板，小孩在中間 (toon.ts 中的 swingKid)，以及一個其腿部不會干擾弧線的框架 (兩端各一個 A 形框架)。
• 距離鏡頭小於約 2 米的道具或漂浮物會變成巨大的截斷斑塊位於畫面邊緣。當攝影機移動時，重新檢查其新位置附近的每個道具 (河流攝影機移入了漂浮的帽子中)。
• 被畫面邊緣切斷的前景灌木看起來像一個「綠色球體」；前景道具必須可辨識或移除。
• 旗幟：紅色 + 黃色星星/菱形看起來像越南國旗。使用符合時代的正確旗幟 (1831 年的英格蘭使用聖喬治十字旗)。
  
  [為翻譯而截斷]