Remotion
Remotion은 React 컴포넌트를 비디오로 변환합니다. JSX를 작성하면 Remotion이 고정된 fps로 각 프레임마다 컴포넌트를 한 번씩 호출하고, 결과 프레임을 MP4(또는 다른 형식)로 결합합니다.
핵심 개념
Remotion은 프레임 번호와 빈 캔버스를 제공합니다. React 컴포넌트가 해당 프레임에 무엇을 렌더링할지 결정합니다.
명령형 의미의 애니메이션 타임라인은 없습니다. 시간은 숫자 (frame)이며, 컴포넌트는 해당 숫자와 props의 순수 함수입니다. 이것이 애니메이션이 반드시 useCurrentFrame()으로 구동되어야 하는 이유입니다. CSS 전환과 setTimeout은 렌더링 중 비결정적이므로 깜빡이거나 동기화가 깨집니다.
이 스킬을 사용해야 하는 경우
- 사용자가 Remotion 프로젝트(
remotion.config.ts또는package.json에@remotion/*있음)를 가지고 있고 컴포지션을 빌드, 변경 또는 디버깅하려는 경우 - 사용자가 "Remotion / 코드 / 프로그래매틱 방식으로 비디오를 만들자"고 말하는 경우
- 사용자가 Remotion 오류를 붙여넣거나
interpolate,spring,Sequence,useCurrentFrame,Composition등에 대해 묻는 경우 - 사용자가 기존 Remotion 프로젝트를 렌더링하거나 Lambda 렌더링을 설정하려는 경우
사용하지 말아야 할 경우
- AI 모델(Veo, Sora, Runway, Kling, HeyGen)로 비디오 생성 → video 스킬 사용
- 기존 비디오 파일 편집(자르기/붙이기/연결) → ffmpeg 사용, Remotion 아님
- 라이브 스트리밍 → Remotion은 오프라인 렌더링 전용
워크플로우
-
프로젝트 감지 또는 스캐폴딩.
- 새 프로젝트:
npx create-video@latest(대화형 — Hello World, Blank, JavaScript, TikTok 등 템플릿 선택) - 기존 프로젝트:
remotion.config.ts,src/Root.tsx,package.json의@remotion/cli확인. Remotion 주요 버전에 주의 — API가 발전하므로 올바른 문서 URL은https://www.remotion.dev/docs(최신) 또는 버전별 페이지입니다.
- 새 프로젝트:
-
컴포지션 찾기 또는 생성. 컴포지션은
src/Root.tsx에서<Composition id="..." component={...} durationInFrames={...} fps={30} width={1920} height={1080} defaultProps={{...}} />를 통해 등록됩니다.id는 CLI가 이름으로 렌더링하는 값입니다. -
시간 및 메타데이터를 위해
useCurrentFrame+useVideoConfig를 사용하여 컴포넌트 구축.<AbsoluteFill>로 레이아웃을 구성하고,<Sequence>로 시간을 분할합니다. -
Studio에서 미리보기:
npx remotion studio(자동 리로드). 프레임을 개별적으로 "테스트"하지 말고 Studio를 여십시오. -
렌더링:
npx remotion render <CompositionId> [output.mp4]. 기본 코덱은 H.264 / MP4입니다. 플래그 및 프로그래매틱 API는 references/rendering.md를 참조하십시오.
빠른 API 참조
자세한 내용은 연결된 파일을 참조하십시오. 작업에 필요할 때만 로드하십시오.
| 주제 | 파일 |
|---|---|
| Composition, hooks, Sequence, AbsoluteFill, 레이아웃 | references/core-concepts.md |
interpolate, spring, Easing, 스태거링(staggering), 일반적인 애니메이션 패턴 | references/animation.md |
렌더링: CLI 플래그, @remotion/renderer, Lambda, 코덱, props | references/rendering.md |
오디오/비디오/이미지: <Audio>, <Video>, <Img>, <OffthreadVideo>, 캡션 | references/media.md |
프로젝트 설정, 파일 규칙, remotion.config.ts | references/project-setup.md |
| 일반적인 패턴: 타이핑 애니메이션, lower-thirds, 데이터 기반, 패럴랙스(parallax) | references/patterns.md |
불변 규칙
useCurrentFrame()을 통해 애니메이션을 적용하십시오.setTimeout,requestAnimationFrame또는 CSStransition을 절대 사용하지 마십시오. 각 프레임이 헤드리스 브라우저에서 독립적으로 렌더링되기 때문에 렌더링 중 깜빡입니다.durationInFrames는 필수이며 정수여야 합니다. 총 초 =durationInFrames / fps.- 컴포넌트를 순수하게 유지하십시오. 최상위 수준의 부작용(side effect)이나 결정론적 시드가 없는
Math.random()을 금지합니다. 동일한 프레임은 항상 동일한 픽셀을 생성해야 합니다. - 렌더링 중 fetch를 하지 마십시오. 데이터 로딩 중 프레임 준비를 차단하려면
delayRender()/continueRender()를 사용하거나, 미리 가져와서 props로 전달하십시오. - 가능하면
<Video>대신<OffthreadVideo>를 사용하십시오. 렌더링 중 비차단(non-blocking) 비디오 읽기를 위해 (더 빠르고, 메모리 사용량이 적습니다). - 동적 데이터는 파일을 편집하지 말고
--props(CLI) 또는inputProps(Studio/프로그래매틱)를 통해 전달하십시오.
일반적인 오류
| 오류 / 증상 | 원인 | 해결책 |
|---|---|---|
| MP4와 Studio 미리보기 간 깜빡임 / 모션 불일치 | CSS 전환 또는 프레임 기반이 아닌 애니메이션 사용 | interpolate(frame, ...) 또는 spring({ frame, fps })로 대체 |
| "Composition not found" | ID 오타 또는 <Composition> 등록 누락 | src/Root.tsx 확인 |
| 렌더링 중단 | 보류 중인 delayRender()가 continueRender()를 호출하지 않음 | 해결되지 않은 Promise 찾기; try/finally 추가 |
| 긴 비디오에서 메모리 부족 | <Video>가 프레임을 메모리에 유지 | <OffthreadVideo>로 전환 |
| 오디오 동기화 불일치 | 오디오 파일 fps 불일치 또는 잘못된 프레임에서 시작 | <Audio>를 <Sequence from={...}>로 감싸기 |
검증
변경 후 항상 다음을 수행하십시오.
npx remotion studio를 실행하고 타임라인을 스크러빙하여 여러 프레임(시작, 중간, 끝)에서 변경 사항이 올바르게 보이는지 확인- 프로그래매틱 변경의 경우 짧은 테스트 세그먼트 렌더링:
npx remotion render <id> out.mp4 --frames=0-60 - TypeScript 프로젝트인 경우 타입 검사:
npx tsc --noEmit
이 중 하나라도 수행하지 않으면 성공을 주장하지 마십시오. 컴파일되는 코드는 비디오가 제대로 보인다는 것을 의미하지 않습니다.