Remotion Server-side Rendering (SSR)

@remotion/renderer 패키지로 Node.js 환경에서 프로그래밍 방식으로 영상을 렌더링한다. 대량 렌더·자동화·백엔드 통합에 적합.

---

📦 설치

npm i @remotion/renderer

📌 Node.js 18+ 필요. Chromium은 자동 설치 (@remotion/renderer 설치 시).

---

🛠️ 기본 사용법: renderMedia()

import { bundle } from "@remotion/bundler";
import { renderMedia, selectComposition } from "@remotion/renderer";

const bundleLocation = await bundle({
  entryPoint: "./src/index.ts",
});

const composition = await selectComposition({
  serveUrl: bundleLocation,
  id: "MyComposition",
  inputProps: { title: "Hello" },
});

await renderMedia({
  composition,
  serveUrl: bundleLocation,
  outputLocation: "out.mp4",
  inputProps: { title: "Hello" },
  codec: "h264",
});

---

🖼️ renderStill() — 단일 프레임

import { renderStill } from "@remotion/renderer";

await renderStill({
  composition,
  serveUrl: bundleLocation,
  output: "frame.png",
  frame: 60,
});

---

🔢 대량 렌더 (배열)

const items = await fetch("https://api.example.com/videos").then(r => r.json());

for (const item of items) {
  await renderMedia({
    composition,
    serveUrl: bundleLocation,
    outputLocation: `out/${item.id}.mp4`,
    inputProps: { title: item.title },
  });
}

💡 병렬화: Promise.all + 동시성 제한으로 속도 향상

import pLimit from "p-limit";
const limit = pLimit(4);  // 동시 4개

await Promise.all(
  items.map((item) =>
    limit(() => renderMedia({
      composition,
      serveUrl: bundleLocation,
      outputLocation: `out/${item.id}.mp4`,
      inputProps: { title: item.title },
    }))
  )
);

---

📊 진행률 추적

import { renderMedia, RenderMediaOnProgress } from "@remotion/renderer";

const onProgress: RenderMediaOnProgress = ({ progress, renderedFrames }) => {
  console.log(`${(progress * 100).toFixed(1)}% (${renderedFrames} frames)`);
};

await renderMedia({
  composition,
  serveUrl: bundleLocation,
  outputLocation: "out.mp4",
  onProgress,
});

---

⏱️ 진행률 폴링 (getRenderProgress)

import { getRenderProgress } from "@remotion/renderer";

// 별도 프로세스에서
const progress = await getRenderProgress({
  renderId: "...",
  bucketName: "remotion-render",
  region: "us-east-1",
});

📌 getRenderProgress는 Lambda에서만 사용. 로컬 SSR은 onProgress 콜백으로 충분.

---

🌐 외부 Serve URL 사용

번들 로컬 빌드 대신 S3·Vercel Blob 등 외부 URL을 직접 사용:

await renderMedia({
  composition,
  serveUrl: "https://my-bucket.s3.amazonaws.com/bundle/index.html",
  outputLocation: "out.mp4",
});

이 패턴은 서버리스 환경에서 필수.

---

🧊 Chromium 설정

await renderMedia({
  composition,
  serveUrl: bundleLocation,
  outputLocation: "out.mp4",
  chromiumOptions: {
    args: ["--no-sandbox", "--disable-gpu"],
  },
});

Docker/CI 환경에서 자주 사용.

---

🎬 오디오 / 비디오 트리밍

ffmpegExecutable로 시스템 FFmpeg 사용 가능:

await renderMedia({
  composition,
  serveUrl: bundleLocation,
  outputLocation: "out.mp4",
  ffmpegExecutable: "/usr/bin/ffmpeg",
});

---

⚠️ 알아둘 점

• 메모리 — 대량 렌더는 1개당 1~2GB RAM 예상
• 번들 캐시 — 동일 코드에 대해 번들을 1회만 빌드하고 재사용
• 헤드리스 Chrome — 서버에 chrome 또는 chromium 설치 필수 (또는 @puppeteer/browsers로 자동 설치)
• License — remotion 패키지의 License는 LICENSE.md 확인

---

📚 영역 구분

• 로컬 1회성: Remotion CLI Render
• 브라우저에서 렌더: Remotion Client-side Rendering
• 대량·서버리스: Remotion Lambda
• 한글 hub: Remotion 렌더링

상위 문서: ← Remotion 렌더링 출처: Remotion 공식 문서 — Server-side rendering 한글화 (2026-07-29) 공급사: Remotion AG

변경 이력

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