TimeCraker/video-motion

video-motion — 影片底材疊動效（Remotion）

設計即程式碼：座標 / 時刻 / 文字全部宣告在 src/cues.ts（資料契約，欄位不許改），fx 元件零硬編碼；改 cues 重跑一條命令即復跑成片。三層動效：字幕 SubtitleTrack / 資料柱 DataBars / 圈註 Spotlight（circle / arrow / box）。

技術圖解、流程/資料畫面、Lottie、3D、地圖或 Studio 參數編輯請依專項視覺製作讀取相關分支。導演給出內容與視覺方向，製作模組交付實際專案素材/程式碼和渲染證據；當前元件、類型與鎖定引擎介面優先。

系列影片請依系列一致性將欄目約定落實到專案的 tokens、字型、場景、字幕、封面與實際音軌。復用實際輸入版本並用本期內容渲染對照，不把改一個主題值當成全片已統一。產品示範請用實際錄製/採集素材疊標註，後期滑鼠或圈註必須對應真實動作與結果。

Step 1 · 劇本設計（看素材，不猜畫面）

1. 抽幀看素材：npx remotion still remotion/index.ts FootageOverlay <輸出>/f-<n>.png --frame=<n>，依鏡頭和關鍵變化選幀；使用實際生成圖的絕對路徑讀圖
2. 寫 src/cues.ts 動效劇本：
   • 字幕講畫面：說觀眾此刻看到的事，依語意與閱讀速度分段
   • 圈註指實物：circle / arrow / box 指向畫面中真實存在且值得注意的元素，座標先用抽幀核實落點
   • 數字要口徑：資料柱數值取真實來源（畫面 HUD / 結算面板 / 後台資料），取不到就在字幕標明「示範資料」
3. 解讀落到與目標相關的細節：HUD、聊天、提示和操作可作為證據，但只標解釋需要的內容；不為 cue 密度標滿整片。

Step 2 · 工程與規格（隨素材自適應）

1. 複製 templates/remotion-app/ 到工作目錄，npm install（Remotion 各子包必須同批安裝，版本嚴格聯動）；裝完跑 npm run typecheck（esbuild 容忍不等於型別乾淨，tsc 一過才現形；模板含 typescript devDependency，隨裝隨跑）
2. 原生規格：node scripts/probe-footage.mjs <素材路徑> 用 ffprobe 產生 src/footage-params.ts——輸出解析度 / 幀率隨素材走，不寫死；換素材重跑該腳本即可
3. 素材不進 skill：渲染帶 --public-dir <素材目錄>（staticFile 直讀專案素材庫）；只有不便帶參數時才把素材複製為 public/footage.mp4
4. cues 請依 1080p 設計座標書寫，FootageOverlay 已內建 transformOrigin: "top left" 整體縮放適應任意畫布——換解析度不改 cues，動效落點不漂移

Step 3 · 生成（一條命令）

渲染前先過校驗：node scripts/verify-cues.mjs（deck 字幕換 src/deck-cues.ts 參數），error 清零才進渲染；總時長 warn 只提醒不攔。

cd <remotion-app>
npx remotion render remotion/index.ts FootageOverlay <倉庫>/products/<專案名>/demo.mp4 --crf=16 --public-dir <素材目錄>

產物住倉庫 products/<專案名>/（目錄法：skill 是純工具，產物不落 skill 內；跨倉庫使用時落該專案根 output/<skill 名>/）；--crf=16 高品質。大素材渲染放背景跑（1440p60 × 30s 約 10 分鐘），以退出碼 + ffprobe 驗收，不憑進度條。

Step 4 · 三級核查（必做，不可跳）

① 程式：渲染退出碼 0；npx remotion compositions remotion/index.ts 輸出的 durationInFrames / 寬 / 高 / fps 與素材元資料一致；npx remotion still 依關鍵字幕、資料變化和轉場選取代表幀——每條字幕 start+0.3s / end-0.3s、資料柱 t-0.3s / t+1.5s、圈註 t+0.5s / t+ttl+0.3s（以 compositions 輸出的實際 fps 換算幀號）。

② 讀圖：讀取實際 PNG 逐幀核對：出現 / 消失時刻與文字、柱高比例與數值標籤、圈註類型與落點、底材無花屏無拉伸、全幀無亂碼（中文走 Microsoft YaHei 回退）。問題回寫對應源檔案，重渲染後檢查原問題與相鄰銜接；遇到無法判斷或無法修復的阻塞再明確報告。

③ 連續播放與審聽：抽幀不能證明節奏和同步，請依 media-qc 的視聽方法檢查實際片段和音軌，記錄檢查範圍；用戶終審成片。

Step 5 · 交付

報告：成片路徑與大小 / 解析度幀率（=素材原生）/ 三級核查結論（含抽幀核對表）/ cues.ts 位置（可復跑）。產物與 mp4 一律不進 git。

PPT 逐頁成片（DeckVideo，第二種成片）

一套引擎兩種成片：上面 Steps 是「影片底材疊動效」，這一節是「PPT 逐頁」——pptx 頁圖 + 逐頁配音直出成片，頁時長跟配音實際長度走，字幕按分段稿時間軸出現。

1. pptx 與分段稿：ppt skill 產物 pptx；寫 narration 分段稿 script.json，ref 寫 "page N"（N=頁號），先過 python skills/narration/templates/verify_narration.py <script.json> 全綠。每段剝後 ≤20 字（字幕單行藥丸直接顯示段文字），頁內多段以句號連接成該頁口播
2. 頁圖：python scripts/extract_pages.py <in.pptx> public/deck/pages——COM 轉 PDF 後 fitz 渲 200dpi，出 p-<N>.png（2667×1500，畫布 contain 鋪滿）
3. 配音：測試走 powershell -File scripts/make_deck_audio.ps1 <script.json> public/deck/audio（SAPI Huihui 逐頁出 page-N.wav）；正式流程人工在剪映逐頁配音，匯出同名 page-N.wav 放同目錄，下游無感
4. 接線與渲染：node scripts/build-deck-params.mjs <script.json> public/deck 產生 src/deck-params.ts + src/deck-cues.ts（頁起點 / 總時長 / 字幕攤時全是派生值，勿手改）→ npx remotion render remotion/index.ts DeckVideo <倉庫>/products/<專案名>/deck.mp4 --crf=16
5. 三級核查：同 Step 4 三級（程式 ffprobe / compositions 對帳 + 抽幀讀圖 + 使用者看片）。L2 抽幀要點：每頁首幀+0.3s 查頁序；交疊中點取下頁 start+0.25s（交疊尾在頁窗尾部，0.5s 交叉溶解）；字幕 start+0.3s / end+0.3s 查文字與退場。頁首幀+0.3s 處 spring 淡入未滿、整幀偏灰，是轉場中間態不是缺陷

頁圖與配音住 public/deck/（.gitignore 已覆蓋，不入 git）；畫布 1920×1080@30 常數在 build-deck-params.mjs 頂部，改兩行即 4K。

場景化成片 v2→v3 質感工藝（scene-kit 直繪，第三種成片）

PPT 逐頁成片的升級線：畫面主體從「PPT 頁圖」換成 Remotion 元件直繪的動效場景（src/scene-kit/ 24 元件），頁時長/音訊/字幕機制沿用 deck-params 派生鏈。判「素」判「low」對照 docs/2026-08-30-motion-grammar.md；本節是質感工藝的硬規則。

品質底線

按 docs/2026-08-30-motion-grammar.md 的內容類型選擇驗收方式。保留 tokens 與品牌連續性；畫面以真實主體和可讀資訊為中心，運動解釋變化。留白、靜止與每鏡支撐資訊數量依鏡頭目標判斷，不再套固定配額或靜幀 PPT 否決。

先由 content-director 留事實來源、分鏡與美術簡報，再看代表幀和短樣片。結構圖優先 SVG，真實介面用截圖/錄影，插畫需要時接可用 imagegen 工具並登記資產。新 ArtLayer 和更多動效不自動代表美術品質通過。

場景設計方法（通用，不預設答案）

先查 assets/patterns.md 成頁方案庫——同類情景已有驗證過的 PAT 條目就套用改參數（情景→版式→元件→坑→參考幀都在條目裡），沒有再從零設計。每頁文案先定內容類型（敘事痛點/功能示範/資料說服/流程說明/概念/行動號召六類），再按「主體由文案內容定、同類型多頁不重複同一視覺方案、背景族服務內容情緒」三條規則定主體形式與元件組合。開工前產出設計表（每頁：文案摘要→內容類型→主體形式→背景族→元件組合→理由→畫面資訊包逐條+出處→主體標註），設計表前置複核，過了才寫程式碼；支撐資訊逐條標出處（口播稿/專案文件/素材可見內容）。

三條換來的硬教訓（寫成規則）

1. 完成態允許閱讀停頓：聊天、圖表或流程需要表現狀態變化時使用已有元件；靜止鏡頭依資訊與節奏判斷，不為檢查結果強加裝飾動效。
2. 包裝元件必須顯式透傳 width：新容器包舊元件時丟 width = 區塊級元素撐滿父容器（插畫蓋標題、手機殼撐到 700px 寬兩輪同根因）；包容器一律 style={{ width, ...style }}。
3. 長截圖先驗空白率再定方案：拿到長截圖先依行算 std/空白佔比（PIL 一段腳本），懶載入沒渲染進截圖的「空長圖」滾動即死空氣——先裁切特寫，素材修復再回切滾動。

MG 武器庫（S0-S6，成片質感的主力彈藥）

模板自帶全套武器，家底與逐元件用法以 assets/component-catalog.md 為準（scene-kit 24 元件 / entrance-kit 九動詞 / vendor 社群精選 / fonts），此處只記鐵律：

• 版本鐵律：所有 @remotion/* 必須精確同版（如 4.0.533，不帶 ^）——版本錯配是 Remotion 硬報錯不是警告；新增包先對齊存量版本（check-docs 第 3.7 項斷言看管，漂了會紅）
• 4.0.533 API 事實（與文件/記憶有出入，已實測；4.0.518→4.0.533 升級經 still 基線 PSNR 全 inf 對照，API 形狀不變）：evolvePath 返回 dash 屬性對非裁剪 path；interpolatePath(value, from, to) 三獨立參數；fitText 只吃 withinWidth 且返回 {fontSize} 物件；中文多行不能用 fitTextOnNLines（依空格分詞）；parseSrt 吃 {input} 物件（裸字串報 undefined.split）、返回 {captions:[{text,startMs,endMs}]} 毫秒制
• transform 包裝坑（S6 雙坑實錄）：帶 transform 的包裝動詞（CameraPush/SlideGroup/TextBreath/BlurTrail）不得直接包 position:absolute 子樹——transform 元素是 absolute 後代的 containing block，流內高度塌 0、內容頂格溢出。元件已自足（CameraPush 根 inset 0、BlurTrail 主層流內），使用時仍避免在無尺寸的 absolute 父級裡裸包
• 官方 <Trail>/TransitionSeries 語義：Trail 根是 AbsoluteFill（頁級覆蓋語義），元素級殘影用 scene-kit 的 BlurTrail（已 relative 化）；TransitionSeries 轉場吃相鄰頁時長，成片引擎預設零轉場（Series 硬切）+ 頁內動詞
• vendor 紀律：copy-paste 入庫非 npm 依賴；升級=重新拉取重做 intake；紀律四條見模板 src/vendor/README.md
• Lottie 資產流：免費商用 JSON 進 assets/lottie/（README 三欄位登記）→ 用時複製進專案 public/ → LottieLayer src 引用；intake 禁帶 expressions 的 JSON（渲染不確定）
• 複雜效果預算：ShutterBlur 的 samples 和 BlurTrail 的 layers 會增加渲染成本；ThreeStage 依場景與機器差異實測。先渲染代表幀/短片，再決定規模，不設全片固定鏡頭配額。

驗收流程（四級）

L1 程式（渲染退出碼取完整日誌，禁管道尾；ffprobe = compositions 幀數對帳）；L2 抽幀（依風險選擇進場/穩定全景/資訊特寫/轉場及字幕代表幀，核對實際圖；放大僅用於檢查細節，不固定每頁數量）；L2.5 靜音測試（逐頁盲答主旨）；L3 報告（含技術範圍、關鍵幀證據、人工待審項與需要時的新舊對照）。確認具有通用價值的元件、tokens 與版式再依資產回流約定回寫模板/登記簿；專案專用內容保留在專案內，沒有新經驗不另造工單。渲染命令同 DeckVideo（composition 換成場景化元件，如 DeckVideoV2），封面用 npx remotion still 出圖（still 幀號要容納入場 spring 時長）。

封面出圖（Cover，第四種產物）

不渲影片渲一幀：一條命令出 1920×1080 封面 PNG，發影片時配圖用。

1. props：products/<專案名>/cover-<名>.json 寫 { title, subtitle?, badge?, bg?, preset }。preset ∈ photo（bg 圖鋪滿 + 底部 55% 黑漸層遮罩保對比度）/ dark（深色漸層，缺省）/ clean（淺底 + 頂部細線）；bg 是 remotion-app public/ 下相對路徑。subtitle 省略即不渲染；badge 省略回落 ASTERFORGE 品牌角標
2. 渲染：npx remotion still src/cover-index.ts Cover <輸出>.png --props=<json 檔案路徑>（獨立入口不經 Root.tsx，與 DeckVideo 並行施工零衝突）
3. 核查：讀圖查標題完整不截斷、photo 遮罩下文字可讀、無亂碼方塊；使用實際產物絕對路徑，複查核對當前版本或雜湊。標題行數依目標畫幅與閱讀需要調整。

邊界與坑

• 使用實際產物絕對路徑讀圖，複查核對當前檔案版本或雜湊；僅在具體工具確有路徑限制時才轉換路徑。
• GBK 控制台：print 全英文
• Chrome Headless Shell 首次 npx remotion browser ensure 從 Google 來源下載（百 MB 級），中國網路可能逾時——失敗即報，不反覆重試大檔案下載
• 大媒體、依賴與快取不進 Git；製作配方、封面、字幕、發布配置與驗收元資料依歸檔規則保留。

當前流程與技術參考

用 node scripts/studio.mjs init --id <名稱> --line b 帶出模板，job.json 的 deps/typecheck 可復跑；本專案 params/render/QC 命令在場景和實際音軌確定後加入 job.json。渲染後呼叫 media-qc，技術報告與用戶終審分開記錄；通過歸檔校驗後清理快取。

官方 remotion-best-practices 透過 python scripts/install-upstream-skills.py 固定安裝到專案快取，再由 setup-skills 掛載。來源見 references/upstream.json；它是技術參考，不替換本倉工作流。官方參考 4.0.538 與當前引擎 4.0.533 分開管理，使用新 API 前先核對本地型別與實際渲染，不自動升級。