Kinetic 影片轉換至 DaVinci Resolve
將 kinetic 影片的 spec.js 轉換為 Resolve 時間軸，其中每個鏡頭都是一個獨立片段，並帶有其自身的 Fusion 合成：真實的 Text+ 和 Text3D、關鍵幀攝影機，以及相同的節拍時序。剪輯師隨後可以在 Fusion 頁面中開啟任何鏡頭，重新輸入文字、修剪或更換音樂。
這是使用 Resolve 工具進行的重建，而非像素級比對。請說明與原始版本相比有哪些變更（setup 會以 notes 形式回傳清單），並回報給使用者。
開始之前
- Resolve Studio 正在運行中，且已開啟一個專案。請使用
get_resolve_status檢查，並呼叫get_whats_new一次（Resolve 伺服器會要求）。 - 影片資料夾包含
spec.js及引擎檔案，且已在該資料夾中執行過npm install playwright。 - 在 Resolve 外部，需要有安裝 Pillow 的 Python 環境，用於測量字型。ffmpeg 需位於 PATH 環境變數中。
詢問使用者
在開始建置之前，請從對話中（如果可能的話）決定以下事項：
- **哪個專案。**時間軸會新增到已開啟的專案中。請告知使用者是哪個專案。切換專案可能會遺失他們未儲存的工作，因此如果是錯誤的專案，請要求他們切換。
- **時間軸名稱。**預設為
<標題> (Fusion)。檢視現有的時間軸，並選取一個未被使用的名稱。切勿重複使用或取代您在此工作階段中未建立的時間軸。 - **字型。**Text+ 只能看到已安裝的字型，而影片常用的 Archivo 通常不在其中。如果專案有顯示品牌字型，請使用它。呼叫
fonts_available(resolve, 'Lato', 'Inter')來檢查；未經詢問請勿安裝字型。粗體字重（Black、Heavy、ExtraBold）閱讀效果最佳。 - **音訊。**可以來自現有時間軸的音樂剪輯（
audio_from_timeline）、檔案（audio_from_file），或無音訊。如果某個時間軸已經包含此影片的音樂，請優先提供該選項，因為這樣可以保留使用者的編輯。
步驟
以下 SKILL 代表此技能的資料夾，F 代表影片資料夾。每個 Resolve 步驟都透過 run_script_unsafe 執行，該函數每次呼叫限制為 60 秒，並以以下程式碼開頭：
SKILL = r'<此技能資料夾路徑>'; F = r'<影片資料夾路徑>'
exec(open(SKILL + r'\scripts\resolve_build.py', encoding='utf-8').read())
1. 匯出規格（在 shell 中執行）：
node "<SKILL>/scripts/export_film.mjs" "<F>"
此步驟會將檔案寫入 <F>/resolve/film.json，並將標誌匯出為透明 PNG，同時輸出它找到的區塊。
2. 建立時間軸：
result = setup(resolve, project, F, '我的影片 (Fusion)', 'Lato', 'Black', 'Inter', 'Medium')
最後兩個字型是給小文字列和模擬 UI 使用的。此步驟會建立時間軸、一個 Kinetic Films / <標題> 的資料夾、一個黑色佔位片段，並回傳鏡頭數量和 notes。時間軸尺寸和影格率來自專案設定，因此一個以 60 fps 製作的影片可以放到 30 fps 的時間軸上。此功能僅在 1920x1080、60 fps 下經過驗證，因此請仔細檢查其他格式。
3. 測量字型（在 shell 中執行，使用安裝了 Pillow 的 Python）：
python "<SKILL>/scripts/measure_fonts.py" "<F>" Lato Black
如果沒有此步驟，文字將使用估計的寬度，可能無法很好地填滿畫面。如果回報找不到字型檔案，請繼續進行，但需仔細檢查排版是否正確。
**4. 建置。**重複執行直到 done 為 true；它會從上次中斷的地方繼續：
result = build_batch(project, F, 40)
然後添加 HUD（僅當影片有 HUD 時）、音訊和場景標記：
result = dict(hud=add_hud(project, F), audio=audio_from_timeline(project, F, '音樂剪輯'), markers=add_markers(project, F))
HUD 是時間軸上第二軌的一個 Fusion 片段，涵蓋整個影片。剪輯師可以停用該片段來移除 HUD。
**5. 檢查畫面。**在 Resolve 21.2 或更新版本上，此步驟會在幾秒內直接從時間軸匯出每個鏡頭中間畫面的標記圖表，無需渲染，也不會改變渲染設定。這些圖片會儲存到 <F>/resolve/review/。檢查是否有全黑畫面、文字是否保持在畫面內、提示文字是否清楚顯示、圖片是否覆蓋整個畫面。在渲染前修正任何問題。frame_grid(project, F, seconds=[4.2, 9.35]) 可以在指定時間點（例如甩鏡結尾）產出全尺寸畫面。
result = frame_grid(project, F)
這些畫面與相同影格渲染的結果一致（已在 21.2 上驗證）。在較舊的 Resolve 版本上，若沒有 ExportThumbnails 功能，則會引發錯誤，此時請改為從渲染結果判斷。
6. 渲染並測量動態。
result = start_render(project, F, 'my_film') # 在有 GPU H.264 編碼器時優先選用
# 後續呼叫：result = wait_render(project, result_job_id, 50)
對於 30 秒、1080p60 的影片，在強勁的 GPU 上預計需要 2 到 4 分鐘。之後，僅移除您自己的工作，使用 remove_job。渲染佇列中可能包含使用者的其他工作。start_render 會變更專案的渲染設定，請告知使用者。
動態只能從影片中測量。如果 scenario-kinetic-film 的腳本已安裝，請對渲染結果執行 holds.py 和 dyn.py。目標是：靜止畫面不超過 40%，結束卡前無任何畫面停留超過 0.6 秒，中位數動態值為 2.5 或更高。請回報這些數字，包括未達標的項目。
若要修改內容，請修正後使用 setup(..., replace=True) 重建（僅限於此技能建立的時間軸），然後重複步驟 4 到 6。若要修正少數鏡頭，可以使用 rebuild_shots(project, F, [8.2, 13]) 僅替換指定時間點（以秒為單位）或鏡頭索引的合成，並保留其他所有內容。如果影片的文字有變更，請重新執行步驟 3。
**7. 完成。**除非使用者要求，否則將儲存動作留給使用者：儲存也會提交他們已開啟的其他未儲存編輯。回報時間軸名稱、備註、渲染時間和審查數據。請提及該佔位片段必須保留在其資料夾中，否則鏡頭可能會顯示為離線。
禁止事項及其原因
以下每一項都會耗費大量時間才能發現。詳細資訊請參閱 references/fusion-traps.md；在修改 fusion_lib.py 或遇到問題時，請先閱讀該文件。
- **請勿在建立合成時鎖定合成。**否則片段會渲染為黑色。僅在建立 Loader 時可以鎖定，如同
Shot.loader的做法；否則設定 Loader 的片段會在使用者螢幕上開啟一個強制性的檔案選擇器，從而停止所有腳本執行。 - **請勿使用
ExportCurrentFrameAsStill進行審查。**它會超過 Fusion 的處理速度，回傳黑色或過時的畫面。frame_grid使用Timeline.ExportFrame和ExportThumbnails，是可靠的，但僅限於目前時間軸：尚未開啟過的時間軸會在回報成功的同時匯出黑色畫面。 - **請勿疊加動態模糊。**同時對文字自身的移動和攝影機套用模糊會使運算量倍增。僅對攝影機套用模糊，且僅在快速移動時。
- **請勿假設更快的編碼器能解決渲染緩慢的問題。**Fusion 畫面生成通常是瓶頸。在變更設定前請先進行測量。
參考資料
- references/block-map.md：說明 14 種區塊如何轉換以及哪些部分做了近似處理。如果影片使用了 Graph、Counters、Progress、Chain、Prompt、Notes 或 Rewind，或使用者詢問某個鏡頭的相似度，請閱讀此文件。
- references/fusion-traps.md：透過經驗發現的 API 行為，以及如何恢復卡住的 Resolve。