REMOTION 모션 디자인 — 구현 스킬
1. 코딩 전 검토
CLAUDE.md,MASTER_PROMPT.md및 아키텍처 문서를 읽습니다.- 실제 Remotion/React/TypeScript 버전과 패키지 매니저를 확인합니다.
- 기존 진입점과 컴포지션 레지스트리를 찾습니다.
- 저장소의 규칙을 따르고, 필요 없이 종속성을 변경하지 않습니다.
beyond-video, 스크립트, 스토리보드 및 스타일 바이블의 출력물을 제작 사양으로 사용합니다.- 기억에 의존하지 말고 설치된 버전의 Remotion 소스(예: 참조 클론의
packages/core/src)에서 사용하는 API를 검증합니다.
2. 컴포지션 프로필
기본값:
- 너비: 1080
- 높이: 1920
- fps: 60
- 종횡비: 9:16
- 지속 시간: 양의 정수(프레임 단위)
모든 컴포지션은 고유한 ID와 명시적 메타데이터가 필요합니다. 이유 없이 여러 레이어에 서로 다른 FPS 값을 저장하지 마십시오.
<Composition>은 id, fps, width, height, durationInFrames,
defaultProps, 그리고 선택적으로 calculateMetadata(props로부터 동적 지속 시간/메타데이터) 및 schema를 허용합니다. durationInFrames는 양수여야 합니다.
3. 타임라인 엔지니어링
- 지속 시간과 시작 프레임을 중앙 집중식 데이터/구성에 유지합니다.
- 하나의 프레임 간격 규칙을 사용하고,
[start, end)를 권장합니다. - 씬의
durationInFrames는 양수여야 합니다. - 컴포지션의 총 지속 시간이 모든 씬과 꼬리/마무리를 포함하는지 확인합니다.
- 오버랩과 간격을 검증합니다. 오버랩은 전환/합성을 위해 의도된 경우에만 허용됩니다.
- 최종 프레임 경계에 부동 소수점을 의존하지 마십시오.
4. 결정론적 애니메이션 — 시간/프레임 API (Remotion 4.x)
시간 소스:
useCurrentFrame()— 현재 프레임, 0부터 시작. 컴포지션 컴포넌트 내에서만 사용 가능하며, 컴포지션 외부에서는 오류를 발생시킵니다.useVideoConfig()—{width, height, fps, durationInFrames, id, defaultProps, defaultVideoImageFormat, ...}반환; 컴포지션 외부에서는 오류를 발생시킵니다.
보간 및 스프링:
interpolate(input, inputRange, outputRange, options?)— 숫자, 문자열, 부울 및 배열 출력에 대한 오버로드. 옵션:easing,extrapolateLeft/extrapolateRight('extend' | 'identity' | 'clamp' | 'wrap'),output,outputType,posterize. 모션이 범위를 넘어서지 않아야 할 때는 외삽을 클램프합니다.spring({frame, fps, config?, from=0, to=1, durationInFrames?, durationRestThreshold?, delay=0, reverse=false}).SpringConfig:damping(기본값 10),mass(1),stiffness(100),overshootClamping(false).damping <= 0은 애니메이션이 절대 안정되지 않게 합니다(무한 루프 오류).measureSpring({fps, config?, threshold=0.005})— 스프링이 안정될 때까지의 프레임 수;threshold=0은Infinity를 반환합니다.
규칙:
- 모션은 프레임과 props의 함수여야 합니다.
- 입자/노이즈/무작위 값을 시드합니다.
setInterval,setTimeout,requestAnimationFrame,Date.now()및 자체 실행 CSS 키프레임을 비디오 모션의 주요 소스로 사용하지 마십시오.- 컴포지션 렌더링 중에 네트워크 데이터를 가져오지 마십시오.
- 불안정한 URL 또는 로그인이 필요한 URL의 오디오/비디오를 포함하지 마십시오.
delayRender(label?, options?)는continueRender(handle)가 호출될 때까지 렌더링을 보류합니다(예: 비동기 자산). 타임아웃은 CLI--timeout으로 설정됩니다.
5. Sequence, Series 및 로컬 vs 전역 프레임
이것은 가장 자주 잘못 이해되는 규칙입니다. 실제로 한 번 컴포넌트가 Series.Sequence 내에서 전역 프레임을 계산하여 버그가 발생한 적이 있습니다:
<Sequence>내부에서useCurrentFrame()은 Sequence 시작점을 기준으로 한 상대적 프레임을 반환합니다:(frame - (cumulatedFrom + relativeFrom)) * playbackRate. Sequence 내부의 컴포넌트는 전역 프레임을 보지 않습니다.<Sequence>props:from?,name?,durationInFrames?(양수여야 함;loop사용 시 필수),layout('absolute-fill'|'none'),premountFor,loop및 크롭 props(layout="absolute-fill"인 경우에만).<Series.Sequence>는 오직<Series>내부에서만 사용할 수 있습니다.<Series>외부의Series.Sequence는 "이 컴포넌트는<Series />컴포넌트 내부에 있어야 합니다."라는 오류를 발생시킵니다.- 두 가지 유효한 라우팅 패턴 중 하나를 선택하고 일관성을 유지하십시오:
- 전역 프레임 라우터 (비디오 프로젝트에서 사용됨): 하나의 라우터 컴포넌트가 전역
useCurrentFrame()을 사용하고[start, end)범위로 비트를 선택합니다. 비트 컴포넌트는 전역 프레임에서 계산합니다. - Series: 각
Series.Sequence가 하나의 비트를 보유합니다. 비트 컴포넌트는 로컬 프레임(Sequence 시작 시 0)에서 계산합니다.
- 전역 프레임 라우터 (비디오 프로젝트에서 사용됨): 하나의 라우터 컴포넌트가 전역
- 명시적인 이유 없이 하나의 컴포지션에서 두 패턴을 혼합하지 마십시오.
6. 씬/컴포넌트 구조
- 하나의 씬은 하나의 내러티브/시각적 책임을 가집니다.
- 씬 props는 TypeScript로 정의됩니다.
- 재사용 가능한 컴포넌트는 명확한 시각적 작업을 해결합니다.
- 전체 비디오를 하나의 파일에 담지 마십시오.
- 콘텐츠 구성, 렌더러, 스타일 토큰 및 자산 참조를 분리합니다.
- 선택적 자산에 대해 설계된 폴백을 추가합니다. 중요한 자산이 누락된 것을 절대 숨기지 마십시오.
7. 미디어 컴포넌트 및 자산
<Img src>—onError없이 로드에 실패한 이미지는 렌더를 취소합니다(cancelRender). 중요한 자산에는 항상onError를 제공하거나, 렌더링 전에 자산이 존재하는지 확인하십시오.staticFile(path)—public/의 파일을 매핑합니다. 모든 로컬 자산(이미지, 오디오, 비디오)에 사용하십시오.<Audio>— 큐 시트를 props에 매핑하는 방법은sound-design을 참조하십시오(trimBefore/After— 이전 별칭startFrom/endAt—volume,playbackRate). 타임라인에서 큐의 위치는<Sequence from>으로 설정됩니다. 트림 props는 재생되는 파일의 일부만 자릅니다.<Audio>에는mutedprop이 없습니다. 음소거는 CLI 플래그(--muted)입니다.<Video>/<OffthreadVideo>및<Still>은 동일한 프레임 규칙을 따릅니다. 미디어 지속 시간은 파일 메타데이터가 아닌 프레임에서 예약되어야 합니다.
8. 2D 모션
필요에 따라 SVG/도형/CSS/래스터를 사용합니다. 앵커, 변환 원점, 앤티앨리어싱, 레이어링, 클리핑 및 안전 영역을 염두에 두십시오. 모든 변환은 프레임 기반이어야 합니다.
9. 픽셀 및 스틱맨 지원
픽셀 아트:
- 논리적 캔버스와 픽셀 스케일을 고정합니다.
- 스프라이트 크기 조정 시 최근접 이웃 보간을 사용합니다.
- 필요할 때 위치를 그리드에 맞춥니다.
- 팔레트와 스프라이트 크기를 고정합니다.
- 블러와 서브픽셀 반짝임을 피합니다.
스틱맨:
- 비율과 피벗을 일관되게 유지합니다.
- 프로젝트 규모가 정당화될 때 포즈/리그 라이브러리를 사용합니다.
- 실루엣과 제스처를 읽을 수 있도록 애니메이션합니다.
- 표현/포즈를 스토리 비트와 동기화합니다.
걷기 사이클, 후속 동작 및 정지 모션은 character-animation을 참조하십시오.
10. 3D 모션
- 창의적 가치가 있을 때만 3D를 추가합니다.
three,@react-three/fiber,@remotion/three및 해당 문서의 버전을 확인합니다.- Remotion ThreeCanvas 통합의 경우, 설치된 API 버전의 프레임 기반 접근 방식을 따르십시오. 실시간 R3F 패턴이 자동으로 결정론적이라고 가정하지 마십시오.
- 카메라, 변환, 재질, 조명 및 파티클을 프레임에서 구동합니다.
- 렌더러/헤드리스 호환성, 텍스처 크기, 지오메트리 및 계산 비용을 고려합니다.
- 가독성과 유지보수성을 위해 3D 레이어를 2D 타이포그래피/오버레이와 분리합니다.
- 3D 씬을 자세히 연출하는 방법은
3d-scene-director를 참조하십시오.
11. 타이포그래피 및 전환
- 계층 구조와 가독성을 우선시합니다.
- 중요한 카피를 전환으로 가리지 마십시오.
- 모든 전환은 두 비트를 연결하며, 기능 없이 효과를 추가하지 마십시오.
- 스타일 바이블을 통해 모션 곡선과 강도를 일관되게 유지합니다.
- 텍스트 지속 시간을 읽기 요구 사항에 맞춥니다.
12. 마무리 구현
beyond-video 워크시트에 따라 마무리 로고 + CTA를 구현합니다. 로고는 공식 자산 또는 승인된 플레이스홀더에서 가져와야 합니다. 카피, 타이밍, 모티프 및 합성은 해당 비디오에 맞게 제작된 느낌이어야 합니다.
13. 핸드오프 전 QA
컴포지션 ID, 메타데이터, 프레임 범위, 임포트, 타입, 정적 자산, 글꼴, 스타일 일관성, 안전 영역, 마무리 및 자산 라이선스를 확인합니다. 사용 가능한 린트/타입체크/테스트를 실행합니다. MP4를 렌더링하지 마십시오. 커밋/푸시하지 마십시오.
출력 형식
- 컴포지션 레지스트리: ID, 1080×1920, 60 FPS, durationInFrames, 씬 목록 + 프레임 범위.
- 사용된 API: API 이름 + 관련 시그니처 + 확인된 위치(설치된 Remotion 버전).
- 프레임 라우팅 패턴: 전역 또는 Series — 하나의 선택, 컴포지션 전체에 일관됨.
- 자산 레지스트리: 파일,
staticFile, 중요 자산별 폴백/onError. - QA 체크리스트 + 타입체크/린트 결과.
미니 예제
전역 프레임 라우터 (비디오 프로젝트 패턴):
const frame = useCurrentFrame();
const beat = BEATS.find((b) => frame >= b.start && frame < b.end);
return (
<AbsoluteFill>
{beat?.id === 'S01-B01' && <Hook />}
{beat?.id === 'S01-B02' && <Problem />}
</AbsoluteFill>
);
측정된 지속 시간이 있는 스프링:
const settle = measureSpring({fps, config: {damping: 12}});
const progress = spring({frame, fps, config: {damping: 12}});
실패 모드
Series.Sequence내부의 컴포넌트가 전역 프레임을 계산함 → 잘못된 비트, 씬이 잘못된 시간에 표시됨. 해결 방법: 로컬 프레임에서 계산하거나 전역 프레임 라우터로 전환합니다.<Series>없이Series.Sequence사용 → 렌더 시 오류 발생.<Series>로 감싸거나,<Sequence>를 직접 사용합니다(Series.Sequence아님).damping <= 0인spring→ 애니메이션이 절대 안정되지 않음.damping > 0을 유지합니다.onError없이 이미지 누락 → 렌더가 취소됨.onError를 추가하거나 렌더링 전에 자산이 존재하는지 확인합니다.- 컴포지션 외부에서
useCurrentFrame()/useVideoConfig()사용 → 오류 발생. 컴포지션 컴포넌트 내에서만 호출하십시오.