Remotion 설정

Remotion 설정은(는) 무엇을 하나요?

새로운 Remotion 프로젝트를 스캐폴딩하고 나머지 워크플로우가 "Claude에게 프롬프트만 입력하면 되는" 상태로 만듭니다. 이는 일회성 환경 작업입니다. 프로젝트당 한 번 수행하면 이후 remotion-compose와 remotion-render는 바로 창작 루프로 넘어갑니다.

적극적으로 트리거하세요. 사용자가 Claude로 동영상 만들기에 대해 언급한다면 - "Remotion 설정", "Remotion 프로젝트 생성", "Claude로 제품 동영상 만들고 싶어", "동영상 프로젝트 시작" - 이 스킬을 실행하세요.

1단계 - 도구 체인 확인

Remotion은 헤드리스 Chromium으로 렌더링하므로 스캐폴딩 전에 Node를 확인하세요:

node --version   # >= 16 필요; 활성 LTS 릴리스 권장

Node가 16보다 낮으면 중단하고 사용자에게 업그레이드하라고 알리세요 (nvm: nvm install --lts && nvm use --lts). 또한 npx를 사용할 수 있는지 확인하세요 (npm 5.2+와 함께 제공됨).

2단계 - 프로젝트 스캐폴딩

npx create-video@latest

이 명령은 대화형입니다. Blank (Hello World) 템플릿을 추천합니다 - 제품 동영상에 가장 깔끔한 기반입니다. CLI가 프로젝트 디렉토리와 패키지 매니저를 묻습니다; 사용자가 선택하도록 한 후 새 폴더로 cd하여 설치하세요:

cd <프로젝트-이름>
npm install

3단계 - Remotion Agent Skills 설치

Claude Code가 이 리포지토리에서 Remotion 자체 스킬 컨텍스트를 사용할 수 있도록:

npx remotion skills add remotion

이 명령은 Remotion의 에이전트 스킬 파일을 프로젝트에 넣습니다. 설치된 Remotion 버전에서 명령을 사용할 수 없는 경우, 최신 @remotion/cli를 안내하고 계속 진행하세요 - 필수는 아니지만 편의 기능입니다.

4단계 - 폴더 규칙 수립

이후 스킬이 항상 파일 위치를 알 수 있도록 레이아웃을 표준화합니다:

src/
  Root.tsx              # 모든 <Composition>을 등록 (항목 레지스트리)
  index.ts              # registerRoot(RemotionRoot)
  compositions/         # 동영상당 하나의 .tsx 파일 - remotion-compose가 여기에 작성
public/
  assets/               # 이미지, 로고, 오디오 - staticFile()을 통해 참조

템플릿이 생성하지 않은 폴더를 만드세요:

mkdir -p src/compositions public/assets

src/Root.tsx가 레지스트리입니다. 모든 동영상은 여기에 등록된 <Composition>입니다:

// src/Root.tsx
import { Composition } from "remotion";
import { HelloWorld } from "./compositions/HelloWorld";

export const RemotionRoot: React.FC = () => {
  return (
    <Composition
      id="HelloWorld"
      component={HelloWorld}
      durationInFrames={90}
      fps={30}
      width={1920}
      height={1080}
    />
  );
};

// src/index.ts
import { registerRoot } from "remotion";
import { RemotionRoot } from "./Root";
registerRoot(RemotionRoot);

등록할 합리적인 기본값: 가로형 제품 동영상은 30fps와 1920x1080 (세로형 소셜 미디어는 1080x1920), 짧은 길이 - 30fps에서 90프레임은 3초이며, 대부분의 제품 데모 동영상은 15초에서 60초 사이입니다 (450-1800프레임).

5단계 - Google Font 로드

Remotion은 Google Fonts를 기본적으로 지원하여 텍스트가 결정적으로 렌더링됩니다. 한 번 설치하고 로드하세요:

npm install @remotion/google-fonts

// 컴포지션 파일 상단 근처에서 로드
import { loadFont } from "@remotion/google-fonts/Inter";
const { fontFamily } = loadFont();
// 사용: <div style={{ fontFamily }}>...</div>

loadFont()는 글꼴이 준비될 때까지 렌더를 차단하므로, 화면의 텍스트가 스타일이 적용되지 않은 폴백 글꼴로 깜빡이는 일이 없습니다. 브랜드에 맞는 글꼴을 선택하세요 - Inter 대신 Poppins, Roboto 등을 사용할 수 있습니다.

6단계 - 스모크 테스트 컴포지션

환경이 처음부터 끝까지 렌더링되는지 증명할 간단한 컴포지션을 작성하세요:

// src/compositions/HelloWorld.tsx
import { AbsoluteFill, useCurrentFrame, interpolate } from "remotion";
import { loadFont } from "@remotion/google-fonts/Inter";

const { fontFamily } = loadFont();

export const HelloWorld: React.FC = () => {
  const frame = useCurrentFrame();
  const opacity = interpolate(frame, [0, 30], [0, 1], {
    extrapolateRight: "clamp",
  });
  return (
    <AbsoluteFill style={{ backgroundColor: "#0B0B0F", justifyContent: "center", alignItems: "center" }}>
      <h1 style={{ fontFamily, color: "white", fontSize: 90, opacity }}>
        작동합니다.
      </h1>
    </AbsoluteFill>
  );
};

src/Root.tsx에 등록되었는지 확인하고 (4단계), 그런 다음 렌더링하세요:

npx remotion render src/index.ts HelloWorld out/smoke-test.mp4

첫 번째 렌더는 헤드리스 Chromium을 다운로드합니다 (수백 MB - 일반적인 연결에서 처음 한 번은 몇 분 정도 기다려야 함); 이후 이 90프레임 스모크 테스트는 1분 이내에 렌더링되어야 합니다. out/smoke-test.mp4가 페이드인 되는 제목을 재생하면 환경이 정상입니다. 렌더가 실패하면 거의 항상 (a) Chromium 다운로드/권한, (b) 컴포지션이 Root.tsx에 등록되지 않음, 또는 (c) 1단계의 Node 버전 문제입니다.

7단계 - 미리보기를 위한 Remotion Studio 실행

대화형 미리보기 (타임라인 스크럽, 편집 시 핫 리로드):

npx remotion studio

이 명령은 Studio를 **http://localhost:3000**에 제공합니다. create-video 템플릿은 또한 npm run dev를 동일한 기능에 연결합니다. 반복 작업 중에는 Studio를 계속 실행하세요 - 컴포지션 파일을 편집하면 핫 리로드가 즉시 적용됩니다.

결과물

사용자는 작동하는 Remotion 프로젝트를 갖게 됩니다: src/compositions/ + public/assets/ 레이아웃이 적용된 스캐폴딩된 리포지토리, Remotion 에이전트 스킬 설치, Google Font 연결, 등록된 스모크 테스트 컴포지션, 실제로 재생되는 렌더링된 out/smoke-test.mp4, 그리고 미리보기를 위해 실행 중인 Remotion Studio. 스모크 테스트 MP4가 존재하고 재생될 때까지 "설정 완료"가 아닙니다.

금지 사항

• Node 확인을 건너뛰고 스캐폴딩하지 마세요 - 16 미만의 Node는 설치 시가 아닌 Chromium 렌더 내부 깊숙한 곳에서 이해하기 어려운 오류로 실패합니다.
• 스모크 테스트를 렌더링하지 않고 설정 완료를 선언하지 마세요; 컴파일은 되지만 MP4를 한 번도 생성하지 않은 프로젝트는 Chromium 파이프라인이 작동함을 입증하지 못합니다.
• 컴포지션이나 에셋을 임의의 위치에 두지 마세요 - 이후 스킬(remotion-compose, remotion-render)은 src/compositions/와 public/assets/가 존재한다고 가정합니다.
• 에셋을 상대 경로나 URL로 참조하지 마세요; public/에서 staticFile()을 사용하세요. 그렇지 않으면 로컬에서는 작동하지만 다른 곳에서는 깨집니다.
• 화면 텍스트에 시스템 또는 CSS 가져오기 글꼴을 사용하지 마세요 - loadFont()로 차단하지 않으면 렌더 머신에서 텍스트가 폴백 글꼴로 렌더링될 수 있습니다.
• 제품 동영상에 기능이 많은 템플릿을 선택하지 마세요; Blank 템플릿은 사용자가 나중에 삭제해야 하는 데모 코드가 없습니다.

품질 기준

• node --version이 16 이상이며 스캐폴딩 전에 확인되었습니다.
• out/smoke-test.mp4가 존재하고 페이드인 되는 제목을 재생합니다.
• 폴더 규칙이 정확히 지정된 대로 존재하며 스모크 컴포지션이 src/Root.tsx에 등록되어 있습니다.
• 텍스트가 시스템 폴백이 아닌 @remotion/google-fonts의 loadFont()를 통해 렌더링됩니다.
• Remotion Studio가 localhost:3000에서 실행되고 편집 시 핫 리로드됩니다.

인계

스모크 테스트가 렌더링되고 Studio가 켜지면, 사용자에게 프로젝트가 준비되었음을 알리고 인계하세요: "설정이 완료되었습니다. 원하는 동영상을 설명해 주세요 - 길이, 장면, 브랜드 색상 - 그러면 제가 컴포지션을 작성하고(remotion-compose), 렌더링하고 반복하겠습니다(remotion-render)."