Iwang-f/motion-reel

Motion reel

在此儲存庫自己的引擎中建置新影片。除非使用者明確要求，否則不要切換到 Remotion 或 HyperFrames；儲存庫的轉譯契約位於 CLAUDE.md，其效力優先於本檔案。

一部影片分為兩個階段執行，並以擁有者對鏡頭清單及分鏡表的一次核准作為分界：

• 前期製作（本檔案）：腳本、故事、素材、旁白、節奏網格、鏡頭清單、分鏡表。
• 建置（/motion-reel build <film>）：請參閱 build.md 並遵循其指示；跳過本檔案。

此分界讓建置階段保持在全新的上下文中。前期製作階段會在視窗中填入參考資料、拍攝素材與分鏡表圖片，而後續的每一次對話輪次都需為此付出上下文成本。

1. 確定腳本

在擁有者的草稿上執行 node tools/brief.mjs --in=<draft.md>（若專案已存在則加上 --film=<film>：它會寫入 brief/original.md，但不包含內嵌的 base64 內容）。此工具會輸出標題、符合預算的旁白文字，以及草稿中未明確定義的部分。如果沒有草稿，則根據要求填寫 docs/brief-template.md 的標頭欄位，並為每個缺口提出預設值：擁有者只需回覆一個「oke」或提出修正。

在碰觸程式碼和引用信用額度之前，用一則訊息詢問還有哪些事項尚未確定；已在 brief/decisions.md 中的答案保持不變。加入工具無法看見的內容：

• 重疊性：過去是否有關於相同主題或核心概念的影片（請查閱 projects.json）。說明是哪一部，以及這部新影片增加了什麼。重製版應保持舊資料夾不變，並詢問其 decisions.md 中的哪些答案仍然適用。
• 產品 + 網址（或主題）。對於 OpenView 影片，請提供 docs/content-map.md 中的核心概念與公式。
• 品牌：OpenView 影片使用 lib/brand.js。其他品牌：顏色、字型、一個重點色、真實 Logo。
• 參考資料：一個影格、影片或圖片資料夾。或是「無」（請明確說明；無預設外觀）。
• 音樂：提供的音軌（需測量其長度）或「合成」（預設）。
• 旁白：需要在 .env 中設定 ELEVENLABS_API_KEY。若為空，則停止並提示該變數名稱。

當語言、旁白、時長、比例、主題（包含跑馬燈）、資料來源（應用程式、套件或插圖）及情緒強度都確定後，腳本才算完成。這些項目中的任何一項在過去影片的首次試做後若有變動，都需支付成本（mi-demo-40 曾為其旁白支付了三次費用）。將答案記錄在 <project>/brief/decisions.md 中。

來自其他工具（如故事板、壓縮檔、交接檔案）的套件：將其未經修改地複製到 <project>/references/<工具名稱>-<日期>/，此資料夾不會被提交，並僅針對其腳本執行 tools/brief.mjs。僅在需要做出相關決策時，才打開該套件的其他檔案。其鏡頭清單和劇本與草稿的順序一樣具有參考價值。

限制條件：腳本或法規禁止在畫面上出現的文字、數據或事實，應放入 <src>/forbid.json（使用 tools/forbid-lib.mjs）：tools/vo.mjs 會在花費信用額度前拒絕它們，tools/check.mjs 則會在畫面上檢查到時失敗。對於無法透過模式比對的限制（例如一個永遠不帶百分比的姓名），則應放入 brief/decisions.md，並在每次審查分鏡表和檢查表時參照。

為影片選擇一個英文代號（[a-z0-9-]+）。以下所有內容都以此代號 <film> 命名。

專案佈局。 新影片會獲得其 CONTENT 專案資料夾（請參閱 CLAUDE.md 中的「New video project folders」），並在 projects.json 中加入一行 "<film>": "CONTENT/<n>. <Title> (<date>)"；工具隨後會在那裡找到它（tools/paths.mjs）： 鏡頭清單與腳本在 <project>/brief/（shotlist.md），程式碼在 <project>/src/（film.js, timeline.js, vo-lines.json, beats.json, sfx-<film>.mjs），拍攝素材與媒體在 <project>/assets/，分鏡表、檢查表與轉檔成品在 <project>/output/。較舊的影片則會保留 docs/<film>-shotlist.md、film/<film>/、assets/<film>/ 和 out/。以下，<shotlist>、<src>、<assets> 和 <output> 代表適用的路徑。

2. 前期製作

1. 素材。 放入 <assets>/ 中，並在動畫開始前列出。

   • OpenView Logo 與符號：僅能透過 lib/brand.js 繪製；切勿將 SVG 檔案複製到影片中。
   • OpenView 吉祥物：使用 lib/mascot/ 中的程式碼骨架（API 請見 lib/mascot/index.js 的標頭與匯出項目）。
   • OpenView Market Intel：數據與名稱來自最新的 origin/main，圖片使用 Market Intel UI 套件以程式碼繪製。僅當腳本要求使用真實應用程式時，才擷取執行中的應用程式畫面；屆時請遵循 CLAUDE.md 中的「Market Intel source」；透過 capture_mi.mjs --review 選擇波段，並使用 lib/proof.js 繪製。
   • 其他帶有網址的產品：使用 Playwright 擷取真實的螢幕截圖、Logo、顏色與字型。

2. 視覺世界。 閱讀 REFERENCES/motion/visual-grammar-2026-10.md，然後在任何鏡頭之前，於 <shotlist> 頂端撰寫 ## World：一個場景、其物件、場景中的人物、光線的表現，以及腳本中的每個形象與關係如何轉化為可見的事物。使用 lib/world.js 繪製。設計系統應保留在產品自身的畫面上。 風格指南。 如果存在參考資料，請先進行測量： uv run --python 3.11 --with librosa --with numpy tools/ref_probe.py refs/<film>/ref.mp4 refs/<film>/analysis.json 然後撰寫 docs/<film>-style_guide.md：色板（十六進位）、字型、鏡頭長度、轉場、鏡頭移動、紋理、文字進出方式。參考風格，而非內容。基本外觀由 CLAUDE.md 中的「Look」加上 docs/motion-vocab.md 定義；其他影片的風格指南記錄的是那些影片本身，而非基本外觀。

3. 故事。 閱讀 story.md，將主題通過其主題階梯（Topic ladder），並在 <shotlist> 頂端、任何劇本之前，撰寫其故事主幹表格。當每一行都填滿，且該檔案結尾的腳本測試能通過第一行和大綱時，故事主幹才算完成；草稿的順序在此處具有參考價值，而非劇本本身，而草稿中的 ALUR CERITA 和 KANDIDAT HOOK（docs/brief-prompt.md）是其初版。展示故事主幹時一併附上旁白的報價：這是改變影片成本最低的時刻。如果從草稿開始，同一則訊息應說明草稿涵蓋了什麼，以及劇本刪減了什麼，並附上兩者的字數：pandu-supra-80 在首次拍攝後被指出「沒有草稿完整」，而後續的擴充花費了三次額外的工作階段。

4. 旁白（若腳本包含旁白）：遵循 CLAUDE.md 中的「Voice-over」。根據故事主幹，以調查員的口吻（請參閱 story.md 中的「The viewer」）撰寫劇本，字數不超過預算，並在朗讀時計算數字：其印尼語的 1.7，是六部影片以 1.12（1.65–1.75 字/秒）運行時的結果，因此完整的預算應接近腳本所定的秒數。character 預設為 calm, fair narrator, talking to one person。然後建立 <src>/vo-lines.json 以及 story.md 的最後一個章節，直到 tools/script.mjs 通過為止；其 credits 行即為報價。使用 tools/vo.mjs 生成，並加上 --check 參數。定義與法律術語需要像任何數據一樣在 references/sources.md 中標明出處；R-120 要求將註冊名稱保留在畫面之外，而非移出來源檔案。 拍攝素材會決定場景長度：<src>/timeline.js 是基於 lib/vo-clock.js 的場景清單（sceneTimeline；範例：iata-55），執行 node tools/prepare.mjs --film=<film> 會檢查拍攝素材並將時鐘寫入 beats.json。

5. 節奏網格。 如果提供了音軌：使用 librosa 測量 BPM/拍點/強拍/重音，並匯入 <src>/beats.json。 如果是合成音效：選擇 BPM，撰寫 <src>/sfx-<film>.mjs，這是一個基於 lib/synth.mjs 的提示清單（範例：iata-55 的 src/sfx-iata-55.mjs），使其能輸出 beats.json 和一個 LUFS 為 -14 的 <output>/<film>-audio.wav 檔案。

6. 鏡頭清單。 根據節奏網格撰寫 <shotlist>：每個鏡頭需包含影格數、攝影機、螢幕文字、音效、其對應的故事主幹節拍、使用的 docs/motion-vocab.md 效果，以及切入下一個鏡頭的理由（下一步、相同位置、因果關係、時間跳躍、前後呼應、尺寸變化）。沒有理由切換的鏡頭，應作為攝影機移動與下一個鏡頭合併。規劃進入產品的路徑，使其成為一個連續動作，並讓一個世界中的物件變成螢幕，在切割前後兩個鏡頭中命名：這在 delisting-18-80（45–50 秒）的建置階段，為擁有者帶來了唯一一次創意修改。在此處規劃畫面的密度，逐一場景進行：每個場景的運鏡將承載這些密度，因為近期每部影片的首次建置在密度上僅得 4–5 分，並花費後續輪次來增加。列出需要擁有者核准的決策。此處不停留：鏡頭清單需連同分鏡表一起交給擁有者。

7. 分鏡表。 首先在 <src>/film.js 中繪製影片中最寬和最近的鏡頭（匯出 board: [{ t, shot, note }]），並單獨查看這兩個鏡頭（node tools/board.mjs --film=<film> --only=<wide>,<close>，其 -view.jpg 檔案）：它們能顯示世界需要承載多少內容，以及其中的形象在特寫鏡頭下是否依然清晰，而每次重繪的成本相當於兩個鏡頭。然後為每個鏡頭繪製一張靜止畫面。 執行 node tools/board.mjs --film=<film>。其輸出的文字即是機械檢查：修正每一行 warn … mid-move（將 t 移至確定的影格）以及每個 layout 發現（文字位於安全區外、在字幕區域內、重疊、太小），然後再執行一次以確認文字乾淨無誤。 僅閱讀分鏡表的 -view.jpg 總覽，若鏡頭超過 18 個則閱讀其輸出的 pages 頁面，每頁一次，以檢查外觀：在一次通過中修正所有看起來不對的地方，不要進行「查看-修補-重新轉譯」的循環，也不要逐場景檢查（--scenes 參數是為擁有者設計的，非供此審查使用）。 外觀測試，基於該總覽：關閉聲音，僅透過圖片來理解故事；一個陌生人看到的應該是一個場景、人物和物品，而不是投影片。除了字幕之外，一個鏡頭最多只能容納 6 個字，且只能放在物件上；腳本要求完整顯示的證明板與文字行是唯一的例外。若無法通過此測試，則表示需要重繪鏡頭，而非刪減文字。

8. 擁有者審查（唯一的關卡）。 同時展示鏡頭清單與分鏡表（<output>/<film>-board.png），以及需要核准的決策，然後等待那唯一的核准。在此之前，不得進行任何動畫或音效製作。

9. 交接。 當擁有者核准審查後，在 <shotlist> 頂端撰寫一個 ## Build brief 章節：說明已核准的內容、仍待決的事項，以及建置階段所需的檔案（影片模組、拍攝素材、節拍、音效腳本）。然後在新的上下文中開始建置：

   • 桌面應用程式：以全新上下文（非分支）開始一個新的對話階段，並輸入提示 /motion-reel build <film>。
   • 終端機：告知擁有者執行 /clear，然後輸入 /motion-reel build <film>。

   前期製作到此結束：擁有者對鏡頭清單與分鏡表的核准即是完成標準，而建置階段屬於新的對話階段。

3. 嚴格規則

• 時間的純函數：僅允許 seek(t)。不能使用 Math.random、計時器、CSS 轉場、在轉譯模式中使用 requestAnimationFrame，或在影格之間保持狀態。
• 開啟 -view.jpg 預覽；僅在需要查看 --crop 的某個細節時，才檢視全解析度圖片。圖片用於外觀檢查；機械檢查應依賴工具輸出的數字（node tools/check.mjs --film=<film>：seek 掃描、確定性、字型 px、佈局 lint）。
• 上下文即是成本，而對話輪次會放大成本：一個 300k 上下文的輪次，成本相當於三個 100k 輪次，而近期三分之二的訊息只攜帶了一個工具。請在單一訊息中，傳送某個步驟的所有獨立讀取、搜尋和編輯操作。工具是用來執行的，而不是用來閱讀的（--help 提供使用說明）；使用編輯（Edit）功能，切勿重寫整個檔案；長時間執行的指令應在背景執行，並等待通知，不得使用 sleep 或輪詢迴圈。
• 其他影片的原始碼並非範本：影片之間共享 3–16% 的程式碼。透過 Grep 或帶有 offset/limit 參數的 Read 功能，查閱你需要的特定函式，並保持其 film.js 檔案處於關閉狀態。
• 狀態存在於檔案中：brief/decisions.md、references/sources.md、<shotlist>、docs/review_log.md。當專案上下文達到 250k 時會自動壓縮，因此僅存在於對話中的資訊可能在影片製作過程中消失。
• 機密資訊僅來自 .env。切勿列印、記錄或貼上任何金鑰。
• 每個品牌使用單一對話階段：引擎、合成器與匯出管線會被重複使用，而非重建。