akomlik/assemble-timeline

Atomic MCP 時間軸組裝與驗證 (/assemble-timeline)

選項 A：FilmCraft MCP 執行 (filmcraft MCP 伺服器 — 需 FilmCraft v0.17.0+)

1. 環境與橋接驗證

1. 首先執行 python3 ./.agents/skills/assemble-timeline/scripts/check_filmcraft_env.py 來確認 FilmCraft $\ge$ v0.17.0，自動同步 filmcraft-cli 與 FilmCraft.app，並將任何新增的 MCP 指令顯示在 00_Archive_Indexes/filmcraft_capabilities.json 中。
2. 確保 FilmCraft 以橋接模式執行，並將快取路由至 ~/Movies/Cache_And_Previews：

   mkdir -p ~/Movies/Cache_And_Previews && cd ~/Movies/Cache_And_Previews
   open -a FilmCraft --args --control 9876
   

2. 即時視覺組裝模式（預設且建議）

在已開啟的 FilmCraft GUI 中即時觀看時間軸組裝，只會增加不到 1.5 秒的總 socket 執行時間（透過本地橋接的呼叫耗時 $< 20\text{ ms}$），並提供即時的視覺驗證：

1. 在 0 秒處開啟空白畫布： 立即透過 command_run（{"id": "file.open", "params": {"path": "<fcproj_path>"}}）或 sequence.new 在 FilmCraft 中建立並開啟乾淨的 .fcproj 殼層。使用者會看到空白的 4K 序列出現在第 0 秒。
2. 串流媒體匯入： 使用所有選定影片剪輯、照片、封存素材以及選擇的 03_Audio_Library/01_Curated_BGM/ 音軌（A2）的絕對檔案路徑呼叫 media_import。
3. 即時逐場景串流： 當處理經過核准的 Cut Table 中的每個場景時，透過 9876 橋接埠即時串流 command_batch 呼叫：
   • playhead.set：將播放頭移至場景開始時間碼。
   • source.overwrite / timeline.insertClip：將視覺剪輯放置在 V1（或 V2 用於疊加/PIP）上，並將同步音訊放置在 A1 上。
   • motion.apply：對靜態影像注入 Ken Burns EaseIn/EaseOut 縮放與平移關鍵影格（100% $\rightarrow$ 108%，或 4:3 照片為 134% $\rightarrow$ 142% 以防止郵筒式裁切）。
   • audio.append：放入 A2 背景音樂，並帶有 1.5 秒淡入與漸強。
   • voiceover.insert：在每個音訊提示完成合成時，將 A4 旁白片段放入即時時間軸。
4. 廣播級後製：
   • 同語言即時對白尊重法則： 絕不將語言 $L$ 的 A4 旁白放置在以同一語言 $L$ 說出的 A1 即時攝影機對白之上（EN 旁白尊重即時 EN 對白；RU 旁白尊重即時 RU 對白；UA 旁白尊重即時 UA 對白）。當 A4 旁白翻譯包含外語攝影機對白的剪輯（edition_lang != clip_dialog_lang）時，在旁白提示活躍期間將 A1 降低 -12 dB。
   • 自然 1.00x 語速、1:1 V1 == A1 唇形同步與開場音樂導言法則： 絕不對即時攝影機語音（A1）或合成旁白（A4）套用 atempo > 1.0 或內部暫停移除（stop_periods=-1）。務必將說話的視覺剪輯（V1）調整為符合完整的 1.00x 口語句子（src_in、dur），使 V1 和 A1 保持 1:1 影格與樣本同步（透過 atrim=start=...:end=...,asetpts=PTS-STARTPTS 切片，並在 amix 後套用一次 dynaudnorm=f=150:g=7:p=0.90），且絕不溢出到不相關的場景。務必以 1.5s–2.0s 的音樂導言開始每個時間軸和渲染的 .mp4，然後才開始第一個旁白提示。
   • RMS 校準音樂閃避（語音下平均 -28.5 dB）： 透過 ffmpeg volumedetect（compute_bgm_ducked_gain_db）測量每個 A2 音樂音軌的 mean_volume，並將 gain_db = -28.5 - raw_mean_db 設定為閃避後的 BGM 平均 -28.5 dB — 比正規化的 -16.0 dB 平均旁白和即時對白安靜整整 12.5 dB，即使在熱母帶處理的快節奏音軌上也是如此。
   • 將 A4 旁白和 A1 對白標記為 Dialogue（clarity.eqPreset: "Balanced Voice"），並對 A2 音樂執行 essentialSound.generateDucking（reduceDb: -6.0、fadeS: 0.45）。
   • 在結尾視覺剪輯上套用原生 1.5 秒至 2.0 秒的 dip_to_black 轉場。
   • 強制同步結尾音訊淡出： 主音訊輸出（[fullout]）和 A2 上的音樂必須執行同步的 2.0s–2.5s 半正弦淡出（afade=t=out:st=<TOTAL_DUR - FADE_DUR>:d=<FADE_DUR>:curve=hsin），使所有音訊（音樂、攝影機噪音、SFX 尾音）在最末影格或之前達到完全靜音（-infinity dB）。在 .fcproj 中，A2 音軌必須帶有 EndAtCut 音訊淡出轉場（from: Some(clip.id), to: None, align: "EndAtCut"）。聲音絕不能突然中斷。
   • 將多語言字幕軌道寫入 caption_tracks（C1），並設定 enabled: false（預設 burnCaptions: false）。

3. 無頭批次備援方案 (assemble_engine.py)

如果 FilmCraft GUI 未執行或橋接模式離線，則直接透過 assemble_engine.py 在 $< 1$ 秒內自動組裝 .fcproj，並透過 filmcraft-cli 渲染 4K 主 MP4。

• 儲存庫整潔規則： 嚴格保留 .agents/skills/assemble-timeline/scripts/ 給通用、與專案無關的引擎（assemble_engine.py、gpx_widgets.py、generate_voiceover.py、check_filmcraft_env.py）。如果為了特定專案建立了自訂或專屬的組裝腳本，務必將其儲存在該專案的 git 忽略目錄（04_Project_Catalog/YEAR/<project_name>/）內，而絕不放在 .agents/skills/ 內。

4. 視覺驗證與主渲染

1. 在三個時間戳記（第一幕開頭、中點、尾聲）呼叫 render_frame 以確認構圖。
2. 將主 4K MP4 渲染至 ~/Movies/Exports/YEAR/<project_name>.mp4。
3. 如果需要多語言版本（option_b），則重新封裝為 _UA.mp4 和 _RU.mp4 本地化片段。

選項 B：DaVinci Resolve Studio MCP 執行 (davinci-resolve)

1. 建立一個新的時間軸（1920x1080 或 3840x2160、29.97 fps、DaVinci YRGB Color Managed Rec.709）。
2. 透過 media_pool 將選定的媒體匯入 Selects 容器，透過 timeline_edit 將剪輯附加到 V1/V2/A1 並將音樂附加到 A2，透過 transitions 套用 Cross Dissolve 轉場，透過 keyframes 設定 Ken Burns 縮放關鍵影格，並透過 audio / inspector 設定音訊閃避。
3. 在三個時間戳記呼叫 export_still 以視覺驗證剪輯，將 .drp/.drt 備份匯出到 04_Project_Catalog/YEAR/<project_name>/，並將最終的 .mp4 渲染排入佇列至 ~/Movies/Exports/YEAR/，透過 render 完成。