이 스킬이 활성화되면 항상 첫 응답을 :clapper: 이모지로 시작하세요.
Remotion 비디오
Remotion은 React를 사용하여 프로그래매틱 방식으로 비디오를 제작하기 위한 프레임워크입니다. 타임라인 기반 편집기 대신, 모든 프레임이 현재 프레임 번호의 함수인 React 컴포넌트로 컴포지션을 작성합니다. 이를 통해 TypeScript, npm 패키지, 그리고 컴포넌트 기반 아키텍처의 모든 강력한 기능을 활용하여 애니메이션 설명 영상, 소셜 미디어 클립부터 데이터 기반 시각화 및 대규모 개인화 비디오까지 제작할 수 있습니다.
이 스킬은 프로젝트 설정, 컴포지션 구조, interpolate 및 spring을 사용한 프레임 기반 애니메이션, 장면 시퀀싱, 에셋 관리, 오디오 통합, Zod 스키마를 통한 매개변수화된 비디오, 그리고 CLI 또는 프로그래매틱 API를 통한 MP4/WebM 렌더링을 다룹니다.
이 스킬을 사용하는 경우
다음과 같은 경우 이 스킬을 활성화하세요:
- 사용자가 React/TypeScript를 사용하여 프로그래매틱 방식으로 비디오를 만들고 싶어할 때
- Remotion 컴포지션, useCurrentFrame 또는 useVideoConfig에 대해 물을 때
- 텍스트, 요소 또는 장면 간 전환을 애니메이션화해야 할 때
- 코드에서 비디오를 MP4, WebM 또는 GIF로 렌더링하고 싶어할 때
- spring 애니메이션, interpolate 또는 프레임 기반 타이밍에 대해 물을 때
- 처음부터 새로운 Remotion 프로젝트를 설정해야 할 때
- Remotion 비디오에 오디오, 이미지 또는 폰트를 추가하고 싶어할 때
- 매개변수화된/데이터 기반 비디오 생성에 대해 물을 때
- 컴포지션 미리보기를 위해 Remotion 스튜디오를 구성해야 할 때
다음과 같은 경우 이 스킬을 활성화하지 마세요:
- 비디오 생성과 관련 없는 일반적인 React 질문 - React 스킬 사용
- 기존 타임라인 도구(Premiere, DaVinci, FFmpeg CLI)를 사용한 비디오 편집
- 웹 페이지용 CSS 애니메이션 - 애니메이션/모션 디자인 스킬 사용
- 웹 앱에서 비디오 재생 또는 스트리밍 - 미디어 플레이어 스킬 사용
주요 원칙
-
모든 프레임은 순수 함수다 - Remotion 컴포넌트는
useCurrentFrame()을 통해 현재 프레임을 받고 해당 프레임에 대해 결정론적으로 렌더링되어야 합니다. 부작용, 시드 없는 무작위성, 벽시계 시간에 의존하는 것은 허용되지 않습니다. 동일한 프레임 번호는 항상 동일한 시각적 결과를 생성해야 합니다. -
컴포지션이 비디오의 단위다 - 각
<Composition>은 명시적인 크기(너비, 높이), 프레임 속도(fps), 지속 시간(durationInFrames)을 가진 비디오를 정의합니다. 컴포지션을 프로젝트의 "페이지"로 생각하세요 - 각 비디오 변형 또는 장면이 독립적으로 렌더링될 수 있습니다. -
모든 것에 interpolate를 사용하라 -
interpolate()함수는 프레임 번호를 임의의 숫자 값(불투명도, 위치, 크기, 색상 채널)에 매핑합니다.extrapolateRight: 'clamp'와 결합하면 모든 애니메이션의 핵심 도구가 됩니다. 물리 기반 이징이 필요할 때는spring()을 사용하세요. -
시퀀스로 시간 오프셋을 지정하라 -
<Sequence from={frame}>을 사용하여 자식 요소가 나타나기 시작하는 시점을 지연시키고,<Series>를 사용하여 자식 요소를 차례로 재생하세요. 시퀀싱을 위해 setTimeout 또는 수동 프레임 계산을 절대 사용하지 마세요 - 선언적 기본 요소가 미리보기와 렌더링에서 올바르게 처리합니다. -
에셋은 정적이고, 데이터는 동적이다 - 이미지, 폰트, 오디오 파일은
public/폴더에 넣고staticFile()로 참조하세요. 동적 데이터(API 응답, 데이터베이스 레코드)의 경우,delayRender()/continueRender()를 사용하여 데이터가 로드될 때까지 렌더링을 일시 중지하세요.
핵심 개념
컴포지션 구조
모든 Remotion 프로젝트에는 컴포지션을 등록하는 루트 파일이 있습니다:
import { Composition } from 'remotion';
import { MyVideo } from './MyVideo';
export const RemotionRoot: React.FC = () => {
return (
<Composition
id="MyVideo"
component={MyVideo}
durationInFrames={150}
fps={30}
width={1920}
height={1080}
/>
);
};
프레임 기반 타이밍
Remotion의 모든 타이밍은 초가 아닌 프레임으로 표현됩니다. 변환 방법:
- 초를 프레임으로:
초 * fps - 프레임을 초로:
프레임 / fps
30fps에서 5초 비디오는 150프레임입니다. 프레임 0이 첫 번째 프레임입니다.
애니메이션 모델
Remotion은 두 가지 핵심 애니메이션 기본 요소를 제공합니다:
| 기본 요소 | 사용 사례 | 예시 |
|---|---|---|
interpolate() | 프레임에서 값으로의 선형/고정 매핑 | 페이드, 슬라이드, 스케일 |
spring() | 감쇠/질량을 사용한 물리 기반 애니메이션 | 탱탱한 등장, 자연스러운 움직임 |
둘 다 스타일(불투명도, 변형 등)에 적용하는 숫자를 반환합니다.
일반적인 작업
1. 새 Remotion 프로젝트 설정
npx create-video@latest
이 명령어는 TypeScript, 샘플 컴포지션, 그리고 Remotion 스튜디오가 구성된 프로젝트를 스캐폴딩합니다. 프로젝트 구조는 다음과 같습니다:
my-video/
src/
Root.tsx # 모든 컴포지션 등록
MyComp.tsx # 첫 번째 컴포지션 컴포넌트
public/ # 정적 에셋 (이미지, 폰트, 오디오)
remotion.config.ts # Remotion 설정
package.json
다음 명령어로 미리보기 스튜디오를 시작하세요:
npx remotion studio
2. useCurrentFrame을 사용한 기본 컴포지션 생성
import { AbsoluteFill, useCurrentFrame, useVideoConfig, interpolate } from 'remotion';
export const FadeInText: React.FC = () => {
const frame = useCurrentFrame();
const { fps } = useVideoConfig();
const opacity = interpolate(frame, [0, 30], [0, 1], {
extrapolateRight: 'clamp',
});
const translateY = interpolate(frame, [0, 30], [20, 0], {
extrapolateRight: 'clamp',
});
return (
<AbsoluteFill
style={{
justifyContent: 'center',
alignItems: 'center',
backgroundColor: '#0f0f0f',
}}
>
<h1
style={{
fontSize: 80,
color: 'white',
opacity,
transform: `translateY(${translateY}px)`,
}}
>
Hello Remotion
</h1>
</AbsoluteFill>
);
};
3. 단어별 텍스트 애니메이션
텍스트를 단어로 분할하고 <Sequence>를 사용하여 각 단어의 등장을 지연시킵니다:
import { AbsoluteFill, Sequence, useCurrentFrame, interpolate } from 'remotion';
const AnimatedWord: React.FC<{ children: string }> = ({ children }) => {
const frame = useCurrentFrame();
const opacity = interpolate(frame, [0, 15], [0, 1], {
extrapolateRight: 'clamp',
});
const translateY = interpolate(frame, [0, 15], [10, 0], {
extrapolateRight: 'clamp',
});
return (
<span
style={{
display: 'inline-block',
opacity,
transform: `translateY(${translateY}px)`,
marginRight: 12,
}}
>
{children}
</span>
);
};
export const WordByWord: React.FC<{ text: string }> = ({ text }) => {
const words = text.split(' ');
return (
<AbsoluteFill
style={{
justifyContent: 'center',
alignItems: 'center',
backgroundColor: '#1a1a2e',
flexWrap: 'wrap',
padding: 100,
}}
>
{words.map((word, i) => (
<Sequence key={i} from={i * 8}>
<AnimatedWord>{word}</AnimatedWord>
</Sequence>
))}
</AbsoluteFill>
);
};
4. spring을 사용한 요소 애니메이션
자연스러운 물리 기반 애니메이션을 위해 spring()을 사용하세요:
import { AbsoluteFill, useCurrentFrame, useVideoConfig, spring } from 'remotion';
export const SpringCard: React.FC = () => {
const frame = useCurrentFrame();
const { fps } = useVideoConfig();
const scale = spring({
frame,
fps,
config: { damping: 200, stiffness: 100, mass: 0.5 },
});
const slideUp = spring({
frame: frame - 10,
fps,
config: { damping: 12, stiffness: 100 },
});
return (
<AbsoluteFill style={{ justifyContent: 'center', alignItems: 'center', backgroundColor: '#0d1117' }}>
<div
style={{
width: 400,
height: 250,
backgroundColor: '#161b22',
borderRadius: 16,
transform: `scale(${scale}) translateY(${(1 - slideUp) * 50}px)`,
}}
>
<p style={{ color: 'white', fontSize: 32 }}>Spring Animation</p>
</div>
</AbsoluteFill>
);
};
5. Sequence와 Series를 사용한 장면 전환
겹치는 장면에는 <Sequence>, 순차 재생에는 <Series>를 사용하세요:
import { AbsoluteFill, Sequence, Series, useCurrentFrame, interpolate } from 'remotion';
const Scene: React.FC<{ color: string; title: string }> = ({ color, title }) => {
const frame = useCurrentFrame();
const opacity = interpolate(frame, [0, 20], [0, 1], {
extrapolateRight: 'clamp',
});
return (
<AbsoluteFill style={{ backgroundColor: color, justifyContent: 'center', alignItems: 'center' }}>
<h1 style={{ color: 'white', fontSize: 72, opacity }}>{title}</h1>
</AbsoluteFill>
);
};
export const MultiScene: React.FC = () => {
return (
<AbsoluteFill>
<Series>
<Series.Sequence durationInFrames={60}>
<Scene color="#e63946" title="Scene One" />
</Series.Sequence>
<Series.Sequence durationInFrames={60}>
<Scene color="#457b9d" title="Scene Two" />
</Series.Sequence>
<Series.Sequence durationInFrames={60}>
<Scene color="#2a9d8f" title="Scene Three" />
</Series.Sequence>
</Series>
</AbsoluteFill>
);
};
6. 에셋 처리 (이미지, 폰트, staticFile)
public/ 폴더의 정적 에셋은 staticFile()을 사용하여 참조합니다:
import { AbsoluteFill, Img, staticFile } from 'remotion';
export const AssetDemo: React.FC = () => {
return (
<AbsoluteFill style={{ justifyContent: 'center', alignItems: 'center' }}>
<Img
src={staticFile('logo.png')}
style={{ width: 300, height: 300 }}
/>
</AbsoluteFill>
);
};
@remotion/google-fonts 또는 CSS @font-face를 사용하여 사용자 정의 폰트를 로드합니다:
import { loadFont } from '@remotion/google-fonts/Inter';
const { fontFamily } = loadFont();
export const FontDemo: React.FC = () => {
return (
<AbsoluteFill style={{ justifyContent: 'center', alignItems: 'center' }}>
<h1 style={{ fontFamily, fontSize: 64, color: 'white' }}>
Custom Font
</h1>
</AbsoluteFill>
);
};
7. 오디오 통합
볼륨 제어 및 타이밍으로 오디오를 추가합니다:
import { AbsoluteFill, Audio, Sequence, staticFile, interpolate } from 'remotion';
export const WithAudio: React.FC = () => {
return (
<AbsoluteFill style={{ backgroundColor: '#000' }}>
<Audio
src={staticFile('background-music.mp3')}
volume={(f) =>
interpolate(f, [0, 30, 120, 150], [0, 0.8, 0.8, 0], {
extrapolateLeft: 'clamp',
extrapolateRight: 'clamp',
})
}
/>
<Sequence from={15}>
<Audio src={staticFile('whoosh.mp3')} volume={0.5} />
</Sequence>
</AbsoluteFill>
);
};
8. 비디오 렌더링
커맨드 라인에서 MP4로 렌더링:
# 기본 컴포지션 렌더링
npx remotion render src/index.ts MyVideo out/video.mp4
# 4K 해상도로 렌더링
npx remotion render src/index.ts MyVideo out/video.mp4 --width 3840 --height 2160
# WebM으로 렌더링
npx remotion render src/index.ts MyVideo out/video.webm --codec vp8
# 특정 프레임 범위 렌더링
npx remotion render src/index.ts MyVideo out/video.mp4 --frames 0-90
# 사용자 정의 props로 렌더링
npx remotion render src/index.ts MyVideo out/video.mp4 --props '{"title": "Hello"}'
프로그래매틱 렌더링에 대한 자세한 내용은 references/rendering-guide.md를 참조하세요.
안티 패턴 / 일반적인 실수
| 실수 | 잘못된 이유 | 대신 해야 할 것 |
|---|---|---|
시드 없이 Math.random() 사용 | 렌더링 중 프레임마다 다른 출력을 생성함 | 결정론적 시드 또는 Remotion의 random() 사용 |
setTimeout / setInterval 사용 | 프레임 기반 렌더링을 깨뜨림 - 타이머가 프레임별로 진행되지 않음 | 모든 타이밍에 useCurrentFrame()과 프레임 계산 사용 |
extrapolateRight: 'clamp' 누락 | 이후 프레임에서 값이 목표 범위를 초과함 | interpolate()에 항상 { extrapolateRight: 'clamp' } 추가 |
| 프레임 계산에서 fps를 하드코딩 | 컴포지션 fps가 변경되면 깨짐 | 타이밍 유도에 useVideoConfig().fps 사용 |
렌더링 출력에 <Video> 사용 | 탐색 오버헤드로 인한 느린 렌더링 성능 | 더 나은 렌더 성능을 위해 <OffthreadVideo> 사용 |
비동기 데이터에 delayRender() 누락 | 데이터가 로드되기 전에 렌더링되어 빈/손상된 프레임 표시 | 즉시 delayRender() 호출, 준비되면 continueRender() 호출 |
| 비결정론적 값이 있는 인라인 스타일 | 미리보기와 렌더링 간에 깜빡임 또는 불일치 발생 | 모든 스타일 값을 프레임 번호에서만 유도 |
| 거대한 단일 컴포지션 | 유지 관리가 어렵고 장면을 독립적으로 렌더링할 수 없음 | 여러 컴포지션으로 분할하거나 장면에 Series 사용 |
주의사항
-
extrapolateRight 기본값은 'extend'입니다 - 클램핑 없이
interpolate(frame, [0, 30], [0, 1])을 작성하면 프레임 30 이후에도 값이 계속 증가합니다(예: 프레임 60에서 불투명도 2). 의도적으로 외삽하려는 경우가 아니라면 항상{ extrapolateRight: 'clamp' }를 전달하세요. -
spring()은 해당 컨텍스트의 프레임 0에서 시작합니다 -
<Sequence from={60}>내부에서spring()을 사용할 때, spring에 전달되는 프레임은 부모의 프레임 60에서 0으로 재설정됩니다. 부모의 원시 프레임을 전달하면 애니메이션이 이미 완료됩니다. 부모의 프레임이 아닌 Sequence 자식 내부에서useCurrentFrame()을 사용하세요. -
staticFile() 경로는 public/을 기준으로 합니다 -
staticFile('images/logo.png')를 호출하면public/images/logo.png를 찾습니다. 절대 경로 또는public/외부의 경로를 사용하면 미리보기에서 조용히 실패하고 렌더링 중에 오류가 발생합니다. 모든 에셋이public/디렉토리에 있는지 확인하세요. -
delayRender에는 30초 시간 제한이 있습니다 - 비동기 작업(API 호출, 폰트 로드)이 30초보다 오래 걸리면 렌더링이 중단됩니다. 느린 작업의 경우
delayRender('Loading data', { timeoutInMilliseconds: 60000 })로 시간 제한을 늘리세요. -
컴포지션 크기는 짝수여야 합니다 - 비디오 코덱(H.264, VP8)은 짝수 너비와 높이가 필요합니다. Remotion은 홀수 크기가 제공되면 오류를 발생시킵니다.