fusion-macro-cli

fusion-macro-cli は、Fusion コンポジションから DaVinci Resolve のタイトルプリセット (.setting) を作成します。 .drt / .drp / .setting からコンポジションを抽出し、TOML 宣言から .setting を組み立て、チェックし、Resolve で PNG にレンダリングし、Templates ディレクトリを .drfx にアーカイブします。

このツールが行わないこと: Fusion レンダリングの再現（PNG は preview を通じて Resolve から取得します）; 何を公開するか、どのように名前を付けるかの決定（それは宣言で行います）; いくつのプリセットを作成するかの決定（1つの宣言で1つの .setting が作成されます）; 多くのコンポジションの分類（show の出力を自分で集約してください）; Resolve での .drfx の登録（ユーザーがそれを置き換えて Resolve を再起動します）。

用語

ツール: コンポジション内のノード。タイプ（TextPlus、Background、...）と名前を持ちます。名前はマクロ内も含め、コンポジション全体で一意です。
入力: ツールのパラメータ。値、式、またはモディファイア接続を保持します。
コントロール: インスペクタで1つのウィジェットとして表示される入力のセット。例えば TextPlus の Red1 Green1 Blue1 Alpha1。
マクロ: MacroOperator。ツールを含み、選択した入力を InstanceInput として公開します。
公開: 入力をマクロの外に InstanceInput として公開します。
フォーム: .setting の形状。どちらのフォームもトップレベルにちょうど1つのツールを持ちます。
- マクロフォーム: ツールは .comp のツールをラップする MacroOperator です。インスペクタには、宣言からの名前を持つ公開された入力のみが表示されます。
- ツールフォーム: ツールは .comp の1つのツール（通常は TextPlus）で、そのまま保存されます。インスペクタはそのツール自身のインスペクタであり、すべての入力が表示されます。
スキーマ: 各ツールタイプの入力と出力の定義。Fusion から schema dump で取得します。
宣言: フォームと、マクロフォームの場合は何を公開するかを示す TOML。
Templates ディレクトリ: 直下に Edit/ があり、構造が Edit/Titles/<カテゴリ>/... であるディレクトリ。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 バージョンごとに一度だけスキーマを取得します。Fusion ページで実際のコンポジションを開いた状態で:

fusion-macro-cli schema dump

スキーマがない場合でも、show check fix apply pack は実行されますが、スキーマを必要とするルールはスキップされ（skipped rule (no schema): ...）、show はデフォルトとの比較やコントロールの分割ができません。

フロー

work/
  0003_title.comp   extract の出力; このファイルを編集します
  0003_title.toml   宣言

<Templates>/Edit/Titles/<カテゴリ>/
  title_blue.setting   apply -o の出力
  title_blue.png       preview の出力

ステージ	入力	出力	注記
`schema dump`	—	schema	Resolve バージョンごとに一度だけ
`extract`	`.drt` / `.drp` / `.setting`	`.comp`
`declare`	`.setting`	`.toml`	既存のプリセットを再構築する際に、同じフォームの宣言を作成します
`.comp` の編集	`.comp`	`.comp`	値、式、`UserControls`、ツール名は `.comp` で編集します
`check <comp>` / `fix <comp>`	`.comp`	違反 / `.comp`	マクロを作成する前に違反を修復します
`show <comp>`	`.comp`	stdout	スキーマを使用した公開候補
宣言の作成	—	`.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 は同じコントロールの他の入力をリストし、 IC_NAME は label が省略された場合にインスペクタが表示する名前です。デフォルトと等しい入力はカウントされるだけです。--all でリストされます。

3. `.comp` の編集

値、式、UserControls、ツール名は .comp で編集します。宣言はフォームと、.comp に欠けている情報のみを保持します: マクロフォームの場合は公開された入力、マクロ出力、マクロ名。ツールフォームの場合は保存するツールです。色のバリエーションなど値のみが異なるプリセットの場合は、.comp をコピーし、値を変更し、コピーごとに宣言を作成します。 1つのプリセット内で色を切り替えるには、UserControls に ComboControl 入力（ColorSelect など）を追加し、公開された色の expression で選択から色を計算します。

4. フォームの選択と宣言の作成

プリセットの要件に基づいてフォームを選択します:

マクロフォーム: インスペクタに一部の入力のみを表示し、独自の名前を付けたい場合（日本語ラベル、ColorSelect コンボによって駆動されるカラーピッカーなど）、またはプリセットが複数のツールを組み合わせる場合（Background と Merge を伴う TextPlus、モディファイアなど）。
ツールフォーム: 1つのツールがプリセット全体をレンダリングし、その標準のインスペクタをユーザーが編集するのが適切な場合。例えば、フォント、色、シェーディングが設定された TextPlus のみのテキストスタイル。ツールフォームには公開された入力がないため、以下の入力選択に関するガイダンスのほとんどは該当しません。ツールに関するルールは引き続き実行されます。

ツールフォームの宣言:

name = "01 Blue Subtitle"      # 出力ファイル名
source = "0001_01 Blue Subtitle.comp"
form = "tool"
tool = "Template"              # 保存する .comp のツール; この名前を維持します

名前付きツールのみが書き込まれます。コンポジション内の別のツールへの接続は no-dangling として報告されます。プリセットに複数のツールが必要な場合はマクロフォームを使用してください。

マクロフォームの宣言:

name = "title_blue"            # マクロ名と出力ファイル名
source = "0003_title.comp"     # 宣言からの相対パス
form = "macro"                 # 省略時のデフォルト

[[output]]                     # 少なくとも1つ; 少なくとも1つの出力はイメージである必要があります
tool = "Merge1"                # ポートはデフォルトで "Output" になります

[[publish]]                    # 順序 = インスペクタの順序
tool = "Template"
input = "StyledText"
label = "テキスト"              # 省略するとスキーマのコントロール名 (IC_NAME) が表示されます

[[publish]]
tool = "Template"
input = "Red1Clone"
label = "色"                   # ラベルはコントロールの先頭にのみ付けます

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

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

page はデフォルトの Controls のままにしておきます。それ以外の値は page-controls に違反します。 expression は InstanceInput 自体の式であり、別の公開入力（ColorSelect など）に従うコントロールの場合に使用します。

マクロフォームでは、以下のように公開する入力を選択します。公開された入力は、以下の条件が満たされた場合にのみインスペクタに表示され、編集可能です。

色 (ColorControl): コントロールの先頭から赤、緑、青を公開します。アルファは省略可能です。一部のみを公開すると、編集できないスウォッチが表示されます。不透明度のみを公開するには、UserControls に SliderControl 入力を追加し、アルファに式を設定します。
マルチエレメント TextPlus: TextPlus には各シェーディング要素（塗り、アウトライン、シャドウなど）ごとに Red<n> Thickness<n> などがあり、SelectElement で選択された要素の入力のみを表示します（選択された要素 = SelectElement 値 + 1; 存在しない場合は要素1）。公開された入力も同じルールに従うため、選択されていない要素の入力は表示されません。
- 要素1の色の場合、Red1Clone Green1Clone Blue1Clone（必要に応じて Alpha1Clone）を公開します。これらは選択に関係なく表示され、その値は Red1 などに反映されます。
- 要素2以降の入力も表示するには、.comp のツールの UserControls に入力を追加し、要素の入力にそれらの値を取る式を書き、UserControls の入力を公開します。要素の入力を直接公開すると、TextPlus ごとに1つの要素のみが表示されます。
折りたたみ可能グループ (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/<カテゴリ>"

--dry-run は、チェック結果と結果の show 出力を表示しますが、書き込みは行いません。違反がある場合、apply は何も書き込まず、終了コード1で終了します。違反は <パス>: <ルール> <場所>: <メッセージ> として出力されます。references/rules.md でルールを確認してください。.comp または宣言で原因を修正し、再度適用してください。

6. 表示とプレビュー

fusion-macro-cli show "<Templates>/Edit/Titles/<カテゴリ>/title_blue.setting"
fusion-macro-cli preview "<Templates>/Edit/Titles/<カテゴリ>/title_blue.setting"

preview は、挿入されたアイテムの最後のフレームを 103×58 でレンダリングし、.setting の隣に <name>.png を書き込みます。この PNG がプリセットのサムネイルになります。デフォルトでは、サムネイルはレンダリングされたコンテンツに10%のマージンを加えたものにクロップされます（--framing content）。そのため、フレームの端近くにあるキャプションでもサムネイルが埋まります。フレーム内の位置が重要な場合は --framing frame を使用してください。テキストスタイルのプリセット（ツールフォーム、1つのText+）の場合、--sample-text Ag --sample-size 0.5 を渡すと、プリセット自身のテキストの代わりに固定サイズでタイプサンプルをレンダリングします。フレーミングはデフォルトで frame になり、サンプル同士が比較可能になります。 --frame N は <name>_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: 2つのフォーム、宣言形式、およびキー、ControlGroup、`Pa...

Resolve Fusion タイトル