Motion Forge: Code-to-Video (Code2Video) 산업 등급 제작 기술 주 가이드

이 프로젝트 자체는 완전히 독립적이며 배포 가능한 Code-to-Video 산업 등급 Skill입니다. 시스템은 Remotion 4.x + React 19 + TypeScript + Three.js (@remotion/three) + Canvas 2D + SVG 통합 멀티 기술 스택 코어를 기반으로 하며, 265개의 원자적 모션 카드(9개 전문 영역으로 분류), 하위 시각적 베이스(_shared/), 시각적 로컬 디버깅 워크벤치 및 엄격한 G1/G2 이중 품질 확인 게이트를 내장하고 있습니다.

핵심 아키텍처 및 5대 기술 철칙
이중 품질 확인 게이트 표준 운영 절차 (G1 & G2 Gates SOP)
다중 시나리오 독립 파이프라인 시스템 (Scenario Pipelines)
265개 모션 카드 전체 자산 및 감독 의사 결정 심법 (Creative & Open Motion Design)
Film IR 스토리보드 프로토콜 및 멀티 기술 스택 렌더링 규칙
CLI 도구 체인 전체 수명 주기 및 로컬 워크벤치 상호 작용
최종 전달 및 문제 해결 체크리스트

1. 핵심 아키텍처 및 5대 기술 철칙

비디오 스토리보드나 렌더링 코드를 작성하기 전에 에이전트는 다음 5가지 양보할 수 없는 설계 규율을 반드시 준수해야 합니다.

절대적 분리 및 로컬 클록 원칙 (Local Frame Only):
- 각 스토리보드(Scene)는 로컬 프레임 번호(frame 0부터 durationInFrames까지)만 사용하며, 스토리보드 내부에 전체 영상의 절대 타임스탬프(absoluteFrame 또는 from)를 하드코딩하는 것을 엄격히 금지합니다. 전체 영상의 절대 클록은 Core 레이어에서 타임라인 누적을 통해 컴파일합니다.
- 스토리보드 간 내부 컴포넌트를 상호 import하는 것을 엄격히 금지합니다. 모든 스토리보드가 공유하는 상태는 반드시 Film IR의 props를 통해 전달되어야 합니다.
- 모션 카드(Cards)는 모션 수학과 시각적 로직만을 담당하며, 프로젝트별 특정 카피나 비즈니스 이미지 경로를 카드 내부에 하드코딩하는 것을 엄격히 금지합니다.
순수 함수 프레임 클럭 결정론 (Frame-Deterministic Execution):
- 모든 애니메이션 변형, 객체 변위, 투명도 변환은 반드시 현재 로컬 프레임 frame의 순수 수학 계산 함수여야 합니다: $Value = f(frame)$.
- 브라우저의 requestAnimationFrame, setInterval, setTimeout 또는 외부 자체 실행 타임라인 사용을 엄격히 금지합니다.
- 시드가 설정되지 않은 무인수 Math.random() 사용을 엄격히 금지합니다 (Remotion 내장 시드 처리 random(seed)를 반드시 사용). 동일한 프레임이 seek되어 렌더링되더라도 화면 픽셀이 100% 멱등성(idempotent)을 유지하도록 보장합니다.
실제 자산 로컬 폐쇄 원칙 (Local Assets Only):
- 렌더링 엔진은 비디오 합성 과정에서 외부 원격 검증되지 않은 URL에 직접 연결하는 것을 금지합니다 (네트워크 차단, 핫링크 방지, 요청 지연 방지).
- 외부 이미지, 비디오 클립, 오디오 배경 음악은 반드시 Providers가 사전에 다운로드하여 프로젝트 로컬 디렉토리에 저장하고, assets.json에 통합 등록하여 관리해야 합니다. 누락된 자산은 반드시 명시적으로 표시하고 사용자에게 보고해야 하며, 묵시적으로 자리 표시하거나 가짜 데이터로 속이는 것을 엄격히 금지합니다.
멀티 기술 경로 통합 프레임 렌더링 철학 (Multi-Tech Rendering):
- 타이포그래피 및 상호 작용 UI는 HTML/CSS + Spring 탄성 애니메이션을 사용합니다.
- 기하학적 윤곽, 연결선, 차트 및 마스크는 SVG 경로 보간을 사용합니다.
- 파티클, 유체 및 수만 개의 고주파 운동 지점은 Canvas 2D를 사용합니다.
- 3D 입체 모델, 공간 조명 및 3차원 카메라 무빙은 Three.js (@remotion/three) 를 사용합니다.
- 모든 기술 경로는 Remotion의 useCurrentFrame() 프레임 동기화 클록을 통일적으로 따릅니다.
프로젝트 엔지니어링 독립화 원칙 (Standalone Project):
- 이 Skill 디렉토리는 프로세스 규범, 모션 카드 참조, 일반 런타임 템플릿 및 forge create 프로젝트 생성기만을 담당합니다. 사용자 프로젝트의 모든 내용(core/, cards/, scenes/, public/ 자산, film.json, package.json, 워크벤치 및 렌더링 결과물)은 반드시 사용자 프로젝트 자체 디렉토리에 위치해야 하며, 독립적으로 npm ci를 실행하고, 독립적으로 검증 및 렌더링하여 Skill 디렉토리에서 분리되어 실행 가능해야 합니다.
- 프로젝트별 코드/자산을 Skill 디렉토리에 쓰거나, 심볼릭 링크를 사용하여 프로젝트 내용을 Skill 디렉토리에 연결하는 것을 엄격히 금지합니다. forge create는 런타임, 모션 카드 및 기본 Film을 실제 파일로 프로젝트에 복사하며, 프로젝트별 스토리보드 컴포넌트는 프로젝트의 scenes/ 아래에 직접 작성됩니다.
- Skill 디렉토리 내 output/projects/와 CLI의 게이트 프로세스는 Skill 자체 예시에만 적용됩니다. 실제 프로젝트의 G1/G2 검토 기록은 프로젝트 디렉토리 내에 저장됩니다.
새 프로젝트 초기화 (입력: 프로젝트 절대 경로 및 입력 자산, 출력: 독립적으로 종속성 설치 가능한 엔지니어링 스켈레톤):
1. 템플릿 디렉토리에서 npm run forge -- create --dir /absolute/project --input <입력> [--audio-kind song|instrumental] [--name <id>]를 실행합니다. 대상은 템플릿 외부의 빈 디렉토리여야 하며, 명령어는 완전한 런타임 복사본을 생성하고, 로컬 자산을 public/assets/<id>/에 복사하며, 프로젝트 초안을 생성합니다.
2. 초기화 완료 후 PROJECT_ROOT로 이동하여 npm ci, npm run validate -- --project <id>를 실행합니다. 실제 프로젝트의 코드, 자산, Film IR, 승인 상태 및 출력은 모두 PROJECT_ROOT/output/projects/<id>/와 PROJECT_ROOT/public/ 내에 자체 포함됩니다.
3. 로컬 자산은 public/ 아래의 상대 경로만 사용합니다. 원격 소스는 소스 메타데이터 기록으로만 사용되며 렌더링 참조에 포함되지 않습니다. 자산이 부족하면 즉시 중단하며, 프로젝트가 절대 경로나 외부 심볼릭 링크로 독립 엔지니어링을 가장할 수 없도록 해야 합니다.
4. 이후 모든 명령어는 먼저 cd <PROJECT_ROOT>를 실행한 후 프로젝트 내 스크립트를 실행합니다. 렌더링 결과물과 검토 기록은 템플릿 디렉토리에 다시 쓰면 안 됩니다.
5. 템플릿 디렉토리는 create 시에만 읽기 전용 소스로 사용됩니다. 생성 후 프로젝트의 import, npm 종속성, 스크립트 및 자산 참조는 더 이상 해당 디렉토리를 가리키지 않아야 합니다.

실패 분기 및 복구 경로

트리거 조건	1차 처리	여전히 실패하거나 변경이 필요한 경우
프로젝트 루트 디렉토리가 불분명하거나 Skill 디렉토리에 쓰려고 함	쓰기 중단, 사용자와 프로젝트 절대 경로 확인, 이후 명령어는 해당 프로젝트 디렉토리를 작업 디렉토리로 사용	명확한 경로를 얻을 때까지 방안만 논의하고 파일을 생성하지 않음
필수 자산 누락, 읽기 불가 또는 라이선스 불명확	구체적인 경로와 이유 보고, 영향받는 스토리보드 일시 중단, 묵시적 자리 표시나 자산 조작 금지	사용자가 자산을 보충하거나 대체 방안을 명시적으로 승인하고 G1을 동시에 수정
G1 미확인 또는 수정 요청	설계 단계에 머물며 `film.json` 및 `design-review.md` 수정	샘플 장면을 만들지 않고 G1 승인 명령어를 실행하지 않음
샘플 장면에서 블랙 스크린, 오디오-비디오 불일치, 텍스트 오버플로 또는 품질 불량	G2 잠금 유지, 특정 스토리보드 찾아 수정, 샘플 장면만 다시 렌더링	G2 재제출, 전체 영상 렌더링으로 샘플 검증을 대체하지 않음
승인된 내러티브, 레이아웃, 지속 시간, 자산 또는 오디오 변경	기존 G1/G2 결론 무효화, G1으로 돌아가 영향받는 범위 재확인	새 G1 통과 후 유성 샘플 장면 재제작 및 확인
빌드, 검증 또는 렌더링 명령어 실패	전체 로그 보존, 근본 원인 수정 후 동일 명령어 재실행, 오류 주석 처리 또는 검증 건너뛰기 금지	여전히 실패하면 전달 중단, 차단 항목 및 완료된 검증 사항 명확히 보고
독립성 스캔에서 외부 절대 경로, `file:` 종속성 또는 Skill 디렉토리를 가리키는 심볼릭 링크 발견	필요한 코드 또는 자산을 프로젝트에 실제로 복사하고 프로젝트 내 참조로 변경	격리된 복사본에서 다시 설치 및 렌더링, 통과하지 않으면 독립 실행 가능하다고 선언하지 않음

2. 이중 품질 확인 게이트 표준 운영 절차 (G1 & G2 Gates SOP)

에이전트가 "공상에 빠져 코드를 무분별하게 쌓아 심각한 계산 낭비와 예상치 이탈"을 초래하는 것을 방지하기 위해 시스템은 이중 확인 게이트(Two-Gate Review) 를 강제합니다. 게이트를 건너뛰고 전체 영상을 직접 렌더링하는 것을 엄격히 금지합니다!

[사용자 입력]
   ↓
[요구사항 분석 & 자산 준비]
   ↓
[Film IR 초안 작성]
   ↓
【🔴 CHECKPOINT G1: 스토리보드 및 디자인 확인】 → 사용자에게 정리된 대본 및 시각적 테이블 제시, STOP 승인 대기
   ↓ (사용자 확인 통과 후 npm run forge -- approve-design 실행)
[실제 유성 샘플 장면 제작]
   ↓
【🔴 CHECKPOINT G2: 유성 샘플 장면 확인】 → 대표 장면 비디오 렌더링, 사용자가 실제 시청각 품질과 오디오-비디오 정렬 확인, STOP 승인 대기
   ↓ (사용자 확인 통과 후 npm run forge -- approve-sample 실행)
[전체 영상 코드 조립 및 배치 렌더링]
   ↓
[최종 전달 (MP4 + 편집 가능한 프로젝트 + 워크벤치)]

1. G1 게이트: 스토리보드 및 시각 디자인 확인 (Design Review)

복잡한 렌더링 코드를 작성하기 전에 에이전트는 먼저 《G1 스토리보드 및 시각 디자인 방안》을 완성하고, 사용자에게 정리된 Markdown 검토 문서를 제시해야 하며, 최소한 다음을 포함해야 합니다:

기본 속성: 영상 유형, 대상 청중, 화면 비율 (가로 16:9 / 세로 9:16), 목표 총 지속 시간 및 프레임 레이트 (예: 30fps)
시각 테마: 주요 색상, 배경색, 텍스트 주요 색상, 강조 색상 (Accent), 타이포그래피 글꼴 패밀리
메인 클럭 선택: 나레이션 음성 정렬 / 노래 가사 정렬 / 순수 음악 비트 그리드 / 텍스트 읽기 시간
스토리보드 대본 상세표 (반드시 아래 표 형식으로 사용자에게 제시):

스토리보드 번호	장면 이름	내러티브 목적 및 의미 (Semantic)	나레이션	실제 화면 텍스트 (On-Screen Text)	화면 설명	주 모션 카드 (Primary)	카메라 카드 (Camera)	전환 카드 (Transition)	로컬 지속 시간 (프레임/초)
S01	시작 돌파	Hook: 긴장감 조성	왜 90%의 기업 AI 전환이 모두 데모 단계에서 멈출까요?	"왜 90%의 기업 AI 전환이 실패로 끝날까?"	중앙 거대 고대비 제목 + 빨간색 경고 발광 바닥판	`typography/halation-bloom`	`camera/slow-push`	`transition/cube-rotate`	90f (3.0초)
S02	데이터 표시	Data 증명: 참담한 통계 제시	두 가지 숫자를 먼저 보세요. 78%는 장난감 단계에 멈춰 있고, 12%는 부정적 수익을 창출합니다.	"78%가 장난감 단계에 정체12%가 부정적 ROI 창출"	좌우 이중 비교 패널 + 동적 숫자 및 낙사 차트	`data/particle-sand-fill`	없음	`transition/whip-pan`	150f (5.0초)

🔴 CHECKPOINT · STOP: 사용자에게 제시한 후, 반드시 이번 라운드를 종료하고 스토리보드 계획에 동의하는지 질문해야 합니다. 동일 라운드에서 승인을 실행하거나, 샘플 장면을 제작하거나, 전체 영상을 렌더링해서는 안 됩니다.
통과 신호: 사용자가 후속 응답에서 G1을 명시적으로 확인한 경우에만 에이전트가 PROJECT_ROOT에서 다음을 실행합니다:
```
npm run forge -- approve-design --project <project-id>
```

2. G2 게이트: 유성 샘플 장면 확인 (Sample Review)

G1 확인 통과 후 즉시 전체 영상을 렌더링해서는 안 됩니다. 반드시 전체 영상에서 가장 대표적이고, 시각적으로 가장 복잡하며, 실제 오디오-비디오 요소를 포함하는 1개의 스토리보드 (일반적으로 Hook 장면 또는 핵심 클라이맥스 장면)를 선택하여 샘플 장면 비디오를 제작 및 렌더링해야 합니다:

렌더링 명령어:

npm run forge -- render --project <project-id> --scope sample

품질 검사 핵심 사항:
- 오디오와 비디오가 정확하게 동기화되었습니까? 자막이 발음 시작 1~2프레임 전에 들어옵니까?
- 화면 텍스트에 가림, 줄바꿈 손상, 안전 영역 이탈이 있습니까?
- 모션 효과 속도와 음악 분위기가 일치합니까? 호흡감(여유)이 느껴집니까?
🔴 CHECKPOINT · STOP: 실제 샘플 장면 비디오와 품질 검사 결과를 제공한 후, 반드시 이번 라운드를 종료하고 사용자 검토를 기다려야 합니다. 스스로 사용자를 대신하여 G2를 승인해서는 안 됩니다.
통과 신호: 사용자가 샘플 장면을 명시적으로 확인한 경우에만 PROJECT_ROOT에서 다음을 실행합니다:
```
npm run forge -- approve-sample --project <project-id>
```
G2 승인이 완료된 후에만 프로젝트 상태 머신이 전체 영상 최종 렌더링 권한을 잠금 해제합니다!

3. 다중 시나리오 독립 파이프라인 시스템 (Scenario Pipelines)

다양한 입력 유형에 대한 종단 간 처리 로직은 pipelines/ 디렉토리 아래에 독립적인 지침 파일로 분리되어 있습니다. 에이전트는 사용자 입력의 실제 유형에 따라 해당 가이드를 참조해야 합니다:

시나리오 유형	적용 입력 및 영상 유형	해당 독립 Pipeline 가이드 파일
시나리오 1: URL 링크 영상 제작	블로그, 공식 계정, SaaS 랜딩 페이지, 기술 문서, 뉴스 보도	`pipelines/url-to-video.md`
시나리오 2: 순수 음악 오디오 영상 제작	순수 악기, 전자 음악, 서사적 배경 음악; 철학 영상, 비트 맞춤 플래시, 감성 산문	`pipelines/instrumental-to-video.md`
시나리오 3: 노래(보컬 포함) 영상 제작	전체 노래 (보컬+반주); 다이내믹 가사 MV, 음악 내러티브 스토리 단편	`pipelines/song-to-video.md`
시나리오 4: 순수 테마 자체 계획 영상 제작	한 문장 테마/주제; 심층 과학, 인문 철학, 비즈니스 인사이트, 교양 단편	`pipelines/theme-to-video.md`
시나리오 5: 사용자 멀티모달 자산 혼합 편집	사용자 자체 이미지, 스크린샷, 짧은 비디오 클립, 녹음 나레이션; 제품 데모, Vlog	`pipelines/assets-to-video.md`
콘텐츠 기획 일반 규칙	테마/URL의 구조화된 기획, 내러티브 아크, 사실 추적 및 Film IR 변환	`pipelines/content-planning.md`
시나리오 확장 가이드	새로운 입력(예: 표, PPT, 2인 팟캐스트 등)을 확장하는 방법	`pipelines/extending-pipeline.md`

4. 265개 모션 카드 전체 자산 및 감독 의사 결정 심법 (Creative & Open Motion Design)

시스템에 내장된 265개의 원자적 모션 카드는 에이전트가 비디오를 제작하기 위한 시각적 브러시입니다.

1. 개방형 선택 원칙: 제한 없는 예술적 상상력

경직된 답습과 교조적 제한을 엄격히 금지합니다: 이 시스템은 "특정 영상 유형은 반드시 특정 카드를 사용해야 한다" 고 절대 제한하지 않습니다. 반대로, 우리는 에이전트가 카피의 감정적 긴장감, 내러티브 서스펜스, 청각적 비트에 따라 자율적으로 매칭하고 혁신할 것을 장려합니다.
에이전트는 진정한 시각 감독입니다: 모션 카드는 모듈식 블록 세트입니다. 원래 기술 제품용으로 설계된 interaction/command-palette-summon을 고대 사상가의 "지식 검색"을 표현하는 데 사용할 수 있습니다. 공항 기계식 뒤집기 패널 typography/split-flap-flip을 시간 여행이나 생명 카운트다운을 표현하는 데 사용할 수도 있습니다.
무단계 매개변수 자유 조절: 각 카드는 풍부한 매개변수(예: 스프링 강성, 중력 크기, 블러 반경, 파티클 수 등)를 노출하며, 에이전트는 film.json의 params에서 개인화된 모션 감각을 자유롭게 사용자 정의할 수 있습니다.

2. 9대 영역 모션 효과 분류 자산 전체 (265개 카드)

모든 265개 카드는 표준화된 캡슐화가 완료되었으며, 가로/세로 화면 이중 모드 자동 적응을 지원하고, 영역별로 완전히 내응집되고 분리되어 있습니다:

분류 (Kind)	디렉토리 및 총 카드 수	핵심 시각적 기능	대표 카드 자산 (코드에서 직접 참조 가능)
`camera` (카메라 무빙)	`cards/camera/` (21장)	공간 확대/축소, 패닝, 틸트; 렌즈 초점 거리, 원근 왜곡; 평면 화면에 깊이 공간 생성	`dolly-zoom` (히치콕 슬라이딩 줌), `slow-push` (깊고 느린 푸시), `slow-pull` (점진적 풀아웃), `shot-crash-zoom-punch` (강한 임팩트 줌), `space-camera-moves` (3차원 공간 롤링), `tension-camera-moves` (수평선 기울기 긴장감), `overhead-camera-moves` (탑뷰 대규모 패닝), `whip-pan` (휩 팬), `orbit-drift` (궤도 드리프트)
`typography` (텍스트 타이포그래피)	`cards/typography/` (52장)	제목 엔트리, 자막 리듬, 핵심 문장 강조, 코드 터미널, 문자 디코딩	`split-flap-flip` (공항 복고 기계식 뒤집기), `scramble-decode` (잡음 매트릭스 디코딩), `halation-bloom` (필름 붉은 빛 과다 노출), `type-rhythm-sync` (비트 자막 정렬), `tracking-expand-reveal` (자간 확장 공개), `terminal-typewriter` (해커 터미널 타자기), `keyword-reveal` (키워드 점진적 표시), `quote-card` (우아한 명언 카드), `highlighter-sweep` (형광펜 밑줄 표시), `cel-flash-stomp` (스톱모션 강한 임팩트 스트로브)
`interaction` (컴포넌트 및 상호작용)	`cards/interaction/` (58장)	실물 모방, 상호작용 위젯, 부유 카드, 팝업 및 커서 협업	`command-palette-summon` (Cmd+K 부유 소환), `stack-reveal` (카드 접힘 펼침), `popup-book-rise` (종이 공예 팝업북 솟아오름), `masking-tape-slap` (마스킹 테이프 부착), `autolayout-gap-dial` (자동 레이아웃 다이얼), `carousel-3d` (3D 캐러셀), `theme-switch-moves` (테마 전환 리플), `collab-cursor-moves` (다중 커서 협주곡), `type-and-filter` (입력 필터), `glassmorphism-card` (유리 모프 패널)
`data` (데이터 및 차트)	`cards/data/` (20장)	물리적 파티클 침강, 동적 꺾은선/막대 그래프, 대시보드, 숫자 질주	`particle-sand-fill` (중력 낙사 침강), `counter-confetti` (숫자 질주 + 색종이 조각), `number-counter` (롤링 카운터), `chart-grow` (막대/꺾은선 성장), `chart-live-moves` (실시간 데이터 스트림), `gauge-readout-moves` (게이지 바늘 점프), `before-after-slider-scrub` (전후 비교 슬라이더), `scroll-brake-moves` (스크롤 브레이크 정지)
`effects` (특수 효과 및 조명)	`cards/effects/` (22장)	렌즈 플레어, HUD 스캔 조준선, 3D 자전 결정, 분위기 미립자 장	`three-crystal` (Three.js 3D 자전 결정), `light-play-moves` (스캐닝 라이트 확산), `spotlight-sweep-moves` (서치라이트 그림자), `glow-flyline-moves` (발광 비행선 궤적), `fui-hud-moves` (기술 와이어프레임 확장), `impact-feedback` (애니메이션 강한 임팩트 충격파), `canvas-particles` (수만 개 흐르는 미립자), `flying-words` (단어 구름 이동)
`rhythm` (편집 및 리듬)	`cards/rhythm/` (8장)	리듬 프레임 드롭, 플래시 컷 중단, 분할 화면 대결, 몽타주 컷	`beat-cut-moves` (비트 플래시 빠른 컷), `speed-ramp-freeze` (변속 정지 주석), `quad-split-parallel-scenes` (4분할 화면 평행 시선), `panel-grid-moves` (만화 컷 재배열), `rhythm-interrupt-moves` (점프 컷 강한 추진), `trailer-grammar-moves` (예고편 강한 임팩트 블랙 스크린)
`commercial` (상업 장면)	`cards/commercial/` (43장)	제품 프레젠테이션 장면, 브랜드 오프닝/엔딩, 오프닝 주제, 최종 랜딩	`hook` (페인 포인트 후크 장면), `price-card` (가격 및 플랜 카드), `features` (기능 목록 스트림), `store-card` (매장 및 위치 안내), `fact-sheet` (사실 설명 목록), `brand-ink-open` (잉크 확산 오프닝), `logo-shrink-wordmark-lockup` (로고 축소 최종 랜딩), `ui-to-brand-morph` (UI가 브랜드 로고로 변형)
`transition` (장면 전환)	`cards/transition/` (26장)	장면 경계의 시공간 변환 및 시선 전환, 어색한 점프 컷 제거	`cube-rotate` (3D 큐브 다차원 뒤집기), `clock-wipe` (시계 바늘 지우기), `bubble-swarm-takeover` (버블 떼 마스크), `color-block-step-wipe` (색상 블록 단계별 지우기), `paper-plane-messenger` (종이비행기 이동), `push-through` (관통 추진), `whip-pan` (고속 휩 팬 블러), `dark-tunnel` (어두운 터널 이동)
`media` (멀티미디어 디스플레이)	`cards/media/` (15장)	외부 이미지, 비디오 클립의 엔트리 구성 및 PIP 비교	`media-pop-in` (가볍고 빠른 팝인), `split-compare` (좌우 분할 화면 슬라이더 비교), `svg-path` (벡터 경로 확장), `video-pip-float` (부유 PIP), `photo-polaroid-scatter` (폴라로이드 사진 흩뿌리기)

기반 베이스 (cards/_shared/): 전체 라이브러리에서 공통으로 사용하는 렌더링 프리미티브(예: SpeedBlur 동적 블러, softShadow 이중 레이어 물리적 부드러운 그림자, Stage 스테이지 라이트 반사판) 및 상업용 타이포그래피 글꼴 크기 자동 계산을 제공하며, 독립 카드로 외부에 노출되지 않습니다.

3. 6대 영상 유형별 클래식 영감 조합 패러다임 (참고용, 자유로운 혁신 장려)

다음은 일반적인 스타일에 대한 영감 조합 참고일 뿐이며, 고정된 규칙이 아닙니다. 에이전트는 실제 창의성에 따라 자유롭게 혼합하여 사용할 수 있습니다.

과학 및 전문 교양 (Science Explainer):
- 영감 조합: typography/scramble-decode (문자 디코딩 돌파) + data/particle-sand-fill (물리적 낙사 규모 시연) + media/svg-path (개념 연결선) + transition/color-block-step-wipe.
철학 사변 및 심층 산문 (Philosophical Essay):
- 영감 조합: typography/halation-bloom (하이라이트 필름 오버레이) + camera/dolly-zoom (공간 깊이 이탈) + typography/quote-card (우아한 인용) + effects/canvas-particles (미약한 부유 먼지).
기술 제품 및 기능 출시 (Product Promo):
- 영감 조합: effects/three-crystal (3D 구성 요소 등장) + interaction/command-palette-summon (생산성 호출) + data/counter-confetti (성능 기록 경신) + transition/cube-rotate.
비즈니스 전략 및 데이터 대시보드 (Business & Strategy):
- 영감 조합: data/gauge-readout-moves (게이지 바늘) + data/chart-live-moves (곡선 성장) + typography/highlighter-sweep (데이터 마킹) + transition/clock-wipe.
음악 감정 및 동적 MV (Music Story & Lyrics):
- 영감 조합: typography/type-rhythm-sync (메인 비트 자막) + typography/cel-flash-stomp (코러스 스톱모션 강세) + camera/shot-crash-zoom-punch (강한 임팩트 충돌) + transition/whip-pan.
복고 수작업 및 스크랩북 (Scrapbook & Handcrafted):
- 영감 조합: interaction/masking-tape-slap (테이프 부착) + interaction/popup-book-rise (팝업북 솟아오름) + typography/split-flap-flip (기계식 뒤집기) + transition/paper-plane-messenger.

4. 4-슬롯 조립 규칙 및 객관적 품질 레드라인

각 스토리보드는 film.json의 motion 속성에서 4개의 분리된 슬롯을 지원합니다:

{
  "motion": {
    "camera": { "cardId": "camera/slow-push", "params": { "scale": 1.15 } },
    "primary": { "cardId": "data/particle-sand-fill", "params": { "gravity": 1.2 } },
    "text": { "cardId": "typography/halation-bloom", "params": { "bloomIntensity": 0.8 } },
    "transitionOut": { "cardId": "transition/cube-rotate", "params": { "direction": "left" } }
  }
}

객관적 품질 레드라인 (반드시 준수):
1. 명확한 시각적 초점: 동일한 스토리보드에서 화면은 명확한 주인공이 있어야 합니다. 격렬한 primary 컴포넌트 모션을 사용하는 경우, 카메라 무빙 camera는 안정적으로 호흡해야 합니다. 카메라 무빙이 강한 shot-crash-zoom-punch를 사용하는 경우, 컴포넌트 콘텐츠는 상대적으로 정적 상태를 유지하여 시각적 어지러움을 방지해야 합니다.
2. 충분한 인지 체류 시간 (Cognitive Hold Time): 모션 효과가 완전히 진입 및 전개된 후, 화면 텍스트와 핵심 구조는 최소 45~90프레임 (1.5초 ~ 3.0초)의 안정적인 체류 시간을 확보해야 합니다. 시청자가 여유롭게 읽고 이해할 수 있도록 하며, 애니메이션이 끝나자마자 즉시 전환하는 것을 엄격히 금지합니다.
3. 텍스트 길이와 화면 비율 매칭: 가로 화면 한 줄 텍스트는 22자(한국어 기준 약 22자, 영어 기준 약 40자)를 초과하지 않는 것이 좋습니다. 세로 화면 한 줄은 14자(한국어 기준 약 14자)를 초과하지 않는 것이 좋습니다. 줄바꿈 중복이나 비디오 안전 영역 이탈을 방지합니다.

5. Film IR 스토리보드 프로토콜 및 멀티 기술 스택 렌더링 규칙

film.json은 전체 프로젝트의 유일한 의미론적 소스 트루스입니다.

1. 표준 Film IR 구조

{
  "id": "project-slug",
  "title": "프로젝트 비디오 제목",
  "genre": "explainer",
  "brief": {
    "goal": "핵심 내러티브 목표",
    "audience": "대상 청중",
    "tone": "기조 분위기"
  },
  "output": { "width": 1920, "height": 1080, "fps": 30 },
  "theme": {
    "background": "#0a0f1d",
    "foreground": "#f8fafc",
    "accent": "#38bdf8",
    "fontFamily": "Inter, Noto Sans KR, sans-serif"
  },
  "scenes": [
    {
      "id": "scene-01",
      "title": "장면 이름",
      "intent": "내러티브 의도",
      "semantic": "hook",
      "durationInFrames": 90,
      "onScreenText": ["실제 화면 주 제목", "부제목 설명 카피"],
      "layout": { "kind": "center-headline" },
      "renderer": "html",
      "sceneComponent": "scene/stack-explainer",
      "motion": {
        "camera": { "cardId": "camera/slow-push" },
        "primary": { "cardId": "interaction/stack-reveal" },
        "text": { "cardId": "typography/scramble-decode" },
        "transitionOut": { "cardId": "transition/cube-rotate" }
      },
      "props": {},
      "qa": { "keyFrames": [20, 45, 80] }
    }
  ]
}

2. 이중 모드 자동 적응 메커니즘 (16:9 ↔ 9:16)

모든 장면과 카드는 통일된 반응형 크기 조정을 지원합니다. 스토리보드 코드에서 기본 비율 컨테이너를 사용합니다:

import React from 'react';
import { useVideoConfig } from 'remotion';

export const AdaptiveStage: React.FC<{ children: React.ReactNode }> = ({ children }) => {
  const { width, height } = useVideoConfig();
  const isPortrait = height > width;
  const baseWidth = isPortrait ? 1080 : 1920;
  const baseHeight = isPortrait ? 1920 : 1080;

  // 기준 해상도 기반의 스케일 계수를 계산하여 중앙 정렬
  const scaleFactor = Math.min(width / baseWidth, height / baseHeight);
  return (
    <div style={{ position: 'relative', width: '100%', height: '100%', display: 'flex', justifyContent: 'center', alignItems: 'center' }}>
      <div style={{ width: baseWidth * scaleFactor, height: baseHeight * scaleFactor, position: 'relative', overflow: 'hidden' }}>
        {children}
      </div>
    </div>
  );
};

3. 명시적 렌더러 선언

각 스토리보드에는 사용할 기술 스택을 설정하는 renderer 필드가 포함되어야 합니다:

html (기본값): React DOM + CSS 애니메이션 (대부분의 텍스트와 UI 장면에 적합).
canvas: useCanvas() 훅을 제공하는 Canvas 2D 컴포넌트 (파티클, 데이터 시각화, 그래픽 이펙트에 적합).
svg: <svg> 래퍼 컴포넌트 (로고 애니메이션, 경로 그리기, 마스크에 적합).
three: @remotion/three의 <ThreeCanvas> 컴포넌트 (3D 객체 및 공간 이펙트에 적합).

canvas, svg, three 렌더러는 렌더링 엔진에 자동 선택을 트리거하므로 수동 전환이 필요 없습니다.

6. CLI 도구 체인 전체 수명 주기 및 로컬 워크벤치 상호 작용

이 시스템은 완전한 CLI 명령어 세트를 제공합니다. 프로젝트의 package.json에 "forge" 스크립트로 등록되어 있으므로 npm run forge -- <command> 형식으로 실행합니다:

1. 프로젝트 시작

npm run forge -- create --dir /absolute/path/to/project --input <input-url|local-path|theme-text> [--audio-kind song|instrumental] [--name <project-id>]

2. 품질 게이트 명령어

# G1 확인: 디자인 검토 문서 생성 및 제출
npm run forge -- submit-design --project <project-id> [--open]

# G1 승인 (사용자 확인 후)
npm run forge -- approve-design --project <project-id>

# G2: 샘플 장면 렌더링
npm run forge -- render --project <project-id> --scope sample

# G2 승인 (사용자 확인 후)
npm run forge -- approve-sample --project <project-id>

3. 렌더링 명령어

# 전체 영상 렌더링 (G2 승인 후에만 가능)
npm run forge -- render --project <project-id> [--concurrency 4]

# 특정 장면만 렌더링 (디버깅용)
npm run forge -- render --project <project-id> --scene scene-01

4. 로컬 워크벤치 (개발 서버)

프로젝트 루트에서 다음을 실행하면 Remotion Studio가 열립니다:

npm run forge -- studio --project <project-id>

이 워크벤치는 다음과 같은 기능을 제공합니다:

개별 장면 미리보기: 스토리보드 탐색기와 타임라인 스크러빙.
G1/G2 검토 패널: film.json 및 G2 샘플 장면에 대한 즉시 피드백.
데이터 검사기: 현재 Film IR 상태, props 흐름 및 모션 카드 매개변수의 실시간 보기.
문제 진단: 분리 위반, 종속성 오류 및 자산 누락에 대한 자동 검사.

5. 검증 명령어

npm run forge -- validate --project <project-id>

이 명령어는 프로젝트 독립성의 5가지 핵심 규칙을 자동으로 검사합니다:

경로 검사: 모든 import가 프로젝트 내 절대 경로이거나 상대 경로인지 확인하고, 외부 또는 Skill 디렉토리 경로가 없는지 확인.
자산 검사: public/ 디렉토리 아래에 등록된 모든 자산이 존재하는지 확인.
종속성 검사: file: 종속성 또는 외부 심볼릭 링크가 없는지 확인.
스토리보드 프레임 검사: scene 컴포넌트가 절대 프레임 번호를 사용하지 않는지 확인.
Film IR 일관성 검사: film.json의 장면 ID와 프로젝트 scenes/ 디렉토리의 컴포넌트가 일치하는지 확인.

7. 최종 전달 및 문제 해결 체크리스트

최종 전달 품목 (최종 렌더링 전 확인)

G1/G2 게이트가 모두 통과되었습니까? (승인 레코드 존재)
오디오 트랙이 정확하게 동기화되었습니까? (특히 나레이션과 배경 음악의 볼륨 밸런스)
부재 자산이 없습니까? (검증 명령어 실행)
프로젝트가 독립적이며 외부 종속성이 없습니까? (심볼릭 링크, 외부 절대 경로)
최종 출력 해상도와 프레임 레이트가 요구 사항을 충족합니까?
최종 비디오는 필수 사회적 미디어 안전 영역(예: TikTok의 안전 영역)의 텍스트를 준수합니까?

일반적인 문제 해결

문제점	가능한 원인	해결 방법
렌더링 중 블랙 스크린	scene 컴포넌트에서 `useCurrentFrame()`을 사용하지 않거나, 절대 프레임 잘못 사용	scene 컴포넌트가 로컬 프레임만 사용하고 `DurationInFrames` 내에서 올바르게 렌더링되는지 확인
자막과 오디오 동기화 불일치	G2 단계에서 오디오 트랙이 올바르게 로드되었는지 확인하지 않음	`assets.json`에서 오디오 파일이 올바르게 가리키고 있는지 확인하고, 로컬 사본을 다시 다운로드
텍스트가 화면 가장자리를 넘어감	`AdaptiveStage` 컨테이너를 사용하지 않거나, 안전 영역을 확인하지 않음	화면 가장자리에 최소 5% 여백을 유지하고, 더 짧은 텍스트로 변경
`Math.random()`을 사용했으나 일관성 없는 출력 확인	시드를 설정하지 않은 `Math.random()`을 사용	Remotion의 `random(seed)`로 변경
`npm run forge` 명령어를 찾을 수 없음	`package.json`에 `forge` 스크립트가 등록되지 않음	`package.json`에 `"forge": "ts-node src/cli/index.ts"` 추가하고 `npm ci` 재실행

이 Skill 시스템의 최종 해석권은 SKILL.md에 있습니다. 이 문서는 최신 관리 지침을 따릅니다. 특정 파이프라인에 대한 자세한 내용은 해당 파이프라인 파일을 참조하십시오.

hyqlai/motion-forge

motion-forge란 무엇인가요?

즐겨 사용하는 AI에게 물어보기

문서