Títulos Fusion de Resolve

fusion-macro-cli

fusion-macro-cli crea presets de títulos de DaVinci Resolve (.setting) a partir de composiciones de Fusion. Extrae composiciones de archivos .drt / .drp / .setting, ensambla un .setting a partir de una declaración TOML, lo verifica, lo renderiza en Resolve a un PNG y archiva un directorio Templates en un archivo .drfx.

Lo que la herramienta no hace: reproducir el renderizado de Fusion (los PNG provienen de Resolve a través de preview); decidir qué publicar o cómo nombrarlo (eso va en la declaración); decidir cuántos presets crear (una declaración genera un .setting); clasificar muchas composiciones (agrega la salida de show tú mismo); registrar el .drfx en Resolve (el usuario lo reemplaza y reinicia Resolve).

Términos

• Herramienta: un nodo en una composición. Tiene un tipo (TextPlus, Background, ...) y un nombre. Los nombres son únicos en toda la composición, incluso dentro de macros.
• Entrada: un parámetro de una herramienta. Contiene un valor, una expresión o una conexión de modificador.
• Control: un conjunto de entradas que se muestran como un widget en el inspector, por ejemplo Red1 Green1 Blue1 Alpha1 de TextPlus.
• Macro: un MacroOperator. Contiene herramientas y expone las entradas seleccionadas como InstanceInput.
• Publicar: exponer una entrada fuera de la macro como un InstanceInput.
• Forma: la forma de un .setting. Ambas formas tienen exactamente una herramienta en el nivel superior.
  • Forma de macro: la herramienta es un MacroOperator que envuelve las herramientas del .comp. El inspector muestra solo las entradas publicadas, con los nombres de la declaración.
  • Forma de herramienta: la herramienta es una herramienta del .comp (normalmente un TextPlus), guardada tal cual. El inspector es el propio inspector de esa herramienta, con cada entrada.
• Esquema: las definiciones de entrada y salida de cada tipo de herramienta, obtenidas de Fusion con schema dump.
• Declaración: el TOML que indica la forma y, para la forma de macro, qué publicar.
• Directorio Templates: un directorio con Edit/ directamente debajo y la estructura Edit/Titles/<categoría>/..., la misma estructura que Templates/ de Fusion.

Verificar la instalación

fusion-macro-cli --help

Si falta el comando, instálalo con cualquiera de uv, pipx o pip que esté disponible (Python 3.11 o posterior, sin dependencias):

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 y preview utilizan la API de scripting de DaVinci Resolve Studio. Antes de ejecutarlos, pide al usuario que inicie Resolve Studio y habilite el scripting externo en Preferencias. Resolve Free no puede usar scripting externo; con Free, pasa --console y pide al usuario que pegue la línea impresa en la consola de la página Fusion después de cambiar su idioma a Py3. Todos los demás comandos funcionan sin Resolve.

Obtén el esquema una vez por versión de Resolve, con una composición real abierta en la página Fusion:

fusion-macro-cli schema dump

Sin un esquema, show check fix apply pack aún se ejecutan, pero las reglas que necesitan el esquema se omiten (regla omitida (sin esquema): ...) y show no puede comparar con valores predeterminados ni dividir controles.

Flujo

trabajo/
  0003_title.comp   salida de extract; edita este archivo
  0003_title.toml   la declaración

<Templates>/Edit/Titles/<categoría>/
  title_blue.setting   salida de apply -o
  title_blue.png       salida de preview

Etapa	Entrada	Salida	Notas
schema dump	—	esquema	Una vez por versión de Resolve
extract	.drt / .drp / .setting	.comp
declare	.setting	.toml	Crea una declaración de la misma forma a partir de un preset existente al reconstruirlo
Editar el .comp	.comp	.comp	Los valores, expresiones, UserControls y nombres de herramientas se editan en el .comp
check <comp> / fix <comp>	.comp	violaciones / .comp	Repara las violaciones antes de hacer la macro
show <comp>	.comp	stdout	Candidatos para publicar, con el esquema
Escribir la declaración	—	.toml	Elige primero la forma
apply	.comp + .toml	.setting	Ejecuta check internamente y no escribe nada si hay violaciones
show <setting>	.setting	stdout	El resultado publicado (forma de macro) o las entradas de la herramienta guardada (forma de herramienta)
preview	.setting	PNG y una línea de tiempo	El usuario verifica el renderizado y el inspector visualmente en Resolve
pack	directorio Templates	.drfx	Archiva solo lo que pasa las verificaciones

1. Extraer la composición

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

Para reconstruir un preset existente, crea el .comp y la declaración a partir del .setting. Ambos funcionan para cualquier forma. Desde una forma de macro, el .comp extraído no contiene las Inputs, Outputs o el nombre de la macro; declare los escribe en la declaración. Desde una forma de herramienta, el .comp contiene la herramienta guardada con su nombre y se nombra según el archivo .setting; declare escribe form = "tool" y el nombre de la herramienta.

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

2. Verificar, reparar y listar candidatos

fusion-macro-cli check trabajo/0003_title.comp
fusion-macro-cli fix trabajo/0003_title.comp            # sobrescribe; -o <dir> escribe en otro lugar
fusion-macro-cli show trabajo/0003_title.comp

check fix show aceptan varias rutas y directorios a la vez (fusion-macro-cli check trabajo/ other.setting).

Un .comp extraído de un .drt normalmente contiene los MediaIn y MediaOut que Resolve añade y fotogramas clave en la posición de la línea de tiempo. fix repara las violaciones que tienen un procedimiento de reparación (no-media-io, keyframe-origin y otras). Las violaciones que quedan se manejan editando el .comp. Después de que fix elimine MediaIn, las conexiones desde él se convierten en violaciones no-dangling; reconéctalas en el .comp si tenían una fuente real.

Si el .comp contiene un MacroOperator, ejecuta show antes de fix: fix aplana la macro (no-macro) y elimina sus Inputs y Outputs. Una Expression de InstanceInput no tiene lugar en el .comp; transfiérela a la expression de la declaración.

show <comp> lista, por herramienta, las entradas que se pueden establecer desde fuera: HEAD marca la cabeza de un control, SIBLINGS lista las otras entradas del mismo control y IC_NAME es el nombre que el inspector muestra cuando se omite label. Las entradas iguales a sus valores predeterminados solo se cuentan; --all las lista.

3. Editar el .comp

Los valores, expresiones, UserControls y nombres de herramientas se editan en el .comp. La declaración solo contiene la forma y la información que le falta al .comp: para la forma de macro, las entradas publicadas, las salidas de la macro y el nombre de la macro; para la forma de herramienta, la herramienta a guardar. Para presets que solo difieren en valores, como variantes de color, copia el .comp, cambia los valores y escribe una declaración para cada copia. Para cambiar colores dentro de un solo preset, añade una entrada ComboControl (como ColorSelect) a UserControls y calcula el color en la expression del color publicado a partir de la selección.

4. Elegir la forma y escribir la declaración

Elige la forma según lo que necesite el preset:

• Forma de macro cuando el inspector debe mostrar solo algunas entradas, con nombres que elijas (etiquetas en japonés, un selector de color impulsado por un combo ColorSelect, ...), o cuando el preset combina varias herramientas (TextPlus con Background y Merge, modificadores, ...).
• Forma de herramienta cuando una herramienta renderiza todo el preset y su inspector estándar es lo que el usuario debe editar, como un estilo de texto que es solo un TextPlus con fuentes, colores y sombreado configurados. La forma de herramienta no tiene entradas publicadas, por lo que la mayor parte de la guía a continuación sobre la elección de entradas no aplica; las reglas para las herramientas aún se ejecutan.

Una declaración de forma de herramienta:

name = "01 Blue Subtitle"      # nombre del archivo de salida
source = "0001_01 Blue Subtitle.comp"
form = "tool"
tool = "Template"              # la herramienta del .comp a guardar; conserva este nombre

Solo se escribe la herramienta nombrada. Una conexión desde ella a otra herramienta del .comp se reporta como no-dangling; usa la forma de macro si el preset necesita más de una herramienta.

Una declaración de forma de macro:

name = "title_blue"            # nombre de la macro y nombre del archivo de salida
source = "0003_title.comp"     # relativo a la declaración
form = "macro"                 # el valor predeterminado cuando se omite

[[output]]                     # al menos uno; al menos una salida debe ser una imagen
tool = "Merge1"                # el puerto predeterminado es "Output"

[[publish]]                    # orden = orden en el inspector
tool = "Template"
input = "StyledText"
label = "Text"                 # omítelo para mostrar el nombre del control del esquema (IC_NAME)

[[publish]]
tool = "Template"
input = "Red1Clone"
label = "Color"                # pon label solo en la cabeza de un control

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

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

Deja page con su valor predeterminado Controls; cualquier otro valor viola page-controls. expression es una expresión en el propio InstanceInput, que se usa cuando el control sigue a otra entrada publicada (como ColorSelect).

En la forma de macro, elige las entradas a publicar de la siguiente manera. Una entrada publicada se muestra y se puede editar en el inspector solo cuando se cumplen estas condiciones.

• Colores (ColorControl): publica rojo, verde y azul, comenzando por la cabeza del control. Alfa puede omitirse. Publicar solo algunas de ellas muestra una muestra que no se puede editar. Para publicar solo la opacidad, añade una entrada SliderControl a UserControls y maneja alfa con una expresión.
• TextPlus multielemento: TextPlus tiene Red<n> Thickness<n> y otros para cada elemento de sombreado (relleno, contorno, sombra, ...) y muestra solo las entradas del elemento seleccionado por SelectElement (elemento seleccionado = valor de SelectElement + 1; elemento 1 si está ausente). Las entradas publicadas siguen la misma regla, por lo que una entrada de un elemento no seleccionado no se muestra.
  • Para los colores del elemento 1, publica Red1Clone Green1Clone Blue1Clone (y Alpha1Clone si es necesario). Se muestran independientemente de la selección y sus valores llegan a Red1 y los demás.
  • Para mostrar también entradas del elemento 2 o posteriores, añade entradas a los UserControls de la herramienta en el .comp, escribe expresiones en las entradas del elemento que tomen los valores de ellas y publica las entradas de UserControls. Publicar las entradas del elemento directamente muestra solo un elemento por TextPlus.
• Grupos colapsables (NestControl, como Softness<n> de TextPlus): publica las entradas secundarias (SoftnessX<n> SoftnessY<n>), no el grupo. Un grupo publicado muestra un encabezado "∨" vacío y se traga el siguiente control.
• Entradas impulsadas por expresiones: no las publiques; la expresión proporciona el valor, por lo que las ediciones no llegan al renderizado. Añade una entrada de UserControls, publícala y haz referencia a ella desde la expresión.
• Entradas conectadas: una entrada alimentada por la salida de otra herramienta se muestra con un botón de fotograma clave rojo. Publica la entrada del modificador fuente en su lugar (para TextPlus.StyledText alimentado por StyledTextCLS, publica el Text del modificador).
• Expresiones: refiérete a una entrada de UserControls como <tool>.<input>. Un identificador simple puede resolverse a un nombre interno de la herramienta en su lugar; preview reporta tales discrepancias con código de salida 1, y check no puede detectarlas.

5. Aplicar

fusion-macro-cli apply trabajo/0003_title.toml --dry-run
fusion-macro-cli apply trabajo/0003_title.toml -o "<Templates>/Edit/Titles/<categoría>"

--dry-run muestra el resultado de la verificación y la salida de show del resultado sin escribir. Con violaciones, apply no escribe nada y sale con 1. Las violaciones se imprimen como <ruta>: <regla> <ubicación>: <mensaje>; busca la regla en references/rules.md. Arregla la causa en el .comp o la declaración y vuelve a aplicar.

6. Mostrar y previsualizar

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

preview renderiza el último fotograma del elemento insertado a 103×58 y escribe <nombre>.png junto al .setting; este PNG es la miniatura del preset. Por defecto, la miniatura se recorta al contenido renderizado más un margen del 10% (--framing content), por lo que un título cerca del borde del fotograma aún llena la miniatura. Usa --framing frame cuando la posición dentro del fotograma importe. Para presets de estilo de texto (forma de herramienta, un solo Text+), pasa --sample-text Ag --sample-size 0.5 para renderizar una muestra de tipo a un tamaño fijo en lugar del texto propio del preset; el encuadre entonces predetermina a frame para que las muestras sean comparables. --frame N escribe <nombre>_f<N>.png. --sample-text [TEXT] renderiza una muestra de tipo de un TextPlus de forma de herramienta con el texto reemplazado por Ag o TEXT. Deja una línea de tiempo llamada fusion-macro-cli preview YYYY-MM-DD HHMMSS.

Una check exitosa y un PNG escrito no prueban que el preset sea correcto: si las entradas se muestran y se pueden editar no se puede confirmar solo con check. Pide al usuario que mire el renderizado y el inspector en la línea de tiempo que dejó preview, y no reportes el preset como correcto antes de que el usuario lo confirme.

7. Empaquetar

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

pack verifica cada .comp y .setting bajo Edit/ y escribe el archivo solo si no hay violaciones. Después de reemplazar un .drfx, el usuario debe reiniciar Resolve; Resolve almacena en caché la lista de títulos y no la vuelve a leer hasta el reinicio.

Códigos de salida

0 éxito; 1 violaciones, un error de archivo o un fallo en Resolve; 2 argumentos no válidos.

Recursos adicionales

Lee estos cuando la tarea necesite detalles:

• references/commands.md: entrada, salida, opciones, comportamiento y códigos de salida de cada comando
• references/declaration.md: las dos formas, el formato de declaración y cómo las claves, ControlGroup, `Pa...

[...truncado para traducción]