Titres Fusion Resolve

fusion-macro-cli

fusion-macro-cli crée des préréglages de titres DaVinci Resolve (.setting) à partir de compositions Fusion. Il extrait des compositions de fichiers .drt / .drp / .setting, assemble un fichier .setting à partir d'une déclaration TOML, vérifie ce fichier, le rend dans Resolve en PNG, et archive un répertoire Templates en un fichier .drfx.

Ce que l'outil ne fait pas : reproduire le rendu Fusion (les PNG proviennent de Resolve via preview) ; décider quoi publier ou comment le nommer (cela se fait dans la déclaration) ; décider combien de préréglages créer (une déclaration produit un fichier .setting) ; classer plusieurs compositions (agrégez la sortie show vous-même) ; enregistrer le fichier .drfx dans Resolve (l'utilisateur le remplace et redémarre Resolve).

Termes

• Outil : un nœud dans une composition. Il a un type (TextPlus, Background, ...) et un nom. Les noms sont uniques dans toute la composition, y compris à l'intérieur des macros.
• Entrée : un paramètre d'un outil. Il contient une valeur, une expression ou une connexion de modificateur.
• Contrôle : un ensemble d'entrées affiché sous forme d'un widget dans l'inspecteur, par exemple Red1 Green1 Blue1 Alpha1 de TextPlus.
• Macro : un MacroOperator. Il contient des outils et expose les entrées sélectionnées sous forme d'InstanceInput.
• Publier : exposer une entrée à l'extérieur de la macro en tant qu'InstanceInput.
• Forme : la forme d'un fichier .setting. Les deux formes ont exactement un outil au niveau supérieur.
  • Forme macro : l'outil est un MacroOperator qui encapsule les outils du fichier .comp. L'inspecteur n'affiche que les entrées publiées, avec les noms de la déclaration.
  • Forme outil : l'outil est un outil du fichier .comp (généralement un TextPlus), sauvegardé tel quel. L'inspecteur est celui de l'outil lui-même, avec toutes ses entrées.
• Schéma : les définitions d'entrée et de sortie de chaque type d'outil, obtenues depuis Fusion avec schema dump.
• Déclaration : le fichier TOML qui indique la forme et, pour la forme macro, ce qui doit être publié.
• Répertoire Templates : un répertoire avec Edit/ directement en dessous et la structure Edit/Titles/<catégorie>/..., la même structure que Templates/ de Fusion.

Vérifier l'installation

fusion-macro-cli --help

Si la commande est manquante, installez-la avec l'un des outils uv, pipx ou pip disponibles (Python 3.11 ou ultérieur, sans dépendances) :

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 et preview utilisent l'API de script de DaVinci Resolve Studio. Avant de les exécuter, demandez à l'utilisateur de démarrer Resolve Studio et d'activer les scripts externes dans les Préférences. Resolve Free ne peut pas utiliser les scripts externes ; avec Free, passez --console et demandez à l'utilisateur de coller la ligne imprimée dans la console de la page Fusion après avoir basculé sa langue sur Py3. Toutes les autres commandes fonctionnent sans Resolve.

Obtenez le schéma une fois par version de Resolve, avec une composition réelle ouverte sur la page Fusion :

fusion-macro-cli schema dump

Sans schéma, les commandes show, check, fix, apply, pack s'exécutent toujours, mais les règles qui ont besoin du schéma sont ignorées (règle ignorée (pas de schéma) : ...) et show ne peut pas comparer avec les valeurs par défaut ni diviser les contrôles.

Flux

work/
  0003_title.comp   sortie de extract ; modifiez ce fichier
  0003_title.toml   la déclaration

<Templates>/Edit/Titles/<catégorie>/
  title_blue.setting   sortie de apply -o
  title_blue.png       sortie de preview

Étape	Entrée	Sortie	Notes
schema dump	—	schéma	Une fois par version de Resolve
extract	.drt / .drp / .setting	.comp
declare	.setting	.toml	Crée une déclaration de la même forme à partir d'un préréglage existant lors de sa reconstruction
Modifier le fichier .comp	.comp	.comp	Les valeurs, expressions, UserControls et noms d'outils sont modifiés dans le fichier .comp
check <comp> / fix <comp>	.comp	violations / .comp	Réparez les violations avant de créer la macro
show <comp>	.comp	stdout	Candidats à la publication, avec le schéma
Écrire la déclaration	—	.toml	Choisissez d'abord la forme
apply	.comp + .toml	.setting	Exécute check en interne et n'écrit rien en cas de violations
show <setting>	.setting	stdout	Le résultat publié (forme macro) ou les entrées de l'outil sauvegardé (forme outil)
preview	.setting	PNG et une timeline	L'utilisateur vérifie le rendu et l'inspecteur visuellement dans Resolve
pack	répertoire Templates	.drfx	Archive uniquement ce qui passe les vérifications

1. Extraire la composition

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

Pour reconstruire un préréglage existant, créez le fichier .comp et la déclaration à partir du fichier .setting. Les deux fonctionnent pour les deux formes. À partir d'une forme macro, le fichier .comp extrait ne contient pas les Inputs, Outputs ou le nom de la macro ; declare les écrit dans la déclaration. À partir d'une forme outil, le fichier .comp contient l'outil sauvegardé avec son nom et est nommé d'après le fichier .setting ; declare écrit form = "tool" et le nom de l'outil.

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

2. Vérifier, réparer et lister les candidats

fusion-macro-cli check work/0003_title.comp
fusion-macro-cli fix work/0003_title.comp            # écrase ; -o <rép> écrit ailleurs
fusion-macro-cli show work/0003_title.comp

check, fix, show acceptent plusieurs chemins et répertoires à la fois (fusion-macro-cli check work/ other.setting).

Un fichier .comp extrait d'un fichier .drt contient généralement les MediaIn et MediaOut ajoutés par Resolve ainsi que des images clés à la position de la timeline. fix répare les violations qui ont une procédure de réparation (no-media-io, keyframe-origin, et autres). Les violations restantes sont traitées en modifiant le fichier .comp. Après que fix a supprimé MediaIn, les connexions qui en proviennent deviennent des violations no-dangling ; reconnectez-les dans le fichier .comp si elles avaient une source réelle.

Si le fichier .comp contient un MacroOperator, exécutez show avant fix : fix aplatit la macro (no-macro) et supprime ses Inputs et Outputs. Une Expression d'InstanceInput n'a pas sa place dans le fichier .comp ; reportez-la dans l'expression de la déclaration.

show <comp> liste, par outil, les entrées qui peuvent être définies de l'extérieur : HEAD marque la tête d'un contrôle, SIBLINGS liste les autres entrées du même contrôle, et IC_NAME est le nom que l'inspecteur affiche lorsque label est omis. Les entrées égales à leurs valeurs par défaut sont seulement comptées ; --all les liste.

3. Modifier le fichier .comp

Les valeurs, expressions, UserControls et noms d'outils sont modifiés dans le fichier .comp. La déclaration ne contient que la forme et les informations manquantes dans le fichier .comp : pour la forme macro, les entrées publiées, les sorties de la macro et le nom de la macro ; pour la forme outil, l'outil à sauvegarder. Pour les préréglages qui diffèrent uniquement par les valeurs, comme les variantes de couleur, copiez le fichier .comp, modifiez les valeurs et écrivez une déclaration pour chaque copie. Pour changer les couleurs au sein d'un même préréglage, ajoutez une entrée ComboControl (telle que ColorSelect) aux UserControls et calculez la couleur dans l'expression de la couleur publiée à partir de la sélection.

4. Choisir la forme et écrire la déclaration

Choisissez la forme en fonction de ce dont le préréglage a besoin :

• Forme macro lorsque l'inspecteur doit afficher uniquement certaines entrées, avec des noms de votre choix (étiquettes en japonais, un sélecteur de couleur piloté par une combo ColorSelect, ...), ou lorsque le préréglage combine plusieurs outils (TextPlus avec Background et Merge, des modificateurs, ...).
• Forme outil lorsqu'un seul outil rend l'ensemble du préréglage et que son inspecteur standard est ce que l'utilisateur doit modifier, par exemple un style de texte qui n'est qu'un TextPlus avec des polices, couleurs et ombrages définis. La forme outil n'a pas d'entrées publiées, donc la majeure partie des conseils ci-dessous sur le choix des entrées ne s'applique pas ; les règles pour les outils s'exécutent toujours.

Une déclaration de forme outil :

name = "01 Blue Subtitle"      # nom du fichier de sortie
source = "0001_01 Blue Subtitle.comp"
form = "tool"
tool = "Template"              # l'outil du fichier .comp à sauvegarder ; il conserve ce nom

Seul l'outil nommé est écrit. Une connexion de celui-ci vers un autre outil du fichier .comp est signalée comme no-dangling ; utilisez la forme macro si le préréglage nécessite plus d'un outil.

Une déclaration de forme macro :

name = "title_blue"            # nom de la macro et nom du fichier de sortie
source = "0003_title.comp"     # relatif à la déclaration
form = "macro"                 # valeur par défaut lorsqu'omise

[[output]]                     # au moins une ; au moins une sortie doit être une image
tool = "Merge1"                # port par défaut sur "Output"

[[publish]]                    # ordre = ordre dans l'inspecteur
tool = "Template"
input = "StyledText"
label = "Texte"                # omettre pour afficher le nom de contrôle du schéma (IC_NAME)

[[publish]]
tool = "Template"
input = "Red1Clone"
label = "Couleur"              # mettre le label uniquement sur la tête d'un contrôle

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

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

Laissez page à sa valeur par défaut Controls ; toute autre valeur viole page-controls. expression est une expression sur l'InstanceInput elle-même, utilisée lorsque le contrôle suit une autre entrée publiée (comme ColorSelect).

Dans la forme macro, choisissez les entrées à publier comme suit. Une entrée publiée est affichée et modifiable dans l'inspecteur uniquement si ces conditions sont remplies.

• Couleurs (ColorControl) : publiez le rouge, le vert et le bleu, en commençant par la tête du contrôle. L'alpha peut être omis. Publier seulement certaines d'entre elles affiche un nuancier qui ne peut pas être modifié. Pour publier uniquement l'opacité, ajoutez une entrée SliderControl aux UserControls et pilotez l'alpha avec une expression.
• Éléments multiples de TextPlus : TextPlus a Red<n> Thickness<n> et autres pour chaque élément d'ombrage (remplissage, contour, ombre, ...) et n'affiche que les entrées de l'élément sélectionné par SelectElement (élément sélectionné = valeur de SelectElement + 1 ; élément 1 si absent). Les entrées publiées suivent la même règle, donc une entrée d'un élément non sélectionné n'est pas affichée.
  • Pour les couleurs de l'élément 1, publiez Red1Clone Green1Clone Blue1Clone (et Alpha1Clone si nécessaire). Elles sont affichées quelle que soit la sélection, et leurs valeurs atteignent Red1 et les autres.
  • Pour afficher également les entrées de l'élément 2 ou suivants, ajoutez des entrées aux UserControls de l'outil dans le fichier .comp, écrivez des expressions sur les entrées de l'élément qui prennent les valeurs de ces entrées, et publiez les entrées des UserControls. Publier directement les entrées d'un élément n'affiche qu'un seul élément par TextPlus.
• Groupes repliables (NestControl, comme Softness<n> de TextPlus) : publiez les entrées enfants (SoftnessX<n> SoftnessY<n>), pas le groupe. Un groupe publié affiche un en-tête "∨" vide et absorbe le contrôle suivant.
• Entrées pilotées par expression : ne les publiez pas ; l'expression fournit la valeur, donc les modifications n'atteignent pas le rendu. Ajoutez une entrée UserControls, publiez-la et référencez-la dans l'expression.
• Entrées connectées : une entrée alimentée par la sortie d'un autre outil est affichée avec un bouton d'image clé rouge. Publiez plutôt l'entrée du modificateur source (pour TextPlus.StyledText alimenté par StyledTextCLS, publiez le Text du modificateur).
• Expressions : référencez une entrée UserControls comme <outil>.<entrée>. Un identifiant nu peut se résoudre en un nom interne à l'outil ; preview signale ces incohérences avec un code de sortie 1, et check ne peut pas les détecter.

5. Appliquer

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

--dry-run affiche le résultat de la vérification et la sortie show du résultat sans écrire. En cas de violations, apply n'écrit rien et se termine avec le code 1. Les violations s'impriment comme <chemin> : <règle> <emplacement> : <message> ; recherchez la règle dans references/rules.md. Corrigez la cause dans le fichier .comp ou la déclaration et appliquez à nouveau.

6. Afficher et prévisualiser

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

preview rend la dernière image de l'élément inséré à 103×58 et écrit <nom>.png à côté du fichier .setting ; ce PNG est la vignette du préréglage. Par défaut, la vignette est recadrée sur le contenu rendu plus une marge de 10% (--framing content), de sorte qu'une légende près du bord du cadre remplit toujours la vignette. Utilisez --framing frame lorsque la position dans le cadre est importante. Pour les préréglages de style de texte (forme outil, un seul Text+), passez --sample-text Ag --sample-size 0.5 pour rendre un échantillon de police à une taille fixe au lieu du texte propre du préréglage ; le cadrage par défaut devient alors frame pour que les échantillons restent comparables. --frame N écrit <nom>_f<N>.png. --sample-text [TEXTE] rend un échantillon de police d'un TextPlus de forme outil avec le texte remplacé par Ag ou TEXTE. Il laisse une timeline nommée fusion-macro-cli preview AAAA-MM-JJ HHMMSS.

Une vérification check réussie et un PNG écrit ne prouvent pas que le préréglage est correct : la vérification seule ne peut pas confirmer que les entrées sont affichées et modifiables. Demandez à l'utilisateur d'examiner le rendu et l'inspecteur sur la timeline laissée par preview, et ne signalez pas le préréglage comme correct avant que l'utilisateur ne le confirme.

7. Empaqueter

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

pack vérifie chaque fichier .comp et .setting sous Edit/ et écrit l'archive uniquement s'il n'y a aucune violation. Après avoir remplacé un fichier .drfx, l'utilisateur doit redémarrer Resolve ; Resolve met en cache la liste des titres et ne la relit qu'au redémarrage.

Codes de sortie

0 succès ; 1 violations, une erreur de fichier ou un échec dans Resolve ; 2 arguments invalides.

Ressources supplémentaires

Lisez ce qui suit lorsque la tâche nécessite des détails :

• references/commands.md : entrée, sortie, options, comportement et codes de sortie de chaque commande
• references/declaration.md : les deux formes, le format de déclaration et comment les clés, ControlGroup, `Pa...

… [tronqué pour la traduction]