Resolve Fusion 타이틀

fusion-macro-cli

fusion-macro-cli는 Fusion 컴포지션으로부터 DaVinci Resolve 타이틀 프리셋(.setting)을 생성합니다. .drt / .drp / .setting에서 컴포지션을 추출하고, TOML 선언문에서 .setting을 조립하며, 이를 검사하고, Resolve에서 PNG로 렌더링하며, Templates 디렉토리를 .drfx로 압축합니다.

이 도구가 수행하지 않는 작업: Fusion 렌더링 재현(preview를 통해 Resolve에서 PNG를 가져옴); 게시할 항목이나 이름 결정(선언문에서 처리); 생성할 프리셋 수 결정(하나의 선언문이 하나의 .setting을 생성); 많은 컴포지션 분류(show 출력을 직접 집계); Resolve에 .drfx 등록(사용자가 교체하고 Resolve를 다시 시작).

용어

• 도구: 컴포지션의 노드입니다. TextPlus, Background 등과 같은 유형과 이름을 가집니다. 이름은 매크로 내부를 포함하여 전체 컴포지션에서 고유해야 합니다.
• 입력: 도구의 매개변수입니다. 값, 표현식 또는 수정자 연결을 보유합니다.
• 컨트롤: 인스펙터에서 하나의 위젯으로 표시되는 입력 세트입니다(예: TextPlus의 Red1 Green1 Blue1 Alpha1).
• 매크로: MacroOperator입니다. 도구를 포함하고 선택된 입력을 InstanceInput으로 노출합니다.
• 게시: 입력을 매크로 외부에 InstanceInput으로 노출합니다.
• 형식: .setting의 형태입니다. 두 형식 모두 최상위에 정확히 하나의 도구를 가집니다.
  • 매크로 형식: 도구는 .comp의 도구를 감싸는 MacroOperator입니다. 인스펙터에는 게시된 입력만 선언문의 이름으로 표시됩니다.
  • 도구 형식: 도구는 .comp의 도구 중 하나(일반적으로 TextPlus)이며, 있는 그대로 저장됩니다. 인스펙터는 해당 도구 자체의 인스펙터로, 모든 입력이 표시됩니다.
• 스키마: schema dump로 Fusion에서 얻은 각 도구 유형의 입력 및 출력 정의입니다.
• 선언문: 형식과 (매크로 형식의 경우) 게시할 내용을 명시하는 TOML 파일입니다.
• Templates 디렉토리: Edit/이 바로 아래에 있고 Edit/Titles/<category>/... 구조를 가지는 디렉토리로, 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 페이지 콘솔(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/<category>/
  title_blue.setting   apply -o의 출력물
  title_blue.png       preview의 출력물

단계	입력	출력	비고
schema dump	—	스키마	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를 복사하고 값을 변경한 후 각 복사본에 대한 선언문을 작성하세요. 하나의 프리셋 내에서 색상을 전환하려면 UserControls에 ComboControl 입력(예: ColorSelect)을 추가하고 게시된 색상의 expression에서 선택 항목을 기반으로 색상을 계산하세요.

4. 형식 선택 및 선언문 작성

프리셋에 필요한 것에 따라 형식을 선택하세요:

• 매크로 형식: 인스펙터에 선택한 입력만 표시되어야 하고, 원하는 이름(일본어 레이블, ColorSelect 콤보로 구동되는 색상 선택기 등)을 사용하거나, 프리셋이 여러 도구(TextPlus와 Background 및 Merge, 수정자 등)를 결합할 때 사용합니다.
• 도구 형식: 하나의 도구가 전체 프리셋을 렌더링하고 표준 인스펙터만으로 사용자가 편집하기에 충분할 때 사용합니다. 예: 글꼴, 색상, 음영이 설정된 TextPlus만 있는 텍스트 스타일. 도구 형식에는 게시된 입력이 없으므로 아래 입력 선택에 대한 대부분의 지침은 적용되지 않지만 도구에 대한 규칙은 여전히 실행됩니다.

도구 형식 선언문:

name = "01 Blue Subtitle"      # 출력 파일 이름
source = "0001_01 Blue Subtitle.comp"
form = "tool"
tool = "Template"              # 저장할 .comp의 도구; 이 이름을 유지합니다.

지정된 도구만 기록됩니다. .comp의 다른 도구에 대한 연결은 no-dangling으로 보고됩니다. 프리셋에 둘 이상의 도구가 필요한 경우 매크로 형식을 사용하세요.

매크로 형식 선언문:

name = "title_blue"            # 매크로 이름 및 출력 파일 이름
source = "0003_title.comp"     # 선언문 기준 상대 경로
form = "macro"                 # 생략 시 기본값

[[output]]                     # 최소 하나; 적어도 하나의 출력은 이미지여야 함
tool = "Merge1"                # 포트 기본값은 "Output"

[[publish]]                    # 순서 = 인스펙터 순서
tool = "Template"
input = "StyledText"
label = "Text"                 # 생략 시 스키마의 컨트롤 이름(IC_NAME) 표시

[[publish]]
tool = "Template"
input = "Red1Clone"
label = "Color"                # 컨트롤의 헤드에만 레이블 지정

[[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당 하나의 요소만 표시됩니다.
• 접을 수 있는 그룹(NestControl, 예: TextPlus의 Softness<n>): 그룹이 아닌 하위 입력(SoftnessX<n> SoftnessY<n>)을 게시하세요. 게시된 그룹은 빈 "∨" 제목을 표시하고 다음 컨트롤을 삼킵니다.
• 표현식 기반 입력: 게시하지 마세요. 표현식이 값을 제공하므로 편집이 렌더링에 도달하지 않습니다. UserControls 입력을 추가하고 게시한 후 표현식에서 참조하세요.
• 연결된 입력: 다른 도구의 출력에 의해 공급되는 입력은 빨간색 키프레임 버튼으로 표시됩니다. 대신 소스 수정자의 입력을 게시하세요(StyledTextCLS에 의해 공급되는 TextPlus.StyledText의 경우 수정자의 Text를 게시).
• 표현식: UserControls 입력을 <tool>.<input>으로 참조하세요. 식별자만 사용하면 도구 내부 이름으로 확인될 수 있습니다. 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/<category>"

--dry-run은 검사 결과와 결과의 show 출력을 표시하지만 기록하지는 않습니다. 위반 사항이 있으면 apply는 아무것도 쓰지 않고 종료 코드 1을 반환합니다. 위반 사항은 <path>: <rule> <location>: <message> 형식으로 출력됩니다. 규칙에 대한 자세한 내용은 references/rules.md를 참조하세요. .comp 또는 선언문에서 원인을 수정하고 다시 적용하세요.

6. 표시 및 미리보기

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

preview는 삽입된 항목의 마지막 프레임을 103×58로 렌더링하고 .setting 옆에 <name>.png를 기록합니다. 이 PNG가 프리셋 썸네일입니다. 기본적으로 썸네일은 렌더링된 콘텐츠에 10% 여백을 더한 영역으로 잘립니다(--framing content). 따라서 프레임 가장자리 근처의 캡션이 썸네일을 채웁니다. 프레임 내 위치가 중요한 경우 --framing frame을 사용하세요. 텍스트 스타일 프리셋(도구 형식, 하나의 Text+)의 경우 --sample-text Ag --sample-size 0.5를 전달하여 프리셋 자체 텍스트 대신 고정된 크기로 문자 샘플을 렌더링합니다. 이 경우 프레이밍은 기본적으로 frame이므로 샘플을 비교할 수 있습니다. --frame N은 <name>_f<N>.png를 기록합니다. --sample-text [TEXT]는 도구 형식 TextPlus의 텍스트를 Ag 또는 TEXT로 대체하여 문자 샘플을 렌더링합니다. preview는 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: 두 가지 형식, 선언문 형식, 키, ControlGroup, Pa... (번역을 위해 잘림)