fusion-macro-cli

fusion-macro-cli 从 Fusion 合成中创建 DaVinci Resolve 标题预设（.setting 文件）。它从 .drt / .drp / .setting 文件中提取合成，根据 TOML 声明组装 .setting 文件，对其进行检查，在 Resolve 中将其渲染为 PNG，并将 Templates 目录归档为 .drfx。

该工具不做的事情：重现 Fusion 渲染（PNG 来自 Resolve 的 preview 命令）；决定发布什么或如何命名（这些在声明中定义）；决定制作多少个预设（一份声明生成一个 .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 即可运行。

在 Fusion 页面打开一个真实的合成后，获取一次模式文件（每个 Resolve 版本一次）：

fusion-macro-cli schema dump

如果没有模式文件，show、check、fix、apply、pack 命令仍可运行，但需要模式文件的规则将被跳过（输出 skipped rule (no schema): ...），并且 show 命令无法比较默认值或拆分控件。

工作流程

work/
  0003_title.comp   提取的输出；编辑此文件
  0003_title.toml   声明文件

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

阶段	输入	输出	备注
`schema dump`	—	模式文件	每个 Resolve 版本一次
`extract`	`.drt` / `.drp` / `.setting`	`.comp`
`declare`	`.setting`	`.toml`	从现有预设创建相同形式的声明，用于重建它
编辑 `.comp` 文件	`.comp`	`.comp`	在 `.comp` 文件中编辑值、表达式、`UserControls` 和工具名称
`check <comp>` / `fix <comp>`	`.comp`	违规项列表 / `.comp`	在创建宏之前修复违规
`show <comp>`	`.comp`	标准输出	发布候选，附带模式信息
编写声明文件	—	`.toml`	首先选择形式
`apply`	`.comp` + `.toml`	`.setting`	内部运行 `check`，如有违规则不写入文件
`show <setting>`	`.setting`	标准输出	发布结果（宏形式）或保存的工具的输入（工具形式）
`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 列出同一控件的其他输入， IC_NAME 是省略 label 时检查器显示的名称。等于默认值的输入仅被计数；使用 --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]]                     # 至少一个；至少一个输出必须为图像
tool = "Merge1"                # 端口默认为 "Output"

[[publish]]                    # order = 检查器顺序
tool = "Template"
input = "StyledText"
label = "Text"                 # 省略以显示模式的控件名称 (IC_NAME)

[[publish]]
tool = "Template"
input = "Red1Clone"
label = "Color"                # 仅将标签放在控件的头部

[[publish]]
tool = "Template"
input = "Green1Clone"

[[publish]]
tool = "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 输入引用为 <tool>.<input>。裸标识符可能会解析为工具内部的名称；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。违规信息格式为 <path>: <rule> <location>: <message>；在 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），并将 <name>.png 写入到 .setting 文件旁边；此 PNG 即为预设缩略图。默认情况下，缩略图会裁剪为渲染内容加上 10% 的边距（--framing content），因此帧边缘附近的标题仍会填充缩略图。当帧内的位置重要时，请使用 --framing frame。对于文本样式预设（工具形式，一个 Text+），请传递 --sample-text Ag --sample-size 0.5 以在固定大小下渲染文本样本，而不是使用预设本身的文本；此时裁剪默认为 frame，以便样本保持可比性。 --frame N 会写入 <name>_f<N>.png。--sample-text [TEXT] 会使用替换了文本 Ag 或 TEXT 的工具形式 TextPlus 渲染文本样本。它会留下一个名为 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：两种形式、声明格式以及键、ControlGroup、Pa 的说明

…（原文被截断）

达芬奇 Fusion 片头