Code-to-Video Explainer Studio (범용 코드화 애니메이션 비디오 엔진)
📘 상세 사용 설명서 전체는 다음을 참조하세요: README.md (환경 점검, 6가지 스타일 가이드, 더빙方案, 크로스 Agent 마운팅 및 일반적인 문제 해결 매뉴얼 포함).
본 스킬은 파일 읽기/쓰기 및 명령줄 실행이 가능한 모든 AI Coding Agent(Claude Code, Codex, DeepSeek Harness, OpenHands/OpenClaw, Antigravity, Cursor 등)를 전문 비디오 총감독, 애니메이션 프로그래머 및 프로듀서로 변모시킵니다. 로컬 코드 기반 비디오 렌더링 엔진을 구동하여 모든 텍스트, 코드 저장소, 논문 또는 아이디어를 1080p 60fps 잉크 종이 질감의 고화질 애니메이션 설명 동영상으로 신속하게 변환합니다.
핵심 3대 철칙 (모든 Agent는 반드시 준수해야 함)
- 먼저 스토리보드를 승인받고, 그다음 코드를 작성하라(Human-in-the-Loop):
사용자가
storyboard.json을 명확히 확인하기 전까지 절대 구체적인 페이지 코드를 작성하거나 최종 렌더링을 실행해서는 안 됩니다. - 시간은 순수 함수 $Visual = f(t)$:
페이지 코드는 시간 독립 변수 $t$의 순수 함수여야 합니다. 절대
Math.random()(난수는 반드시PV.rng(seed)사용),Date.now(), CSS 트랜지션/requestAnimationFrame을 사용해서는 안 됩니다. - 자막 회피 영역(Safe Zone):
캔버스 크기는 1920×1080입니다. 하단 영역 $y > 900$은 자막 전용 구역이므로 어떤主体 도형이나 텍스트도 배치해서는 안 됩니다; 콘텐츠 주요 활동 영역은
x: 140~1780, y: 180~880을 유지해야 합니다.
제작 파이프라인 (표준 5단계 작업법)
1단계: 자료 소화 및 스토리보드 디자인 (Storyboard)
사용자가 비디오 제작을 요청하거나 자료를 제공할 때:
- 핵심 은유 설정: 전체 영상을 관통하는 하나의 구체적인 사물을 결정합니다 (예: 어텐션 메커니즘 설명에는 "스포트라이트", 캐시 설명에는 "책상 위의 포스트잇", 유체 방정식 설명에는 "수조와 수도관").
- 내러티브 구조 계획:
- Hook(처음 3초 갈고리): 반직관적인 질문이나 핵심 고통점을 제시합니다.
- Intuition(직관 확립): 핵심 비유를 도입합니다.
- Mechanism(원리 분석): 핵심 공식이나 단계를 분해합니다.
- Example & Numbers(예시와 계산): 구체적인 데이터로 한 번 실행해 봅니다.
- Close(승화 및 마무리): 처음과 끝을 맞추고 시작 부분의 갈고리에 답합니다.
- 스토리보드 구조 생성:
4
8페이지 분량의 스토리보드 개요를 출력하며, 각 페이지에4개의id,section,say(대본 개요) 및 2beats(구체적인 동작 비트, object, action, text, camera 포함)를 명확히 기재합니다. - 사용자 확인 요청: 스토리보드를 사용자에게 제시하며 질문합니다: "스토리보드 개요가 생성되었습니다. 각 페이지 구조와 내러티브 템포를 확인해 주십시오. 이상이 없으면 코드 드로잉 단계로 넘어가겠습니다."
자세한 규격과 구조 템플릿은 다음을 참조하세요: STORYBOARD_RULES.md
2단계: 대본 및 타임라인 생성 (Script & Narration)
스토리보드 확인 후 script.js를 확정합니다:
- 각 페이지의 구체적인 나레이션 대사를 추출하고 16자(한국어 기준)를 초과하지 않는
cues(자막 단문)로 분할합니다. - 음성 엔진(로컬
CosyVoice 3포트 9880, Edge-TTS 또는 환경 변수의VOLCENGINE_TTS_API_KEY/ELEVENLABS_API_KEY)을 호출하여 각 문장의 오디오를 생성합니다. - 실제 읽기 시간 스탬프를 추출하여 각
cue에 물리적 시간점(P.c(i)시작 시점,P.cw(i, '키워드')단어 수준 적중 시점)을 부여합니다.
3단계: 페이지별 애니메이션 프로그래밍 (Page Drawing Code)
각 페이지 화면은 pages/pNN.js 파일에 해당하며, 엔진 선언형 API를 사용하여 작성합니다:
ENGINE.visual('p01', (P) => {
P.title('① 핵심 원리 직관', { accent: 'orange' });
// 나레이션 0번째 문장 바인딩하여 메인 카드 펼치기
P.card(200, 260, 700, 480, { title: '입력 특징', at: P.c(0) });
// 특정 단어 발화 시 화살표 및 하이라이트 트리거
P.arrow(920, 500, 1100, 500, { at: P.cw(1, '변환') });
// 수학 공식 단계적 유도
P.mathDecompose(1140, 400, 600, {
title: '어텐션 점수',
terms: [
{ latex: 'Q K^T', name: '쿼리와 키 곱', color: 'blue', at: P.c(2) },
{ latex: '\\sqrt{d_k}', name: '스케일링 팩터', color: 'orange', at: P.c(3) }
]
});
});
팁: 하위 에이전트나 병렬 작업을 지원하는 Agent 환경에서는 여러 하위 Agent를 파견하여 서로 다른 페이지를 병렬로 동시에 작성하여 생성 속도를 높일 수 있습니다.
전체 API 문법 및 컴포넌트 목록은 다음을 참조하세요: API.md
4단계: 기하학 및 시각 자가 점검 루프 (Automated QA Loop)
코드 작성이 완료되면 반드시 자가 점검을 실행해야 하며, 절대 건너뛰어서는 안 됩니다:
- 프로젝트 디렉토리에서 자가 점검 도구를 실행합니다:
node engine/tools/check.mjs --only p01 - 피드백 처리:
Collision detected또는Safe zone overlap메시지가 나타나면:- 출력에서
Fix suggestion: ...을 추출하여 제안된 좌표를 그대로pages/pNN.js의 좌표 값에 적용합니다.
- 각 페이지가 모두 녹색 통과(Passed) 상태가 될 때까지 자가 점검을 반복합니다.
5단계: 1080p 멀티코어 헤드리스 압축 렌더링 (Render)
모든 페이지 자가 점검 통과 후 병렬 렌더링 명령을 실행합니다:
# 16:9 가로 1080p 60fps 렌더링 (하드웨어 가속 지원)
node engine/tools/render.mjs --fps 60 --workers 4 --hw
- 출력 위치는
<프로젝트 디렉토리>/out/입니다:<프로젝트명>-with-subtitles.mp4(정확한 이중 언어 자막 포함)<프로젝트명>-no-subtitles.mp4(자막 없는 순수 버전)- 게시용 카피와 각 챕터 시간 스탬프.
빠른 실행 모드: 완전 자동 원클릭 영상 제작 (CLI Run)
사용자가 완전 자동으로 엔드투엔드 초안 비디오를 원하는 경우 프로젝트 루트 디렉토리에서 통합 자동화 CLI를 직접 호출할 수도 있습니다:
# 엔드투엔드 완전 자동 실행 (문서 자동 분석 -> 스토리보드 생성 -> 페이지 생성 -> 인코딩 완료)
node apps/cli/dist/cli.js run <자료 파일 경로> --style warm-story --duration 60
또는 실시간 타임라인 미리보기가 필요할 때 웹 작업대를 시작합니다:
node apps/cli/dist/cli.js serve
범용 Agent 크로스 플랫폼 호출 가이드 (Universal Compatibility)
본 스킬은 특정 Agent 실행 환경에 종속되지 않으며, Node.js 환경과 파일 읽기/쓰기 능력만 충족하면 됩니다:
- Claude Code: 프로젝트 루트 디렉토리의
CLAUDE.md에서 본 파일을 참조하면 전역적으로 적용되거나 사용자 정의 명령으로 사용할 수 있습니다. - OpenHands / OpenClaw: 본 스킬 디렉토리를 프로젝트 내에 배치하고
AGENTS.md에서 선언하면 자동으로 마운트됩니다. - DeepSeek Harness / 자체 구축 Agent: System Prompt 또는 Skill Tool Context로 대형 모델에 직접 주입합니다.
- Cursor / Windsurf: 대화 중
@SKILL.md를 통해 호출합니다.