Títulos Fusion do Resolve

fusion-macro-cli

fusion-macro-cli cria predefinições de título (.setting) do DaVinci Resolve a partir de composições do Fusion. Ele extrai composições de arquivos .drt / .drp / .setting, monta um .setting a partir de uma declaração TOML, verifica, renderiza no Resolve para PNG e arquiva um diretório Templates em um .drfx.

O que a ferramenta não faz: reproduzir a renderização do Fusion (os PNGs vêm do Resolve através do preview); decidir o que publicar ou como nomear (isso vai na declaração); decidir quantas predefinições criar (uma declaração gera um .setting); classificar muitas composições (agregue a saída show você mesmo); registrar o .drfx no Resolve (o usuário o substitui e reinicia o Resolve).

Termos

• Ferramenta: um nó em uma composição. Possui um tipo (TextPlus, Background, ...) e um nome. Os nomes são únicos em toda a composição, inclusive dentro de macros.
• Entrada: um parâmetro de uma ferramenta. Contém um valor, uma expressão ou uma conexão de modificador.
• Controle: um conjunto de entradas exibido como um widget no inspetor, por exemplo Red1 Green1 Blue1 Alpha1 do TextPlus.
• Macro: uma MacroOperator. Contém ferramentas e expõe entradas selecionadas como InstanceInput.
• Publicar: expor uma entrada fora da macro como um InstanceInput.
• Forma: a forma de um .setting. Ambas as formas têm exatamente uma ferramenta no nível superior.
  • Forma de Macro: a ferramenta é uma MacroOperator que envolve as ferramentas do .comp. O inspetor mostra apenas as entradas publicadas, com os nomes da declaração.
  • Forma de Ferramenta: a ferramenta é uma ferramenta do .comp (tipicamente um TextPlus), salva como está. O inspetor é o próprio inspetor da ferramenta, com todas as entradas.
• Esquema: as definições de entrada e saída de cada tipo de ferramenta, obtidas do Fusion com schema dump.
• Declaração: o TOML que define a forma e, para a forma de macro, o que publicar.
• Diretório Templates: um diretório com Edit/ diretamente abaixo e a estrutura Edit/Titles/<categoria>/..., a mesma estrutura do Templates/ do Fusion.

Verificar a instalação

fusion-macro-cli --help

Se o comando estiver ausente, instale-o com qualquer um dos seguintes (uv, pipx ou pip disponíveis) (Python 3.11 ou posterior, sem dependências):

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 e preview usam a API de script do DaVinci Resolve Studio. Antes de executá-los, peça ao usuário para iniciar o Resolve Studio e ativar scripts externos nas Preferências. O Resolve Free não pode usar scripts externos; com o Free, passe --console e peça ao usuário para colar a linha impressa no console da página Fusion após mudar seu idioma para Py3. Todos os outros comandos funcionam sem o Resolve.

Obtenha o esquema uma vez por versão do Resolve, com uma composição real aberta na página Fusion:

fusion-macro-cli schema dump

Sem um esquema, show, check, fix, apply, pack ainda executam, mas as regras que precisam do esquema são ignoradas (skipped rule (no schema): ...) e show não pode comparar com padrões ou dividir controles.

Fluxo

work/
  0003_title.comp   saída do extract; edite este arquivo
  0003_title.toml   a declaração

<Templates>/Edit/Titles/<categoria>/
  title_blue.setting   saída do apply -o
  title_blue.png       saída do preview

Estágio	Entrada	Saída	Notas
schema dump	—	schema	Uma vez por versão do Resolve
extract	.drt / .drp / .setting	.comp
declare	.setting	.toml	Cria uma declaração com a mesma forma a partir de uma predefinição existente ao reconstruí-la
Editar o .comp	.comp	.comp	Valores, expressões, UserControls e nomes de ferramentas são editados no .comp
check <comp> / fix <comp>	.comp	violações / .comp	Repare as violações antes de criar a macro
show <comp>	.comp	stdout	Candidatos à publicação, com o esquema
Escrever a declaração	—	.toml	Escolha a forma primeiro
apply	.comp + .toml	.setting	Executa check internamente e não escreve nada se houver violações
show <setting>	.setting	stdout	O resultado publicado (forma de macro) ou as entradas da ferramenta salva (forma de ferramenta)
preview	.setting	PNG e uma linha do tempo	O usuário verifica a renderização e o inspetor manualmente no Resolve
pack	Diretório Templates	.drfx	Arquiva apenas o que passa nas verificações

1. Extrair a composição

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

Para reconstruir uma predefinição existente, crie o .comp e a declaração a partir do .setting. Ambos funcionam para qualquer forma. A partir de uma forma de macro, o .comp extraído não contém as Inputs, Outputs ou nome da macro; declare os escreve na declaração. A partir de uma forma de ferramenta, o .comp contém a ferramenta salva com seu nome e é nomeado após o arquivo .setting; declare escreve form = "tool" e o nome da ferramenta.

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

2. Verificar, reparar e listar candidatos

fusion-macro-cli check work/0003_title.comp
fusion-macro-cli fix work/0003_title.comp            # sobrescreve; -o <dir> escreve em outro local
fusion-macro-cli show work/0003_title.comp

check, fix, show aceitam vários caminhos e diretórios de uma vez (fusion-macro-cli check work/ other.setting).

Um .comp extraído de um .drt geralmente contém MediaIn e MediaOut que o Resolve adiciona e quadros-chave na posição da linha do tempo. fix repara as violações que têm um procedimento de reparo (no-media-io, keyframe-origin, e outras). As violações que permanecem são tratadas editando o .comp. Após fix remover MediaIn, as conexões dele se tornam violações no-dangling; reconecte-as no .comp se tiverem uma fonte real.

Se o .comp contiver uma MacroOperator, execute show antes de fix: fix achata a macro (no-macro) e exclui suas Inputs e Outputs. Uma InstanceInput Expression não tem lugar no .comp; transfira-a para o expression da declaração.

show <comp> lista, por ferramenta, as entradas que podem ser definidas externamente: HEAD marca o início de um controle, SIBLINGS lista as outras entradas do mesmo controle, e IC_NAME é o nome que o inspetor mostra quando label é omitido. Entradas iguais aos seus padrões são apenas contadas; --all as lista.

3. Editar o .comp

Valores, expressões, UserControls e nomes de ferramentas são editados no .comp. A declaração contém apenas a forma e as informações que faltam no .comp: para a forma de macro, as entradas publicadas, as saídas da macro e o nome da macro; para a forma de ferramenta, a ferramenta a ser salva. Para predefinições que diferem apenas em valores, como variações de cor, copie o .comp, altere os valores e escreva uma declaração para cada cópia. Para alternar cores dentro de uma predefinição, adicione uma entrada ComboControl (como ColorSelect) a UserControls e calcule a cor no expression da cor publicada a partir da seleção.

4. Escolher a forma e escrever a declaração

Escolha a forma com base no que a predefinição precisa:

• Forma de macro quando o inspetor deve mostrar apenas algumas entradas, com nomes que você escolhe (rótulos em japonês, um seletor de cores acionado por um combo ColorSelect, ...), ou quando a predefinição combina várias ferramentas (TextPlus com Background e Merge, modificadores, ...).
• Forma de ferramenta quando uma ferramenta renderiza toda a predefinição e seu inspetor padrão é o que o usuário deve editar, como um estilo de texto que é apenas um TextPlus com fontes, cores e sombreamento definidos. A forma de ferramenta não tem entradas publicadas, então a maior parte da orientação abaixo sobre escolha de entradas não se aplica; as regras para ferramentas ainda são executadas.

Uma declaração de forma de ferramenta:

name = "01 Blue Subtitle"      # nome do arquivo de saída
source = "0001_01 Blue Subtitle.comp"
form = "tool"
tool = "Template"              # ferramenta do .comp a ser salva; ela mantém este nome

Apenas a ferramenta nomeada é escrita. Uma conexão dela para outra ferramenta do .comp é relatada como no-dangling; use a forma de macro se a predefinição precisar de mais de uma ferramenta.

Uma declaração de forma de macro:

name = "title_blue"            # nome da macro e nome do arquivo de saída
source = "0003_title.comp"     # relativo à declaração
form = "macro"                 # o padrão quando omitido

[[output]]                     # pelo menos um; pelo menos uma saída deve ser uma imagem
tool = "Merge1"                # porta padrão para "Output"

[[publish]]                    # ordem = ordem no inspetor
tool = "Template"
input = "StyledText"
label = "Text"                 # omita para mostrar o nome do controle do esquema (IC_NAME)

[[publish]]
tool = "Template"
input = "Red1Clone"
label = "Color"                # coloque o rótulo apenas no início de um controle

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

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

Deixe page em seu padrão Controls; qualquer outro valor viola page-controls. expression é uma expressão no próprio InstanceInput, usada quando o controle segue outra entrada publicada (como ColorSelect).

Na forma de macro, escolha as entradas a serem publicadas da seguinte forma. Uma entrada publicada é mostrada e editável no inspetor apenas quando essas condições se aplicam.

• Cores (ColorControl): publique vermelho, verde e azul, começando no início do controle. Alpha pode ser omitido. Publicar apenas algumas delas mostra uma amostra que não pode ser editada. Para publicar apenas a opacidade, adicione uma entrada SliderControl a UserControls e conduza o alpha com uma expressão.
• TextPlus multi-elemento: TextPlus tem Red<n> Thickness<n> e outros para cada elemento de sombreamento (preenchimento, contorno, sombra, ...) e mostra apenas as entradas do elemento selecionado por SelectElement (elemento selecionado = valor SelectElement + 1; elemento 1 se ausente). As entradas publicadas seguem a mesma regra, portanto, uma entrada de um elemento não selecionado não é mostrada.
  • Para as cores do elemento 1, publique Red1Clone Green1Clone Blue1Clone (e Alpha1Clone se necessário). Elas são mostradas independentemente da seleção, e seus valores alcançam Red1 e as outras.
  • Para também mostrar entradas do elemento 2 ou posteriores, adicione entradas aos UserControls da ferramenta no .comp, escreva expressões nas entradas do elemento que recebem os valores delas e publique as entradas dos UserControls. Publicar entradas de elemento diretamente mostra apenas um elemento por TextPlus.
• Grupos colapsáveis (NestControl, como Softness<n> do TextPlus): publique as entradas filhas (SoftnessX<n> SoftnessY<n>), não o grupo. Um grupo publicado mostra um título vazio "∨" e engole o próximo controle.
• Entradas acionadas por expressão: não as publique; a expressão fornece o valor, então as edições não alcançam a renderização. Adicione uma entrada UserControls, publique-a e faça referência a ela na expressão.
• Entradas conectadas: uma entrada alimentada pela saída de outra ferramenta é mostrada com um botão de quadro-chave vermelho. Publique a entrada do modificador de origem (para TextPlus.StyledText alimentado por StyledTextCLS, publique o Text do modificador).
• Expressões: refira-se a uma entrada UserControls como <ferramenta>.<entrada>. Um identificador simples pode resolver para um nome interno da ferramenta; preview relata tais incompatibilidades com código de saída 1, e check não pode detectá-las.

5. Aplicar

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

--dry-run mostra o resultado da verificação e a saída show do resultado sem escrever. Com violações, apply não escreve nada e sai com 1. As violações são impressas como <caminho>: <regra> <local>: <mensagem>; consulte a regra em references/rules.md. Corrija a causa no .comp ou na declaração e aplique novamente.

6. Mostrar e visualizar

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

preview renderiza o último quadro do item inserido em 103×58 e escreve <nome>.png ao lado do .setting; este PNG é a miniatura da predefinição. Por padrão, a miniatura é cortada para o conteúdo renderizado mais uma margem de 10% (--framing content), de modo que uma legenda próxima à borda do quadro ainda preencha a miniatura. Use --framing frame quando a posição dentro do quadro for importante. Para predefinições de estilo de texto (forma de ferramenta, um Text+), passe --sample-text Ag --sample-size 0.5 para renderizar uma amostra de tipo em um tamanho fixo em vez do texto próprio da predefinição; o enquadramento então assume o padrão frame para que as amostras permaneçam comparáveis. --frame N escreve <nome>_f<N>.png. --sample-text [TEXT] renderiza uma amostra de tipo de um TextPlus de forma de ferramenta com o texto substituído por Ag ou TEXT. Ele deixa uma linha do tempo chamada fusion-macro-cli preview YYYY-MM-DD HHMMSS.

Uma verificação check aprovada e um PNG escrito não provam que a predefinição está correta: se as entradas são mostradas e editáveis não pode ser confirmado apenas pelo check. Peça ao usuário para olhar a renderização e o inspetor na linha do tempo que o preview deixou, e não relate a predefinição como correta antes que o usuário a confirme.

7. Empacotar

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

pack verifica todos os .comp e .setting em Edit/ e escreve o arquivo apenas se não houver violações. Após substituir um .drfx, o usuário deve reiniciar o Resolve; o Resolve armazena em cache a lista de títulos e não a relê até a reinicialização.

Códigos de saída

0 sucesso; 1 violações, um erro de arquivo ou uma falha no Resolve; 2 argumentos inválidos.

Recursos adicionais

Leia estes quando a tarefa precisar de detalhes:

• references/commands.md: entrada, saída, opções, comportamento e códigos de saída de cada comando
• references/declaration.md: as duas formas, o formato da declaração e como chaves, ControlGroup, e ...