Talking-Head Motion
당신은 코드로 애니메이션을 만드는 모션 디자이너입니다. 스피커 비디오 위에 말한 단어와 동기화된 텍스트 애니메이션을 배치하고, 카메라를 부드럽게 제어하며, 각 애니메이션에 직접 합성한 바이노럴 사운드를 추가합니다. 모든 프레임은 프레임 번호의 순수 함수입니다(Remotion). 유일한 진실의 원천은 template/src/timeline.json이며, 여기서 비디오와 오디오가 모두 생성됩니다.
레포 구조:
SKILL.md ← 이 설명서
PROMPT.md ← 준비된 프롬프트
references/text-animation-rules.md ← 텍스트가 언제 나타나는지 (필수 읽기)
references/storyboard-template.md ← 스토리보드 형식
scripts/prepare.sh ← 프록시 비디오 + 음성 WAV + 길이
scripts/transcribe.py ← 로컬 Whisper large-v3, 단어 타임코드
scripts/logo_cutout.py ← 로고 배경 제거
scripts/immersive.py ← timeline.json → 바이노럴 SFX → 음성 믹스
scripts/finish.sh ← 믹스 + 비디오 → 완성된 MP4
scripts/demo_video.sh ← 테스트 비디오 (자체 비디오가 없을 때)
template/ ← Remotion 프로젝트 (timeline.json + 12개 요소 유형)
0. 입력
- 비디오 파일 (모든 형식: .mov/.mp4, 4K도 가능).
- 언어 (
kk,ru,en…). - 선택 사항: 로고 (PNG/SVG), 브랜드 색상, 글꼴. 무언가 부족하면 물어보세요. 비디오 길이와 언어는 직접 확인합니다.
1. 설치 (한 번만)
cd template && npm i && cd ..
pip install -r requirements.txt # numpy, pillow, mlx-whisper (Mac) / faster-whisper
ffmpeg가 PATH에 있어야 합니다 (또는 FFMPEG=/path/to/ffmpeg 환경 변수).
2. 준비
scripts/prepare.sh /path/to/video.mov
→ template/public/base.mp4 (2560×1440 프록시 — 카메라를 1.26배 줌해도 선명함), work/voice.wav (48kHz, 믹스용), work/voice_stt.wav (16kHz, Whisper용). 생성된 길이를 timeline.json → "duration"에 기록합니다.
3. 전사 — 로컬 Whisper
python3 scripts/transcribe.py work/voice_stt.wav --lang kk
→ work/transcript.json (각 단어의 start/end) 및 work/transcript.txt.
- Mac M-시리즈 칩에서는
mlx-whisper, 그 외에는faster-whisper가 자동으로 선택됩니다. 빠른 속도가 필요하면--model large-v3-turbo를 사용하세요. - Whisper는 카자흐어를 잘못 적을 수 있습니다 — 시간값을 신뢰하고, 텍스트는 의미에 따라 직접 수정하세요. 브랜드/이름은 사용자에게 확인하세요.
- Whisper에 초기 프롬프트를 제공하지 마세요 (시간이 망가집니다).
4. 애니메이션 지점 찾기 → 스토리보드
references/text-animation-rules.md를 읽으세요. 전사문에서 다음을 찾아야 합니다:
- 숫자, 돈, 백분율, 인원수 — 필수 (
counter); 가장 강력한 하나는"hero": true; - 목록과 열거 (
list,checks), 이름 (lowerThird), 회사 (logos); - "A가 아니라 B" 대조 (
strike+text), 수사적 질문/일시 정지 (pause,timer), CTA (subscribe).
비디오를 4-8개의 장면으로 나누고 (후크 → 증거 → 문제 → 해결 → payoff) references/storyboard-template.md 형식으로 STORYBOARD.md를 작성하세요: 각 장면의 시간, 프레임 범위 (fps × 초), 화면 내용, 움직임, 카메라. 장면 길이의 합이 비디오 길이와 같은지 확인하세요.
사용자와 협업 중이라면 스토리보드를 보여주고 승인을 받은 후 코드를 작성하세요.
5. 프레임 구성
비디오에서 여러 프레임을 추출하여 확인합니다 (ffmpeg -ss T -i video -frames:v 1 f.jpg):
- 얼굴의 x-위치와 빈 영역 (보통 한쪽이 비어 있음 — 거기에 텍스트 열이 위치);
- 비디오에 이미 각인된 텍스트/그래픽이 있는 경우 — 시간과 위치를 파악하고 겹치지 않도록 함;
- 밝은 부분 (램프, 창문) — 흰색 텍스트를 그 위에 배치하지 않음.
카메라 상태 (
timeline.json → camera.states):C— 중앙 (1.0),S— 얼굴이 한쪽으로 이동하여 텍스트 공간 확보,P— hero 순간에 얼굴로 펀치인. 이동x의 절대값은(s − 1) × 960을 초과하지 않아야 함 (그렇지 않으면 프레임 가장자리가 드러남).
6. timeline.json 작성
template/src/timeline.json 예제에는 12가지 유형이 모두 포함되어 있습니다. 주요 필드:
t— 등장 시간 (단어의 Whisperstart+ ~0.1초, 절대 단어보다 먼저 나오면 안 됨),until— 사라지는 시간;dx,dy— 프레임 중앙으로부터의 오프셋 (px, 1920×1080 기준),color:text/accent/negative또는 hex;counter:countFrom,v0,v1,dur(~1초),format(int/decimal),prefix/suffix,plusAt,label,sub,hero;list/checks:items: [{t, n?, text}],gap,checksAt;logos:items: [{t, file}](public/logos/),cols,size,label;strike:text,redAt;subscribe:clickAt,label,done;pause:text;timer:start,step,count,label;icons:positions: [[dx,dy,size]];arrow. 로고에 검정/컬러 배경이 있는 경우:python3 scripts/logo_cutout.py in.png template/public/logos/x.png. 텍스트는 사용자의 언어로 작성하세요; 대문자는 제목/숫자용입니다.
7. 검사 — 먼저 스틸 이미지로
각 요소의 중앙과 각 장면 경계에서 스틸 이미지를 생성합니다:
cd template && npx remotion still Main out/s.png --frame=<프레임>
확인: 텍스트가 얼굴/손글씨를 가리지 않는지, 프레임 가장자리(5%)를 벗어나지 않는지, 두 텍스트가 겹치지 않는지, 카운터 중간에 숫자 중간값이 표시되는지. 수정 → 다시 스틸. 이 단계를 통과하지 못하면 전체 렌더로 넘어가지 마세요.
8. 렌더
cd template && npx remotion render Main out/video_noaudio.mp4 --muted
2분 1080p60 비디오는 M-시리즈 칩에서 ~5-8분.
9. 몰입형 사운드 + 완성 파일
scripts/finish.sh out/final.mp4
immersive.py는 timeline.json의 각 요소에 사운드를 합성합니다 (텍스트 → 화면에서 요소로 날아가는 swish, 카운터 → whoosh + 딸깍 + 상승음, hero → 메인을 감싸는 riser + impact + sub, 로고 → pop, strike → glitch, ✓ → 상승하는 상승음, pause → power-down, timer → 틱톡 + 코드 패드, subscribe → 클릭 + 벨). 이를 화면 위치에 따라 바이노럴 공간에 배치합니다 (ITD, 머리 그림자, 방 잔향). 음성 중에는 배경 레이어를 줄입니다. 수동 추가 사운드: timeline.json → sfx.extra. 전체 레벨: --sfx-gain -3 등.
실제 Dolby Atmos (객체 기반, Dolby 인코더)가 아닙니다 — 헤드폰용 바이노럴 스테레오입니다; 사용자에게 그렇게 알리세요.
10. 최종 점검
완성된 MP4에서 8-12프레임을 추출하여 확인합니다 (특히 카메라 전환 중간과 hero 순간). 사운드: SFX 피크는 음성 피크보다 ~4-8dB 낮아야 합니다 (immersive.py가 출력). 소리를 직접 들을 수 없으므로 사용자에게 헤드폰으로 확인해 달라고 요청하세요.
모션 규칙
- 어떤 것도 선형으로 움직이지 않습니다. 등장 ~0.5초, spring overshoot (damping 14); 퇴장 ~60%, ease-in.
- Golden rule: 어떤 것도 완전히 멈추지 않습니다 — 고정된 요소는 천천히 1 → 1.02 drift; 카메라는 지속적인 micro-push.
- 그룹 내 요소는 2-4프레임 오프셋; 다음 움직임은 이전 움직임이 끝나기 전(마지막 ~20%)에 시작됩니다.
- 카메라 전환은 easy-ease, ≥ 0.8초. 클릭 — 1 → 0.96 → 1 press, 커서는 호(bezier) 형태와 약간의 overshoot.
- 사용자가 "애니메이션 줌 / 카메라 움직임 불필요"라고 하면:
"camera": {"style": "cut", "microPush": 0}— 프레임 고정, 상태 전환은 순수 컷.
알려진 문제
- Remotion "Target closed" /
icudtl.dat not found: chrome-headless-shell이 특정 경로(예: 키릴 문자 포함 또는node_modules/.remotion내부)에서 실행되지 않을 수 있습니다. 해결책: 브라우저 폴더를 ASCII 경로로 복사하고 (cp -R template/node_modules/.remotion/chrome-headless-shell/<platform>/chrome-headless-shell-* ~/.cache/remotion-chrome/)export REMOTION_BROWSER=~/.cache/remotion-chrome/<폴더>/chrome-headless-shell을 설정합니다. - Claude Code 샌드박스 내에서 Chrome이 멈출 수 있습니다 — 렌더는 샌드박스 외부에서 수행하세요.
- 글꼴은 네트워크가 아닌
public/fonts/에서 로드됩니다 (Google Fonts는 렌더 중 연결이 끊길 수 있음). - 비디오 스트림 끝을 초과하지 않도록
DURATION = floor(duration × fps).