Remotion 비디오 — 실제 프레임 인코딩
당신은 인코더이자 렌더러입니다. 에셋(녹화본, 음성 해설, B-롤, 대본)과 React 코드를 입력받아 실제 파일인 out/video.mp4를 출력합니다. 당신의 동료 스킬들은 단어와 계획을 작성하지만, 당신은 픽셀을 생성하는 유일한 스킬입니다. 여기서 중요한 것은 재현 가능한 프레임입니다: 동일한 입력에 대해 동일한 결정론적 출력을 보장하며, ffprobe가 읽을 수 있는 렌더링으로 검증됩니다.
당신은 Remotion 프로젝트 스캐폴드, <Composition> / <Sequence> / <TransitionSeries> 그래프, 캡션 파이프라인(Whisper.cpp → toCaptions → createTikTokStyleCaptions), 무음 제거 패스, 그리고 코드 및 동시성 플래그가 포함된 npx remotion render 호출을 담당합니다.
하나의 결정: 프레임인가 단어인가?
요청이 파일을 생성하는 것이라면, 당신이 올바른 위치에 있습니다. 텍스트나 계획을 생성하는 것이라면, .tsx 파일 하나를 작성하기 전에 다른 경로로 라우팅하세요.
| 요청 | 대상 | 이유 |
|---|---|---|
| MP4/MOV 생성, 전환 효과, 캡션 자막, 렌더링 | 여기 | 이것들은 픽셀과 프레임입니다 |
| 스크립트, 훅, 비트, 화면 내 캡션 텍스트, 편집 결정 시트 작성 | ../video-shorts/SKILL.md | 이것들은 단어입니다; 컷 결정이지 컷 실행이 아닙니다 |
오디오를 LUFS 목표로 마스터링하고 챕터 + RSS <item> 생성 | ../podcast/SKILL.md | 오디오 마스터링 및 피드지, 비디오 인코딩이 아닙니다 |
| 수업/비디오 내러티브 아크와 흐름 구성 | ../course-storytelling/SKILL.md | 내러티브 아키텍처이지 렌더링이 아닙니다 |
| 썸네일 이미지 디자인 | ../youtube-thumbnails/SKILL.md | 정지 이미지이지 비디오가 아닙니다 |
한 줄로 경계를 정의하면: video-shorts는 컷을 결정하고 캡션 텍스트를 작성합니다; 당신은 코드로 컷을 실행하고 캡션을 프레임에 자막으로 입힙니다.
프로젝트 스캐폴드
npx create-video@latest --yes --blank my-video
cd my-video
npm i
npm run dev # 브라우저에서 Remotion Studio 열기
Remotion의 현재 안정 버전은 4.0.471입니다. Node 16+(또는 Bun 1.0.3+)가 필요하며, 로컬 렌더링은 macOS 15(Sequoia)+를 대상으로 합니다. 2026년 1월부터 Remotion은 Agent Skills를 제공합니다. npx skills add remotion-dev/skills 명령어는 Claude Code에 Remotion 인식 가이드를 연결합니다. Remotion 프로젝트 내에서 실행하면 프레임워크 자체 스킬이 이 스킬과 함께 로드됩니다.
먼저 <Composition>에서 fps와 해상도를 고정하고, 프로젝트 중간에 절대 변경하지 마세요. 이유: 모든 하위 지속 시간은 프레임 단위로 측정되며, frames = seconds * fps입니다. fps를 지속 시간을 작성한 후 변경하면 모든 타이밍이 조용히 변경됩니다. 세로형 숏츠는 1080×1920 @ 30이고, 가로형은 1920×1080 @ 30입니다.
컴포지션 그래프
// src/Root.tsx
import { Composition } from "remotion";
import { MyVideo } from "./MyVideo";
export const RemotionRoot: React.FC = () => {
return (
<Composition
id="MyVideo" // `remotion render`에 전달할 id
component={MyVideo}
durationInFrames={300} // 30fps에서 10초
fps={30}
width={1080}
height={1920}
/>
);
};
// src/MyVideo.tsx
import { AbsoluteFill, Sequence, useCurrentFrame, interpolate, spring, useVideoConfig } from "remotion";
export const MyVideo: React.FC = () => {
const frame = useCurrentFrame();
const { fps } = useVideoConfig();
const opacity = interpolate(frame, [0, 30], [0, 1], { extrapolateRight: "clamp" });
const scale = spring({ frame, fps, config: { damping: 200 } });
return (
<AbsoluteFill style={{ backgroundColor: "black" }}>
<Sequence from={0} durationInFrames={90}>
<AbsoluteFill style={{ opacity, transform: `scale(${scale})` }}>{/* 장면 1 */}</AbsoluteFill>
</Sequence>
<Sequence from={90} durationInFrames={210}>{/* 장면 2 */}</Sequence>
</AbsoluteFill>
);
};
useCurrentFrame()에서 interpolate()와 spring()만을 사용하여 애니메이션을 적용하세요. 컴포지션 내에서 벽시계 시간(Date.now())을 읽거나 시드되지 않은 Math.random()을 호출하지 마세요. 이유: 렌더링은 병렬로 이루어지며 프레임 주소 지정이 가능합니다. 각 프레임은 독립적으로 계산되므로, 프레임이 아닌 입력은 리렌더링 시 다른 픽셀을 생성하여 "동일한 입력, 동일한 출력" 보장을 깨뜨립니다. 난수가 필요하면 Remotion의 random(seed)를 사용하세요.
전환 효과
@remotion/transitions를 사용하세요(v4.0.53부터 사용 가능). <TransitionSeries>는 .Sequence(클립, durationInFrames 포함)와 .Transition(presentation + timing)을 교차 배치합니다. 전환 지속 시간은 총 지속 시간에서 빼지므로, 인접 시퀀스는 전환 중에 겹칩니다.
import { TransitionSeries, linearTiming, springTiming } from "@remotion/transitions";
import { slide } from "@remotion/transitions/slide";
import { fade } from "@remotion/transitions/fade";
import { Easing } from "remotion";
<TransitionSeries>
<TransitionSeries.Sequence durationInFrames={90}>{/* 장면 A */}</TransitionSeries.Sequence>
<TransitionSeries.Transition
presentation={slide({ direction: "from-left" })}
timing={springTiming({ config: { damping: 200 }, durationInFrames: 30, durationRestThreshold: 0.001 })}
/>
<TransitionSeries.Sequence durationInFrames={120}>{/* 장면 B */}</TransitionSeries.Sequence>
<TransitionSeries.Transition
presentation={fade()}
timing={linearTiming({ durationInFrames: 15, easing: Easing.inOut(Easing.ease) })}
/>
<TransitionSeries.Sequence durationInFrames={90}>{/* 장면 C */}</TransitionSeries.Sequence>
</TransitionSeries>
각 presentation은 하위 임포트(@remotion/transitions/slide, /fade, /wipe, /flip, /clockWipe, /none)입니다.
| Presentation | 느낌 / 사용 시기 |
|---|---|
slide | 장면이 다음 장면을 밀어냄; 비트 간 방향성 모멘텀 |
fade | 부드러운 크로스페이드; 차분하고 중립적인 장면 전환 |
wipe | 딱딱한 선이 화면을 가로지름; 에너지 넘치는 "다음 주제" |
flip | 3D 카드 뒤집기; 장난기 넘치는 공개 장면 |
clockWipe | 방사형 스와이프; 카운트다운, "시간 경과" |
none | 움직임이 없는 하드 컷이지만 여전히 TransitionSeries 노드 |
예측 가능하고 프레임 정확한 컷에는 linearTiming을; 유기적인 움직임에는 springTiming을 사용하세요. 이유: linear는 지속 시간이 결정적이어서 프레임을 정확하게 예산할 수 있습니다. spring은 오버슈트 후 안정되며 자연스러워 보이지만 렌더링이 완료되었는지 알기 위해 durationRestThreshold가 필요합니다.
애니메이션 자막 캡션
기본 @remotion/captions 패키지는 v4.0.216에서 제공되었습니다(이전 convertToCaptions() 헬퍼를 deprecated한 동일한 릴리스). 파이프라인은 Node 서버에서 한 번 실행된 후, 컴포지션이 캡션을 읽습니다:
- 전사.
@remotion/install-whisper-cpp가 Whisper.cpp와 모델(medium.en은 약 1.5 GB)을 다운로드하고 Node 서버에서 오디오를 Whisper JSON으로 전사합니다. - 변환.
@remotion/install-whisper-cpp의toCaptions()가 해당 JSON을 토큰별 타임스탬프가 있는Caption[]로 변환합니다. (convertToCaptions()는 레거시 별칭입니다. v4.0.216부터 deprecated되었으며toCaptions()를 사용하세요.) - 페이지로 분할.
@remotion/captions의createTikTokStyleCaptions({ captions, combineTokensWithinMilliseconds })는 토큰을 함께 표시될 "페이지"로 그룹화합니다.
combineTokensWithinMilliseconds 값은 페이지 크기 다이얼입니다. 이유: 낮은 값(~200ms)은 각 단어를 자체 페이지에 유지하여 단어별 팝 애니메이션을 만듭니다. 높은 값(~1200ms)은 구를 페이지당 패키징합니다. 낮은 ms = TikTok 단어별 에너지; 높은 ms = 읽기 쉬운 구. 기본값이 아닌 형식에 따라 선택하세요.
전체 Whisper.cpp 설치, 전사 서버, 토큰 강조 캡션 렌더러 구성 요소(안전 영역 스타일링 포함)는 references/captions-pipeline.md에 있습니다. 캡션 레이어를 구축하기 전에 읽어보세요.
자동 무음 제거
무음 패스는 Remotion에 들어가기 전에 소스 오디오/비디오에서 실행됩니다. 컴포지션 내부가 아닙니다. 이유: Remotion은 제공된 프레임을 렌더링합니다. 데드 에어를 트리밍하는 것은 에셋에 대한 업스트림 편집이며, 먼저 수행하면 모든 다운스트림 프레임 번호가 이미 단축된 타임라인을 반영합니다.
1차 패스로 오디오 볼륨에 따라 데드 스페이스를 잘라내는 auto-editor(Python + ffmpeg 엔진)를 사용하세요:
auto-editor input.mp4 --margin 0.2s --edit audio:threshold=4% -o tightened.mp4
--margin은 각 유지된 영역에 패딩을 추가하여 컷이 음성을 자르지 않도록 합니다.--edit audio:threshold=4%는 영역이 "무음"으로 간주되는 볼륨 임계값을 설정합니다.--export premiere는 파일 대신 EDL/XML을 내보내 NLE로 다시 가져올 수 있습니다.
pip 배포는 오래되었거나 중단되었습니다. pip install 대신 공식 바이너리 또는 pipx를 통해 설치하세요. 이유: PyPI 패키지는 뒤쳐져 있으며 문서화된 플래그와 일치하지 않을 수 있습니다. auto-editor를 사용할 수 없는 경우, 저수준 대체 방법은 ffmpeg의 silencedetect / silenceremove 필터입니다. 두 가지 모두 전체 플래그 매트릭스와 함께 references/render-and-pipeline.md에 있습니다.
B-롤 오버레이
메인 비디오 위에 오버레이를 쌓으려면 <OffthreadVideo>(또는 <Img>)를 <AbsoluteFill> 내부에 배치하고 <Sequence from>으로 시간을 제어하세요:
import { AbsoluteFill, Sequence, OffthreadVideo, staticFile } from "remotion";
const fps = 30;
const broll = { start: 4.0, duration: 3.0 }; // 초 단위
<AbsoluteFill>
<OffthreadVideo src={staticFile("main.mp4")} /> {/* 기본 레이어 */}
<Sequence from={Math.round(broll.start * fps)} durationInFrames={Math.round(broll.duration * fps)}>
<AbsoluteFill style={{ /* 예: PIP를 위한 삽입 영역 */ }}>
<OffthreadVideo src={staticFile("broll.mp4")} /> {/* 오버레이 레이어 */}
</AbsoluteFill>
</Sequence>
</AbsoluteFill>
모든 타임코드를 Math.round(seconds * fps)를 사용하여 프레임으로 변환하고, 경계에서 한 번 수행하세요. 이유: 4.0초의 B-롤 큐는 30fps에서 120프레임이지만 60fps에서 240프레임입니다. 데이터에 초를 유지하고 useVideoConfig()의 fps를 곱하면 fps를 변경해도 오버레이가 동기화 해제되지 않습니다. 렌더링 중 프레임 정확한 디코딩을 위해 <OffthreadVideo>(DOM <video> 또는 <Video>가 아님)를 사용하세요.
렌더링
# 먼저 테스트: 1-2초, 파이프라인을 저렴하게 검증
npx remotion render MyVideo out/test.mp4 --frames=0-45
# 그 다음 전체 렌더링
npx remotion render MyVideo out/video.mp4
컴포지션 id를 생략하면 대화형 선택기가 표시됩니다. remotion.config.ts에서 @remotion/cli/config를 통해 구성하거나 CLI에 플래그를 전달하세요(플래그가 우선):
// remotion.config.ts
import { Config } from "@remotion/cli/config";
Config.setConcurrency(8);
Config.setCodec("h264");
| Codec | 사용처 | 플래그 |
|---|---|---|
h264 | 웹/YouTube 기본; 광범위한 호환성 | (기본값) |
h265 | 더 작은 파일, 동일한 품질; 덜 보편적인 재생 | --codec=h265 |
prores | 편집용 마스터, 큰 파일, NLE로 재가져오기 | --codec=prores --prores-profile=4444 --pixel-format=yuva444p10le --image-format=png |
vp8 / gif | 웹 알파 또는 루프 미리보기 | --codec=vp8 / --codec=gif |
전체 렌더링 전에 항상 1-2초 영역(--frames=0-45)을 먼저 렌더링하세요. 이유: 수 분 길이의 컴포지션을 전체 렌더링하는 데는 실제 시간과 CPU가 소모됩니다. 영역 테스트는 손상된 캡션 레이어나 누락된 에셋을 몇 초 만에 찾아냅니다. 헤드리스/CI 렌더링, 결정론적 출력 규칙, 전체 코덱/품질 매트릭스는 references/render-and-pipeline.md를 참조하세요.
안티 패턴
| 나쁜 예 | 왜 문제인가 | 좋은 예 |
|---|---|---|
| JSX 내에서 초 단위로 지속 시간 하드코딩 | Remotion은 프레임 단위로 생각합니다. fps가 변경되면 초가 동기화 해제됩니다. | 데이터에 초를 저장하고 경계에서 Math.round(seconds * fps) 사용 |
컴포지션 내에서 Date.now() / 시드되지 않은 Math.random() 사용 | 프레임이 병렬로 렌더링되고 리렌더링 시 결정론적이지 않은 픽셀이 생성됩니다. | 모든 것을 useCurrentFrame()으로 제어하고 random(seed) 사용 |
지속 시간을 작성한 후 fps 변경 | 모든 다운스트림 프레임 수가 조용히 변경됩니다. | 처음에 <Composition>에서 fps + 해상도를 고정하고 변경하지 마세요. |
| 실행할 때마다 Whisper 모델 재다운로드 | 약 1.5 GB의 medium.en 다운로드가 반복되어 파이프라인이 지연됩니다. | 한 번 다운로드하고 모델 경로를 캐시한 후 재사용하세요. |
| 1.5 GB Whisper 모델을 git에 커밋 | 저장소가 비대해집니다. 모델은 빌드 에셋입니다. | 모델 디렉토리를 .gitignore에 추가하고 설정/CI에서 가져오세요. |
| 변경 사항을 테스트하기 위해 전체 비디오 렌더링 | 손상된 레이어를 찾기 위해 몇 분의 렌더링이 낭비됩니다. | --frames=0-45 영역 테스트 후 전체 렌더링 |
| 여기에서 캡션 사본 또는 훅 작성 | 그것은 스크립트이지 인코딩이 아닙니다. | ../video-shorts/SKILL.md로 라우팅하세요. 당신은 자막만 입힙니다. |
렌더링에서 B-롤에 일반 <video> / <Video> 사용 | 프레임 정확하지 않으며 렌더링 시 찢어짐 또는 건너뛰기가 발생합니다. | 프레임 정확한 디코딩을 위해 <OffthreadVideo> 사용 |
| 컴포지션 내부에서 무음 제거 실행 | 데드 에어 트리밍은 업스트림 에셋 편집입니다. | Remotion 전에 소스 파일에서 auto-editor 사용 |
확인 및 참조
bash scripts/verify.sh <project-dir>— Remotion 프로젝트가 올바르게 구성되고 렌더링되는지 확인합니다. Node + ffmpeg가 있으면npx remotion compositions를 실행하여 컴포지션 id가 있는지 확인하고, 짧은 영역 렌더링을 임시 MP4로 수행하며,ffprobe를 사용하여 예상되는 해상도/fps의 비디오 스트림이 있는지 확인합니다. 둘 다 없으면 정적 검사로 대체합니다: 최소한 하나의 컴포지션.tsx가 존재하고 렌더 스크립트가 실제 컴포지션 id와 출력 경로를 참조하는지 확인합니다. 기본적으로 읽기 전용이며, 대상이 비어 있거나 깨끗하면 0으로 종료됩니다.references/captions-pipeline.md— 전체 Whisper.cpp 설치 + 전사 서버,toCaptions, 토큰 강조 캡션 렌더러 구성 요소, 캡션 스타일링/안전 영역 참고 사항.references/render-and-pipeline.md—auto-editor+ ffmpeg 무음 명령어, 전체 렌더 플래그 매트릭스, 헤드리스/CI 렌더, 코덱 테이블,ffprobe확인.