Rendervid 배포 - 브라우저, Node.js, 클라우드 및 Docker 렌더링

소개

Rendervid는 워크플로우가 요구하는 어디서나 렌더링할 수 있도록 설계되었습니다. 브라우저에서 즉각적인 미리보기가 필요하든, 서버에서 프로덕션급 비디오 인코딩이 필요하든, 클라우드 인프라 전반에 걸친 대규모 병렬 렌더링이 필요하든, Rendervid는 각 환경에 전용 패키지를 제공합니다. 모든 배포 대상은 동일한 템플릿 시스템 과 컴포넌트 라이브러리 를 공유하므로, 브라우저에서 작동하는 템플릿은 AWS Lambda나 Docker 컨테이너에서도 동일하게 작동합니다.

이 가이드는 네 가지 배포 환경, 각 환경에서 사용 가능한 렌더링 옵션, 그리고 모션 블러, GIF 내보내기 및 성능 최적화와 같은 고급 기능을 다룹니다. 마지막에는 프로젝트에 맞는 배포 경로와 구성 방법을 정확히 알게 될 것입니다.

                        +---------------------+
                        |   JSON Template     |
                        +----------+----------+
                                   |
              +--------------------+--------------------+
              |                    |                    |
     +--------v--------+  +-------v--------+  +-------v---------+
     |     Browser      |  |    Node.js     |  |     Cloud       |
     | @rendervid/      |  | @rendervid/    |  | @rendervid/     |
     | renderer-browser |  | renderer-node  |  | cloud-rendering |
     +---------+--------+  +-------+--------+  +-------+---------+
               |                   |                    |
        Canvas / WebM         FFmpeg / Playwright   Parallel Workers
               |                   |                    |
     +---------v--------+  +------v---------+  +-------v---------+
     | MP4, WebM, PNG,  |  | MP4, WebM, MOV,|  | AWS Lambda      |
     | JPEG, WebP       |  | GIF, H.265     |  | Azure Functions |
     +------------------+  +----------------+  | GCP Functions   |
                                               | Docker          |
                                               +-----------------+

브라우저 렌더링

@rendervid/renderer-browser 패키지는 사용자의 브라우저 내에서 클라이언트 측 렌더링을 완전히 처리합니다. 서버 인프라가 필요하지 않습니다. 이는 템플릿에서 미리보기까지 가장 빠른 경로입니다.

브라우저 렌더링을 사용해야 하는 경우

• 비주얼 에디터 에서 템플릿 편집 중 실시간 미리보기
• 즉석에서 비디오 또는 이미지 자산을 생성해야 하는 웹 애플리케이션
• 서버 측 렌더링을 커밋하기 전 새 템플릿 프로토타이핑
• MP4, WebM, PNG, JPEG 또는 WebP 출력이 충분한 경량 내보내기

설치

npm install @rendervid/renderer-browser

작동 방식

브라우저 렌더링은 HTML Canvas API를 사용하여 템플릿의 각 프레임을 그립니다. 렌더러는 모든 장면과 레이어를 순회하고, 애니메이션과 이징 함수를 적용하며, 결과를 캔버스 요소에 합성하고, 각 프레임을 캡처합니다. 비디오 출력의 경우, 프레임은 브라우저의 내장 MediaRecorder API(WebM) 또는 WebAssembly 기반 MP4 인코더를 사용하여 인코딩됩니다.

지원되는 출력 형식

코드 예제

import { BrowserRenderer } from "@rendervid/renderer-browser";

const renderer = new BrowserRenderer();

const template = {
  width: 1920,
  height: 1080,
  fps: 30,
  scenes: [
    {
      duration: 5,
      layers: [
        {
          type: "text",
          text: "Hello from the Browser",
          fontSize: 72,
          color: "#ffffff",
          position: { x: 960, y: 540 },
          animation: {
            entrance: { type: "fadeIn", duration: 1 },
          },
        },
      ],
    },
  ],
};

// 미리보기를 위해 캔버스 요소로 렌더링
const canvas = document.getElementById("preview") as HTMLCanvasElement;
await renderer.preview(template, canvas);

// MP4로 내보내기
const mp4Blob = await renderer.render(template, {
  format: "mp4",
  quality: "standard",
});

// PNG로 단일 프레임 내보내기
const pngBlob = await renderer.renderFrame(template, {
  format: "png",
  frameNumber: 0,
});

브라우저 렌더링 제한사항

• FFmpeg 액세스가 없어 H.265/HEVC 및 MOV는 사용할 수 없습니다
• GIF 내보내기는 팔레트 최적화를 위해 Node.js 렌더러가 필요합니다
• 최대 해상도는 브라우저의 Canvas 크기 제한에 따라 다릅니다 (일반적으로 4096x4096 또는 8192x8192)
• 렌더링 속도는 클라이언트 장치의 CPU 및 GPU에 따라 다릅니다

Node.js 렌더링

@rendervid/renderer-node 패키지는 완전한 FFmpeg 통합을 통한 서버 측 렌더링을 제공합니다. Playwright 또는 Puppeteer를 사용하여 헤드리스 브라우저에서 각 프레임을 렌더링한 다음, 프레임을 FFmpeg로 파이프하여 전문가급 비디오 인코딩을 수행합니다.

Node.js 렌더링을 사용해야 하는 경우

• 전체 코덱 지원(H.264, H.265, VP9)을 갖춘 프로덕션 비디오 인코딩
• 자동화된 파이프라인에서 수백 또는 수천 개의 템플릿을 배치 처리
• 템플릿 JSON을 받아 렌더링된 비디오를 반환하는 REST API
• 자동화된 콘텐츠 생성을 위한 CI/CD 파이프라인
• 팔레트 최적화 및 디더링 제어를 갖춘 GIF 내보내기

설치

# 렌더러 설치
npm install @rendervid/renderer-node

# Playwright 설치 (브라우저 바이너리 포함)
npx playwright install chromium

# FFmpeg 설치 (비디오 인코딩에 필요)
# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt-get install ffmpeg

# Windows (Chocolatey를 통해)
choco install ffmpeg

지원되는 출력 형식

렌더링 품질 프리셋

Rendervid는 인코딩 매개변수를 제어하는 네 가지 품질 프리셋을 제공합니다:

GPU 가속

Node.js 렌더러는 인코딩을 GPU로 오프로드하는 하드웨어 가속을 지원합니다. 이는 많은 레이어, 고해상도 및 효과를 가진 복잡한 템플릿의 렌더 시간을 크게 줄입니다.

const result = await renderer.render(template, {
  format: "mp4",
  quality: "high",
  outputPath: "/output/video.mp4",
  hardwareAcceleration: true,
});

GPU 가속은 호환 가능한 NVIDIA(NVENC), AMD(AMF) 또는 Intel(Quick Sync) 하드웨어가 있는 시스템에서 사용할 수 있습니다. FFmpeg는 해당 인코더 지원으로 컴파일되어야 합니다.

코드 예제

import { NodeRenderer } from "@rendervid/renderer-node";

const renderer = new NodeRenderer();

const template = {
  width: 1920,
  height: 1080,
  fps: 60,
  scenes: [
    {
      duration: 10,
      layers: [
        {
          type: "video",
          src: "/assets/background.mp4",
          fit: "cover",
        },
        {
          type: "text",
          text: "{{headline}}",
          fontSize: 64,
          color: "#ffffff",
          fontFamily: "Inter",
          position: { x: 960, y: 540 },
          animation: {
            entrance: { type: "slideInUp", duration: 0.8 },
            exit: { type: "fadeOut", duration: 0.5 },
          },
        },
      ],
    },
  ],
  inputs: {
    headline: {
      type: "text",
      label: "Headline",
      default: "Your Product, Elevated",
    },
  },
};

// 사용자 정의 입력으로 렌더링
const result = await renderer.render(template, {
  format: "mp4",
  quality: "high",
  outputPath: "/output/promo.mp4",
  renderWaitTime: 2000, // 미디어 로드를 위해 2초 대기
  inputs: {
    headline: "Summer Sale — 50% Off Everything",
  },
});

console.log(`렌더링됨: ${result.outputPath}`);
console.log(`지속 시간: ${result.duration}초`);
console.log(`파일 크기: ${(result.fileSize / 1024 / 1024).toFixed(2)} MB`);

배치 처리

많은 템플릿을 순차적으로 처리하려면 배치 API를 사용하세요:

import { NodeRenderer } from "@rendervid/renderer-node";

const renderer = new NodeRenderer();

const templates = [
  { template: socialTemplate, inputs: { name: "Alice" }, output: "alice.mp4" },
  { template: socialTemplate, inputs: { name: "Bob" }, output: "bob.mp4" },
  { template: socialTemplate, inputs: { name: "Carol" }, output: "carol.mp4" },
];

for (const job of templates) {
  await renderer.render(job.template, {
    format: "mp4",
    quality: "standard",
    outputPath: `/output/${job.output}`,
    inputs: job.inputs,
  });
}

단일 머신에서 진정한 병렬 렌더링을 원한다면 아래의 Docker 로컬 렌더링 섹션을 참조하세요.

클라우드 렌더링

@rendervid/cloud-rendering 패키지는 클라우드 인프라 전반에 걸친 분산 병렬 렌더링을 가능하게 합니다. 한 머신에서 프레임을 순차적으로 렌더링하는 대신, 클라우드 렌더링은 작업을 동시에 프레임을 렌더링하는 많은 워커 함수에 분산한 다음, 이를 최종 출력으로 병합합니다.

클라우드 렌더링을 사용해야 하는 경우

• 시간당 수백 개의 비디오를 처리하는 고처리량 파이프라인
• 순차 렌더링이 너무 느린 장편 콘텐츠
• 10-50배 속도 향상이 중요한 시간에 민감한 워크로드
• 예측할 수 없는 수요 급증을 처리하기 위한 자동 확장

아키텍처

+------------------+
|   Your App       |
|  (Coordinator)   |
+--------+---------+
         |
         | 1. 비디오를 프레임 청크로 분할
         v
+--------+---------+
|   Chunk Splitter |
+--------+---------+
         |
         |  2. 청크를 워커에 배포
         v
+--------+---+---+---+---+--------+
|  Worker 1  | Worker 2  | Worker N |
|  (Lambda/  | (Lambda/  | (Lambda/ |
|   Azure/   |  Azure/   |  Azure/  |
|   GCP)     |  GCP)     |  GCP)    |
+-----+------+----+------+----+----+
      |            |           |
      | 3. 각 워커가 프레임 렌더링
      v            v           v
+-----+------+----+------+----+----+
|  Frames    |  Frames   |  Frames |
|  001-030   |  031-060  |  061-090|
+-----+------+----+------+----+----+
      |            |           |
      +------+-----+-----+----+
             |
             v
     +-------+--------+
     |     Merger      |
     | (FFmpeg concat) |
     +-------+---------+
             |
             | 4. 최종 비디오로 결합
             v
     +-------+---------+
     |  Object Storage  |
     |  S3 / Blob / GCS |
     +------------------+
             |
             | 5. 다운로드 또는 제공
             v
     +-------+---------+
     |   Final Output   |
     |   video.mp4      |
     +------------------+

단계별 작동 방식:

1. 코디네이터는 템플릿을 분석하고 총 지속 시간과 FPS를 기반으로 렌더링해야 하는 프레임 수를 결정합니다.
2. 청크 분할기는 총 프레임 수를 청크로 나눕니다 (예: 30fps 비디오의 경우 청크당 30프레임 = 청크당 1초).
3. 각 워커 함수는 청크 할당(시작 프레임, 종료 프레임)을 받고, Node.js 렌더러를 사용하여 해당 프레임을 렌더링하며, 렌더링된 세그먼트를 객체 스토리지에 업로드합니다.
4. 병합기는 모든 세그먼트를 다운로드하고 FFmpeg를 사용하여 최종 비디오로 연결합니다.
5. 최종 출력은 클라우드 제공업체의 객체 스토리지(S3, Azure Blob 또는 GCS)에 저장되며 선택적으로 로컬 파일 시스템에 다운로드됩니다.

클라우드 구성

import { CloudRenderer } from "@rendervid/cloud-rendering";

const cloudRenderer = new CloudRenderer({
  provider: "aws", // "aws" | "azure" | "gcp" | "docker"
  quality: "standard", // "draft" | "standard" | "high"
  downloadToLocal: true,
  outputPath: "/output/final.mp4",
});

전체 구성 인터페이스:

interface CloudRenderConfig {
  provider: "aws" | "azure" | "gcp" | "docker";
  quality: "draft" | "standard" | "high";
  downloadToLocal: boolean;
  outputPath: string;

  awsConfig?: {
    region: string;
    s3Bucket: string;
    s3Prefix: string;
  };

  azureConfig?: {
    resourceGroup: string;
    storageAccount: string;
    containerName: string;
  };

  gcpConfig?: {
    projectId: string;
    bucketName: string;
    region: string;
  };

  dockerConfig?: {
    volumePath: string;
    workersCount: number;
  };
}

AWS Lambda 설정

AWS Lambda는 가장 일반적인 클라우드 배포 대상입니다. 각 워커 함수는 별도의 Lambda 호출에서 실행되어 대규모 병렬 처리를 가능하게 합니다.

전제 조건:

• Lambda 및 S3 액세스 권한이 있는 AWS 계정
• 구성된 AWS CLI
• Node.js 18+ Lambda 런타임

구성:

import { CloudRenderer } from "@rendervid/cloud-rendering";

const renderer = new CloudRenderer({
  provider: "aws",
  quality: "high",
  downloadToLocal: true,
  outputPath: "/output/video.mp4",
  awsConfig: {
    region: "us-east-1",
    s3Bucket: "my-rendervid-output",
    s3Prefix: "renders/",
  },
});

const result = await renderer.render(template);
console.log(`${result.renderTime}ms에 렌더링됨`);
console.log(`사용된 워커: ${result.workersUsed}`);
console.log(`출력: ${result.outputUrl}`);

일반적인 AWS Lambda 구성:

• 메모리: 1024-3008 MB (더 많은 메모리 = 더 많은 CPU = 더 빠른 렌더링)
• 타임아웃: 300초 (5분)
• 임시 스토리지: 512 MB - 10 GB
• 동시성: 100-1000 (워크로드에 따라 조정)

Azure Functions 설정

const renderer = new CloudRenderer({
  provider: "azure",
  quality: "standard",
  downloadToLocal: true,
  outputPath: "/output/video.mp4",
  azureConfig: {
    resourceGroup: "rendervid-rg",
    storageAccount: "rendervidstore",
    containerName: "renders",
  },
});

const result = await renderer.render(template);

Google Cloud Functions 설정

const renderer = new CloudRenderer({
  provider: "gcp",
  quality: "standard",
  downloadToLocal: true,
  outputPath: "/output/video.mp4",
  gcpConfig: {
    projectId: "my-project-id",
    bucketName: "rendervid-output",
    region: "us-central1",
  },
});

const result = await renderer.render(template);

비용 비교

모든 클라우드 제공업체는 개발 및 저용량 프로덕션 중 상당한 렌더링 워크로드를 커버하는 무료 티어를 제공합니다.

성능 벤치마크

클라우드 렌더링은 단일 머신 순차 렌더링에 비해 10-50배 속도 향상을 달성합니다. 정확한 속도 향상은 워커 수, 템플릿 복잡성 및 비디오 지속 시간에 따라 다릅니다.

더 긴 비디오는 워커 시작 및 프레임 병합의 오버헤드가 더 많은 프레임에 분산되기 때문에 병렬 처리의 이점을 더 많이 받습니다.

Docker 로컬 렌더링

Docker 기반 렌더링은 클라우드 렌더링과 동일한 병렬 렌더링 아키텍처를 제공하지만, 완전히 로컬 머신에서 실행됩니다. 완전히 무료이며, 클라우드 계정을 사용하지 않으며, 자체 호스팅 설정, 개발 및 클라우드 비용 없이 병렬 렌더링을 원하는 팀에 이상적입니다.

Docker 렌더링을 사용해야 하는 경우

• 클라우드 제공업체 계정 없이 무료 병렬 렌더링
• 방화벽 뒤의 자체 호스팅 인프라
• 클라우드 렌더링 워크플로우의 로컬 개발 및 테스트
• 병렬 처리의 이점을 받지만 자동 확장이 필요하지 않은 소규모 및 중규모 워크로드

설치

# Docker가 설치되어 실행 중인지 확인
docker --version

# 클라우드 렌더링 패키지 설치
npm install @rendervid/cloud-rendering

구성

import { CloudRenderer } from "@rendervid/cloud-rendering";

const renderer = new CloudRenderer({
  provider: "docker",
  quality: "high",
  downloadToLocal: true,
  outputPath: "/output/video.mp4",
  dockerConfig: {
    volumePath: "/tmp/rendervid-work",
    workersCount: 8, // 병렬로 실행할 Docker 컨테이너 수
  },
});

const result = await renderer.render(template);
console.log(`${result.renderTime}ms에 ${result.workersUsed} 워커를 사용하여 렌더링됨`);

workersCount 선택: 머신에서 사용 가능한 CPU 코어 수로 설정하세요. 예를 들어, 8코어 머신은 8 워커로 잘 작동합니다. 코어 수를 초과하면 처리량을 개선하지 않고 컨텍스트 전환으로 인한 오버헤드가 추가됩니다.

Docker 아키텍처

+------------------+
|   Coordinator    |
|  (your process)  |
+--------+---------+
         |
   +-----+-----+-----+-----+
   |     |     |     |     |
+--v--+ +--v-+ +-v--+ +-v--+
| C1  | | C2 | | C3 | | C4 |  ... Docker 컨테이너
+--+--+ +--+-+ +-+--+ +-+--+
   |      |     |      |
   v      v     v      v
+--+------+-----+------+--+
|    Shared Volume          |
|    /tmp/rendervid-work    |
+-------------+-------------+
              |
              v
      +-------+--------+
      |     Merger      |
      +-------+---------+
              |
              v
      +-------+---------+
      |  /output/video  |
      +-----------------+

각 Docker 컨테이너는 Node.js, Playwright 및 FFmpeg가 사전 설치된 독립형 워커입니다. 워커는 공유 볼륨에서 프레임 할당을 읽고, 프레임을 렌더링하며, 결과를 다시 작성합니다. 그런 다음 코디네이터는 모든 세그먼트를 최종 출력으로 병합합니다.

모션 블러

Rendervid는 시간적 슈퍼샘플링을 통해 모션 블러를 지원합니다. 프레임당 단일 순간을 렌더링하는 대신, 렌더러는 시간의 약간 다른 지점에서 여러 서브 프레임을 캡처하고 이를 함께 혼합합니다. 이는 물체가 노출 중에 움직일 때 카메라가 만드는 자연스러운 블러를 생성합니다.

품질 프리셋

구성

const result = await renderer.render(template, {
  format: "mp4",
  quality: "high",
  outputPath: "/output/cinematic.mp4",
  motionBlur: {
    enabled: true,
    quality: "high", // 프레임당 16 샘플
  },
});

시간적 슈퍼샘플링 작동 방식

프레임 N (모션 블러 없음):          프레임 N (모션 블러 있음, 5 샘플):

  단일 순간:                    5개의 서브 프레임 혼합:

  +--------+                         +--------+   +--------+   +--------+
  |    O   |                         |   O    | + |    O   | + |     O  |  ...
  +--------+                         +--------+   +--------+   +--------+
                                              |
                                              v
                                     +--------+
                                     |  ~O~   |  <- 혼합된 결과
                                     +--------+

각 서브 프레임은 애니메이션 타임라인을 작은 증분(1/fps를 샘플 수로 나눈 값)만큼 진행합니다. 그런 다음 서브 프레임은 알파 혼합되어 최종 프레임을 생성합니다. 서브 프레임 사이에 움직인 물체는 동작 경로를 따라 흐릿하게 나타나고, 정지한 요소는 선명하게 유지됩니다.

성능 고려사항

모션 블러는 샘플 수에 비례하여 렌더 시간을 곱합니다. 30fps에서 10초 비디오는 300프레임입니다. high 품질(16 샘플)을 사용하면 렌더러는 300개 대신 4,800개의 서브 프레임을 생성해야 합니다. 개발 중에는 draft 품질을 사용하고 최종 내보내기에만 high 또는 ultra로 전환하세요.

클라우드 렌더링 및 Docker 병렬 렌더링은 프레임당 비용이 워커 전체에 분산되기 때문에 모션 블러와 잘 작동합니다. 16 워커에 분산된 프레임당 16배 증가는 한 머신에서 블러가 없는 렌더와 거의 동일한 총 렌더 시간을 초래합니다.

GIF 내보내기

Rendervid의 GIF 내보내기는 단순한 프레임-GIF 변환을 훨씬 뛰어넘습니다. FFmpeg의 팔레트 생성 파이프라인을 사용하여 구성 가능한 디더링, 색상 수 및 파일 크기 제약으로 최적화된 고품질 애니메이션 GIF를 생성합니다.

GIF 최적화 작동 방식

표준 GIF 인코딩은 256색의 단일 전역 팔레트를 사용하며, 이는 종종 밴딩과 불량한 색상 재현을 초래합니다. Rendervid는 2단계 접근 방식을 사용합니다:

1. 1단계 (palettegen): 모든 프레임을 분석하여 비디오의 전체 색상 범위를 가장 잘 나타내는 최적의 256색 팔레트를 생성합니다.
2. 2단계 (paletteuse): 부드러운 그라디언트를 위한 선택적 디더링과 함께 최적화된 팔레트를 사용하여 각 프레임을 다시 인코딩합니다.

최적화 프리셋

디더링 옵션

구성

const result = await renderer.render(template, {
  format: "gif",
  outputPath: "/output/animation.gif",
  gif: {
    preset: "social",       // 480x480 해상도
    colors: 256,            // 2-256 색상 팔레트
    dithering: "floyd_steinberg",
    targetSizeKB: 5000,     // 5MB 미만으로 자동 최적화
    fps: 15,                // 낮은 FPS = 더 작은 파일
  },
});

console.log(`GIF 크기: ${(result.fileSize / 1024).toFixed(0)} KB`);
console.log(`예상 크기: ${result.estimatedSizeKB} KB`);

파일 크기 추정 및 자동 최적화

targetSizeKB를 설정하면 Rendervid는 렌더링 전에 출력 파일 크기를 추정하고 대상을 충족하기 위해 매개변수(색상 수, 해상도, FPS)를 자동으로 조정합니다. 이는 파일 크기 제한이 있는 플랫폼(예: Slack의 50 MB 제한, 이메일의 일반적인 10 MB 제약)에 특히 유용합니다.

// 2MB 이메일 제약에 맞게 자동 최적화
const result = await renderer.render(template, {
  format: "gif",
  outputPath: "/output/email-banner.gif",
  gif: {
    preset: "email",
    targetSizeKB: 2000,
  },
});

패키지 아키텍처

Rendervid는 13개의 패키지로 구성된 모노레포로 구성됩니다. 각 패키지는 집중된 책임을 가지며, 모든 배포 시나리오를 지원하기 위해 함께 구성됩니다.

@rendervid/
├── core                    엔진, 타입, 검증, 애니메이션 시스템
│   ├── 템플릿 파서 및 검증기 (AJV + JSON Schema)
│   ├── 애니메이션 엔진 (40+ 프리셋, 30+ 이징 함수)
│   ├── 레이어 시스템 (text, image, video, shape, audio, group, lottie, custom)
│   └── 장면 관리 및 전환 (17 타입)
│
├── renderer-browser        클라이언트 측 렌더링
│   ├── Canvas 기반 프레임 렌더링
│   ├── WebM 내보내기를 위한 MediaRecorder
│   └── WebAssembly MP4 인코더
│
├── renderer-node           서버 측 렌더링
│   ├── Playwright/Puppeteer 헤드리스 브라우저
│   ├── FFmpeg 통합 (fluent-ffmpeg)
│   ├── GPU 가속
│   └── GIF 최적화 파이프라인
│
├── cloud-rendering         멀티 클라우드 오케스트레이션
│   ├── AWS Lambda 제공업체
│   ├── Azure Functions 제공업체
│   ├── Google Cloud Functions 제공업체
│   ├── Docker 로컬 제공업체
│   ├── 청크 분할기 및 병합기
│   └── 객체 스토리지 어댑터 (S3, Blob, GCS)
│
├── player                  비디오/템플릿 플레이어 컴포넌트
├── editor                  비주얼 템플릿 에디터 (Zustand 상태)
├── components              사전 구축된 React 컴포넌트
│   ├── AnimatedLineChart
│   ├── AuroraBackground
│   ├── WaveBackground
│   ├── SceneTransition
│   └── TypewriterEffect
│
├── templates               템플릿 정의 및 예제 (100+)
├── testing                 테스팅 유틸리티
│   ├── Vitest 사용자 정의 매처
│   ├── 스냅샷 테스팅 헬퍼
│   └── 시각적 회귀 유틸리티
│
├── editor-playground       에디터 개발 환경
├── player-playground       플레이어 개발 환경
├── mcp                     Model Context Protocol 서버
└── docs                    VitePress 문서 사이트

패키지 연결 방식

• @rendervid/core는 기초입니다. 다른 모든 패키지는 템플릿 타입, 검증 및 애니메이션 시스템을 위해 이에 의존합니다.
• @rendervid/renderer-browser와 @rendervid/renderer-node는 모두 코어 템플릿을 사용하지만 다른 파이프라인(Canvas vs. FFmpeg)을 통해 출력합니다.
• @rendervid/cloud-rendering은 renderer-node를 래핑하고 클라우드 함수 또는 Docker 컨테이너 전체에 작업을 배포합니다.
• @rendervid/player와 @rendervid/editor는 재생 및 비주얼 편집을 위한 React 기반 UI 패키지입니다. 에디터는 상태 관리를 위해 Zustand를 사용합니다.
• @rendervid/components는 템플릿에서 사용할 수 있는 사전 구축된 React 컴포넌트 (AnimatedLineChart, AuroraBackground 등)를 제공합니다.
• @rendervid/testing은 템플릿 검증을 위한 Vitest 매처 및 스냅샷 테스팅 헬퍼를 제공합니다.
• mcp는 Model Context Protocol을 통해 AI 에이전트에 Rendervid의 기능을 노출하는 AI 통합 레이어입니다.

기술 스택

Rendervid는 신뢰성, 성능 및 개발자 경험을 위해 선택된 최신 TypeScript 스택으로 구축되었습니다.

테스팅

Rendervid는 템플릿 검증을 위한 사용자 정의 Vitest 매처, 스냅샷 테스팅 헬퍼 및 시각적 회귀 유틸리티를 제공하는 전용 테스팅 패키지(@rendervid/testing)를 포함합니다.

Vitest 사용자 정의 매처

import { describe, it, expect } from "vitest";
import "@rendervid/testing/matchers";

describe("Product Showcase Template", () => {
  it("유효한 템플릿이어야 합니다", () => {
    expect(template).toBeValidTemplate();
  });

  it("올바른 치수를 가져야 합니다", () => {
    expect(template).toHaveResolution(1920, 1080);
  });

  it("최소한 하나의 텍스트 레이어를 포함해야 합니다", () => {
    expect(template).toContainLayerOfType("text");
  });

  it("헤드라인에 애니메이션이 있어야 합니다", () => {
    expect(template.scenes[0].layers[0]).toHaveAnimation("entrance");
  });
});

스냅샷 테스팅

스냅샷 테스팅은 템플릿을 이미지로 렌더링하고 저장된 참조와 비교합니다. 모든 시각적 변경은 테스트를 실패하게 하여 의도하지 않은 회귀를 쉽게 포착할 수 있습니다.

import { describe, it } from "vitest";
import { renderSnapshot } from "@rendervid/testing";

describe("Template Visual Regression", () => {
  it("프레임 0에서 참조 스냅샷과 일치해야 합니다", async () => {
    const snapshot = await renderSnapshot(template, { frame: 0 });
    expect(snapshot).toMatchImageSnapshot();
  });

  it("중간 지점에서 참조 스냅샷과 일치해야 합니다", async () => {
    const totalFrames = template.fps * template.scenes[0].duration;
    const snapshot = await renderSnapshot(template, {
      frame: Math.floor(totalFrames / 2),
    });
    expect(snapshot).toMatchImageSnapshot();
  });
});

CI에서 시각적 회귀 테스팅

시각적 회귀 테스트를 CI/CD 파이프라인에 통합하여 프로덕션에 도달하기 전에 렌더링 변경 사항을 포착하세요:

# .github/workflows/visual-regression.yml
name: Visual Regression Tests
on: [pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 18
      - run: npx playwright install chromium
      - run: npm ci
      - run: npm run test:visual

성능 최적화

가능한 가장 빠른 렌더 시간을 얻으려면 시간이 어디에 소비되는지와 어떤 레버를 당길 수 있는지 이해해야 합니다. 다음은 가장 영향력 있는 최적화 전략입니다.

1. 올바른 배포 대상 선택

2. 템플릿 복잡성 최적화

• 레이어 수 줄이기. 모든 레이어는 독립적으로 렌더링됩니다. 레이어가 적을수록 프레임당 그리기 작업이 적습니다.
• 개발 및 테스트 중에는 draft 품질 사용. 최종 내보내기에만 high 또는 lossless로 전환하세요.
• 미리보기 중 애니메이션 단순화. 많은 이징 함수가 있는 복잡한 키프레임 시퀀스는 프레임당 계산을 추가합니다.

3. renderWaitTime 현명하게 사용

renderWaitTime 옵션은 외부 미디어(이미지, 비디오, 폰트)가 로드될 수 있도록 렌더링을 일시 중지합니다. 모든 자산이 로드되도록 보장하는 최소값으로 설정하세요. 일반적으로 500-2000ms 값이 사용됩니다. 너무 높게 설정하면 모든 프레임에서 시간을 낭비합니다.

await renderer.render(template, {
  renderWaitTime: 1000, // 1초면 일반적으로 충분합니다
});

4. 병렬 렌더링 활용

10초보다 긴 비디오의 경우, 병렬 렌더링(Docker 또는 클라우드)이 순차 렌더링보다 빠릅니다. 손익분기점은 하드웨어 및 클라우드 구성에 따라 다르지만, 일반적으로:

• < 10초: 단일 Node.js 렌더러로 충분
• 10-60초: 4-8 워커를 사용하는 Docker
• 1-10분: 8-16 워커를 사용하는 Docker 또는 클라우드
• > 10분: 50개 이상의 워커를 사용하는 클라우드 렌더링

5. GIF 출력 최적화

GIF는 본질적으로 큽니다. 파일 크기를 관리 가능하게 유지하려면:

• FPS를 10-15로 낮추기. 대부분의 GIF는 감소된 프레임 속도에서도 괜찮아 보입니다.
• 프리셋(social, web, email)을 사용하여 해상도 줄이기.
• 단순 애니메이션의 경우 색상을 128개 이하로 제한.
• targetSizeKB를 사용하여 Rendervid가 매개변수를 자동 최적화하도록 하기.
• 파일 크기가 그라디언트 품질보다 중요한 경우 디더링 피하기(none).

6. GPU 가속 활성화

호환 가능한 GPU가 있는 머신에서 하드웨어 가속 인코딩은 인코딩 단계의 렌더 시간을 2-5배 줄일 수 있습니다. 이는 고해상도(4K+) 및 고비트레이트 출력에 가장 영향력이 큽니다.

7. 자산 사전 로드

템플릿이 외부 이미지 또는 비디오를 참조하는 경우, 렌더링 전에 로컬 스토리지에 사전 다운로드하세요. 렌더링 중 네트워크 지연은 느리거나 실패한 렌더의 가장 일반적인 원인입니다.

다음 단계

• Rendervid 시작하기: 설치 및 첫 렌더링을 위해 Rendervid 개요 를 방문하세요
• 템플릿 시스템 배우기: JSON 템플릿 구조, 변수, 장면, 레이어 및 애니메이션에 대한 템플릿 시스템 문서 를 읽어보세요
• 컴포넌트 탐색: AnimatedLineChart 및 AuroraBackground와 같은 사전 구축된 React 컴포넌트를 위해 컴포넌트 라이브러리 를 탐색하세요
• AI 통합 설정: MCP를 통해 Claude Code, Cursor 또는 Windsurf를 Rendervid에 연결하려면 AI 통합 가이드 를 참조하세요
• 소스 보기: 전체 소스 코드 및 100개 이상의 예제 템플릿을 위해 Rendervid GitHub 저장소 를 방문하세요