motion-build

Papercut 建置

使用函式庫建置每個片段，而不是從頭開始撰寫 Remotion 專案。請先閱讀一次 $MOTION_LIB/core/README.md。

前置檢查

• 安裝：標準 或 完整。需要函式庫、Node 20+、npm、ffmpeg、Python 工具（numpy, Pillow, soundfile）以及用於音訊渲染的 Chrome 或 Chromium。使用 motion-explainer 中的指令進行探測；如果缺少任何項目，請執行 ./install.sh --doctor 並將其移交給 motion-setup。
• 函式庫：$MOTION_LIB，否則使用 ~/.config/motion-explainer/config.env 中的 MOTION_LIB= 行，否則詢問一次。如果完全沒有函式庫，則根據 $MOTION_LIB/style/$MOTION_STYLE/remotion/RECIPES.md 中的草稿進行建置。
• 僅為 Remotion 引擎載入 Remotion 最佳實踐技能（remotion-best-practices，來自 Remotion 插件，或執行 npx skills add remotion-dev/skills -g -y -a <你的 harness id>；install.sh --mode standard 會執行此操作）並遵循其關於標記、字幕和 Studio 的路由規則。對於 kyfram，則載入 kyfram 技能。
• 需要來自前期階段的 video/STORYBOARD.md 和 narration/script.json。
• 整個工具鏈的冒煙測試：$MOTION_LIB/core/tools/selftest.sh 會在一個臨時資料夾中建置 examples/hello-reel/ 並渲染一個靜態幀。

1. 建構與驗證引擎

片段專案應已從接收 / motion-strategy 階段建構完成。驗證 video/episode.json 中記錄的 engine：

• 如果尚未建構，請詢問使用者（remotion、fframes 或 kyfram）並執行：

  $MOTION_LIB/new_episode.sh <系列目錄> NN-代號 CompId [輸出名稱] --engine remotion|fframes|kyfram
  

• 從 video/ 執行的預覽指令：

  • fframes：cargo run --release -- preview（或安裝 CLI：cargo install --locked cargo-fframes）
  • kyfram：渲染一次，然後執行 kyfram view out/cache/kyfram/build/<場景>.lgv（編譯後的腳本：前奏 + 生成的標頭 + 你的場景）
  • remotion：npx remotion studio（或 npm run dev）

• fframes：片段專案是一個 Rust crate（media/、src/main.rs）。使用 cargo run --release -- render 或 $MOTION_LIB/core/tools/render.sh 進行渲染。

• kyfram：片段專案是 .lgv 腳本（scenes/、media/fonts/、src/plan.json）。使用 $MOTION_LIB/core/tools/render.sh 進行渲染（它會按場景快取並拼接）。首先呼叫 kyfram 技能。

• remotion：React 專案（src/、package.json）。使用 npx remotion render <CompId> out/<輸出>.mp4 或 render.sh 進行渲染。

2. 規劃：episode.json、旁白、時間點

根據分鏡腳本，填寫 video/episode.json：

• scenes：[["S01Hook", "l1_hook", 0], ["S02Name", "l2_name", "called"], ...]（場景 ID、旁白行 ID、第一個詞的索引或確切的詞）。
• banners：{"S01Hook": "TAKEAWAY IN CAPS"}。hook：請參閱 motion-hook。cuts：攝影機/切換表的切換欄位。bed、whipScene、cutSfx、gaps（一行之後的額外節拍，以秒為單位）。

然後執行 motion-voice 直到其時間點步驟（它會以 build_vo.py 和 timing_md.py 結束）。接著，從 video/ 執行：

python3 $MOTION_LIB/core/tools/stubs.py        # 根據引擎生成多檔案場景樁

build_vo.py 會標記任何少於 1.2 秒的場景；將其合併到相鄰場景中。timing_md.py 會將時間點部分寫入 STORYBOARD.md（絕對幀和單詞提示），因此 Agent 永遠不會開啟 plan.json。

3. 素材

遵循 $MOTION_LIB/style/$MOTION_STYLE/docs/asset-prompts.md：一個能夠輸出透明 PNG 的影像工具，用於背景和複雜的靜態道具；用程式碼處理角色、所有文字、標籤、儀表板、按鈕和 UI。生成的影像中不能包含文字。如果沒有影像工具，則完全用程式碼搭配紙張濾鏡建置所有道具；風格可以維持。背景：使用函式庫的 <Backdrop> 組合（style/$MOTION_STYLE/remotion/public/bg/backdrops/_sheet.jpg）；僅在片段需要函式庫中沒有的場景時才生成新的背景。證明截圖：node $MOTION_LIB/core/tools/capture.mjs <網址> public/proof/x.png，並使用素材包的 RealShot 顯示。

4. 場景（嚴格的多檔案架構）

絕對不要將所有場景放在一個檔案中。 每個場景必須存在於其獨立的檔案中，以允許平行 Agent 工作、獨立測試和清晰的 Git 差異。

檢查來自 video/episode.json 的 engine：

對於 Remotion（engine: "remotion"）

• 檔案結構：
  • src/scenes/<場景>.tsx（例如 S01Hook.tsx、S02Name.tsx）— 每個場景剛好一個檔案。
  • src/scenes/<場景>.parts.tsx（可選）— 僅供該場景的私有子元件使用。
  • src/scenes/index.ts — 由 stubs.py 自動管理的註冊陣列 SCENES。請勿在此處內聯場景主體。

1. 首先由你根據 HOOK 區塊在 src/scenes/S01Hook.tsx 中建置 S01Hook。這是 Agent 們比對的參考場景（提示常數、攝影機、限制後的 interpolate）。
2. 將其餘場景按場景分組（每個 Agent 負責 2-3 個場景），分配給場景 Agent 平行處理。簡報是 style/$MOTION_STYLE/remotion/AGENT_BRIEF.md。
3. 檔案所有權：一個 Agent 只寫入 src/scenes/<場景>.tsx、可選的 <場景>.parts.tsx 和 tools/cue_sheet.d/<場景>.json。切勿編輯其他場景或 index.ts。
4. Agent 們讀取 style/$MOTION_STYLE/remotion/CATALOG.md 和 $MOTION_LIB/core/audio/CATALOG.md。

對於 fframes（engine: "fframes"）

• 檔案結構：
  • src/scenes/<場景_蛇形>.rs（例如 s01_hook.rs、s02_name.rs）— 每個場景剛好一個檔案，定義其結構體和 impl Scene for <場景>。
  • src/scenes/mod.rs — 透過 stubs.py 自動註冊所有場景模組（pub mod s01_hook; pub use s01_hook::*;）。
  • src/main.rs / lib.rs — 僅透過 Video::define_scenes() 掛載場景。請勿在 main.rs 內編寫場景繪圖程式碼。

1. 首先建置 s01_hook.rs 作為參考場景。
2. 將其餘場景分配給 Agent 們平行處理（每個 Agent 僅擁有 src/scenes/<場景_蛇形>.rs）。
3. 讀取 style/$MOTION_STYLE/fframes/src/ 以獲取可用的攝影機、場景和道具結構體，而非 TSX 元件。

對於 kyfram（engine: "kyfram"）

• 檔案結構：
  • scenes/<場景>.lgv（例如 S01Hook.lgv）— 每個場景剛好一個腳本，僅包含形狀。
  • 渲染器會預先加上 $MOTION_LIB/core/kyfram/lgv/core.lgv、style/$MOTION_STYLE/kyfram/PRELUDE.lgv 和一個生成的標頭（SCENE_ID、BANNER、DUR、FPSR、CAPS 以及 scene() 呼叫），因此場景永遠不會呼叫 scene()、永遠不會硬編碼其持續時間或字幕提示，也永遠不會重新宣告輔助函數。

1. 呼叫 kyfram 技能。首先由你建置 S01Hook.lgv 作為參考場景，並使用 bash $MOTION_LIB/core/tools/render.sh 加上 bash $MOTION_LIB/core/tools/qa.sh hook 0-<N> 6 0.3 6 驗證它。
2. 將其餘場景分配給 Agent 們平行處理（每個 Agent 僅擁有 scenes/<場景>.lgv），並在簡報中指定 kyfram 技能。
3. Agent 們讀取 style/$MOTION_STYLE/kyfram/PRELUDE.lgv 以獲取標記和素材（drawRoom、drawHero、drawBanner、drawCaptions），並在渲染後讀取 out/cache/kyfram/build/<場景>.lgv 以取得確切的編譯腳本。
4. SFX 和背景音樂的接線遵循下面的 Remotion 流程；一旦 public/vo/voiceover.wav 檔案存在，render.sh --voice 會將其混入 mp4。

建置規則：1080x1920、30 fps、場景在素材包的轉場序列中串接。全域圖層：VO 和音樂 <Audio>、帶有 <Boil> 的膠帶橫幅、<WordTagCaptions>、<GrainOverlay>。每個道具都用 <Paper> 包裹，入場使用 <PopIn>，每個場景都在其分鏡攝影機內執行。沒有 CSS 動畫。保持底部 20% 區域淨空。相鄰場景永不共享背景。預設英雄是一個方形橙色小生物（標記 C.hero #D67354，陰影 C.heroLo #A9553B，別名 you）；配件和名稱標籤用以區分角色。

5. 音效

根據名稱從 $MOTION_LIB/core/audio/sfx/*.js 選取 SFX，並根據預設從 $MOTION_LIB/core/audio/beds/*.json 選取背景音樂。對於 kyfram，首先呼叫 kyfram 技能，並在 tools/cue_sheet.d/<場景>.json 中寫入每個場景的 SFX 行；它與 fframes 和 Remotion 共享相同的音效管線。從 video/ 執行：

python3 $MOTION_LIB/core/tools/cues.py && node $MOTION_LIB/core/audio/render.mjs

cues.py 會合併 Agent 們的行到 tools/cues.json 中，並在空氣音效超過每秒 2.5 個時列印一條筆記。render.mjs 會寫出 public/audio/music.wav 和 fx.wav。

6. 渲染

預覽：cargo run --release -- preview（fframes）、npx remotion studio（remotion）或 kyfram view out/cache/kyfram/build/<場景>.lgv（kyfram）。僅在要求時渲染，且務必透過包裝器執行——它會從 episode.json 中選擇引擎：

$MOTION_LIB/core/tools/render.sh        # -> out/<輸出>.mp4

旗標：--workers N（預設 3）、--conc N、--force、--keep。每個場景都會被快取，因此在修復後只有已更改的場景會重新渲染；對素材包、計劃、旁白或字幕的更改會導致所有東西重新渲染。首次執行會下載 Remotion 的無頭 Chrome，並且 out/cache 將會佔用數 GB 的 ProRes 空間。

要修復或重建一個場景：編輯 src/scenes/<場景>.tsx，使用 motion-qa 檢查它，然後再次執行 render.sh。

7. 收集（片段完成後）

python3 $MOTION_LIB/core/tools/harvest.py .       # 從 video/ 執行；唯讀報告
python3 $MOTION_LIB/core/tools/catalog.py         # 重新生成兩個目錄

按照 library/HARVEST.md 的描述，推廣素材包修復、可重複使用的元件、新的 SFX 和重複出現的節拍，並在 library/CHANGELOG.md 中新增一個條目。

• 當一個動作看起來僵硬或模糊時，請檢查 $MOTION_LIB/style/$MOTION_STYLE/docs/motion-principles.md 以找到匹配的原則及其素材包輔助功能。

交接

接下來是 motion-qa，它會讀取專案中的靜態幀和 STORYBOARD.md。在構建過程中對每個場景執行它，並在最終渲染前對整個片段執行一次。在發佈後，motion-strategy 會執行分析。