Craft Music Video (FilmCraft + EffectCraft)
효과적인 뮤직 비디오 제작을 위한 재사용 가능한 워크플로우로, EffectCraft(2D 장면, 모션 그래픽, VFX, 독립적인 알파 자막 레이어)와 FilmCraft(멀티트랙 메인 편집, 리듬 동기화, 오디오 믹싱/마스터링, 글로벌 컬러 그레이딩, Master + Clean 이중 내보내기)를 결합합니다.
공통 2D 애니메이션 메서드(프레이밍, 예상 동작을 포함한 포즈 변경, 캐릭터/카메라 앵커, EffectCraft 페어렌팅 함정, 레이어 순서 및 텍스트 가독성): craft-2d-animation 참조.
전체 MCP 참조, 검증된 엔진 명령 및 Flatpak 구성: references/mcp-and-commands.md.
0. MCP 및 샌드박스 사전 요구사항 (시작 전 확인)
- 현재 세션에
effectcraft및filmcraftMCP 서버가 노출되어 있는지 확인하거나, 깔끔하게 CLI(effectcraft-cli/filmcraft-cli)로 전환합니다.- 서버가 없으면 호출을 임의로 생성하지 말고, 정확한 구성(Flatpak Linux
ai.storyteller.filmcraft/ai.storyteller.effectcraft또는 네이티브 바이너리, headless 또는 bridge 모드)을 위해 references/mcp-and-commands.md를 참조하세요.
- 서버가 없으면 호출을 임의로 생성하지 말고, 정확한 구성(Flatpak Linux
- Flatpak(Linux) 주의사항: 기본적으로
ai.storyteller.effectcraft는xdg-documents,xdg-pictures,xdg-videos에만 접근할 수 있습니다. 프로젝트가 다른 곳(예:~/.t3/projects/...)에 있으면--filesystem=<프로젝트_루트>를 전달하거나 오버라이드를 구성하세요:flatpak override --user --filesystem=home ai.storyteller.effectcraft - GUI vs Headless 충돌: 동일한
.ecproj또는.fcproj를 그래픽 애플리케이션과 MCP/CLI headless에서 동시에 열지 마십시오. 열려 있는 창을 제어하려면--bridge를 사용하세요.
1. 역할 분담: EffectCraft vs FilmCraft
| 영역 | EffectCraft (.ecproj) | FilmCraft (.fcproj) |
|---|---|---|
| 주요 용도 | 2D 애니메이션 장면(V01..Vnn), 독립적인 투명 레이어 자막(L01..Lnn), 타이포그래피, 파티클, 2D/3D 합성 | 멀티트랙 메인 편집(V1 장면 + V2 RGBA 자막 + A1 마스터 오디오), 프레임 동기화, 전환, 글로벌 컬러 그레이딩, 이중 내보내기(자막 포함 + 클린) |
| 생성 | comp.new, layer.newText, layer.newShape, layer.newSolid, layer.newAdjustment, add_effect, JSX 스크립트(ec_runtime.py) | file.newSequence, timeline.place, timeline.setTrack, timeline.razor, timeline.trim, timeline.move, clip.speedDuration |
| 음악 동기화 | audio/lyrics_timing.json의 정확한 기준 + 청취; 측정된 반응 효과가 필요할 때만 선택적으로 keys.audioToKeyframes | 각 섹션, 마지막 악센트 및 블랙 컷에 markers.add; 프레임 정확한 정렬(frame: f0) |
| 스타일링 & 컬러리티 | 레이어 스타일, 마스크, 베지어, 글로우, 그림자, 프리컴포지션(layer.precompose) | Lumetri Color(lumetri.applyPreset, lumetri.setLook, lumetri.applyMatch), sequence.colorSettings, sequence.applyVideoTransition |
| 오디오 | 중간 렌더링에 오디오 내보내기 없음(--audio off) | A1의 원본 마스터 트랙(기본적으로 0.0 dB로 유지하여 원본 마스터 보존; 요청 시에만 essentialSound.* 또는 sequence.normalizeMixTrack 사용) |
2. 파일 교환 파이프라인 및 기술적 일관성
프로젝트 폴더 규칙
<project_root>/
├── audio/ # 마스터 트랙 (WAV/FLAC/MP3) + lyrics_timing.json (편집 가능한 단일 소스)
├── footage/ # 비디오 러시, 사진, 로고 등
├── renders_vfx/ # EffectCraft 중간 렌더링: V01..Vnn.mov (RGB) + L01..Lnn.mov (RGBA)
├── previews/ # PNG 캡처 (render-frame) + 미리보기용 짧은 MP4 (예: 후렴, 솔로)
├── projects/ # .ecproj 및 .fcproj 파일
├── scripts/ # 클립별 생성기 (T3 Code 공유 도구 중요)
└── exports/ # 최종 1080p 산출물: *_lyrics.mp4 및 *_clean.mp4
호환 가능한 교환 형식
- EffectCraft → FilmCraft의 투명도가 있는 자막 및 오버레이(
V2):- 권장(단일 파일): QuickTime Apple ProRes 4444 (
.mov),format: "prores",proresProfile: "4444",channels: "rgba",audio: "off". - 무손실 대안: PNG 시퀀스 또는 OpenEXR(
channels: "rgba"), FilmCraft에서image_sequence: true로 가져오기. - 알파에 금지:
H264,Hevc및Av1은 알파 채널을 처리하지 못함(alpha: false).
- 권장(단일 파일): QuickTime Apple ProRes 4444 (
- EffectCraft의 불투명 시각 장면(
V1):format: "prores",proresProfile: "hq",channels: "rgb",audio: "off".
- FilmCraft의 최종 전달:
- 웹/배포:
format: "h264"(.mp4, preset"High Quality 1080p HD"). - 마스터 아카이브:
format: "prores". (참고: Linux에서 하드웨어 인코더가 없으면hevc및av1을 사용하지 못할 수 있습니다.)
- 웹/배포:
해상도, 프레임 레이트(FPS) 및 컬러리티 정렬
- 처음부터 EffectCraft(
comp.new)와 FilmCraft(file.newSequence) 간에 공유되는 단일(width, height, fps)쌍을 고정합니다(예:1920×1080@30또는24fps). - 프레임 정렬 섹션: 각 섹션의 경계를 정수 프레임(
f0 / fps .. f1 / fps)으로 계산하여 섹션 합계가 드리프트나 갭 없이 오디오 트랙의 실제 길이를 정확히 커버하도록 합니다. - 색 공간: 두 소프트웨어 모두 SDR에서
workingSpace: "rec709"사용(EffectCraft의file.projectSettings, FilmCraft의sequence.colorSettings; HDR/Log 러시인 경우autoToneMap: true). - 시간 변환: EffectCraft는 초(
f64) 단위로 작업하고, FilmCraft는 틱(254016000000틱 =1초)을 사용하며timeline.place에서frame/seconds도 허용합니다.
3. 핵심 음악 메서드 (귀 맞춤, 편집 가능한 타이밍, 독립 자막 및 기악)
A. 귀 맞춤 및 마스터 오디오의 정확한 끝 측정
- 항상 44.1kHz(
hop = 441= 정확히 10,000ms)에서 원본 트랙을 측정합니다(audio_cues.py analyze사용). 22.05kHz의 반올림된 스텝을 사용하지 마십시오. 3분 동안 수백 밀리초의 드리프트가 발생할 수 있습니다. - 편집을 잠그기 전에 MP3/WAV의 정확한 끝을 확인합니다: 마지막 강한 악센트, 마지막 드럼/악기 히트(예: 블랙 컷) 및 최종 사일런스까지의 리버브 실제 끝을 찾습니다.
- 트랙을 조각으로 실제로 듣기: 겹치는 조각(예: 18초, 2초 오버랩)으로 자른 후 전환, 후렴, 코러스 및 구문 끝 주변의 짧은 클립(
audio_cues.py slice)을 추출하고 귀로 정확한 BPM과 각 보컬 진입을 확인합니다.
B. 편집 가능한 단일 타이밍 파일 (audio/lyrics_timing.json) 및 불확실한 기준
모든 자막 타이밍을 수동으로 편집 가능한 단일 JSON 파일(audio/lyrics_timing.json)에 중앙 집중화하고, EffectCraft 생성기에서 다시 읽습니다:
meta: 오디오 파일, 오디오/비디오 길이(ms),fps,bpm,first_drum_hit_ms,last_accent_ms,black_cut_ms.sections: 프레임 정렬start_ms/end_ms경계.phrases:start_ms,end_ms및display_end_ms(필요시+250~+600 ms연장하여 계획이나 섹션이 변경되어도 마지막 단어를 읽을 수 있도록 함).- 메인 보컬의 경우
type: "lead", 코러스, 응답 및 애드립의 경우 별도 항목으로type: "echo". words(단어/그룹별 분할) 애니메이션이나 시각적 악센트가 필요한 경우에만; 그렇지 않으면 전체 구를 깔끔하게 표시.- 모호한 기준(코러스, 에코, 겹치는 보컬라이즈, 짧은 외침)에는
"uncertain": true+"review_note": "..."를 추가하여 사용자가 코드를 건드리지 않고 쉽게 수동으로 재조정할 수 있도록 합니다.
C. 독립 레이어 자막 (V2 RGBA) 및 Master / Clean 이중 내보내기
- 영구적인 검은 띠 없음: 각 구를 계획의 여유 공간에 배치(craft-2d-animation §5 참조), 부드러운 그림자, 안전 여백 및
display_end_ms가 섹션 컷을 넘을 때 자동 연속성(isContIn/isContOut). - 전용 투명 트랙: 순수 기악 섹션은 생략하고 별도의 컴포지션
L01..Lnn에서 자막을 생성, ProRes 4444 RGBA로 렌더링하여 FilmCraft의V2에 배치. V1의 장면 내 텍스트 유지: 간판, 화면, 사본, 그림은 장면V01..Vnn에 남겨둠.- 완전히 동일한 이중 내보내기: 자막 포함 버전 내보내기(
V2활성화),V2비활성화(timeline.setTrack {"track": "V2", "enabled": false}) 후 클린 버전을 100% 동일한 편집 및 오디오로 내보내기, 그런 다음 최종.fcproj저장 전에V2를 다시 활성화.
D. 기악 구간의 시각적 액션 (일반적인 오디오 파형 금지)
- 일반적인 시각적 버팀목 금지: 오디오 파형, 오실로스코프 지그재그, 인트로/솔로/인터루드의 장식용 떠다니는 원 없음.
- 귀로 선택한 악센트에 맞춰 그려진 액션 안무: 문이 쾅 닫힘, 천장 조명이 하나씩 켜짐, 리프에 맞춰 3D 종이/카드보드 세트가 펼쳐짐, 물체가 미끄러지거나 캐릭터가 예상 동작과 유지로 포즈 변경.
- 악센트 사이 계획 유지: 두 강한 비트 사이에 명확하고 안정적인 이미지를 남겨 액션을 읽기 쉽게 함.
- 공통 2D 규칙 적용: 다양한 프레이밍(와이드 / OTS / 프로필 / 클로즈업), 전체 실루엣, 변환 전 중립 앵커 계층 구조(craft-2d-animation 참조).
4. 단계별 워크플로우
1단계 — 귀 기반 오디오 분석 및 타이밍 스켈레톤
- 44.1kHz로 마스터 조사(
audio_cues.py analyze)하여 정확한 길이, 10ms 과도 현상 및 트랙 끝 세부 정보 얻기. - 청취 조각 추출(
audio_cues.py slice) 및 청취하여 정확한 BPM, 프레임 정렬 섹션 경계, 구, 에코 및 최종 컷 설정. audio/lyrics_timing.json초기화 및 채우기, 의심스러운 기준은"uncertain": true+"review_note"로 표시한 후 JSON 검증(lyrics_overlay.py --validate).
2단계 — 컷 / 짧은 스토리보드 (전체 렌더링 전)
- 짧은 편집 계획(시간 / 섹션 / 장소 및 프레이밍 / 그려진 시각적 액션 / 자막 처리 표) 작성.
- 전체 렌더링을 시작하기 전에 사용자에게 컷(및 기악 구간 악센트 선택) 제시.
3단계 — EffectCraft에서 장면(V01..Vnn) 및 자막(L01..Lnn) 생성
- craft-2d-animation의 앵커, 중립 페어렌팅 및 스태킹 규칙에 따라 2D 장면(
V01..Vnn) 구축(ec_runtime.py사용). audio/lyrics_timing.json에서lyrics_overlay.py를 통해 직접 투명 자막 컴포지션(L01..Lnn, 기악 제외) 생성.- 빠른 확인을 위한 캡처(
render-frame --max-side 960) : 주요 계획(및 자막의 경우--transparent)에서 비디오 렌더링 전에 겹침이나 앵커 오프셋을 즉시 수정. - 짧은 MP4 미리보기(사운드 포함) (예: 후렴 1개 + 솔로 1개): 이 1-2개 섹션만 렌더링하고 정확한 마스터 오디오 조각과 먹싱한 후, 보고 듣기하여 에코 진입, 계획 간 마지막 단어 유지 및 솔로 가독성을 필요에 따라 재조정.
- 저전력 전체 렌더링:
./renders_vfx/로render_ec_batch.sh사용(한 번에 1개 렌더링 순차적,V*는 ProRes HQ RGB,L*는 ProRes 4444 RGBA,ffprobe를 통한 자동 재개). projects/<clip>.ecproj저장.
4단계 — FilmCraft에서 조립 및 이중 내보내기
assemble_filmcraft.py를 통해 Rec.709 시퀀스 조립(또는 MCPfile.newProject,file.newSequence,media_import,timeline.place,markers.add사용):A1: 원본 마스터 오디오 그대로(volumeDb: 0.0)V1:V01..Vnn.mov를 정확한 프레임(frame: f0)에 배치V2:L01..Lnn.mov(ProRes 4444 RGBA)를 동일한 정확한 프레임에 배치(audio: false)
- 시퀀스 확인(
inspect sequence) +V1+V2및V1단일 합성 프레임 몇 개를 렌더링하여 알파 컷 및 클린 버전의 다이제틱 텍스트 존재 확인. - 자막 포함 버전 내보내기(
*_lyrics.mp4),V2비활성화, 클린 버전 내보내기(*_clean.mp4), 그런 다음V2다시 활성화하고projects/<clip>.fcproj저장.
5단계 — 최종 필수 감사 (사운드 포함 + 무음)
- 사운드 포함
*_lyrics.mp4내보내기 확인: 구 끝, 후렴 컷, 에코 진입, 정확한 블랙 컷 및 원본 오디오 트랙의 깔끔한 끝 확인. - 무음(뮤트)
*_clean.mp4의 기악 구간(솔로, 인터루드) 확인: 캐릭터 목표와 시각적 진행이 오디오 없이 100% 이해 가능한지, 잔여 오디오 파형이 없고 장면 내 텍스트가 그대로 있는지 확인. - 산출물 제시 및
lyrics_timing.json에서"uncertain": true로 표시된 기준 명시적으로 나열.
5. T3 Code 공유 도구 및 종속성
재사용 가능한 도구는 **~/.t3/shared/craft-video/**에 있습니다:
| 도구 | 경로 | 뮤직 비디오 사용법 |
|---|---|---|
| 44.1kHz 오디오 분석 및 분할 | ~/.t3/shared/craft-video/audio_cues.py | 정확한 길이, 과도 현상, BPM 및 최종 사일런스 측정; 겹치는 청취 조각 및 짧은 클립 추출 |
| 타이밍 JSON 생성기 및 검증기 | ~/.t3/shared/craft-video/lyrics_overlay.py | audio/lyrics_timing.json을 EffectCraft용 EffectCraft 생성 스크립트로 변환(또는 --generate-ae는 After Effects용); --validate 플래그로 JSON 일관성 확인 |
| 렌더링 배치 | ~/.t3/shared/craft-video/render_ec_batch.sh | renders_vfx/에 V*(ProRes HQ RGB) 및 L*(ProRes 4444 RGBA)를 순차적으로 한 번에 하나씩 렌더링; ffprobe로 깨진 파일 감지 시 자동 재개 |
| FilmCraft 조립기 | ~/.t3/shared/craft-video/assemble_filmcraft.py | 시퀀스 생성, A1(원본 마스터 0.0 dB) + V1(장면) + V2(RGBA 자막) 배치, 섹션 마커, 이중 내보내기 |
| 도우미: 44.1kHz 홉 상수 | ~/.t3/shared/craft-video/helpers/audio_constants.py | SAMPLE_RATE = 44100, HOP_MS = 10 → HOP_SAMPLES = 441 (다른 홉 값은 드리프트를 유발하므로 변경하지 마십시오) |
주의:
ec_runtime.py(EffectCraft Python 런타임)는 프로젝트별 생성 스크립트로,~/.t3/shared/craft-video/에 속하지 않고./scripts/아래 프로젝트 자체에 포함됩니다.
6. render_ec_batch.sh 재개 메커니즘
render_ec_batch.sh는 renders_vfx/에서 이미 존재하는 파일을 확인하여 중단된 배치를 재개합니다:
- 각 출력 파일에 대해 먼저
ffprobe로 유효성 확인(ffprobe -v error -show_entries stream=codec_type -of csv=p=0 "$file" 2>&1 | grep -q video). - 유효한 비디오 스트림이 발견되면 파일을 건너뜁니다.
- 파일이 없거나 깨지면(
ffprobe가 비디오 스트림을 찾지 못함) EffectCraft로 장면을 다시 렌더링합니다. - 렌더링이
--timeout 600(600초)을 초과하면 스크립트가 해당 출력을 건너뛰고 사용자에게 경고합니다.
7. 일반적인 함정 및 지침
- 무단
audioToKeyframes금지:keys.audioToKeyframes는 측정된 반응 효과에만 사용하고 장면 전체의 오디오 파형 진동에는 사용하지 마십시오. - 음소거 및 건너뛰기 방지: 각 최종 자막 내보내기를 사운드 포함 및 무음으로 확인하고, 모든 의심스러운 기준을 사용자에게 명시적으로 알리십시오.
- 오디오 트랙 수정 금지:
A1마스터를 절대0.0 dB에서 변경하지 말고(요청 시에만essentialSound.*또는normalizeMixTrack사용), Audio Ducking을 적용하지 마십시오. - 장면 간 자막 이동 방지:
display_end_ms가 섹션 컷을 넘으면 자동 연속성(isContIn/isContOut)을 사용하십시오. - 항상 전체 JSON 경로 사용:
lyrics_overlay.py에서 가져오기 충돌을 방지하고 일관된 앵커 기준을 보장하기 위해audio/lyrics_timing.json의 절대 경로를 생성기에 전달하십시오.