Remotion Parameterized Videos

JSON 데이터 → 영상个性化의 핵심. inputProps로 데이터를 주입하고, calculateMetadata로 컴포지션 메타데이터를 동적으로 결정한다. 카드뉴스·맞춤 인사 영상·대량 렌더에 필수.

---

🎯 핵심 개념

개념	설명
inputProps	컴포지션에 주입하는 외부 데이터 (JSON)
<Composition> props	React props로 컴포지션에 전달
calculateMetadata	props 기반 메타데이터(width, fps 등) 동적 결정
Zod 스키마	props 타입 안전성 (선택)

---

1️⃣ 가장 단순한 예: 이름 넣기

src/Root.tsx:

import { Composition } from "remotion";
import { MyComp, myCompSchema } from "./MyComp";

export const RemotionRoot: React.FC = () => {
  return (
    <Composition
      id="MyComp"
      component={MyComp}
      durationInFrames={150}
      fps={30}
      width={1920}
      height={1080}
      schema={myCompSchema}
      defaultProps={{ title: "Hello World", color: "#f5576c" }}
    />
  );
};

src/MyComp.tsx:

import { z } from "zod";

export const myCompSchema = z.object({
  title: z.string(),
  color: z.string(),
});

export const MyComp: React.FC<z.infer<typeof myCompSchema>> = ({ title, color }) => {
  return (
    <AbsoluteFill style={{ backgroundColor: color, justifyContent: "center" }}>
      <h1 style={{ color: "white", fontSize: 80 }}>{title}</h1>
    </AbsoluteFill>
  );
};

Studio에서 우측 사이드바에 자동으로 title, color 입력 폼이 생긴다.

---

2️⃣ calculateMetadata로 동적 길이 결정

데이터 길이에 맞춰 영상 길이를 자동 조정:

import { CalculateMetadataFunction } from "remotion";

const calculateMetadata: CalculateMetadataFunction<Props> = async ({ props }) => {
  return {
    durationInFrames: props.items.length * 60,  // 아이템당 1초
    fps: 30,
  };
};

<Composition
  id="Slideshow"
  component={Slideshow}
  calculateMetadata={calculateMetadata}
  schema={schema}
  defaultProps={{ items: ["A", "B", "C"] }}
/>

---

3️⃣ JSON 파일에서 props 읽기

const calculateMetadata: CalculateMetadataFunction<Props> = async ({ props }) => {
  const res = await fetch(`https://api.example.com/data/${props.id}`);
  const data = await res.json();
  return {
    props: { ...data },  // props 갱신
    durationInFrames: data.frames.length,
  };
};

fetch는 calculateMetadata 안에서만 가능 (Studio 미리보기 시 자동 실행).

---

4️⃣ CLI에서 props 전달

npx remotion render src/index.ts MyComp out.mp4   --props='{"title":"Custom Title","color":"#1234ff"}'

대량 렌더 시 스크립트에서 JSON props를 만들어 여러 개를 한 번에 출력할 수 있다.

---

5️⃣ Zod 스키마 활용

타입 안전성을 위해 Zod 스키마 사용:

import { z } from "zod";

const schema = z.object({
  title: z.string().min(1).max(100),
  items: z.array(z.object({
    text: z.string(),
    color: z.string().regex(/^#[0-9a-f]{6}$/),
  })),
  duration: z.number().positive(),
});

• 자동 TypeScript 타입 추론
• Studio에서 입력 검증
• defaultProps 자동 완성

자세한 Zod 패턴: https://www.remotion.dev/docs/zod-types/

---

💡 실전 사용 사례

사례	패턴
카드뉴스 (데이터 → 슬라이드)	items[] + calculateMetadata로 길이 자동
맞춤형 인사 영상 (이름 받기)	단일 string prop + CLI --props
대량 SNS 콘텐츠	JSON 배열로 일괄 렌더
데이터 시각화	data prop + 차트 컴포넌트

---

⚠️ 알아둘 점

• inputProps는 반드시 직렬화 가능한 JSON이어야 함 (함수·순환 참조 불가)
• calculateMetadata는 비동기 가능. 외부 API 호출은 await 가능
• Lambda 렌더 시 props 크기 제한 확인: Lambda 한도
• 동적으로 결정된 메타데이터는 Studio 사이드바에 자동 반영

---

📚 영역 구분

• props 검증: Zod types 가이드
• 대량 렌더: Remotion 렌더링 → Lambda
• 한글 hub: Remotion 비주얼 & 미디어

상위 문서: ← Remotion 비주얼 & 미디어 출처: Remotion 공식 문서 — Parameterized videos 한글화 (2026-07-29) 공급사: Remotion AG

변경 이력

날짜	변경
2026-07-29	초판 작성 (공식 Parameterized videos 가이드 한글화)
2026-07-29	메타데이터 블록을 본문 하단으로 이동