remotion-demo-video은(는) 무엇을 하나요?

Remotion 4.x 프로모/데모/트레일러 영상 제작을 위한 효율적인 워크플로우입니다. 프로젝트 레이아웃, 애니메이션 프리미티브, 렌더링 명령어 및 실제 시간을 낭비하는 일반적인 함정들을 체계화합니다.

이 스킬을 사용해야 할 때

사용자가 Remotion 비디오를 제작, 편집, 렌더링 또는 디버깅하려는 경우에 사용합니다. 특히 다음과 같은 경우에 유용합니다:

제품/논문/저장소 데모용 새 Remotion 프로젝트 부트스트래핑
기존 Remotion 프로젝트에 새 장면 추가
사전 녹화된 화면 캡처를 오버레이, 제목, 전환 효과로 다듬어진 비디오로 연결
렌더링 — 단일 장면, 전체 타임라인, 투명(알파) 오버레이, PNG 시퀀스
Remotion 특이 문제 디버깅 (composition-id 불일치, 기본값 동기화 오류, <Sequence> 내부 useCurrentFrame 예상치 못한 값 반환, ffmpeg 정리 중 Windows EPERM 오류 등)

워크플로우에 대한 이해 방식

정교한 Remotion 비디오는 "하나의 거대한 타임라인을 하나의 MP4로 렌더링하는 것"이 아닙니다. 이는 각각 독립적으로 렌더링 가능한 작은 장면(씬)들의 집합이며, 다운스트림 편집기(DaVinci Resolve, Premiere, Final Cut)에서 조립되어 음악, 내레이션, 장면 간 전환 효과가 추가됩니다.

SimWorld 프로모를 출시하면서 얻은 가장 중요한 통찰력이며, 이 스킬은 기본적으로 사용자를 이 워크플로우로 안내해야 합니다. Remotion 내에서 모든 것을 처리하려는 것(최종 타이밍 조정, 오디오 믹싱, 디졸브)은 번거롭고 느리지만, 편집기에서 처리하는 것은 간단합니다.

각 도구를 장점에 맞게 사용

Remotion이 뛰어난 점: 프로그래매틱하고 반복 가능하며 매개변수화된 장면 — 애니메이션 제목, 데이터 기반 차트, UI 목업, After Effects에서 수동 키프레임으로 작업해야 할 모든 것. 장면 로직은 코드에 있으며, "30개의 다른 제품 이름으로 동일한 제목을 다시 만드는 것"은 단순히 props 하나만 변경하면 됩니다.
다운스트림 편집기가 뛰어난 점: 타이밍, 오디오, 디졸브, 색보정, "이 장면을 1.2초 더 길게"와 같은 작업. 편집기에서는 즉시 가능하지만 Remotion에서는 코드를 수정하고 다시 렌더링해야 하는 모든 작업입니다.

루프

대본을 결정합니다. 목표 시간(초)이 포함된 비트별 개요. 총 길이는 일반적으로 30~90초입니다.
프로젝트 셸을 한 번 설정합니다. theme.ts (팔레트, 폰트, fps, 크기), Root.tsx (컴포지션 레지스트리), 공유 컴포넌트(Reveal, ProgressBar, 이징).
장면을 하나씩 구축합니다. 각 장면은 frame 0을 기준으로 설계된 독립적인 <AbsoluteFill> React 컴포넌트이며, 자체 <Composition>을 가지고 있어 단독으로 렌더링할 수 있습니다. Studio에서 반복 작업(npm run dev)을 props 패널로 수행하고, 마음에 들면 MP4로 렌더링합니다(npm run render:<scene>).
완성된 각 장면을 자체 클립으로 렌더링합니다. 이것이 실제 결과물이며, 전체 타임라인 MP4가 아닙니다. 장면별 클립은 모든 편집기의 타임라인에 드래그하여 넣을 수 있습니다. 알파 채널이 필요한 클립(하단 1/3, 화면 캡처 위에 합성할 로고)에는 --codec=prores --pixel-format=yuva444p10le --prores-profile=4444를 사용합니다.
선택적으로 theme.ts의 TIMELINE 상수를 읽는 <Sequence> 블록을 사용하여 장면을 Main.tsx에 연결합니다. 이렇게 하면 전체 흐름을 확인하기 위한 전체 타임라인 미리보기 렌더링(npm run render)을 제공하지만, 이를 마스터가 아닌 미리보기로 취급합니다.
DaVinci / Premiere / Final Cut에서 조립합니다. 장면별 클립을 순서대로 트랙에 놓고, 트림 핸들을 조정하여 정확한 타이밍을 맞추고, 음악/내레이션/사운드 디자인을 추가하고, 장면 간 전환 효과를 적용하고(이 미학에는 일반적으로 1프레임 디졸브가 적절함), 색보정을 수행하고, 내보냅니다.

전체 Remotion 렌더링을 언제 제안해야 할까요?

전체 타임라인 렌더링은 다음 경우에만 올바른 출력입니다:

사용자에게 다운스트림 편집기가 없고 오늘 바로 단일 결과물이 필요한 경우.
비디오가 완전히 무음인 경우(음악이나 내레이션이 전혀 없음).
하드 컷보다 더 복잡한 장면 간 전환 효과가 없는 경우(그리고 하드 컷조차도 장면별 접근 방식으로 코드에서 조정하기가 더 쉽습니다).

그렇지 않으면 기본적으로 장면별 렌더링 + 편집기 조립을 권장합니다.

이 스킬은 scaffold/에 작업 스캐폴드를 번들로 제공합니다. 새 프로젝트의 시작점으로 복사한 다음 필요에 따라 아래 참조를 읽으십시오.

실제 종단 간 루프 (입력이 논문/사양/저장소인 경우)

이것은 이 스킬이 실제로 설계된 워크플로우입니다. 사용자는 보통 "X라고 말하는 애니메이션 제목을 원해요"라고 말하며 들어오지 않습니다. 그들은 논문 PDF, 프로젝트 사양서 또는 기존 저장소를 가지고 와서 "이것을 60초 비디오로 만들어 주세요"라고 질문합니다. 이 스킬은 그 루프를 빠르고 다루기 쉽게 만들기 위해 존재합니다.

1. 소스 자료        →  논문 PDF / 사양서 / 기존 저장소 / README
        ↓
2. Claude 분석       →  내러티브 비트 추출; 각 비트가
                             보여줘야 할 것(UI 화면, 실험
                             녹화, 차트, 에이전트 시점 등) 식별
        ↓
3. Claude 스캐폴딩   →  각 시각적 영역에
   <VideoPlaceholder slot="..." />가 포함된 장면 코드 +
                             사용자가 녹화해야 하는 모든 클립을 나열한
                             ASSETS.md 생성
                             (슬롯 이름, 길이, 보여줘야 할 내용)
        ↓
4. 사용자 영상 녹화  →  스캐폴드의 슬롯 이름과 일치하는
                             mp4 파일을 public/clips/<slot>.mp4에 저장
        ↓
5. Claude 교체       →  <VideoPlaceholder>를
   자리 표시자를 클립으로  <OffthreadVideo src={staticFile("clips/<slot>.mp4")}>로 교체
        ↓
6. 장면별 반복       →  npm run render:<scene>, 확인, 텍스트 /
                             타이밍 / 애니메이션 조정, 재렌더링. 코드 측
                             변경은 빠름; 영상 재녹화가 필요하면
                             루프에서 가장 느린 부분임.
        ↓
7. 편집기에서 조립   →  장면별 MP4를 DaVinci / Premiere / FCP에
                             불러오고, 음악 + 내레이션 + 장면 간
                             전환 효과 추가, 내보내기.

2단계 세부 사항 — 소스 자료 분석

사용자가 논문/사양서를 건네주면 코드를 작성하기 전에 다음을 수행하십시오:

내러티브를 추출합니다. 3~5개의 비트로 구성된 아크는 무엇입니까? ("문제 → 우리의 방법 → 주요 결과 → 영향"이 기본 템플릿입니다. 실제 논문에 맞게 변경하십시오.) 내러티브가 장면 목록을 결정합니다.
각 비트에 대해 무엇을 보여줄지 결정합니다. 애니메이션 텍스트만으로는 지루합니다. 각 비트에는 구체적인 시각적 요소(UI 화면, 실험 녹화, 차트, 비교, 시스템 다이어그램)가 있어야 합니다. 주장과 일치하는 시각적 요소를 연결하십시오. 논문이 "방법 X가 3배 빠르다"고 주장한다면, 나란히 타이밍을 보여주십시오.
Remotion이 생성하는 것과 사용자가 녹화해야 하는 것을 구분합니다. Remotion은 제목, 전환 효과, 차트, UI 목업, 레이아웃, 애니메이션 다이어그램에 탁월합니다. Remotion은 생성할 수 없습니다: 사용자 제품의 실제 화면 녹화, 실험 영상, 에이전트 시점, 프로젝트 외부의 모든 것. 이러한 항목은 사용자가 제공해야 하는 영상으로 나열하십시오.
스캐폴딩 전에 타임라인을 스케치합니다. 목표 시간이 포함된 비트별 개요를 작성하여 총합이 30~90초가 되도록 합니다. 일치하도록 theme.ts의 TIMELINE을 업데이트합니다. 장면을 구축하기 전에 총 길이가 결정되어야 각 장면이 예산을 알 수 있습니다.

3단계 세부 사항 — 자리 표시자를 사용한 스캐폴딩

이 스킬의 주요 전달 규칙: 슬롯 이름. 사용자가 녹화해야 하는 모든 클립은 안정적인 slot 문자열을 얻습니다. 자리 표시자와 실제 클립은 해당 슬롯 이름을 공유합니다.

// 스캐폴딩 중:
<VideoPlaceholder
  slot="agent-loop"
  description="연속 에이전트 녹화: 걷고, 실패하고, 업데이트된 정책으로 재시도합니다."
  accent={COLORS.blue}
/>

// 사용자가 public/clips/agent-loop.mp4를 녹화한 후, 다음으로 교체:
<OffthreadVideo
  src={staticFile("clips/agent-loop.mp4")}
  muted
  style={{ position: "absolute", inset: 0, width: "100%", height: "100%", objectFit: "cover" }}
/>

항상 스캐폴드 루트에 ASSETS.md를 작성하십시오 (스캐폴드는 템플릿을 제공합니다). 사용자가 채워야 하는 모든 슬롯을 나열하며, 다음 정보를 포함합니다: 슬롯 이름(= 파일 이름), 보여줘야 할 내용, 목표 길이, 종횡비 권장 사항 및 타이밍 참고 사항(예: "7초 부근에 실패 이벤트"). 이것이 사용자의 녹화 작업에 대한 단일 정보 소스입니다.

4~5단계 세부 사항 — 자산 전달

사용자가 public/clips/에 파일을 넣어 돌아옵니다. 세 가지를 확인하십시오:

파일 이름이 슬롯 이름과 정확히 일치하는지 확인합니다. agent-loop.mp4, agent_loop.mp4 또는 AgentLoop.mp4가 아닙니다.
길이가 장면 길이보다 최소한 같거나 (<Loop>를 사용하여 더 짧고 반복해야 하는 경우를 제외) 확인합니다.
종횡비가 적절한지 확인합니다. — 전체 화면 장면의 경우 컴포지션의 1920×1080과 일치해야 합니다. 2×2 그리드의 카드의 경우 4:3 또는 16:9 모두 작동합니다. 일관성만 유지하면 됩니다.

그런 다음 각 <VideoPlaceholder>를 <OffthreadVideo>로 기계적으로 교체합니다. 슬롯당 한 줄 교체입니다. 애니메이션 로직은 변경되지 않습니다. 사용자의 녹화가 시간에 민감한 경우(예: "7초에 실패 이벤트"), 장면 prop으로 노출하여 시간 종속 오버레이(FAIL 스탬프, 보상 번호)를 재녹화 없이 조정할 수 있습니다.

이 루프가 스킬에 중요한 이유

이 스킬의 역할은 "요청 시 Remotion 코드를 작성하는 것"이 아닙니다. 소스 자료에서 출시 비디오로 가는 루프를 다루기 쉽게 만드는 것입니다. 자리 표시자 패턴은 Claude가 한 번에 전체 비디오 구조를 스캐폴딩한 다음 ASSETS.md를 전달하여 사용자가 정확히 무엇을 녹화해야 하는지 알 수 있게 해줍니다. 이것 없이는 루프가 멈춥니다. 사용자는 잘못된 것을 녹화하거나, 스캐폴딩이 영상을 기다리거나, 코드 구조를 사후에 다시 맞춰야 합니다.

사용자가 소스 자료를 가지고 나타나면, 올바른 첫 번째 움직임은 일반적으로 다음과 같습니다:

"먼저 논문/사양서를 읽겠습니다. 그런 다음 목표 시간이 포함된 장면별 개요, 녹화해야 할 클립 목록을 제안하고, 자리 표시자가 있는 코드를 스캐폴딩하여 제가 장면을 계속 구축하는 동안 녹화를 시작할 수 있도록 하겠습니다."

새 프로젝트 빠른 시작

# 1. 스캐폴드 복사
cp -r <skill-dir>/scaffold ./my-demo
cd my-demo
npm install

# 2. 라이브 편집을 위해 Remotion Studio 열기
npm run dev    # http://localhost:3000 열림

# 3. 반복 작업 중 단일 장면 렌더링
npm run render:opening

# 4. 준비가 되면 전체 타임라인 렌더링
npm run render

스캐폴드에는 하나의 작동 장면(OpeningTitle), 크림-웜 테마, Reveal + 이징, ProgressBar, 자리 표시자 Main 타임라인, 그리고 사전 구성된 렌더링 스크립트가 포함된 package.json이 포함되어 있습니다.

프로젝트 레이아웃 (효율적인 구조)

my-demo/
├── package.json                      # 렌더링 스크립트, 프리렌더 훅
├── remotion.config.ts                # 코덱 / 픽셀 포맷 기본값
├── tsconfig.json
├── public/
│   ├── assets/                       # 로고, 정적 이미지 (staticFile("assets/..."))
│   └── clips/                        # 화면 캡처 / 비디오 소스
├── scripts/
│   └── sync-clips.mjs                # 각 렌더링 전에 클립 정규화
└── src/
    ├── index.ts                      # registerRoot(Root)
    ├── Root.tsx                      # <Composition> 레지스트리 — id, schema, defaultProps
    ├── theme.ts                      # COLORS, FONT_STACK, RADIUS, SHADOWS, TIMELINE
    ├── fonts.ts                      # @remotion/google-fonts + 로컬 @font-face
    ├── Main.tsx                      # 전체 타임라인 컴포저 (<Sequence> 블록)
    ├── components/
    │   ├── Reveal.tsx                # 페이드 + 라이즈 래퍼 (delay/duration/rise)
    │   ├── Easing.ts                 # EASE_OUT, EASE_IN_OUT (베지어)
    │   ├── ProgressBar.tsx           # 하단에 고정된 4단계 표시기
    │   └── VideoPlaceholder.tsx      # 슬롯 레이블이 있는 회색 카드, 나중에 OffthreadVideo로 교체
    └── scenes/
        ├── OpeningTitle.tsx          # 파일당 하나의 장면, 각각 <AbsoluteFill>
        ├── ProductReveal.tsx
        ├── AgentLoop.tsx
        └── ...

이 구조가 효과적인 이유: 장면이 독립적이어서(단독 렌더링 및 반복이 쉬움), 공유 시각적 언어가 theme.ts + components/에 있어 일관된 디자인을 유지하며, Root.tsx가 렌더링 가능한 항목의 단일 정보 소스입니다.

컴포지션 패턴 (주의 깊게 읽어보세요)

모든 장면은 세 가지를 내보냅니다:

Zod 스키마 — Remotion Studio에서 props 패널 UI를 정의합니다(슬라이더, 드롭다운).
*_DEFAULTS 상수 — 이 장면이 전체 타임라인에 포함될 때 Main.tsx에서 사용하는 값입니다.
React 컴포넌트 자체, React.FC<Props>로 타입이 지정됩니다.

// src/scenes/ProductReveal.tsx
import { z } from "zod";

export const productRevealSchema = z.object({
  titleSize:     z.number().min(40).max(280),
  subtitleSize:  z.number().min(14).max(80),
  outerPaddingV: z.number().min(0).max(200),
});
export type ProductRevealProps = z.infer<typeof productRevealSchema>;

export const PRODUCT_REVEAL_DEFAULTS: ProductRevealProps = {
  titleSize: 168,
  subtitleSize: 64,
  outerPaddingV: 80,
};

export const ProductReveal: React.FC<ProductRevealProps> = (p) => { ... };

그런 다음 Root.tsx에서 기본값의 인라인 복사본과 함께 등록합니다:

<Composition
  id="ProductReveal"
  component={ProductReveal}
  durationInFrames={120}
  fps={30}
  width={1920}
  height={1080}
  schema={productRevealSchema}
  defaultProps={{
    // ⚠ PRODUCT_REVEAL_DEFAULTS의 인라인 복사본 — Remotion Studio의
    // "Save default props"는 AST를 통해 이 객체에 다시 씁니다.
    // 위에 내보낸 상수와 동기화 상태를 유지하십시오.
    titleSize: 168,
    subtitleSize: 64,
    outerPaddingV: 80,
  }}
/>

중복의 이유: Remotion Studio의 "Save default props" 버튼은 AST 조작을 통해 Root.tsx의 defaultProps={…} 리터럴을 편집합니다. 가져온 상수를 다시 쓸 수 없습니다. 따라서 인라인 복사본은 Studio가 변경하는 버전이고, 내보낸 *_DEFAULTS는 Main.tsx가 읽는 버전입니다. Studio가 새 값을 기록하면, 이를 내보낸 상수에 복사하여 전체 타임라인 렌더링에서도 사용하도록 합니다. 이것은 references/pitfalls.md의 함정 #4입니다.

애니메이션 프리미티브 (실제로 필요한 작은 세트)

Remotion의 모든 애니메이션은 useCurrentFrame() + interpolate()입니다. 내부 시계나 "재생"은 없습니다. 모든 프레임은 프레임 번호의 순수 함수입니다.

기본 애니메이션 빌딩 블록:

페이드 인/아웃: interpolate(frame, [0, 15], [0, 1]) — Easing과 결합하여 부드럽게 만듭니다.
슬라이드/라이즈: interpolate(frame, [0, 20], [50, 0]) — Y 위치를 위로 이동합니다.
스케일: interpolate(frame, [0, 30], [0.8, 1]) — 확대 효과입니다.
회전: CSS transform: rotate(${interpolate(...)}deg) — 진입 회전에 사용합니다.
텍스트 문자별 표시: 일반적인 CSS clip-path 또는 SVG 텍스트 패스로 문자열을 문자로 분할합니다.

스캐폴드의 Reveal.tsx는 하나의 일관된 함수로 fade + rise를 래핑합니다. 대부분의 장면에 이것으로 충분합니다. 모든 진입 애니메이션에 대해 처음부터 새 interpolate() 호출을 작성하지 마십시오 — Reveal만 사용하십시오. 사용자 정의가 필요한 경우에만 인라인 interpolate를 사용하십시오.

렌더링 전략

이 스킬은 네 가지 렌더링 명령어를 사용합니다:

명령어	용도	세부 사항
`npm run dev`	Studio에서 반복 작업	Props 패널을 통한 라이브 리로드, 단일 장면, `?composition=SceneName`으로 특정 장면을 고정합니다.
`npm run render:<scene>`	단일 장면 MP4	`package.json` 스크립트: `npx remotion render src/index.ts <SceneName> out/<SceneName>.mp4`
`npm run render`	전체 타임라인 미리보기	`Main.tsx`를 렌더링합니다. MP4로 내보내지만 편집기로 가져오는 최종 출력물은 아닙니다.
`npm run render:<scene> -- --codec=prores --pixel-format=yuva444p10le --prores-profile=4444`	알파가 있는 클립	로고, 하단 1/3, 화면 캡처 위에 합성해야 하는 모든 것에 사용합니다. 파일 크기는 크지만 후반 작업에 필수적입니다.

시퀀스 렌더링 가정

render:<scene> 스크립트는 src/index.ts가 Root.tsx를 등록한다고 가정합니다. Root.tsx는 모든 <Composition> 등록의 단일 소스입니다. 장면을 추가한 후에 Root.tsx에 등록하는 것을 잊지 마십시오. 그렇지 않으면 Remotion이 알 수 없는 composition-id에 대해 오류를 발생시킵니다.

sync-clips.mjs 스크립트는 각 렌더링 전에 public/clips/를 정규화합니다(파일 이름을 소문자로 변환, 공백 제거, 길이가 일치하는지 빠르게 확인). pre-commit 훅에 연결하거나 스캐폴드의 render 및 render:<scene> 스크립트에 프리훅으로 포함하는 것이 좋습니다.

자주 마주치는 함정

이 섹션은 비용이 많이 드는 일반적인 Remotion 함정을 문서화합니다. 문제를 발견하면 references/pitfalls.md를 참조하십시오. 하지만 현재 컨텍스트에 맞는 몇 가지를 강조하겠습니다:

composition-id 불일치. Root.tsx의 id는 렌더 명령어의 <SceneName>과 정확히 일치해야 합니다. 하나의 문자 차이로 "구성 요소를 찾을 수 없음" 오류가 발생합니다. package.json 스크립트에서 ID를 업데이트하는 것을 잊지 마십시오.
기본값 동기화 오류. Root.tsx에서 인라인 defaultProps가 *_DEFAULTS 상수와 일치하지 않으면 전체 타임라인 렌더링이 Studio 미리보기와 다른 값을 사용합니다. 사용자가 "Studio에서는 좋아 보이는데 렌더링 결과가 다릅니다"라고 말하면 먼저 기본값을 확인하십시오.
<Sequence> 외부에서 useCurrentFrame(). Main.tsx 내부에서 각 <Sequence>는 자체적인 프레임 컨텍스트를 가져야 합니다. useCurrentFrame()을 최상위 Main에 두고 그 값을 하위 장면으로 전달하지 마십시오. 대신 각 장면이 자체 useCurrentFrame()을 호출하도록 하십시오(독립적으로 렌더링될 수 있도록). <Sequence>는 오프셋을 처리합니다.
Windows의 ffmpeg 정리 실패. EPERM 오류는 일반적으로 Windows에서 이전 렌더링의 ffmpeg 프로세스가 임시 파일을 잠근 경우 발생합니다. 해결 방법: --overwrite 플래그를 추가하거나 Remotion을 업데이트합니다.

참조 (이 스킬이 번들로 제공하는 것)

references/pitfalls.md — Remotion 함정의 전체 목록과 해결 방법.
references/performance.md — 렌더링 속도에 대한 참고 사항(병목 현상이 있는 useMemo, 작은 구성 요소 분할, 하드웨어 가속).
references/animation-patterns.md — 특정 상황별 애니메이션 레시피(차트, 텍스트 입력, 진행 표시줄).
scaffold/ — 위의 모든 항목이 포함된 작업 프로젝트 템플릿. cp -r로 복사하고 즉시 작업을 시작합니다.

remotion-demo-video