marwanhattar94/remotion-motion-graphics

Remotion 모션 그래픽

Remotion은 React 컴포넌트를 프레임별로 비디오로 렌더링합니다. 코드 품질이 병목이 아닙니다. 모션 디자인 기술이 병목입니다. 훈련되지 않은 생성은 선형 이징, 불투명도만 변경하는 페이드, 동시 시작, 평평한 색상, 질감 부재를 만들어냅니다. 이것이 바로 '평범한 AI 비디오'의 모습입니다. 이 스킬은 이를 방지하기 위해 존재합니다.

불가침 규칙 (모든 컴포지션에 적용)

1. 절대 선형 보간을 사용하지 마세요. 모든 interpolate()는 이징 곡선을 가져야 하며, 모든 시작 애니메이션은 spring()을 선호합니다. 항상 extrapolateLeft/Right: "clamp"를 사용하세요.
2. 시작 애니메이션은 2~3개의 속성을 함께 움직입니다. (불투명도 + translateY + scale). 단독 페이드는 금지입니다.
3. 모든 것을 분산(stagger)시키세요. 목록, 단어, 광선, 카드: 3~6프레임 오프셋. 어떤 것도 동시에 시작하지 않습니다.
4. 종료 애니메이션은 존재하며 시작보다 빠릅니다. (~10프레임 vs ~20프레임).
5. 모든 장면에 5레이어 스택, 아래에서 위로: 배경 메시 → 에셋 → 그래픽/타이포 → 컬러 그레이드 → 그레인 + 비네트. 절대 단색 배경을 사용하지 마세요.
6. 모든 정적 이미지에 Ken Burns 효과를 적용하세요. (느린 스케일 1→1.08 + 패닝). 모든 비디오 에셋은 <Video> 대신 <OffthreadVideo>를 사용하세요.
7. 유휴 요소는 숨을 쉬어야 합니다: 화면에 2초 이상 있는 모든 것은 사인파 미세 움직임을 가져야 합니다.
8. 모든 타이밍은 useVideoConfig()를 통해 fps에서 파생됩니다. 마법 같은 프레임 번호는 없습니다.
9. 프로젝트 상단에 하나의 테마 객체 (색상, 이징, 스프링 프리셋, 글꼴). 절대 컴포넌트 내에 헥스 색상이나 이징을 인라인으로 작성하지 마세요.
10. 렌더링하고, 프레임을 추출하고, 살펴보고, 수정하고, 다시 렌더링하세요. 검증되지 않은 렌더링을 절대 전달하지 마세요. 이 루프는 필수입니다 — 아래 검증 섹션을 참조하세요.

워크플로우

단계 1 — 범위 설정

다음을 결정하세요: 지속 시간, fps (기본 30; 빠른 동작이 많을 때만 60), 해상도 (Reels/Shorts는 1080×1920, 가로 영상은 1920×1080), 어떤 에셋이 존재하는지 (이미지, 영상, 오디오, 로고), 그리고 이것이 새 컴포지션인지 기존 프로젝트 편집인지. 기존 프로젝트를 편집하는 경우: 먼저 src/ 전체를 읽고, 테마를 찾거나 (또는 생성하고) 위 규칙을 위반한 부분을 리팩토링한 후 기능을 추가하세요.

단계 2 — 설정

새 프로젝트:

npm install remotion @remotion/cli react react-dom
# 선택 사항: @remotion/transitions @remotion/motion-blur @remotion/google-fonts

이 스킬에서 assets/theme.ts를 src/theme.ts로 복사하고 팔레트를 사용자의 브랜드에 맞게 조정하세요. 구조: src/index.ts (registerRoot) → src/Root.tsx (Composition, duration/fps/size) → src/scenes/*.tsx → src/components/*.tsx. 사용자 에셋은 public/에 넣고 staticFile()을 통해 로드하세요.

단계 3 — 빌드

references/motion-patterns.md에서 재사용 가능한 컴포넌트 구현 (BgMesh, Grade, Grain, Vignette, KenBurns, WordReveal, Stagger, Counter, Spark, transitions, parallax)을 읽으세요. 해당 패턴으로 장면을 구성하세요. 박자, 리듬, 타이포그래피, 컬러 팔레트, 사운드 디자인 규칙은 references/design-rules.md를 읽으세요.

장면 리듬: 강조(HIT) → 유지(15~20 정지 프레임) → 빌드 → 강조(HIT). 처음 15프레임 안에 무언가 움직여야 합니다. 새로운 시각적 요소 없이 90프레임 이상 넘기지 마세요.

단계 4 — 렌더링

npx remotion render src/index.ts <CompId> out/video.mp4 --codec h264 --crf 17

Remotion은 Chromium 바이너리가 필요합니다. 자동 다운로드가 실패하면 (샌드박스, 오프라인 CI) 직접 찾아 명시적으로 전달하세요:

which chromium chromium-browser google-chrome 2>/dev/null
ls /opt/pw-browsers 2>/dev/null   # Playwright 설치 위치
npx remotion render ... --browser-executable=<path>

전체 Chrome에서 "Old Headless mode has been removed" 오류가 발생하면 대신 headless_shell 바이너리를 사용하세요 (Playwright는 chromium_headless_shell-*/chrome-linux/headless_shell로 제공).

단계 5 — 검증 (필수, 절대 생략 불가)

주요 순간의 프레임을 추출하고 각각을 시각적으로 검사하세요. 이식성이 뛰어난 방법 — 시스템 ffmpeg 없이도 작동하며 정확한 프레임을 렌더링합니다:

for f in 15 45 90 150; do
  npx remotion still src/index.ts <CompId> out/check_$f.png --frame $f --overwrite
done

시스템 ffmpeg를 사용할 수 있다면 완성된 mp4에서 추출하여 인코딩 자체도 검증할 수 있습니다 (-ss 시크가 select= 필터보다 이식성이 뛰어나며, select= 필터의 인용 문제는 일부 셸과 Remotion 번들 ffmpeg에서 발생합니다):

ffmpeg -v error -ss 1.5 -i out/video.mp4 -frames:v 1 check_1.png

다음 사항을 찾아 수정하세요 (빈도 순):

• 간격 버그: gap/margin을 em으로 설정하면 부모 글꼴 크기(주로 16px)를 기준으로 적용되므로, 큰 글자 주변 flex 컨테이너에는 px 값을 사용하세요.
• 텍스트가 프레임 가장자리를 넘치거나 닿는 경우 (9:16에서는 중요한 콘텐츠를 세로로 중간 75%에 유지하세요 — 플랫폼 UI가 상단/하단을 덮습니다).
• 시작 전이나 종료 후에 요소가 보이는 경우 (clamp 누락).
• 색상/대비 실패: 프레임당 하나 이상의 요소에 히어로 색상 사용, 어두운 텍스트가 그레이드 위에서 읽히지 않는 경우.
• 레이어 순서 오류 (그레인/비네트는 맨 위에, 그레이드는 콘텐츠 위에 있어야 함). 수정 → 재렌더링 → 재추출 → 재검사. 모든 항목이 깨끗할 때만 전달하세요. 그런 다음 references/design-rules.md 하단의 최종 체크리스트를 실행하세요.

사용자의 기존 영상 편집

처음부터 새로 만드는 대신 기존 mp4를 개선하려면 (자막, 그레이드, 인트로/아웃트로): 파일을 public/에 넣고, 에셋 레이어로 <OffthreadVideo src={staticFile("clip.mp4")} />를 사용하여 렌더링하고, 클립 길이에 맞춰 컴포지션 지속 시간을 설정하고, 그래픽/그레이드/그레인을 위에 쌓으세요. 컴포지션을 설정하기 전에 ffprobe로 클립의 지속 시간과 fps를 확인하세요. 음성에 맞춘 단어 동기화 자막은 references/motion-patterns.md의 자막 섹션을 참조하세요.

참조 파일

• references/motion-patterns.md — 복사-붙여넣기 컴포넌트 라이브러리: 배경, 그레이드/그레인/비네트, Ken Burns, 텍스트 리빌, 카운터, 트랜지션, 패럴랙스, 오디오 동기화, 자막. 컴포넌트를 작성하기 전에 읽으세요.
• references/design-rules.md — 팔레트, 타이포그래피 규칙, 장면 아키텍처, 사운드 디자인, 전달 전 체크리스트. 장면을 디자인하기 전과 최종 전달 전에 읽으세요.
• assets/theme.ts — 모든 프로젝트에 복사할 테마 템플릿.

적극적으로 피해야 할 일반적인 실패 모드

• 아이콘으로 이모지 사용. 이모지는 전체 색상 플랫폼 글리프(초록색 ✳️, 파란색 🌐)로 렌더링되어 팔레트를 무시하고 하나의 히어로 색상 규칙을 조용히 깨며, 지정된 배경 위에 그대로 표시됩니다 (주황색 마스코트가 주황색 타일 위에 있으면 보이지 않음). 테마 색상으로 CSS/SVG를 사용하여 글리프를 그리거나, 추출된 프레임에서 모든 이모지를 확인하세요.
• SFX 에셋이 없다고 해서 무음으로 전달하는 것은 변명이 아닙니다. Node 스크립트로 최소 키트를 16비트 WAV로 합성하세요 (노이즈 버스트 휘파람, 피치 드롭 팝, 사인-썸프 킥/베이스, 불협화음 사인 패드) → public/sfx/에 저장. 다운로드 필요 없음, 완전히 결정적입니다.
• 주제별로 구성되고 재사용 가능한 조각 대신 하나의 거대한 컴포넌트를 생성하는 것.
• Composition과 장면 콘텐츠 간의 durationInFrames 불일치 (무음 구간).
• 재렌더링 시 --overwrite를 잊고 이전 파일을 검사하는 것.
• 글꼴: 히어로 텍스트에 시스템 기본값을 절대 의존하지 마세요. @remotion/google-fonts 또는 @font-face + staticFile을 통해 디스플레이 글꼴을 로드하세요.
• 결과를 사용자에게 "설명"하는 대신 렌더링하고 검증하는 것을 시도하는 것.