fusion-macro-cli

fusion-macro-cli 可從 Fusion 合成中製作 DaVinci Resolve 標題預設 (.setting)。它可從 .drt / .drp / .setting 中提取合成、根據 TOML 宣告組裝 .setting、進行檢查、在 Resolve 中將其渲染為 PNG，並將 Templates 目錄打包成 .drfx。

此工具不做的事：重現 Fusion 渲染（PNG 來自透過 preview 啟動的 Resolve）；決定發布內容或命名方式（這些在宣告中定義）；決定要製作多少個預設（一個宣告產生一個 .setting）；分類多個合成（請自行彙總 show 輸出）；在 Resolve 中註冊 .drfx（使用者需自行替換並重啟 Resolve）。

術語

工具 (Tool)：合成中的一個節點。它有一個類型（TextPlus、Background 等）和一個名稱。名稱在整個合成中是唯一的，包括在巨集內部。
輸入 (Input)：工具的一個參數。它包含一個值、一個表達式或一個修飾器連線。
控制項 (Control)：在檢查器中顯示為一個小工具的一組輸入，例如 TextPlus 的 Red1 Green1 Blue1 Alpha1。
巨集 (Macro)：一個 MacroOperator。它包含工具並將選定的輸入暴露為 InstanceInput。
發布 (Publish)：將輸入作為 InstanceInput 暴露到巨集外部。
形式 (Form)：.setting 的形狀。兩種形式在最頂層都只有一個工具。
- 巨集形式 (Macro form)：工具是一個 MacroOperator，它包裝了 .comp 的工具。檢查器只顯示已發布的輸入，並使用宣告中的名稱。
- 工具形式 (Tool form)：工具是 .comp 中的一個工具（通常是 TextPlus），保持原樣儲存。檢查器是該工具自身的檢查器，顯示所有輸入。
Schema：每個工具類型的輸入和輸出定義，透過 Fusion 的 schema dump 取得。
宣告 (Declaration)：定義形式以及（如為巨集形式）要發布什麼的 TOML 檔案。
Templates 目錄：一個目錄，其下直接包含 Edit/，並具有 Edit/Titles/<category>/... 的結構，與 Fusion 的 Templates/ 結構相同。

檢查安裝

fusion-macro-cli --help

如果缺少此命令，請使用可用的 uv、pipx 或 pip（Python 3.11 或更高版本，無依賴項）安裝：

uv tool install git+https://github.com/GeniusJunP/fusion-macro-cli
pipx install git+https://github.com/GeniusJunP/fusion-macro-cli
pip install git+https://github.com/GeniusJunP/fusion-macro-cli

schema dump 和 preview 使用 DaVinci Resolve Studio 的腳本 API。在執行它們之前，請要求使用者啟動 Resolve Studio 並在偏好設定中啟用外部腳本。 Resolve Free 無法使用外部腳本；如果使用 Free 版本，請傳遞 --console 並要求使用者將列印的行貼到 Fusion 頁面控制台中（需先將其語言切換為 Py3）。所有其他命令無需 Resolve 即可執行。

請在 Resolve 版本中取得一次 schema，並在 Fusion 頁面上開啟一個真實的合成：

fusion-macro-cli schema dump

如果沒有 schema，show、check、fix、apply、pack 仍然可以執行，但需要 schema 的規則將被跳過（跳過規則 (無 schema): ...），且 show 無法與預設值進行比較或拆分控制項。

流程

work/
  0003_title.comp   extract 的輸出；編輯此檔案
  0003_title.toml   宣告

<Templates>/Edit/Titles/<category>/
  title_blue.setting   apply -o 的輸出
  title_blue.png       preview 的輸出

階段	輸入	輸出	備註
`schema dump`	—	schema	每個 Resolve 版本一次
`extract`	`.drt` / `.drp` / `.setting`	`.comp`
`declare`	`.setting`	`.toml`	從現有預設製作相同形式的宣告（重建時使用）
編輯 `.comp`	`.comp`	`.comp`	在 `.comp` 中編輯值、表達式、`UserControls` 和工具名稱
`check <comp>` / `fix <comp>`	`.comp`	違規 / `.comp`	在製作巨集前修復違規
`show <comp>`	`.comp`	stdout	發布候選項（含 schema）
撰寫宣告	—	`.toml`	首先選擇形式
`apply`	`.comp` + `.toml`	`.setting`	內部執行 `check`，如有違規則不寫入任何內容
`show <setting>`	`.setting`	stdout	已發布的結果（巨集形式）或儲存工具的輸入（工具形式）
`preview`	`.setting`	PNG 和時間線	使用者在 Resolve 中目視檢查渲染和檢查器
`pack`	`Templates` 目錄	`.drfx`	只打包通過檢查的內容

1. 提取合成

fusion-macro-cli extract project.drt -o work/        # → work/0003_title.comp

若要重建現有預設，請從 .setting 製作 .comp 和宣告。兩種形式都適用。從巨集形式中，提取的 .comp 不包含巨集的 Inputs、Outputs 或名稱；declare 將它們寫入宣告。從工具形式中，.comp 包含儲存工具及其名稱，並以 .setting 檔案命名；declare 寫入 form = "tool" 和工具名稱。

fusion-macro-cli extract old.setting -o work/
fusion-macro-cli declare old.setting -o work/old.toml --source 0001_old.comp

2. 檢查、修復和列出候選項

fusion-macro-cli check work/0003_title.comp
fusion-macro-cli fix work/0003_title.comp            # 覆寫；-o <dir> 寫入其他位置
fusion-macro-cli show work/0003_title.comp

check、fix、show 可以一次接受多個路徑和目錄（fusion-macro-cli check work/ other.setting）。

從 .drt 提取的 .comp 通常包含 Resolve 添加的 MediaIn 和 MediaOut，以及時間線位置的關鍵影格。 fix 會修復那些有修復程序的違規（no-media-io、keyframe-origin 等）。剩餘的違規則透過編輯 .comp 處理。 fix 移除 MediaIn 後，來自它的連線會變成 no-dangling 違規；如果它們有真實來源，請在 .comp 中重新連線。

如果 .comp 包含 MacroOperator，請在 fix 之前執行 show：fix 會扁平化巨集（no-macro）並刪除其 Inputs 和 Outputs。 InstanceInput Expression 在 .comp 中沒有位置；請將其帶入宣告的 expression 中。

show <comp> 會按工具列出可以從外部設定的輸入：HEAD 標記控制項的開頭，SIBLINGS 列出同一控制項的其他輸入，當省略 label 時，IC_NAME 是檢查器中顯示的名稱。等於其預設值的輸入僅會被計數；--all 則會列出它們。

3. 編輯 `.comp`

在 .comp 中編輯值、表達式、UserControls 和工具名稱。宣告只包含形式以及 .comp 缺少的資訊：對於巨集形式，是已發布的輸入、巨集輸出和巨集名稱；對於工具形式，則是要儲存的工具。對於僅值不同的預設（例如顏色變體），複製 .comp，變更值，並為每個副本撰寫一個宣告。要在一個預設內切換顏色，請在 UserControls 中添加一個 ComboControl 輸入（例如 ColorSelect），並在已發布顏色的 expression 中根據選擇計算顏色。

4. 選擇形式並撰寫宣告

根據預設的需求選擇形式：

巨集形式：當檢查器應僅顯示部分輸入，並使用您選擇的名稱（日文標籤、由 ColorSelect 組合驅動的顏色選擇器等），或者預設組合了多個工具時（TextPlus 搭配 Background 和 Merge、修飾器等），使用此形式。
工具形式：當一個工具就能渲染整個預設，且其標準檢查器就是使用者應編輯的內容時，例如僅包含 TextPlus 並設定了字體、顏色和陰影的文字樣式。工具形式沒有已發布的輸入，因此以下關於選擇輸入的大部分指南不適用；但工具的規則仍然會執行。

一個工具形式的宣告：

name = "01 Blue Subtitle"      # 輸出檔名
source = "0001_01 Blue Subtitle.comp"
form = "tool"
tool = "Template"              # 要儲存的 .comp 工具；它保留此名稱

只會寫入命名的工具。從它到 .comp 中另一個工具的連線會被報告為 no-dangling；如果預設需要多個工具，請使用巨集形式。

一個巨集形式的宣告：

name = "title_blue"            # 巨集名稱和輸出檔名
source = "0003_title.comp"     # 相對於宣告的路徑
form = "macro"                 # 省略時的預設值

[[output]]                     # 至少一個；至少一個輸出必須是影像
工具 = "Merge1"                # 連接埠預設為 "Output"

[[publish]]                    # 順序 = 檢查器順序
工具 = "Template"
input = "StyledText"
label = "文字"                 # 省略則顯示 schema 的控制項名稱 (IC_NAME)

[[publish]]
工具 = "Template"
input = "Red1Clone"
label = "顏色"                 # 僅在控制項的開頭放置標籤

[[publish]]
工具 = "Template"
input = "Green1Clone"

[[publish]]
工具 = "Template"
input = "Blue1Clone"

將 page 保留其預設值 Controls；任何其他值都會違反 page-controls。 expression 是 InstanceInput 自身的表達式，用於當控制項跟隨另一個已發布的輸入時（例如 ColorSelect）。

在巨集形式中，依下列方式選擇要發布的輸入。僅當以下條件成立時，已發布的輸入才會在檢查器中顯示並可編輯。

顏色 (ColorControl)：發布紅色、綠色和藍色，從控制項的開頭開始。Alpha 可以省略。僅發布其中幾個會顯示一個無法編輯的色樣。若要僅發布不透明度，請在 UserControls 中添加一個 SliderControl 輸入，並使用表達式驅動 alpha。
多元素 TextPlus：TextPlus 對每個著色元素（填充、輪廓、陰影等）都有 Red<n>、Thickness<n> 等，並且只顯示由 SelectElement 選擇的元素輸入（選中元素 = SelectElement 值 + 1；如果不存在則為元素 1）。已發布的輸入遵循相同規則，因此未選中元素的輸入不會顯示。
- 對於元素 1 的顏色，請發布 Red1Clone、Green1Clone、Blue1Clone（以及需要的 Alpha1Clone）。無論選擇如何，它們都會顯示，並且它們的值會影響 Red1 等。
- 若要同時顯示元素 2 或更高元素的輸入，請在 .comp 中為工具添加 UserControls 輸入，在元素輸入上編寫表達式以從它們獲取值，然後發布 UserControls 輸入。直接發布元素輸入只會顯示每個 TextPlus 的一個元素。
可折疊群組 (NestControl，例如 TextPlus 的 Softness<n>)：發布子輸入（SoftnessX<n>、SoftnessY<n>），而不是群組本身。發布的群組會顯示一個空的 "∨" 標題，並吞沒下一個控制項。
表達式驅動的輸入：不要發布它們；表達式提供值，因此編輯不會影響渲染。添加一個 UserControls 輸入，發布它，並在表達式中引用它。
已連線的輸入：由另一個工具輸出饋送的輸入會顯示一個紅色關鍵影格按鈕。請改為發布來源修飾器的輸入（對於由 StyledTextCLS 饋送的 TextPlus.StyledText，請發布修飾器的 Text）。
表達式：將 UserControls 輸入引用為 <工具>.<輸入>。裸識別碼可能解析為工具內部名稱；preview 會報告此類不匹配並返回退出碼 1，而 check 無法檢測到它們。

5. 套用

fusion-macro-cli apply work/0003_title.toml --dry-run
fusion-macro-cli apply work/0003_title.toml -o "<Templates>/Edit/Titles/<category>"

--dry-run 顯示檢查結果和結果的 show 輸出，但不寫入。如果有違規，apply 不會寫入任何內容並返回退出碼 1。違規會列印為 <路徑>: <規則> <位置>: <訊息>；請在 references/rules.md 中查詢規則。修復 .comp 或宣告中的原因，然後再次套用。

6. 顯示和預覽

fusion-macro-cli show "<Templates>/Edit/Titles/<category>/title_blue.setting"
fusion-macro-cli preview "<Templates>/Edit/Titles/<category>/title_blue.setting"

preview 會將插入項目的最後一影格渲染為 103×58，並在 .setting 旁邊寫入 <名稱>.png；此 PNG 即為預設縮圖。預設情況下，縮圖會裁剪為渲染內容加上 10% 的邊距（--framing content），因此靠近影格邊緣的標題仍然會填滿縮圖。當影格內的位置很重要時，請使用 --framing frame。對於文字樣式預設（工具形式，單個 Text+），請傳遞 --sample-text Ag --sample-size 0.5 以固定大小渲染類型樣本，而不是使用預設自身的文字；然後 framing 預設為 frame，以便樣本保持可比性。 --frame N 會寫入 <名稱>_f<N>.png。--sample-text [TEXT] 會渲染工具形式 TextPlus 的類型樣本，並將文字替換為 Ag 或 TEXT。它會留下一條名為 fusion-macro-cli preview YYYY-MM-DD HHMMSS 的時間線。

通過 check 和寫入的 PNG 並不能證明預設是正確的：輸入是否顯示且可編輯無法僅透過 check 確認。請要求使用者查看 preview 留下的時間線上的渲染和檢查器，並在使用者確認之前，不要報告預設是正確的。

7. 打包

fusion-macro-cli pack "<Templates>" -o titles.drfx

pack 會檢查 Edit/ 下的每個 .comp 和 .setting，並僅在沒有違規時才寫入存檔。替換 .drfx 後，使用者必須重啟 Resolve；Resolve 會快取標題列表，並且在重啟之前不會重新讀取。

退出碼

0 成功；1 違規、檔案錯誤或 Resolve 中的失敗；2 無效引數。

其他資源

當任務需要細節時，請閱讀以下內容：

references/commands.md：每個命令的輸入、輸出、選項、行為和退出碼
references/declaration.md：兩種形式、宣告格式以及 keys、ControlGroup、`Pa

…

[因翻譯而截斷]

達芬奇 Fusion 片頭