remotion-shorts

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

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

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

Step 3: 프로젝트 세팅

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

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

TTS 생성 + 오디오 통합

# 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

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

Step 8: 렌더링

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

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

주의사항

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