권장: Remotion 모범 사례 로드
이 스킬은
remotion-best-practices(번들에 포함되지 않음)를 함께 사용하면 전체 Remotion 패턴 라이브러리를 활용할 수 있습니다. 선택 사항이며, 없을 경우 아래 최소 규칙이 적용됩니다.
- Pi:
remotion-best-practices에 로드된 스킬을 읽습니다(사용 가능한 스킬 목록에 표시됨).- Claude Code: 진행 전에
remotion-best-practices스킬/도구를 호출합니다.설치되어 있지 않나요? remotion-dev/skills에서 받을 수 있습니다. (문서: remotion.dev/docs/ai/skills).
remotion-best-practices가 설치되지 않은 경우 최소 규칙: chromium을 사용할 수 있어야 하며, 항상 4K 콘텐츠를<Scale4K>로 감싸고,<TransitionSeries>를linearTiming과 함께 사용하며, 오디오를 마스터 클록으로 취급합니다.
비디오 팟캐스트 메이커
주제를 바탕으로 4K Bilibili 수평형 지식 영상을 자동 제작합니다. 코딩 에이전트 + TTS 백엔드 + Remotion + FFmpeg.
목차
- 부트스트랩 — 사전 준비 (1단계 전에 실행)
- 실행 모드 — 자동 vs 대화형 → references/workflow-script.md
- 기존 영상 재생성 — 완성된 영상을 반복 수정
- 워크플로우 — 11단계 파이프라인 + 단계별 파일 포인터 + 필수 중단점
- 하드 규칙 — 절대 타협할 수 없는 제약 조건
- 오디오-마스터 클록 및 동기화
- 영상별 디렉토리 구조
- 추가 리소스 — 각
references/파일 로드 시점 - 사용자 선호도
- 문제 해결
부트스트랩
SKILL_DIR을 이 SKILL.md가 있는 디렉토리로 설정합니다.
- Pi: 에이전트는 로드된 스킬 목록에서 스킬 경로를 알고 있습니다. 명령어 실행 전에
SKILL_DIR을 해당 디렉토리로 설정하세요. - Claude Code:
${CLAUDE_SKILL_DIR}이 자동으로 채워집니다.
SKILL_DIR="${SKILL_DIR:-${CLAUDE_SKILL_DIR}}"
# 사전 준비 (CLI + 백엔드 환경 변수)
python3 "${SKILL_DIR}/scripts/check_prereqs.py"
업데이트는 skills CLI(npx skills update video-podcast-maker -g)를 통해 이루어집니다. 직접 git clone 설치는 README에 따라 git pull을 사용합니다. 이 스킬은 업데이트 확인을 자체적으로 수행하지 않습니다.
사전 준비 실패 — README.md의 설정 안내를 참조하세요. 확인은 백엔드를 인식합니다(TTS_BACKEND 환경 변수 → user_prefs.json의 global.tts.backend → 기본값 edge), 따라서 활성화된 백엔드에 필요한 환경 변수만 검증됩니다.
새 프로젝트의 첫 번째 영상인가요? 기존 Remotion 프로젝트(node_modules/가 이미 설치된)를 재사용하는 것이 좋습니다. 새 프로젝트를 생성하면 한 번에 약 2.2GB의 npm 패키지와 90MB의 Chrome Headless Shell을 다운로드해야 합니다(프로젝트당 한 번). 사용자가 이전 영상에서 사용한 프로젝트가 있다면 그것을 사용하세요. 새 프로젝트가 필요하다면, 1-4단계(주제 연구 및 스크립트 작성)를 진행하는 동안 백그라운드에서 npm install을 실행하세요.
모든 렌더링은 videos/{name}/ 디렉토리로 출력됩니다. 모든 output.mp4, final_video.mp4, thumbnail_*.png 파일은 해당 영상 디렉토리에 직접 저장됩니다. out/ 또는 dist/ 디렉토리로 렌더링하지 마세요. --public-dir videos/{name}/ 규칙으로 모든 것을 독립적으로 유지합니다.
TTS 엔진 — 두 가지 로컬 백엔드, 외부 스킬 불필요:
edge(기본값) — 무료, 키 불필요, edge-tts 사용.azure—AZURE_SPEECH_KEY+AZURE_SPEECH_REGION필요 (Microsoft Speech SDK).
각 엔진은 자체적으로 합성합니다(scripts/tts/backends/native.py). 발음(표시 → 발음 → 자막용 표시로 변환)과 음소 적용이 내장되어 있습니다. check_prereqs.py는 활성화된 백엔드의 환경 변수를 검증합니다.
멀티 플랫폼 TTS? 이전에 9개 백엔드 매트릭스를 제공했던 ttscn 구성 요소 스킬은 더 이상 이 스킬의 종속성이 아닙니다. 해당 플랫폼이 필요하다면 Agents365-ai/ttsCN을 별도로 설치하고 직접 호출하세요. 이 스킬은 edge + azure만 제공합니다.
디자인 학습 바로가기: 사용자가 참고 영상/이미지를 제공하거나 스타일 프로필 저장/목록/삭제를 요청하는 경우, 아래 워크플로우 대신 references/design-learning.md를 참조하세요.
실행 모드
워크플로우 시작 시 자동 모드(기본값)와 대화형 모드를 감지합니다. 자동-기본 결정 테이블과 요청별 재정의는 references/workflow-script.md에 있습니다.
기존 영상 재생성
videos/{name}/ 디렉토리가 이미 존재하고 사용자가 완성되었거나 진행 중인 영상을 반복 수정하는 경우, 해당 디렉토리를 재사용하세요. 새 프로젝트나 videos/{newname}/을 시작하지 마세요.
실제 변경된 내용에 따라 가장 작은 재실행을 선택하세요:
| 변경 사항 | 재실행 | 재사용 (다시 하지 않음) |
|---|---|---|
나레이션 스크립트(podcast.txt) | 7단계(TTS) → 8단계 미리보기 → 렌더링+믹싱 | 주제 연구 + 섹션 설계 |
| 비주얼만(컴포넌트, 레이아웃, 색상) | 8단계 미리보기 → 렌더링+믹싱 | 오디오(podcast_audio.wav / timing.json) |
| 배경 음악만 | BGM 재믹싱 | output.mp4 (재렌더링 불필요) |
| 자막만 | 10.1단계 마무리 | output.mp4 / video_with_bgm.mp4 |
시청자가 보거나 듣는 내용을 변경하는 모든 재실행은 8단계 게이트를 다시 거쳐야 합니다. 변경 사항을 적용하고, Studio 핫 리로드를 기다린 후, 새로운 명시적인 "4K 렌더링" 확인을 기다리세요. 이전 확인은 유효하지 않습니다. 스크립트 변경은 모든 다운스트림 타임스탬프를 변경하므로, 항상 TTS를 통해 timing.json을 재생성하세요. 수동 편집하지 마세요. 재실행 후 다음 명령어로 다시 검증하세요:
python3 ${SKILL_DIR}/scripts/verify_output.py videos/{name}/
워크플로우
완성된 영상을 반복 수정 중인가요?
videos/{name}/이 이미 존재한다면, 위의 기존 영상 재생성을 참조하여 최소 재실행을 하세요. 1단계부터 시작하지 마세요.
1단계 시작 시 에이전트의 작업 추적기에 각 단계별로 하나의 작업을 생성하세요. 시작 시 in_progress, 완료 시 completed로 표시하세요. videos/{name}/ 디렉토리의 파일이 지속적인 기록이므로, 중단된 경우 디렉토리를 검사하여 어디서 재개할지 결정하세요.
| # | 단계 | 출력 | 단계 파일 |
|---|---|---|---|
| 1 | 주제 방향 정의 | topic_definition.md | workflow-script.md |
| 2 | 주제 연구 | topic_research.md | workflow-script.md |
| 3 | 5-7개 섹션 설계 | (메모리 내) | workflow-script.md |
| 4 | 나레이션 스크립트 작성 | podcast.txt | workflow-script.md |
| 4.5 | 발음 사전 점검 (zh-CN) | phonemes.json | workflow-script.md |
| 5 | 에셋 계획 및 확보 | assets/manifest.json | workflow-assets.md |
| 6 | 썸네일 생성 (16:9 + 4:3) | thumbnail_*.png | workflow-production.md |
| 7 | TTS 오디오 생성 | podcast_audio.wav, timing.json | workflow-production.md |
| 8 | Remotion 구성 + Studio 미리보기 | — | workflow-production.md |
| 9 | 4K 렌더링 + BGM 믹싱 | output.mp4, video_with_bgm.mp4 | workflow-production.md |
| 10 | 게시 정보 + 출력 검증 | publish_info.md, final_video.mp4 | workflow-publish.md |
| 11 | 세로형 쇼츠 생성 (선택 사항) | shorts/ | workflow-publish.md |
필수 중단점 (위의 굵은 행):
- 8단계 — Studio 검토. 반드시
npx remotion studio를 실행하고 사용자 피드백을 기다린 후 렌더링하세요. 사용자가 명시적으로 확인("4K 렌더링" / "최종 렌더링")할 때까지 절대 4K를 렌더링하지 마세요. 조정 요청이 포함된 답변은 확인이 아닙니다. 변경 사항을 적용하고, Studio 핫 리로드를 기다린 후, 다시 질문하세요. 각 조정 라운드는 9단계 전에 새로운 확인이 필요합니다. - 10단계 —
verify_output.py. 반드시 통과해야 영상 완료로 선언할 수 있습니다. 종료 코드 0 = 통과, 종료 코드 2 = 경고가 있지만 게시 가능. 일반적인 누락 사항을 자동 수정합니다(final_video.mp4누락 시 생성). 플랫폼 매트릭스에 대해 게시 정보(제목, 설명, 태그, 챕터)를 검증합니다. 5.5단계와 10.2단계에서 생성하세요. 기계 판독 가능 출력을 원하면--format json을 추가하세요.
렌더링 전 감사 (권장) — 8단계 전:
python3 ${SKILL_DIR}/scripts/audit_beat_sync.py <Video.tsx> <timing.json>
나레이션에서 1.5초 이상 벗어난 비트를 플래그합니다.
자동 모드: 시각적 자체 검토. 자동 모드(사용자가 Studio를 보지 않음)로 실행 중일 때는 렌더링 확인을 요청하기 전에 3-5개의 키 프레임 스틸을 렌더링하세요:
npx remotion still src/remotion/index.ts <CompositionId> videos/{name}/_review_001.png --public-dir videos/{name}/ --frame=<중간_프레임>
프레임 선택: 히어로 타이틀(~10% 지점), 밀도 높은 섹션 중간점, 아웃트로. 스틸을 이미지로 읽고 design-guide.md 및 visual-taste.md 체크리스트를 실제 렌더링 출력과 비교하여 실행하세요. 4K 렌더링 전에 오버플로, 대비, 레이아웃 문제를 발견하세요. 검토 후 _review_*.png를 삭제하세요.
검증 체크포인트
| 단계 이후 | 확인 사항 |
|---|---|
| 7 (TTS) | podcast_audio.wav 재생 가능 · timing.json이 모든 섹션 포함 · SRT가 UTF-8 인코딩 |
| 9 (렌더링) | output.mp4가 3840×2160 · 오디오-비디오 동기화 · 검은 프레임 없음 |
| 10 (검증) | verify_output.py 종료 코드 0 (또는 검토된 경고 포함 2) |
하드 규칙
| 규칙 | 요구 사항 |
|---|---|
| 단일 프로젝트 | 모든 영상은 사용자의 Remotion 프로젝트 내 videos/{name}/ 아래에 저장됩니다. 영상마다 새 프로젝트를 절대 생성하지 마세요. |
| 4K 출력 | 3840×2160 (또는 세로형 2160×3840), 1920×1080 디자인 공간 위에 scale(2) 래퍼 사용 |
| 오디오 동기화 | 오디오(podcast_audio.wav + podcast_audio.srt)가 마스터 클록입니다. timing.json은 반드시 실제 TTS 출력에서 생성되어야 하며, 수동으로 추정하지 마세요. 렌더링 전 최종 영상 길이는 오디오와 ±0.5초 이내로 일치해야 합니다. 오디오-마스터 클록 및 동기화를 참조하세요. |
| 썸네일 | 반드시 16:9(1920×1080)와 4:3(1200×900) 두 가지 모두 생성해야 합니다. design-guide.md 참조 |
| 렌더링 전 Studio | 반드시 remotion studio를 실행하여 검토해야 합니다. 사용자가 명시적으로 확인할 때까지 절대 4K를 렌더링하지 마세요. 조정 피드백 ≠ 확인. 적용하고, 핫 리로드한 후, 다시 질문하세요. |
--public-dir | 모든 Remotion 명령어는 --public-dir videos/{name}/을 사용합니다. 모든 출력 파일(output.mp4, final_video.mp4, 썸네일)은 videos/{name}/에 직접 저장되며, out/ 또는 dist/ 디렉토리를 사용하지 마세요. |
시각적 최소 기준(텍스트 크기, 콘텐츠 너비, 안전 영역, 애니메이션 안전)은 references/design-guide.md에 있습니다. 8단계 전에 반드시 로드하세요.
오디오-마스터 클록 및 동기화
황금률
- 오디오는 마스터 클록입니다. 모든 슬라이드 시작, 자막, 챕터 및 애니메이션 비트는
podcast_audio.wav와podcast_audio.srt에서 파생됩니다. - 텍스트 추정이 아닌 TTS에서 타이밍을 생성하세요. 파이프라인:
podcast.txt→generate_tts.py→podcast_audio.wav+podcast_audio.srt+timing.json→ 구성 → 렌더링. - 오디오가 존재하기 전에
timing.json을 수동으로 작성하지 마세요. 이미 큐레이팅된 슬라이드가 있다면,align_timing_from_srt.py를 실행하여 실제 SRT에 고정하세요. - TransitionSeries 오버랩 보정.
TransitionSeries는sum(section.duration_frames) - (N-1) * transitionFrames프레임을 렌더링합니다. 렌더링된 길이가timing.total_frames와 같도록 모든 섹션을 비례적으로 조정하세요. 모든 오버랩 프레임을 첫 번째 섹션에 집어넣지 마세요. 올바른 패턴은templates/Video.tsx에 있습니다.
필수 동기화 체크포인트
| 시점 | 확인 사항 |
|---|---|
| 7단계(TTS) 이후 | timing.json.total_duration이 podcast_audio.wav와 ±0.5초 이내로 일치 |
| 렌더링 전 | Video.tsx가 모든 섹션을 전환 오버랩에 맞게 조정 |
| 렌더링 후 | final_video.mp4 길이가 podcast_audio.wav와 ±0.5초 이내로 일치 |
| 10단계(검증) | verify_output.py 종료 코드 0, 오디오/타이밍에 대해 녹색 보고 |
체크포인트가 하나라도 실패하면 중단하세요. 게시하지 마세요.
출력 사양
| 매개변수 | 수평형 (16:9) | 세로형 (9:16) |
|---|---|---|
| 해상도 | 3840×2160 (4K) | 2160×3840 (4K) |
| 프레임 속도 | 30fps | 30fps |
| 인코딩 | H.264, 16Mbps | H.264, 16Mbps |
| 오디오 | AAC, 192kbps | AAC, 192kbps |
| 길이 | 1-15분 | 60-90초 (하이라이트) |
영상별 디렉토리 구조
project-root/ # Remotion 프로젝트 루트
├── src/remotion/ # Remotion 소스 (Root.tsx, compositions, index.ts)
├── videos/{video-name}/ # 영상별 디렉토리
│ ├── topic_definition.md # 1단계
│ ├── topic_research.md # 2단계
│ ├── podcast.txt # 4단계: 나레이션 스크립트
│ ├── phonemes.json # 4.5단계: 중국어 간체 발음 오버라이드
│ ├── assets/manifest.json # 5단계: 섹션별 에셋 레지스트리
│ ├── publish_info.md # 10단계: 제목/설명/태그
│ ├── podcast_audio.wav # 7단계: TTS 오디오
│ ├── podcast_audio.srt # 7단계: 자막
│ ├── timing.json # 7단계: 타임라인 (애니메이션 구동)
│ ├── thumbnail_*.png # 6단계
│ ├── output.mp4 # 9단계: 4K 렌더링
│ ├── video_with_bgm.mp4 # 9단계: BGM 포함
│ ├── final_video.mp4 # 10단계: 최종 출력
│ └── bgm.mp3 # 배경 음악
└── remotion.config.ts
영상별 --public-dir
모든 Remotion 명령어는 --public-dir videos/{name}/을 사용합니다. 각 영상의 에셋은 자체 디렉토리에 유지되어 병렬 렌더링이 가능합니다:
npx remotion studio src/remotion/index.ts --public-dir videos/{name}/
npx remotion render ... videos/{name}/output.mp4 --public-dir videos/{name}/ --video-bitrate 16M
추가 리소스
| 파일 | 로드 시점 | 용도 |
|---|---|---|
| references/workflow-script.md | 1단계 | 실행 모드 결정, 주제 방향 브레인스토밍, 섹션 설계 패턴, 단계별 명령어 |
| references/workflow-assets.md | 5단계 | 에셋 매니페스트 스키마, 허용 가능한 소스, 섹션 자동 할당 |
| references/workflow-production.md | 6-9단계 | Remotion 구성, TTS 백엔드 호출, 4K 렌더링 플래그, BGM 믹싱 |
| references/workflow-publish.md | 10-11단계 | 게시 정보 필드, 썸네일 규칙, 출력 검증, 세로 쇼츠 생성 |
| references/design-guide.md | 8단계 전 | 텍스트 크기, 콘텐츠 너비, 애니메이션 안전 영역, 색상 팔레트 |
| references/visual-taste.md | 8단계 전 | 브랜드 일관성, 타이포그래피 계층, 그리드 시스템, 시각적 리듬 |
| references/design-learning.md | 사용자 요청 시 | 참고 영상/이미지에서 패턴 추출, 스타일 프로필 관리 |
절대 하드 링크 하지 마세요. 모든 파일은 각 영상 디렉토리에 완전히 복사되어야 합니다.
사용자 선호도
이 스킬은 user_prefs.json (Remotion 프로젝트 루트에 위치)을 읽어서 기본 동작을 재정의합니다. 현재 인식되는 키는 다음과 같습니다:
| 키 | 예시 | 효과 |
|---|---|---|
global.tts.backend | "azure" | edge 대신 Azure TTS를 영구적으로 사용합니다. 자격 증명(AZURE_SPEECH_KEY, AZURE_SPEECH_REGION)이 설정되어 있어야 합니다. |
global.tts.voice | "zh-CN-XiaoxiaoNeural" | 활성 백엔드의 특정 TTS 음성을 강제로 사용합니다. 백엔드 기본값을 재정의합니다. |
global.output.bitrate | "20M" | H.264 비트레이트를 16M(기본값)에서 변경합니다. 더 높은 값은 파일 크기를 늘리지만 압축 아티팩트를 줄입니다. |
global.output.fps | 24 | 프레임 속도를 30(기본값)에서 변경합니다. 영화 같은 느낌에 적합하지만 애니메이션이 덜 부드러울 수 있습니다. |
platforms.default | ["bilibili", "youtube"] | 게시 정보에 표시할 기본 플랫폼 목록입니다(publish_info.md 생성 시 사용). |
user_prefs.json이 없으면 모든 기본값이 적용됩니다. 이 파일은 JSON 형식이어야 하며, 유효하지 않을 경우 파싱 오류 없이 자동 무시됩니다(기본값 사용).
문제 해결
| 문제 | 해결 방법 |
|---|---|
| "chromium not found" / Puppeteer 오류 | npx remotion browser ensure 실행 또는 browser 디렉토리를 수동으로 설치하세요. |
edge-tts 오류 (인증) | pip install --upgrade edge-tts로 최신 버전을 확인하세요. 오래된 버전은 Azure 엔드포인트 변경으로 실패할 수 있습니다. |
output.mp4 조회 시 검은 프레임 | timing.json에 모든 섹션에 대한 항목이 있는지, Video.tsx가 TransitionSeries를 사용하는지 확인하세요. audit_beat_sync.py를 실행하세요. |
| TTS가 중국어 대신 영어를 말함 | phonemes.json에 zh-CN 발음 오버라이드가 포함되어 있는지 확인하세요. 일부 영어 단어는 음소가 필요할 수 있습니다. |
| 렌더링에 너무 오래 걸림 (2시간+) | Chrome 원격 디버깅 포트를 확인하세요. 여러 Remotion 인스턴스가 GPU 메모리를 놓고 경쟁할 수 있습니다. --concurrency=2로 제한하세요. |
final_video.mp4에 오디오가 없음 | FFmpeg 믹싱 단계가 출력에 오디오 코덱을 포함하는지 확인하세요. verify_output.py가 오디오 트랙 존재 여부를 확인합니다. |
이 스킬은 Agents365-ai/video-podcast-maker 프로젝트의 일부입니다.
라이선스 — 자세한 내용은 프로젝트 저장소의 LICENSE 파일을 참조하세요.