Revideo Parameterized Videos

Revideo의 킬러 기능 중 하나 — 하나의 비디오 템플릿에 외부 데이터를 주입해서 대량 변형 영상을 찍어내는 패턴. 사용자명·통계·AI 생성 이미지 같은 변수를 받아 동일한 구조의 영상을 N개 만들 때 쓴다.

🎯 왜 필요한가

시나리오	효과
TikTok 광고 1만 개 (사용자명·도시명 다름)	템플릿 1개 + JSON 1만 개로 처리
통계 대시보드 영상 자동 생성	API 응답을 변수로 넘김
SaaS 사용자 정의 영상 (SaaS 에디터)	에디터 입력 → 변수 → 즉시 렌더

Motion Canvas는 이런 워크플로우가 불가능하다 (UI에서 한 번씩 클릭해야 함). Revideo가 프로그래매틱 영상 SaaS 시장을 노리는 이유가 이 패턴 때문이다.

📝 씬에서 변수 읽기 (`useScene`)

import {Txt, makeScene2D} from '@revideo/2d';
import {useScene, createRef} from '@revideo/core';

export default makeScene2D('scene', function* (view) {
  const textRef = createRef<Txt>();

  // .get('변수명', '기본값')
  const name = useScene().variables.get('username', 'new user');

  view.add(
    <Txt fontSize={1} textWrap={true} ref={textRef} fill={'blue'}>
      Hello {name}!
    </Txt>,
  );
  yield* textRef().scale(30, 2);
});

useScene()은 제너레이터 안에서만 호출 가능. 두 번째 인자가 변수가 안 넘어왔을 때의 기본값.

🎬 CLI 렌더 시 변수 전달 (`renderVideo`)

src/render.ts에서:

import {renderVideo} from '@revideo/renderer';

renderVideo({
  projectFile: './src/project.ts',
  variables: {username: 'Mike'},
});

서버에서 API로 대량 호출할 때 이 인자만 바꿔서 호출:

// 동적 데이터로 1만 개 렌더
for (const user of users) {
  await renderVideo({
    projectFile: './src/project.ts',
    variables: {username: user.name, city: user.city},
  });
}

🖼️ 시각 편집기에서 변수 (Studio / `makeProject`)

src/project.ts의 variables는 시각 편집기에서 보이는 기본값이자, Studio에서 시점 변경 시마다 다시 평가되는 값:

import {makeProject} from '@revideo/core';
import example from './scenes/example?scene';

export default makeProject({
  scenes: [example],
  variables: {username: 'Mike'},
});

npm start로 띄운 Studio에서 변수 슬라이더를 만지며 실시간 미리보기가 가능. 이 값은 project.ts의 기본값을 초기값으로 사용.

🧩 복잡한 파라미터 — AI 서비스 결과 주입

variables에 단순 문자열뿐 아니라 객체, 배열, 파일 경로도 넣을 수 있다. AI 서비스 연동 시 흔한 패턴:

// API → variables → 렌더
const aiResult = await openai.images.generate({
  prompt: `a futuristic city at ${user.city}`,
});
const imageUrl = aiResult.data[0].url;

await renderVideo({
  projectFile: './src/project.ts',
  variables: {
    username: user.name,
    city: user.city,
    backgroundImage: imageUrl,  // 씬에서 <Img src={variables.get('backgroundImage')} /> 로 사용
  },
});

변수 타입	씬에서 받는 법
문자열	`variables.get('name', 'default')`
숫자	`variables.get('count', 0)`
객체	`variables.get('data', {})`
배열	`variables.get('list', [])`
파일 경로 (URL)	`<Video src={variables.get('videoUrl')} />`

💡 팁: AI로 만든 이미지를 public/에 저장 후 경로를 넘기는 게 가장 안정적. URL을 직접 넘기면 만료/네트워크 이슈가 생길 수 있다.

📺 실전 예시 — YouTube Shorts 자동 생성

Revideo 팀이 직접 운영하는 Youtube Shorts 예제는 이 패턴의 정수다:

1. ChatGPT → 스크립트 생성
2. ElevenLabs → 음성 합성 (파일 저장)
3. DALL-E → 배경 이미지 생성 (파일 저장)
4. Revideo → 영상 렌더 (variables에 1, 2, 3 주입)

각 영상마다 변하는 건 변수뿐. 템플릿 코드는 한 번만 짜고 N개 영상 생성.

🎯 다음 단계

첫 영상 만들기: Revideo Quickstart → 이전 손자 페이지
프로젝트 폴더: Revideo 프로젝트 구조 → 이전 손자 페이지
씬 작성 패턴: Revideo Scene Flow 이해하기 → 이전 손자 페이지
SaaS로 만들기: Revideo 웹앱 & Player → Revideo SaaS Template (상위 hub)

🔗 공식 리소스

공식 Parameterized: https://midrender.com/revideo/docs/guide/parameterized-video
YouTube Shorts 예제: https://github.com/redotvideo/examples/tree/main/youtube-shorts
예제 모음: https://github.com/redotvideo/examples

상위 문서: ← Revideo 시작하기 출처: Revideo 공식 문서 — Parameterized Videos 한글화 (2026-07-29) 공급사: Revideo (현 Midrender)

변경 이력

날짜	변경
2026-07-29	초안 작성 — useScene/renderVideo/makeProject variables + AI 연동 패턴 한글화
2026-07-29	메타데이터 블록을 본문 하단으로 이동