kajisho5/remotion-ffmpeg-skill

remotion-ffmpeg-skill 是做什麼的？

ffmpeg-skill 測量 → Remotion 繪製 → ffmpeg-skill 檢查與交付。 腳本位於此檔案旁的 scripts/ 目錄中；使用 python3 <skill-dir>/scripts/<name>.py 執行。腳本加上 --help 即可查看完整參數列表；references/timeline.md 說明時間軸格式以及每個合成可用的選項。

此技能依賴 ffmpeg-skill（位於此技能旁、~/.claude/skills/ffmpeg-skill 或透過 FFMPEG_SKILL_DIR 指定）。它不會直接執行 ffmpeg/ffprobe 指令：測量、檢查與交付皆透過 ffmpeg-skill 的腳本進行，因此其保證得以繼承。

共用參數（每個腳本皆可使用）：--json（在標準輸出輸出一個 JSON 物件；建議使用）、--dry-run（僅規劃，不寫入任何檔案）、--overwrite（唯一能取代現有輸出檔案的方式）、--timeout 秒數。

工作流程（依此順序）

1. 初始化專案一次。 若無 Remotion 專案：執行 init.py ./motion --install（複製模板並執行 npm install；Remotion 的無頭瀏覽器將在首次渲染時下載）。若已有此技能建立的專案，則重複使用。
2. 測量。 執行 analyze.py 來源檔案 [--captions 字幕.srt] [--beats] -o 來源.timeline.json。閱讀摘要與 warnings：VFR 或 HDR 來源必須先透過 ffmpeg-skill 修正（color.py --to-sdr、常數影格率匯出），之後才能繪製 — Remotion 在固定影格網格上渲染 SDR。切勿手動編輯時間軸數字；應重新測量（在安靜環境下使用 --threshold、--min-silence）。
3. 預覽靜態影格。 執行 still.py --project ./motion --comp 合成名稱 --timeline 時間軸 --at 1.5 --at 6 並檢視 PNG：字幕位置、推近效果、顏色。成本低廉；請在完整渲染前執行。
4. 渲染。 執行 render.py --project ./motion --comp 合成名稱 --timeline 時間軸 [--options look.json] -o 輸出.mp4（--fast = 半尺寸預覽、--frames 0-89 = 指定影格範圍、--codec prores -o master.mov = 母版）。它會根據時間軸驗證輸出（影格數、FPS、尺寸、音訊），若不符合則以非零結束碼退出。
   • 形狀： 以最終交付的形狀進行繪製。Reels / TikTok / Shorts 使用 --aspect 9:16（也支援 1:1、4:5、16:9）；--fit blur（形狀變更時的預設值：在模糊副本上置中）、contain（加上黑邊）或 cover（裁切 — 請先透過靜態影格檢查主體）。切勿渲染 16:9 再讓 9:16 模板裁切：字幕邊緣會被切掉。pipeline.py --platform 會自動從 ffmpeg-skill 的模板選取長寬比。
   • 字型： 日文/中文/韓文字幕會自動使用 ffmpeg-skill 在機器上找到的 CJK 字型（暫存至專案中，因此不會出現方塊字）；--font-file F.ttf 使用特定字型；報告中的 font: 行會說明使用了哪種字型，或告知未找到字型。
   • 剪輯應用圖層： --overlay --keep-graphics（Captioned / PeakPulse，原始形狀）會將圖形單獨渲染為透明的 ProRes 4444 .graphics.mov，然後透過 ffmpeg-skill overlay.py 合成到未修改的來源影片上；將此 .mov 交給在 Premiere / Resolve / Final Cut 中進行後製的人員。此方式不會比一般渲染更快。
5. 交付。 執行 deliver.py 輸出.mp4 --platform youtube|reels|tiktok|shorts|x|... 以執行 ffmpeg-skill 的交付模板及其 check.py 表格。格式列可安全修正；判斷列（持續時間、長寬比）會影響內容 — 請詢問使用者。提及 WARN，但無需追蹤。若未指定目標：跳過此步驟並告知。
6. 檢查外觀。 在回覆中必須提及 render.py 寫入的聯絡表（Look: 路徑）並說明其顯示內容。機械性檢查（檢查並報告）：文字位於要求的位置、提示在正確時間出現、無內容被影格裁切。判斷性檢查（描述所見內容，由使用者決定）：文字遮蓋人臉、跳接位置不佳。無圖像檢視：Look: 路徑 (像素未經檢查) — 切勿聲稱已檢視。無聯絡表（結果中出現 look_error，例如缺少 drawtext 的 FFmpeg）：改用 still.py 的影格並傳遞錯誤名稱所指示的修正方式。

選項檔案在渲染前會經過檢查：未知的鍵或錯誤的型別將被拒絕（kind: input）而非靜默忽略。

MCP：mcp/server.py 公開相同的工具（schema 來自 scripts/_contract.py，contract --json 可列印它們）。

一鍵完成所有步驟：pipeline.py 來源檔案 --project ./motion --comp 合成名稱 [--captions 字幕] [--platform 平台] 會依序執行步驟 2→4→5，並在第一步失敗時停止。

請求 → 腳本 / 合成

請求	執行指令
"在此影片上加入動態字幕"	analyze.py --captions → render.py --comp Captioned
"剪掉靜音 / 跳接 / 緊湊化這段談話"（含動態效果）	analyze.py → render.py --comp Jumpcut（若有提供字幕則重新計時）
"圖形隨著音訊反應 / 配合節拍 / 配合場景切換"	analyze.py [--beats] → render.py --comp PeakPulse（若已測量節拍網格則在節拍上產生脈衝）
"卡拉OK字幕 / 逐字高亮"	analyze.py --words WORDS.json [--captions F.srt] → render.py --comp Karaoke（詞彙時間來自本地語音引擎、whisper JSON；若無 SRT 則從詞彙中分組提示）
"下方三分之一 / 名稱標題 / 章節標題"	render.py --comp Titled --options 搭配 lowerThirds / sceneTitles — 文字來自使用者；請詢問，切勿自行發明名稱
"精彩片段 / 最佳時刻"	analyze.py --highlights N [--target S] → render.py --comp Highlights（音訊能量排名：列出候選，並告知）
"配合節拍剪輯 / 音樂蒙太奇"	analyze.py --beats [--highlights N] → render.py --comp BeatMontage（音訊不中斷，畫面每 beatsPerCut 個測量節拍切換；若無可靠的節拍網格則使用場景切換）
"用於 YouTube / Reels / TikTok ..."	pipeline.py --platform（以模板的長寬比渲染，然後交付並檢查），或 render.py --aspect + deliver.py --platform
"直向 / 9:16 / 方形"	render.py --aspect 9:16（或 1:1、4:5）
"日文字幕" / 指定字型	CJK 無需額外設定（自動字型）；使用 --font-file 指定字型
"將圖形作為獨立圖層提供"	render.py --overlay --keep-graphics
"改變顏色 / 字型 / 字幕大小 / 縮放"	修改 --options JSON（references/timeline.md），重新渲染
多個片段（"開場 + 訪談 + 結尾"）	analyze.py A.mp4 B.mov C.mp4（或 pipeline.py 搭配多個輸入）：ffmpeg-skill join.py 會正規化並合併它們，然後在合併後的檔案上進行測量
"預覽" / "顯示某個影格"	still.py
新型圖形	在專案的 src/ 中加入一個讀取 src/timeline.ts 中 Props 的合成；使用 --comp 您的識別碼 渲染（render.py 會回報測量數字，但無內建期望值）
純剪輯 / 裁切 / 調整大小 / 響度調整（無圖形）	非本技能範圍：請直接使用 ffmpeg-skill
某環節出錯	doctor.py [--project 目錄]

此技能決定的內容與不決定的內容

• 決定（機械性）： 合成長度、FPS 與尺寸（來自探測）；剪輯位置（來自測量的靜音）；提示出現時間（來自字幕檔案）；脈衝觸發時間（來自測量的峰值）；渲染結果是否符合其時間軸。
• 不決定： 名稱、標題與章節名稱（下方三分之一與場景標題為使用者提供的文字 — 請詢問）；字幕中出現的文字 — 提示文字完全依照原文繪製，絕不縮短或改寫，即使為了「使其符合空間」也不做（請提供較小的 captionSize）；什麼算是精彩片段；外觀是否良好。這些皆屬於使用者或呼叫端代理程式的決定。
• 絕不發明數據。 若無使用者提供的計時字幕檔案或本地語音轉文字引擎，則不產生字幕；若未透過 --beats 測量，則不使用節拍網格。

避免工作失敗的規則

• Remotion 授權：個人及員工人數不超過 3 人的營利組織免費；較大型公司需要 Remotion 公司授權（https://www.remotion.dev/license）。若使用者明顯是較大型公司，請告知一次。
• 保留使用者的原始檔案：來源檔案會連結至專案的 public/media/ 目錄，絕不修改；輸出檔案絕不覆蓋現有檔案（除非使用 --overwrite）。
• CJK 字幕：自動字型來自 ffmpeg-skill 的字型偵測；當報告指出未找到字型時，請安裝一個（Noto Sans CJK）或傳遞 --font-file — 聯絡表中出現方塊字即為失敗的工作。日文行應在片語之間斷行，而非在單字內部。
• 速度（在 2 核心 Linux 機器上測量，使用所有核心 — render.py 的預設值）：約為影片長度的 2.6 倍（1080p30 下，30 秒耗時 80 秒）。在完整渲染長時間素材前，請先使用 still.py 與 --fast 預覽；在開始長時間渲染前告知使用者預計時間。--concurrency 超過核心數將被 Remotion 拒絕。
• 專案中的所有 Remotion 套件必須為相同版本；模板已固定版本。請勿混用不同版本的 remotion。
• 未通過驗證的渲染即為失敗：請從 --json 回報失敗的行，切勿交付該輸出。