# Remotion Shorts

> 9:16 세로형 숏폼 기술 해설 영상을 Remotion으로 제작. 노트/URL/텍스트/SRT를 다크 테마 타이포 모션그래픽 영상으로 변환하고, 에이전트 팀(기획/제작/검수) 기반으로 GIF+보이스오버+차트+이미지를 포함한 MP4를 렌더링. 사용 시점 - (1) 영상 만들어줘, 숏폼 만들어줘 요청 시, (2) 노트나 문서를 영상으로 변환 요청 시, (3) Remotion 기반 세로형 영상 제작 시, (4) shorts, 숏폼, 릴스, 세로 영상 키워드 시.

- Skill: `jkf87/remotion-shorts` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jkf87/remotion-shorts`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jkf87/remotion-shorts/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jkf87 (https://skillmd.com/u/jkf87)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jkf87/remotion-shorts

---


# Remotion 숏폼 영상 제작

노트/문서/SRT를 9:16 숏폼 영상으로 변환. 에이전트 팀이 기획→제작→검수를 수행.

## 제작 파이프라인

```
입력 분석 → 기획팀(3인 병렬) → GIF 수집 → 제작팀(병렬) → TTS 생성 → 검수팀(병렬) → 렌더링
```

## Step 1: 입력 분석

노트/URL/텍스트/SRT를 읽고 파악:
- 주제와 대상 독자
- 전달할 메시지 3-5개
- 스토리 구조 (문제→해결, 개념→응용, 스토리텔링 등)
- 사용자 이미지가 있으면 확인 (캐릭터, 로고, 스크린샷 등)

## Step 2: 기획팀 디스패치 (3인 병렬)

3개 Agent를 **하나의 메시지에서 동시** 호출. `model: "sonnet"` 지정.

**Agent 1 — 기획자**: 6씬 레이아웃 존 맵 (Y좌표 기반), GIF 배치 구역, 애니메이션 타이밍
**Agent 2 — 카피/GIF 큐레이터**: GIF 키워드 선정 (영어 2-3단어), 중중중약강 리듬
**Agent 3 — 검수자**: 기존 코드 문제 분석, 개선 제안

### 6씬 구조

| 씬 | 역할 | 권장 시간 | GIF 리듬 |
|----|------|-----------|----------|
| 1 | 훅 | 8초 | 없음 or 중 |
| 2 | 맥락/배경 | 8-11초 | 중 |
| 3 | 주요 개념 | 9-10초 | 중 |
| 4 | 시각화/비유 | 8-10초 | 중 or 약 |
| 5 | 비교/심화 | 10초 | 약 |
| 6 | 마무리/CTA | 8-10초 | 강 |

### GIF 배치 패턴 (카드뉴스 방식)

GIF는 **씬 상단 전용 존**(상단 35-50%)에 full-width로 배치. 텍스트와 절대 같은 영역을 공유하지 않음.

```
┌─────────────────┐
│  GIF (full-width)│  ← 상단 35-50%
│  + gradient      │  ← linear-gradient(to bottom, transparent 40%, bg 100%)
│  + 키워드 오버레이│
├─────────────────┤
│  텍스트 콘텐츠   │  ← 하단 50-65%
│  (카드/차트 등)  │
└─────────────────┘
```

- GIF opacity: 1.0 (반투명 처리 금지)
- gradient overlay 필수
- 키워드를 GIF 위에 오버레이 (textShadow로 가독성 확보)
- GIF 없는 씬의 상단 존: 타이포 or 이미지 or 3D 배경으로 활용

### GIF 검색 (gifgrep)

```bash
gifgrep "영어 키워드" --max 1 --format url --quiet 2>/dev/null
```

키워드 패턴: [references/voiceover-workflow.md](references/voiceover-workflow.md) 참조.
결과 부적합 시 대체 키워드로 재검색.

## Step 3: 프로젝트 세팅

```bash
bash scripts/init-project.sh <project-dir>
```

## Step 4: 디자인 스타일 선택 + 씬 코드 작성

### 디자인 스타일 옵션

| 스타일 | 특징 | 적합한 주제 |
|--------|------|-------------|
| **다크 네온** | #0a0a0f 배경, 시안/퍼플 강조, 기본 | 기술 해설 전반 |
| **Aurora Glassmorphism** | breathing gradient 배경, glass 패널, Radar Rings | 프리미엄 기술 소개 |
| **런치 비디오** | Mac AppWindow 크롬, 앰버 강조, 3D perspective, 수렴 라인 | 제품 출시, 도구 소개 |

### 공통 컴포넌트

씬에서 필요에 따라 사용:

- **Highlight** — rough.js 스타일 형광펜 마커 (좌→우 확장, 키워드 강조)
- **ScannerLine** — 위→아래 스캔 수평선 (기술 느낌)
- **CornerBrackets** — 4개 모서리 브래킷 장식
- **GlassPanel** — Glassmorphism 패널 (backdrop-filter blur)
- **AuroraBackground** — breathing radial gradient 배경
- **RadarRings** — 회전 dashed 원 (레이더 느낌)
- **FloatingOrbs** — 부유 글래스 구체 (depth-of-field blur)

### Mac AppWindow 패턴 (런치 비디오 스타일)

모든 콘텐츠를 Mac 윈도우 크롬으로 감싸기:
- 트래픽 라이트 (빨/노/초 14px 원)
- surface 배경 + border
- 콘텐츠 영역: padding 24px 32px

### 이미지 삽입 패턴

사용자가 이미지를 제공한 경우:
1. `public/images/`에 복사
2. `<Img src={staticFile("images/파일명")} />`
3. spring explosive entrance (scale 0→1.15→1, damping 8)
4. continuous floating (Math.sin 기반 y 흔들림)
5. optional glitch 효과 (frame % 90 < 2에서 skewX)
6. 뒤에 rotating dashed tech ring 배치

### 차트 패턴

- **바 차트**: spring으로 바 높이 성장, glow boxShadow
- **라인 차트**: SVG strokeDasharray/offset로 progressive draw, pulsing dot

### 필수 규칙

1. **프레임 기반 애니메이션만** — `useCurrentFrame()` + `interpolate()` / `spring()`
2. **CSS transition/animation 금지**
3. **결정론적 렌더링** — `Math.random()` 금지, `Math.sin(frame * N)` 사용
4. **COLORS 상수 사용** — 하드코딩 색상 금지
5. **폰트는 fonts.ts에서 import**
6. **position absolute + top 기반** (bottom 사용 지양)
7. **WebGL/ThreeCanvas 사용 금지** — headless 렌더링 시 WebGL 컨텍스트 오류. CSS 3D로 대체
8. **GIF는 `<Gif>` 컴포넌트 사용** (`@remotion/gif`) — `<Img>`로 GIF를 넣으면 떨림/끊김 발생

씬 패턴 상세: [references/scene-patterns.md](references/scene-patterns.md)

## Step 5: 제작팀 디스패치 (2-3 병렬)

씬 6개를 2-3개 Agent로 나누어 **병렬 작성**. 각 Agent에게 전달:
- 기획팀 결과 (레이아웃 존 맵, GIF URL, 키워드)
- 디자인 스타일 + COLORS 상수
- 공통 컴포넌트 목록
- GIF/이미지 경로
- 필수 규칙

## Step 6: 대본 작성 + TTS 생성

TTS 엔진 2가지 지원:

| 엔진 | 조건 | 명령어 |
|------|------|--------|
| **ElevenLabs** | API 키 있을 때 | `npx tsx --env-file=.env scripts/generate-voiceover.ts config.json` |
| **Qwen TTS** | API 키 없을 때 (무료) | `npx tsx scripts/generate-voiceover-qwen.ts config.json` |

Qwen TTS는 HuggingFace `Qwen/Qwen3-TTS` Space 사용. Dylan 음성, 한국어 지원, API 키 불필요.

### 대본 작성

`voiceover-config.json`으로 작성. 규칙:
- 구어체, 씬당 1-3문장
- 상투적 표현 배제 ("혁신적", "패러다임")
- **영어/숫자는 소리나는 대로 한글 음역** (예: AI→에이아이, Claude Code→클로드 코드)
- 화면 텍스트는 영어 그대로, 대본에서만 음역

상세 음역 규칙: [references/voiceover-workflow.md](references/voiceover-workflow.md)

### TTS 생성 + 오디오 통합

```bash
# ElevenLabs (API 키 필요)
npx tsx --env-file=.env scripts/generate-voiceover.ts voiceover-config.json

# Qwen TTS (무료, API 키 불필요)
npx tsx scripts/generate-voiceover-qwen.ts voiceover-config.json
```

오디오 길이 측정 → styles의 SCENE_DURATIONS를 오디오+1초 여유로 재설정.
각 씬에 `<Audio src={staticFile("voiceover/ID/scene-0X.mp3")} />` 삽입.

### 렌더링 후 오디오 간극 조정

렌더링 결과를 확인한 후, 음성 사이 간극이 큰 씬이 있으면:
1. `ffprobe`로 각 씬 오디오 길이 재측정
2. 간극이 큰 씬의 SCENE_DURATIONS를 `오디오 길이 + 0.5초`로 줄이기
3. 재렌더링

## Step 7: 검수팀 디스패치 (3팀 병렬)

3개 Agent를 **동시** 호출:

1. **코드 품질** — TS 에러, Remotion 패턴 준수, Math.random/CSS transition/useFrame 미사용
2. **디자인 일관성** — 1080×1920 레이아웃, GIF 존 겹침 없음, 타이포 위계
3. **모션 타이밍** — 애니메이션 씬 내 완료, 오디오 타이밍 동기화, dwell time

체크리스트: [references/review-checklist.md](references/review-checklist.md)

Critical 발견 시 수정 후 재검수. **PASS 받은 후 렌더링 진행**.

## Step 8: 렌더링

```bash
npx remotion render <CompositionId> out/<filename>.mp4 --codec h264
```

WebGL 사용 씬이 있으면 `--concurrency 1` 추가.

## 주의사항

- `.env` 파일은 커밋/업로드 금지 (API 키 포함)
- GIF URL은 Tenor CDN 링크, 장기 보존 시 로컬 저장 권장
- NotoSansKR 폰트 로딩 시 `ignoreTooManyRequestsWarning: true` 설정