AgentMotion — 순수 코드 기반 비디오 생성 통합 프레임워크
"한 줄 명령"을 코드로 완전히 그려낸 MP4로 변환합니다. 이 스킬은 오케스트레이션 레이어입니다: 백엔드 선택, 스타일 선택, 프로세스 진행, 품질 검사를 도와줍니다. 구체적인 그리기 지식은 references/와 styles/에 있습니다.
핵심 불변 규칙 (모든 백엔드 공통)
모든 프레임은 프레임 번호의 순수 함수: frame = f(t). Math.random()(시드 기반 무작위 사용), Date.now(), rAF 누적 상태를 사용하지 마세요. 이것이 결정론적 렌더링, 병렬 프레임 생성, 프레임별 자가 검사가 가능한 전제 조건입니다. 이를 위반하면 렌더링과 미리보기가 일치하지 않습니다.
첫 번째 단계: 백엔드 선택 (결정 트리)
| 시나리오 | 백엔드 | 참고 |
|---|---|---|
| 짧은 영상(≤60초), 외부素材 없음, 일러스트/손그림/스타일화 | 단일 파일 HTML Canvas | references/backends.md §1 |
| 데이터 기반, 배치 개인화(데이터 하나당 영상 하나), 자막/내레이션 오버레이, 3D/차트 컴포넌트 생태계 | React + Remotion | references/backends.md §2 |
| 웹 페이지에서 직접 재생되는 인터랙티브 애니메이션(MP4 불필요) | 단일 파일 HTML, HTML 전달(렌더링 대신) | references/backends.md §3 |
확신이 없으면 Canvas 단일 파일을 선택하세요: 의존성이 가장 적고 에이전트가 한 번에 제대로 작성하기 가장 쉽습니다.
두 번째 단계: 스타일 선택
styles/recipes.md 확인 (15가지 상용급 스타일: 색상 팔레트 / 핵심 기법 / 모션 법칙 / 함정 피하기). 사용자가 스타일을 지정하지 못하면 선택하도록 하거나 주제에 따라 추천하세요. 서로 다른 두 영상은 기본적으로 동일한 비주얼 및 배경 음악을 재사용하지 않습니다.
세 번째 단계: 표준 워크플로 (중간에 멈춰서 묻지 않기)
- 문제 분석: 사용자 입력에서 영상 유형(스토리/설명/요약/루프/데이터 영상), 길이(기본 15-20초), 화면비(기본 1920×1080; 데이터 공유 영상은 1080×1920)를 추론합니다. 자막 언어는 사용자 입력 언어를 따릅니다.
- 스토리보드: 먼저 BPM과 섹션 데이터(
SECTIONS/SHOTS/EVENTS)를 결정합니다. 비주얼과 배경 음악이 동일한 시간 데이터를 읽으므로 오디오와 비주얼이 자연스럽게 정렬됩니다. (references/storyboard.md). - 골격 구축:
templates/starter.html(Canvas 백엔드)을 복사하고 색상 팔레트와 월드 드로잉을 교체합니다. 계약 유지: 페이지가window.C2V = { fps, frames, width, height, draw(frame) }을 노출하고,draw는 순수 함수여야 합니다. - 자가 검사 후 렌더링 (순서 바꾸지 않음):
node scripts/render.mjs film.html sheet.jpg --sheet 1 # 1프레임/초 콘택트 시트, 컷 오프
node scripts/render.mjs film.html still.png --stills 0,90,300 # 특정 시점 스틸
node scripts/env-check.mjs # 환경 점검
node scripts/render.mjs film.html out.mp4 --audio music.mp3 # 전체 영상 렌더링 (선택적 배경 음악)
node scripts/probe.mjs out.mp4 1920x1080 30 # 인코딩 매개변수 확인
- 두 번의 육안 검사 (
references/qc.md): ① 스토리보드 일치도 — 각 샷의 액션 비트에서 프레임 캡처하여 스토리보드 행과 대조 확인; ② 감독 검토 — 콘택트 시트 검토, 리듬/샷 다양성/데드 프레임/각 액션에 소리가 있는지 평가. 최소 두 번 수행하며, 수정할 프레임만 다시 렌더링합니다. - 전달: MP4 + HTML (HTML은 브라우저에서 직접 재생 가능). 마지막에 변경 가능한 항목(스타일 변경, 배경 음악 변경, 길이 변경)을 한두 문장으로 제공합니다.
Remotion 백엔드의 렌더링 및 검증은 npx remotion still → 육안 검사 → npx remotion render를 사용합니다 (references/backends.md §2 참조).
실패 방지 규칙 (가장 빈번한 실패)
- 순수 함수. 어떤 상태 누적이든 병렬 렌더링에서 프레임 오류를 발생시킵니다.
- 손그림 선은 '끓어오르는' 느낌이어야 하지 '떨리는' 느낌이 아니어야 함: wobble 시드는 4프레임마다 변경(≈7.5회/초), 매 프레임 변경은 노이즈로 읽힙니다.
- 신체는 타원과 둥근 모서리 사각형 사용, 다각형 포인트가 많으면 도로 표지판처럼 보입니다.
- 그리기 순서는 명시적으로 뒤에서 앞으로, 대부분 '얼굴이 가려지는' 문제는 그리기 순서 때문입니다.
- 텍스트는 절대 충돌하지 않음: 텍스트 블록과 주요 객체에 점유 공간(claim)을 할당하고, 전달 전에 프레임별로 레이아웃을 확인합니다.
- 컷과 액션 포인트는 비트에 맞춰야 하며, 음량 점프가 ≤+6dB여야 합니다. 그렇지 않으면 놀라는 듯이 읽힙니다 (
references/audio.md).
파일 맵
| 파일 | 내용 |
|---|---|
scripts/render.mjs | 결정론적 렌더링 코어: MP4 / 스틸 / 콘택트 시트, 다중 워커 병렬 처리 |
scripts/env-check.mjs / probe.mjs | 환경 점검 / MP4 인코딩 확인 |
templates/starter.html | 프레임=f(t) 골격: 계약, 시드 기반 무작위, 이징, 카메라, 비트 |
styles/recipes.md | 15가지 스타일 코드 수준 레시피 |
references/*.md | 워크플로 / 스토리보드 / 기법 / 품질 검사 / 배경 음악 / 백엔드 선택 |
examples/hello-drop.html | 즉시 실행 가능한 최소 예제 |
의존성
Node 18+, ffmpeg (PATH 접근 가능), Chrome 또는 Edge; npm i playwright-core (프로젝트 디렉토리에 설치, 이 스킬 디렉토리가 아님).