Resolve-Fusion-Titel

fusion-macro-cli

fusion-macro-cli erstellt DaVinci-Resolve-Titelvoreinstellungen (.setting) aus Fusion-Kompositionen. Es extrahiert Kompositionen aus .drt / .drp / .setting, baut eine .setting aus einer TOML-Deklaration zusammen, überprüft sie, rendert sie in Resolve in ein PNG und archiviert ein Templates-Verzeichnis in eine .drfx.

Was das Tool nicht tut: Fusion-Rendering reproduzieren (PNGs kommen durch preview von Resolve); entscheiden, was veröffentlicht oder wie es benannt wird (das steht in der Deklaration); entscheiden, wie viele Voreinstellungen erstellt werden sollen (eine Deklaration erstellt eine .setting); viele Kompositionen klassifizieren (show-Ausgabe selbst aggregieren); die .drfx in Resolve registrieren (der Benutzer ersetzt sie und startet Resolve neu).

Begriffe

• Tool: ein Knoten in einer Komposition. Es hat einen Typ (TextPlus, Background, ...) und einen Namen. Namen sind in der gesamten Komposition eindeutig, auch innerhalb von Makros.
• Eingabe: ein Parameter eines Tools. Er enthält einen Wert, einen Ausdruck oder eine Modifikatorverbindung.
• Steuerelement: eine Reihe von Eingaben, die im Inspektor als ein Widget angezeigt werden, z. B. Red1 Green1 Blue1 Alpha1 von TextPlus.
• Makro: ein MacroOperator. Es enthält Tools und legt ausgewählte Eingaben als InstanceInput offen.
• Veröffentlichen: eine Eingabe außerhalb des Makros als InstanceInput verfügbar machen.
• Form: die Form einer .setting. Beide Formen haben genau ein Tool auf der obersten Ebene.
  • Makroform: das Tool ist ein MacroOperator, der die Tools der .comp kapselt. Der Inspektor zeigt nur die veröffentlichten Eingaben an, mit den Namen aus der Deklaration.
  • Toolform: das Tool ist ein Tool der .comp (typischerweise ein TextPlus), das so gespeichert wird, wie es ist. Der Inspektor ist der eigene Inspektor dieses Tools mit jeder Eingabe.
• Schema: die Eingabe- und Ausgabedefinitionen jedes Tooltyps, von Fusion mit schema dump bezogen.
• Deklaration: das TOML, das die Form und, für die Makroform, angibt, was veröffentlicht werden soll.
• Templates-Verzeichnis: ein Verzeichnis mit Edit/ direkt darunter und der Struktur Edit/Titles/<category>/..., der gleichen Struktur wie Fusions Templates/.

Installation prüfen

fusion-macro-cli --help

Wenn der Befehl fehlt, installieren Sie ihn mit dem verfügbaren Tool (uv, pipx oder pip, Python 3.11 oder höher, keine Abhängigkeiten):

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 und preview verwenden die Skripting-API von DaVinci Resolve Studio. Bitten Sie den Benutzer, Resolve Studio zu starten und externes Skripting in den Einstellungen zu aktivieren, bevor Sie diese ausführen. Resolve Free kann kein externes Skripting verwenden; bei Free übergeben Sie --console und bitten Sie den Benutzer, die gedruckte Zeile in die Konsole der Fusion-Seite einzufügen, nachdem deren Sprache auf Py3 umgestellt wurde. Alle anderen Befehle funktionieren ohne Resolve.

Holen Sie sich das Schema einmal pro Resolve-Version, während eine echte Komposition auf der Fusion-Seite geöffnet ist:

fusion-macro-cli schema dump

Ohne ein Schema laufen show check fix apply pack trotzdem, aber Regeln, die das Schema benötigen, werden übersprungen (skipped rule (no schema): ...) und show kann weder mit Standardwerten vergleichen noch Steuerelemente aufteilen.

Ablauf

work/
  0003_title.comp   Ausgabe von extract; diese Datei bearbeiten
  0003_title.toml   die Deklaration

<Templates>/Edit/Titles/<category>/
  title_blue.setting   Ausgabe von apply -o
  title_blue.png       Ausgabe von preview

Schritt	Eingabe	Ausgabe	Hinweise
schema dump	—	schema	Einmal pro Resolve-Version
extract	.drt / .drp / .setting	.comp
declare	.setting	.toml	Erstellt eine Deklaration derselben Form aus einer vorhandenen Voreinstellung beim Wiederaufbau
.comp bearbeiten	.comp	.comp	Werte, Ausdrücke, UserControls und Toolnamen werden in der .comp bearbeitet
check <comp> / fix <comp>	.comp	Verstöße / .comp	Verstöße vor der Erstellung des Makros beheben
show <comp>	.comp	stdout	Veröffentlichungskandidaten mit dem Schema
Deklaration schreiben	—	.toml	Zuerst die Form wählen
apply	.comp + .toml	.setting	Führt intern check aus und schreibt nichts, wenn es Verstöße gibt
show <setting>	.setting	stdout	Das veröffentlichte Ergebnis (Makroform) oder die gespeicherten Eingaben des Tools (Toolform)
preview	.setting	PNG und eine Timeline	Der Benutzer überprüft das Rendering und den Inspektor in Resolve visuell
pack	Templates-Verzeichnis	.drfx	Archiviert nur, was die Prüfungen besteht

1. Komposition extrahieren

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

Um eine vorhandene Voreinstellung wieder aufzubauen, erstellen Sie die .comp und die Deklaration aus der .setting. Beides funktioniert für beide Formen. Aus einer Makroform enthält die extrahierte .comp nicht die Inputs, Outputs oder den Namen des Makros; declare schreibt sie in die Deklaration. Aus einer Toolform enthält die .comp das gespeicherte Tool mit seinem Namen und ist nach der .setting-Datei benannt; declare schreibt form = "tool" und den Toolnamen.

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

2. Prüfen, reparieren und Kandidaten auflisten

fusion-macro-cli check work/0003_title.comp
fusion-macro-cli fix work/0003_title.comp            # überschreibt; -o <dir> schreibt woanders hin
fusion-macro-cli show work/0003_title.comp

check fix show akzeptieren mehrere Pfade und Verzeichnisse gleichzeitig (fusion-macro-cli check work/ other.setting).

Eine aus einer .drt extrahierte .comp enthält normalerweise die MediaIn und MediaOut, die Resolve hinzufügt, sowie Keyframes an der Timeline-Position. fix repariert die Verstöße, die einen Reparaturablauf haben (no-media-io, keyframe-origin und andere). Verbleibende Verstöße werden durch Bearbeiten der .comp behoben. Nachdem fix MediaIn entfernt hat, werden Verbindungen davon zu no-dangling-Verstößen; verbinden Sie sie in der .comp neu, wenn sie eine echte Quelle hatten.

Wenn die .comp einen MacroOperator enthält, führen Sie show vor fix aus: fix flacht das Makro ab (no-macro) und löscht seine Inputs und Outputs. Ein InstanceInput Expression hat keinen Platz in der .comp; übertragen Sie ihn in den expression der Deklaration.

show <comp> listet pro Tool die Eingaben auf, die von außen gesetzt werden können: HEAD markiert den Kopf eines Steuerelements, SIBLINGS listet die anderen Eingaben desselben Steuerelements auf, und IC_NAME ist der Name, den der Inspektor anzeigt, wenn label weggelassen wird. Eingaben, die ihren Standardwerten entsprechen, werden nur gezählt; --all listet sie auf.

3. .comp bearbeiten

Werte, Ausdrücke, UserControls und Toolnamen werden in der .comp bearbeitet. Die Deklaration enthält nur die Form und die Informationen, die der .comp fehlen: für die Makroform die veröffentlichten Eingaben, die Makroausgaben und den Makronamen; für die Toolform das zu speichernde Tool. Für Voreinstellungen, die sich nur in Werten unterscheiden, z. B. Farbvarianten, kopieren Sie die .comp, ändern Sie die Werte und schreiben Sie eine Deklaration für jede Kopie. Um Farben innerhalb einer Voreinstellung umzuschalten, fügen Sie eine ComboControl-Eingabe (z. B. ColorSelect) zu UserControls hinzu und berechnen Sie die Farbe im expression der veröffentlichten Farbe aus der Auswahl.

4. Form wählen und Deklaration schreiben

Wählen Sie die Form basierend auf dem, was die Voreinstellung benötigt:

• Makroform, wenn der Inspektor nur einige Eingaben mit von Ihnen gewählten Namen anzeigen soll (japanische Beschriftungen, ein Farbwähler, der von einer ColorSelect-Kombination gesteuert wird, ...), oder wenn die Voreinstellung mehrere Tools kombiniert (TextPlus mit Background und Merge, Modifikatoren, ...).
• Toolform, wenn ein Tool die gesamte Voreinstellung rendert und sein Standardinspektor das ist, was der Benutzer bearbeiten soll, z. B. ein Textstil, der nur ein TextPlus mit Schriftarten, Farben und Schattierungen ist. Die Toolform hat keine veröffentlichten Eingaben, daher trifft der größte Teil der folgenden Anleitung zur Auswahl von Eingaben nicht zu; die Regeln für Tools werden trotzdem ausgeführt.

Eine Toolform-Deklaration:

name = "01 Blue Subtitle"      # Ausgabedateiname
source = "0001_01 Blue Subtitle.comp"
form = "tool"
tool = "Template"              # das zu speichernde Tool der .comp; es behält diesen Namen

Nur das benannte Tool wird geschrieben. Eine Verbindung von ihm zu einem anderen Tool der .comp wird als no-dangling gemeldet; verwenden Sie die Makroform, wenn die Voreinstellung mehr als ein Tool benötigt.

Eine Makroform-Deklaration:

name = "title_blue"            # Makroname und Ausgabedateiname
source = "0003_title.comp"     # relativ zur Deklaration
form = "macro"                 # der Standard, wenn weggelassen

[[output]]                     # mindestens eines; mindestens eine Ausgabe muss ein Bild sein
tool = "Merge1"                # Port standardmäßig "Output"

[[publish]]                    # Reihenfolge = Inspektor-Reihenfolge
tool = "Template"
input = "StyledText"
label = "Text"                 # weglassen, um den Steuerelementnamen des Schemas (IC_NAME) anzuzeigen

[[publish]]
tool = "Template"
input = "Red1Clone"
label = "Color"                # label nur auf den Kopf eines Steuerelements setzen

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

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

Lassen Sie page auf seinem Standard Controls; jeder andere Wert verletzt page-controls. expression ist ein Ausdruck auf dem InstanceInput selbst, der verwendet wird, wenn das Steuerelement einem anderen veröffentlichten Eingabe folgt (z. B. ColorSelect).

In der Makroform wählen Sie die zu veröffentlichenden Eingaben wie folgt aus. Eine veröffentlichte Eingabe wird im Inspektor nur angezeigt und bearbeitet, wenn diese gelten.

• Farben (ColorControl): veröffentlichen Sie Rot, Grün und Blau, beginnend mit dem Kopf des Steuerelements. Alpha kann weggelassen werden. Die Veröffentlichung nur einiger von ihnen zeigt ein Farbfeld, das nicht bearbeitet werden kann. Um nur die Deckkraft zu veröffentlichen, fügen Sie eine SliderControl-Eingabe zu UserControls hinzu und steuern Sie Alpha mit einem Ausdruck.
• Mehrelementiges TextPlus: TextPlus hat Red<n> Thickness<n> und andere für jedes Schattierungselement (Füllung, Kontur, Schatten, ...) und zeigt nur die Eingaben des Elements an, das von SelectElement ausgewählt wurde (ausgewähltes Element = SelectElement-Wert + 1; Element 1, wenn nicht vorhanden). Veröffentlichte Eingaben folgen derselben Regel, daher wird eine Eingabe eines nicht ausgewählten Elements nicht angezeigt.
  • Für die Farben von Element 1 veröffentlichen Sie Red1Clone Green1Clone Blue1Clone (und Alpha1Clone falls benötigt). Sie werden unabhängig von der Auswahl angezeigt und ihre Werte erreichen Red1 und die anderen.
  • Um auch Eingaben von Element 2 oder später anzuzeigen, fügen Sie in der .comp Eingaben zu den UserControls des Tools hinzu, schreiben Sie Ausdrücke auf die Elementeingaben, die die Werte von ihnen übernehmen, und veröffentlichen Sie die UserControls-Eingaben. Das direkte Veröffentlichen von Elementeingaben zeigt nur ein Element pro TextPlus.
• Zusammenklappbare Gruppen (NestControl, wie Softness<n> von TextPlus): veröffentlichen Sie die untergeordneten Eingaben (SoftnessX<n> SoftnessY<n>), nicht die Gruppe. Eine veröffentlichte Gruppe zeigt eine leere „∨“-Überschrift und verschluckt das nächste Steuerelement.
• Ausdrucksgesteuerte Eingaben: veröffentlichen Sie sie nicht; der Ausdruck liefert den Wert, daher erreichen Bearbeitungen das Rendering nicht. Fügen Sie eine UserControls-Eingabe hinzu, veröffentlichen Sie sie und referenzieren Sie sie im Ausdruck.
• Verbundene Eingaben: eine Eingabe, die von der Ausgabe eines anderen Tools gespeist wird, wird mit einer roten Keyframe-Schaltfläche angezeigt. Veröffentlichen Sie stattdessen die Eingabe des Quellmodifikators (für TextPlus.StyledText, das von StyledTextCLS gespeist wird, veröffentlichen Sie den Text des Modifikators).
• Ausdrücke: beziehen Sie sich auf eine UserControls-Eingabe als <tool>.<input>. Ein bloßer Bezeichner kann stattdessen zu einem tool-internen Namen auflösen; preview meldet solche Konflikte mit Exit-Code 1, und check kann sie nicht erkennen.

5. Anwenden

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 zeigt das Prüfergebnis und die show-Ausgabe des Ergebnisses an, ohne zu schreiben. Bei Verstößen schreibt apply nichts und beendet sich mit 1. Verstöße werden ausgegeben als <pfad>: <regel> <ort>: <nachricht>; schlagen Sie die Regel in references/rules.md nach. Beheben Sie die Ursache in der .comp oder der Deklaration und wenden Sie sie erneut an.

6. Anzeigen und Vorschau

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

preview rendert den letzten Frame des eingefügten Elements bei 103×58 und schreibt <name>.png neben die .setting; dieses PNG ist das Vorschaubild der Voreinstellung. Standardmäßig wird das Vorschaubild auf den gerenderten Inhalt plus einen Rand von 10% zugeschnitten (--framing content), sodass eine Bildunterschrift nahe dem Rand des Frames das Vorschaubild dennoch ausfüllt. Verwenden Sie --framing frame, wenn die Position innerhalb des Frames wichtig ist. Für Textstil-Voreinstellungen (Toolform, ein Text+) übergeben Sie --sample-text Ag --sample-size 0.5, um ein Type-Muster in einer festen Größe anstelle des eigenen Texts der Voreinstellung zu rendern; die Rahmung wird dann standardmäßig auf frame gesetzt, sodass Muster vergleichbar bleiben. --frame N schreibt <name>_f<N>.png. --sample-text [TEXT] rendert ein Type-Muster eines Toolform-TextPlus, wobei der Text durch Ag oder TEXT ersetzt wird. Es hinterlässt eine Timeline namens fusion-macro-cli preview YYYY-MM-DD HHMMSS.

Ein bestandenes check und ein geschriebenes PNG beweisen nicht, dass die Voreinstellung richtig ist: ob Eingaben angezeigt und bearbeitet werden, kann von check allein nicht bestätigt werden. Bitten Sie den Benutzer, sich das Rendering und den Inspektor auf der Timeline anzusehen, die preview hinterlassen hat, und melden Sie die Voreinstellung erst dann als korrekt, wenn der Benutzer sie bestätigt hat.

7. Packen

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

pack überprüft jede .comp und .setting unter Edit/ und schreibt das Archiv nur, wenn es keine Verstöße gibt. Nach dem Ersetzen einer .drfx muss der Benutzer Resolve neu starten; Resolve cachet die Titelliste und liest sie erst beim Neustart erneut.

Exit-Codes

0 Erfolg; 1 Verstöße, ein Dateifehler oder ein Fehler in Resolve; 2 ungültige Argumente.

Zusätzliche Ressourcen

Lesen Sie diese, wenn die Aufgabe Details benötigt:

• references/commands.md: Eingabe, Ausgabe, Optionen, Verhalten und Exit-Codes jedes Befehls
• references/declaration.md: die beiden Formen, das Deklarationsformat und wie Schlüssel, ControlGroup, `Pa

…

[für die Übersetzung gekürzt]