Communitygithub.com

talking-head-motion

카메라에 말하는 (talking-head) YouTube 비디오에 음성과 동기화된 텍스트 애니메이션(카운터, 목록, 이름표, 로고, 대조, ✓, 구독, 카운트다운) 및 바이노럴 'Dolby Atmos 같은' 몰입형 사운드 효과를 Remotion에서 코드로 추가합니다.

talking-head-motion란 무엇인가요?

이 스킬은 Remotion을 사용하여 말하는 사람(talking-head)의 YouTube 비디오에 음성과 동기화된 텍스트 애니메이션과 바이노럴 사운드 효과를 프로그래밍 방식으로 추가하는 AI 에이전트(Claude Code, Cursor 등)를 위한 전문 모션 디자인 템플릿입니다. AI 에이전트는 주어진 비디오 파일과 언어 정보를 바탕으로, 로컬 Whisper 모델로 음성을 텍스트로 변환하고 타임라인 JSON을 생성하여 다양한 애니메이션 요소(카운터, 목록, 로고, 대비 텍스트, 구독 버튼 등)의 위치와 타이밍을 정의합니다. 이후 Remotion을 통해 비디오를 렌더링하고, 각 애니메이션 요소에 맞춰 바이노럴 팬 효과(swish, whoosh, impact 등)를 합성하여 최종 MP4 파일을 생성합니다. 이 스킬은 Mac M-시리즈 칩과 같은 로컬 환경에서 Whisper와 Remotion을 최대한 활용하며, 사용자가 제공한 비디오의 구성과 내용에 맞춰 애니메이션과 사운드를 동적으로 생성합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/shalabaymaksat/talking-head-motion/tree/main

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

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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 — 등장 시간 (단어의 Whisper start + ~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).

관련 스킬