| 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
이미지 삽입 패턴
사용자가 이미지를 제공한 경우:
public/images/에 복사<Img src={staticFile("images/파일명")} />- spring explosive entrance (scale 0→1.15→1, damping 8)
- continuous floating (Math.sin 기반 y 흔들림)
- optional glitch 효과 (frame % 90 < 2에서 skewX)
- 뒤에 rotating dashed tech ring 배치
차트 패턴
- 바 차트: spring으로 바 높이 성장, glow boxShadow
- 라인 차트: SVG strokeDasharray/offset로 progressive draw, pulsing dot
필수 규칙
- 프레임 기반 애니메이션만 —
useCurrentFrame() + interpolate() / spring()
- CSS transition/animation 금지
- 결정론적 렌더링 —
Math.random() 금지, Math.sin(frame * N) 사용
- COLORS 상수 사용 — 하드코딩 색상 금지
- 폰트는 fonts.ts에서 import
- position absolute + top 기반 (bottom 사용 지양)
- WebGL/ThreeCanvas 사용 금지 — headless 렌더링 시 WebGL 컨텍스트 오류. CSS 3D로 대체
- 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 생성 + 오디오 통합
npx tsx --env-file=.env scripts/generate-voiceover.ts voiceover-config.json
npx tsx scripts/generate-voiceover-qwen.ts voiceover-config.json
오디오 길이 측정 → styles의 SCENE_DURATIONS를 오디오+1초 여유로 재설정.
각 씬에 <Audio src={staticFile("voiceover/ID/scene-0X.mp3")} /> 삽입.
렌더링 후 오디오 간극 조정
렌더링 결과를 확인한 후, 음성 사이 간극이 큰 씬이 있으면:
ffprobe로 각 씬 오디오 길이 재측정- 간극이 큰 씬의 SCENE_DURATIONS를
오디오 길이 + 0.5초로 줄이기
- 재렌더링
Step 7: 검수팀 디스패치 (3팀 병렬)
3개 Agent를 동시 호출:
- 코드 품질 — TS 에러, Remotion 패턴 준수, Math.random/CSS transition/useFrame 미사용
- 디자인 일관성 — 1080×1920 레이아웃, GIF 존 겹침 없음, 타이포 위계
- 모션 타이밍 — 애니메이션 씬 내 완료, 오디오 타이밍 동기화, 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 설정
