| name | mv-clip-factory |
| description | 음악 + 레퍼런스 영상 → 가사 작성 → 스토리보드 → 웹툰 이미지 생성 → AI 영상 클립 생성 → 최종 MV 편집까지의 전체 뮤직비디오 제작 파이프라인. 뮤직비디오, MV, 영상제작, AI영상, 클립생성, 스토리보드, Veo, 이미지투비디오 시 자동 활성화. |
MV Clip Factory — AI 뮤직비디오 제작 파이프라인
핵심 원칙 3가지 (왕사님 MV 시행착오에서 도출)
이 원칙을 지키면 72시간 → 12시간으로 단축, 비용 $34 → $20으로 절감 가능.
1. 음원 먼저, 씬 나중
- 음원의 에너지 프로파일(RMS, 비트)이 씬 분할의 근거
- 음원 없이 씬을 나누면 반드시 재조정이 발생 (v4→v5에서 11씬→13씬 재작업)
- Phase 1에서 음원 확보 → Phase 3에서 librosa 분석 후 씬 분할
2. 한 번에 확정, 한 번에 생성
- 스토리보드 확정 → 필요 이미지 목록 확정 → prompts.json 완성 → 한 번에 일괄 생성
- 분할 생성(57장→9장→3장)은 3일에 걸쳐 비효율 발생
--dry-run으로 목록 확인 → 한 번에 전량 생성 → --missing으로 실패분만 재생성
3. 1장 테스트, N장 실행
- 도구 선택 전 대표 이미지 1장으로 Veo/Kling/fal.ai 비교 (30분)
- Kling AI 5건 생성 후 포기 = 2시간 낭비 (왕사님 실제 사례)
- 동일 이미지 1장 → 3종 비교 → 최적 도구 결정 → 본 작업 배치 실행
전체 워크플로우
Phase 0: 프로젝트 초기화 & 허브 등록 (10분)
↓
Phase 1: 레퍼런스 수집 & ⚡음원 확보⚡ (2시간)
↓
Phase 2: 가사 작성 & 런닝타임 검증 (1시간)
↓
Phase 3: 음원 분석 → 스토리보드 설계 (2시간)
↓
Phase 3.5: ⚡1장 도구 비교 테스트⚡ (30분)
↓
Phase 4: 이미지 ⚡일괄⚡ 생성 (1시간)
↓
Phase 5: AI 영상 클립 ⚡배치⚡ 생성 (3시간)
↓
Phase 6: 나레이션/자막 (선택) (1시간)
↓
Phase 7: ffmpeg 편집 & 최종 출력 (1시간)
↓
Phase 8: 검수 & 버전 태깅 & 기록 (30분)
⚡ = 왕사님 시행착오에서 추가/변경된 단계
두 가지 시작 방법
| 방법 | 적합한 경우 | 절차 |
|---|
| 웹 위자드 | YouTube URL에서 바로 시작 | http://localhost:8787/new/ → 5단계 자동 |
| 수동 초기화 | 세밀한 제어가 필요할 때 | Phase 0 원커맨드 실행 → Phase 1부터 순차 |
Phase 0: 프로젝트 초기화 & 허브 등록
새 MV 제작 시 반드시 이 단계를 먼저 수행한다. 허브 서버(hub_server.py)가 자동으로 인식하는 구조로 폴더를 생성한다.
0-A: 프로젝트 폴더 생성
허브 서버의 루트 디렉토리(video_creator/) 아래에 프로젝트 폴더를 만든다.
PROJECT_ROOT="/path/to/your/video_creator"
PROJECT_NAME="my-new-mv"
mkdir -p "${PROJECT_ROOT}/${PROJECT_NAME}"/{images,clips,downloads,storyboard,output}
0-B: project.json 생성 (허브 등록 필수 파일)
이 파일이 있어야 허브 서버가 프로젝트를 자동 인식한다.
{
"name": "프로젝트 표시 이름",
"slug": "my-new-mv",
"subtitle": "프로젝트 한줄 설명 — MV",
"description": "프로젝트 상세 설명 (허브 카드에 표시)",
"color": "#D4A853",
"image_dir": "images",
"clip_dir": "clips",
"prompts_file": "prompts.json"
}
필드 설명:
| 필드 | 필수 | 설명 | 예시 |
|---|
name | O | 허브에 표시되는 프로젝트명 | "Journey to the Cross" |
slug | O | URL 경로 (영문, 하이픈 가능) | "journey" → localhost:8787/journey/ |
subtitle | O | 카드 부제목 | "Pixar Style MV" |
description | O | 카드 설명 텍스트 | "픽사 3D 스타일 워십 MV" |
color | O | 테마 색상 (hex) | "#D4A853" (골드), "#4A90D9" (블루) |
image_dir | O | 이미지 폴더 경로 (상대) | "images" |
clip_dir | O | 클립 저장 폴더 경로 (상대) | "clips" |
prompts_file | O | 영상 생성 프롬프트 JSON 경로 | "prompts.json" |
0-C: prompts.json 생성 (빈 파일로 시작)
이미지별 영상 생성 프롬프트를 담는 파일. 초기에는 빈 객체로 생성하고, Phase 4~5에서 채운다.
{}
나중에 이미지가 추가되면 다음 형식으로 채운다:
{
"01_scene_name.jpg": {
"en": "Animate this illustration. [영문 프롬프트]. 5 seconds.",
"ko": "일러스트를 애니메이트. [한글 프롬프트]. 5초."
}
}
0-D: 최종 폴더 구조 확인
video_creator/
├── hub_server.py ← 허브 서버
├── my-new-mv/ ← 새 프로젝트 (자동 인식됨)
│ ├── project.json ← 허브 등록 (필수)
│ ├── prompts.json ← 영상 프롬프트 (필수)
│ ├── images/ ← 웹툰/픽사 이미지
│ ├── clips/ ← AI 영상 클립 (Veo 생성물)
│ ├── downloads/ ← 레퍼런스 영상
│ ├── storyboard/ ← 스토리보드
│ └── output/ ← 최종 MV
├── 0320_왕사님/ ← 기존 프로젝트
├── 0321_신이랑법률사무소/ ← 기존 프로젝트
└── journey-to-cross/ ← 기존 프로젝트
0-E: 허브 서버 반영
프로젝트 폴더 생성 후 허브 서버를 재시작하면 자동 인식된다.
lsof -i :8787 -t | xargs kill; sleep 1
cd ${PROJECT_ROOT} && python3 hub_server.py &
확인: http://localhost:8787/ 에서 새 프로젝트 카드가 보이면 성공.
0-F: 초기화 스크립트 (권장)
스킬의 resources/init_project.sh를 허브 루트에 복사 후 실행한다.
cd /path/to/your/video_creator
bash init_project.sh my-new-mv
스크립트가 자동 생성하는 파일:
project.json — 허브 서버 자동 등록prompts.json — 이미지→영상 프롬프트 DB (빈 상태)constitution.md — 스타일/예산 불변 규칙 (직접 편집)progress.md — Phase 진행 추적output/build_mv.sh — ffmpeg 최종 편집 스크립트
0-G: 수동 초기화 (원커맨드)
SLUG="my-new-mv"
NAME="나의 새 MV"
SUBTITLE="프로젝트 부제 — MV"
DESC="프로젝트 설명"
COLOR="#D4A853"
ROOT="/path/to/your/video_creator"
mkdir -p "${ROOT}/${SLUG}"/{images,clips,downloads,storyboard,output}
cat > "${ROOT}/${SLUG}/project.json" << EOF
{
"name": "${NAME}",
"slug": "${SLUG}",
"subtitle": "${SUBTITLE}",
"description": "${DESC}",
"color": "${COLOR}",
"image_dir": "images",
"clip_dir": "clips",
"prompts_file": "prompts.json"
}
EOF
echo '{}' > "${ROOT}/${SLUG}/prompts.json"
echo "✓ 프로젝트 생성 완료: ${ROOT}/${SLUG}"
echo " 허브 서버 재시작 후 http://localhost:8787/${SLUG}/ 에서 확인"
Phase 1: 레퍼런스 수집 & ⚡음원 확보⚡
원칙 #1 적용: 음원이 확보되어야 Phase 3(씬 분할)을 정확히 할 수 있다.
음원 없이 씬을 나누면 반드시 재조정 필요. (왕사님: 11씬→13씬 재작업)
1-A: 레퍼런스 영상 다운로드
python3 ~/.claude/skills/youtube-downloader/scripts/download_video.py "{URL}" -q best -o "{프로젝트}/downloads"
1-B: 씬 프레임 자동 추출
ffmpeg scene detection으로 주요 장면 전환 프레임을 추출한다.
mkdir -p {프로젝트}/{VIDEO_ID}_extract/frames
ffmpeg -i "{영상파일}" \
-vf "select=gt(scene\,0.3),showinfo" \
-fps_mode vfr -q:v 2 \
"frames/scene_%04d.jpg" \
2>ffmpeg_scene.log
주의: zsh에서 2> 리다이렉트가 ffmpeg 출력으로 해석될 수 있음. /bin/bash -c '...'로 감싸서 실행할 것.
1-C: 타임스탬프 인덱스 생성
grep "pts_time" ffmpeg_scene.log | \
sed -n 's/.*n: *\([0-9]*\) .*pts_time:\([0-9.]*\).*/\1,\2/p' \
> scene_index.csv
1-D: 콘택트 시트 생성
from PIL import Image, ImageDraw, ImageFont
import os, math
frames_dir = "frames"
files = sorted([f for f in os.listdir(frames_dir) if f.endswith(".jpg")])
cols = 5
rows = math.ceil(len(files) / cols)
thumb_w, thumb_h = 256, 144
label_h = 22
sheet = Image.new("RGB", (cols*(thumb_w+3)+3, rows*(thumb_h+label_h+3)+3), (0,0,0))
draw = ImageDraw.Draw(sheet)
font = ImageFont.truetype("/System/Library/Fonts/AppleSDGothicNeo.ttc", 11)
for i, fname in enumerate(files):
col, row = i % cols, i // cols
x = 3 + col * (thumb_w + 3)
y = 3 + row * (thumb_h + label_h + 3)
img = Image.open(os.path.join(frames_dir, fname)).resize((thumb_w, thumb_h), Image.LANCZOS)
sheet.paste(img, (x, y))
draw.text((x+2, y+thumb_h+3), fname.replace(".jpg",""), fill=(180,180,180), font=font)
sheet.save("contact_sheet.jpg", quality=90)
1-E: 댓글/반응 분석 (선택)
YouTube 영상 댓글을 수집하여 관객 감정 패턴, 명장면, 명대사를 추출한다.
분석 프레임워크:
- 핵심 감정 키워드 빈도
- 명장면/명대사 언급 순위
- 재관람 의향 표현
- 관객 연령대/성별 추정
1-F: ⚡레퍼런스 과잉 추출 방지 (중요)
교훈: 왕사님에서 500+장 추출 → 실사용 30장 (6% 활용률)
- 콘택트 시트를 먼저 생성하여 전체 조감
- 씬당 3~5장만 타겟팅 → 나머지는 추출하지 않음
Last_selected_img/ 같은 큐레이션 폴더로 선별 관리
1-G: ⚡음원 생성 & 확보 (Phase 1에서 완료 필수)
음원이 있어야 에너지 분석 → 씬 분할이 정확해진다. Phase 3 전에 반드시 확보.
산출물: output/music/{곡명}.mp3 — 이후 모든 타이밍의 기준
Phase 2: 가사 작성 & 런닝타임 검증
2-A: 서사 구조 → 가사 변환
원작의 서사 아크를 음악 구조로 매핑한다.
서사 아크 → 음악 구조
───────────────────────────────────────
설정/발단 (Setup) → Intro + Verse 1
갈등/전개 (Rising Action) → Pre-Chorus + Chorus 1
심화/전개 (Development) → Verse 2
위기/절정 (Climax) → Pre-Chorus 2 + Chorus 2
결말/해소 (Resolution) → Bridge + Final Chorus
여운 (Denouement) → Outro
2-B: 가사 작성 원칙
- 핵심 모티프 3~4개 설정 — 가사 전체를 관통하는 상징 (예: 강, 줄, 밥상, 이름)
- 모티프 의미 전환 — 시작과 끝에서 같은 단어가 다른 의미를 가짐
- Spoken Word 삽입 — 클라이맥스 직전에 대사 형태의 가사로 감정 폭발
- Outro는 역설 — 가장 비극적인 순간에 가장 따뜻한 말로 마무리
2-B2: 런닝타임 기반 가사 분량 검증 (필수)
가사 작성 후 반드시 목표 런닝타임에 맞는지 검증한다. 템포에 따른 행당 소요 시간이 크게 다르므로, 감으로 작성하면 30~60% 초과하는 경우가 흔하다.
행당 소요 시간 기준표:
| BPM 범위 | 장르 특성 | 행당 소요 시간 | 비고 |
|---|
| 60~70 | 느린 발라드, 워십 | 5~6초 | 음 끌기, 호흡 길음 |
| 70~85 | 미드 발라드, CCM | 4~5초 | 표준 |
| 85~100 | 팝 발라드, 포크 | 3~4초 | 비교적 빠른 전달 |
| 100~120 | 업템포, 댄스 팝 | 2~3초 | 빠른 가사 전달 |
검증 공식:
가용 시간 = 목표 런닝타임 - Intro(8~12초) - 간주(4~8초) - Outro 여운(10~15초)
적정 행 수 = 가용 시간 ÷ 행당 소요 시간
검증 예시 (2분 40초, 72 BPM 발라드):
가용 시간 = 160초 - 8초(인트로) - 6초(간주) - 14초(아웃트로 여운) = 132초
행당 소요 = 5초 (72 BPM 느린 발라드)
적정 행 수 = 132 ÷ 5 = 약 26행
→ 가사가 26행을 넘으면 런닝타임 초과!
섹션별 행 수 가이드 (느린 발라드 기준):
| 구간 | 권장 행 수 | 소요 시간 |
|---|
| Verse | 4행 | ~20초 |
| Pre-Chorus | 2행 | ~10초 |
| Chorus | 4행 | ~22초 |
| Bridge | 3행 | ~15초 |
| Outro (보컬) | 3~4행 | ~15초 |
흔한 실수:
- 김이나 스타일 작사 시 서사적 표현에 몰입하여 행 수가 2배로 늘어남
- Verse를 8행으로 쓰면 Verse 하나에 40초 → 2분 40초 곡에 Verse 2개도 못 넣음
- Chorus도 8행이면 Chorus 자체가 40초 → 곡의 1/4을 차지
검증 템플릿:
### 분량 검증 ({목표시간}, {BPM} BPM)
| 구간 | 행 수 | 소요 시간 | 누적 |
|------|-------|----------|------|
| Intro | — | {N}초 | 0:{NN} |
| Verse 1 | {N}행 | {N}초 | {누적} |
| Pre-Chorus | {N}행 | {N}초 | {누적} |
| Chorus | {N}행 | {N}초 | {누적} |
| (간주) | — | {N}초 | {누적} |
| Verse 2 | {N}행 | {N}초 | {누적} |
| Chorus 2 | {N}행 | {N}초 | {누적} |
| Bridge | {N}행 | {N}초 | {누적} |
| Outro | {N}행 | {N}초 | {누적} |
| 여운 | — | {N}초 | **{최종}** |
| **합계** | **{총행}행** | | **{목표}** ✓/✗ |
2-C: Suno AI 음원 생성
스타일 프롬프트 템플릿:
Style of Music: {장르}, {보컬 스타일}, {악기 구성}, {BPM}, {박자},
{키/조성}, {분위기 키워드}, {믹싱 특성}, {엔딩 스타일}
예시 (한국 사극 발라드):
Style of Music: Korean cinematic ballad, solo male vocal with emotional vibrato,
traditional Korean instruments gayageum and daegeum and haegeum,
gentle piano arpeggios, slow orchestral strings building gradually,
68 BPM, 6/8 time, dark minor key, intimate whisper-like verse,
powerful belting chorus, haegeum solo in bridge,
full orchestra and choir climax in final chorus,
film soundtrack quality, reverb-heavy atmospheric mix,
bittersweet melancholy, fadeout ending with gayageum and water ambience
가사 입력 형식:
[Intro]
가사 텍스트
[Verse 1]
가사 텍스트
[Pre-Chorus]
...
Phase 3: 음원 분석 → 스토리보드 설계
원칙 #1 적용: 음원 에너지 프로파일이 씬 분할의 근거.
이 단계에서 Phase 1-G에서 확보한 음원을 분석하여 자동으로 씬 경계를 도출한다.
3-A: 음원 에너지 프로파일 분석
실제 음원 파일을 분석하여 에너지 곡선을 도출한다.
import librosa
import numpy as np
y, sr = librosa.load("음원.mp3")
rms = librosa.feature.rms(y=y)[0]
segment_len = int(sr * 10 / 512)
energy_profile = [np.mean(rms[i:i+segment_len]) for i in range(0, len(rms), segment_len)]
3-B: 씬 분할 기준
| 기준 | 설명 |
|---|
| 가사 섹션 경계 | [Intro], [Verse], [Chorus] 등 구간 전환 |
| 에너지 변화점 | 급격한 볼륨/템포 변화 지점 |
| 서사 전환점 | 감정 아크의 전환 지점 |
| 영상 호흡 | 48초 단위 클립을 35개 묶어 1씬 |
3-C: 씬 명세서 템플릿
각 씬을 다음 형식으로 상세 기술한다.
### Scene {번호}: {제목}
| 항목 | 내용 |
|------|------|
| **구간** | {시작}~{끝} |
| **길이** | {초}초 |
| **에너지** | {1~10} |
| **가사 섹션** | {Intro/Verse/Chorus...} |
| **설정** | {장소, 시간, 날씨, 분위기} |
| **액션** | {카메라 움직임, 캐릭터 행동, 감정 비트} |
| **카메라** | {Wide/Medium/Close-up, 움직임} |
| **조명** | {광원, 비율, 색온도} |
| **컬러** | {hex 컬러 3~5개} |
| **감정** | {감정 아크 — 시작→끝} |
| **레퍼런스 이미지** | {파일명 목록} |
3-D: 컬러 팔레트 설정
MV 전체를 관통하는 5색 팔레트를 정의한다.
예시:
#1B2838 — 야반 남색 (밤, 슬픔, 왕궁의 어둠)
#8B6914 — 금박 (왕관, 촛불, 따뜻한 기억)
#C4463A — 사약 붉은색 (위기, 배신, 피)
#D4C5A9 — 창호지 미색 (일상, 평화, 밥상)
#4A6741 — 영월 산록 초록 (자연, 유배지, 희망)
Phase 3.5: ⚡1장 도구 비교 테스트 (신규)
원칙 #3 적용: 도구 선택 전 대표 이미지 1장으로 비교. Kling 5건 생성 후 포기 = 2시간 낭비 방지.
테스트 방법
- Phase 4에서 사용할 대표 이미지 1장만 Imagen 4.0으로 먼저 생성
- 같은 이미지로 영상 도구 3종 비교 (각 1클립씩):
tools = {
"veo-3.0": {"model": "veo-3.0-generate-001", "cost": "$0.50", "len": "8s"},
"veo-fast": {"model": "veo-3.0-fast-generate-001", "cost": "$0.25", "len": "8s"},
"wan-2.2": {"model": "fal-ai/wan-i2v", "cost": "$0.10", "len": "5s"},
}
image_tools = {
"imagen-4": {"model": "imagen-4.0-generate-001", "cost": "$0.04"},
"flux2-pro": {"model": "fal-ai/flux-pro/v1.1", "cost": "$0.10"},
}
- 비교 기준: 스타일 일관성, 움직임 자연스러움, 캐릭터 변형 정도
- 최적 도구 결정 → Phase 5 전체 적용
소요: 30분, 비용: ~$0.85 (3클립)
절약: 부적합한 도구로 N클립 생성 후 폐기하는 비용 방지
Phase 4: 웹툰 이미지 ⚡일괄⚡ 생성
원칙 #2 적용: prompts.json 완성 후 한 번에 전량 생성.
분할 생성(왕사님: 57→9→3장, 3일)은 비효율의 원인.
4-A: 캐릭터 디자인 잠금
모든 이미지 생성 시 캐릭터 외형을 일관되게 유지한다.
기본형 (단일 타임라인):
CHARACTER_LOCK = {
"주인공": "17-year-old Korean boy, black silk headband (manggeon), "
"white dopo robe, melancholic dark eyes, slim build, pale skin",
"조연": "40s Korean man, broad shoulders, short dark beard, "
"brown rough peasant clothes, weathered warm face, strong hands",
}
타임라인별 정의 (파리대사관 실전 패턴, 권장):
캐릭터가 시간대/상황별로 다른 모습을 보이는 경우, 타임라인별로 분리 정의한다.
이 패턴은 파리대사관 프로젝트에서 검증되었으며, 캐릭터 일관성 보정률을 50% → 0%로 줄였다.
CHARACTER_LOCK = {
"서연": {
"present": "Late 50s Korean woman, short salt-and-pepper bob, "
"oval face, quiet inner strength, dark navy work vest, "
"grey long-sleeve, company badge, no makeup",
"boardroom": "Same woman but in maroon blazer, white silk blouse, "
"pearl earrings, commanding authoritative posture",
"flashback": "Same woman at age 45, smoother skin, black bob with "
"silver only at temples, navy diplomat suit, "
"noble posture, warm gold lighting",
"ending": "Same 50s woman but with victorious smile, cream suit, "
"confident stride, warm golden lighting",
}
}
앵커 이미지 선정 (중요):
- 각 타임라인에서 가장 잘 나온 이미지 1장을 앵커로 선정
- 나머지 이미지는 앵커와 비교하여 일관성 검증
- 불일치 시 해당 이미지만 재생성 (전체 재생성 금지)
4-A2: 이미지 재생성 시 v1 백업 (파리대사관 교훈)
캐릭터 불일치로 이미지를 재생성할 때, 원본을 반드시 백업한다.
mkdir -p images_v1_backup
cp images/02_*.jpg images/03_*.jpg images_v1_backup/
python3 scripts/generate_images.py --only 02,03,04,05,07,09,12,16,18
검증 기준 (3가지):
- 머리 스타일/색상 일치
- 얼굴형/연령대 일치
- 의상/액세서리 일치
파리대사관 실적: v1 18장 → 9장 유지 + 9장 재생성 = 총 $1.28 (최적화 $0.76)
4-B: 스타일 프리픽스 (모든 프롬프트에 공통 적용)
STYLE_PREFIX = (
"Korean historical sageuk webtoon/manhwa illustration style, "
"detailed ink linework with digital coloring, warm earth tones, "
"muted color palette, cinematic 16:9 widescreen composition, "
"dramatic lighting, film-quality atmosphere. "
)
4-C: 이미지 생성 API (Google Imagen 4.0)
from google import genai
from google.genai import types
client = genai.Client(api_key=API_KEY)
result = client.models.generate_images(
model='imagen-4.0-generate-001',
prompt=STYLE_PREFIX + CHARACTER_LOCK["주인공"] + scene_prompt,
config=types.GenerateImagesConfig(
number_of_images=1,
)
)
img_data = result.generated_images[0].image.image_bytes
with open(f"{output_dir}/{filename}.jpg", "wb") as f:
f.write(img_data)
4-D: 중복 제거
대량 생성 후 MD5 해시 기반으로 동일 이미지를 탐지하여 제거한다.
import hashlib, os
hashes = {}
for f in sorted(os.listdir(img_dir)):
with open(os.path.join(img_dir, f), "rb") as fp:
h = hashlib.md5(fp.read()).hexdigest()
if h in hashes:
os.rename(os.path.join(img_dir, f), os.path.join("_duplicates", f))
else:
hashes[h] = f
4-E: 내용 기반 파일명 리네이밍
이미지 내용을 분석하여 다음 형식으로 파일명을 변경한다.
{번호}_{장소}_{캐릭터}_{액션}_{감정}.jpg
예시:
01_palace_throne_young_king_audience.jpg
24_tiger_eom_encounter_misty_forest.jpg
44_farewell_eom_crying_holding_hands.jpg
66_silhouette_carrying_body_sunrise_river.jpg
4-F: 13씬 폴더 분류
생성된 이미지를 스토리보드 씬별 폴더로 분류한다.
Last_selected_img/
├── 01_전주_어둠속대금소리/
├── 02_인트로_나는이제어디로갑니까/
├── 03_1절전반_이산골에왕은없다/
│ ├── 09_arrival_overlooking_riverside_village.jpg
│ ├── 11_village_people_group_mountain_path.jpg
│ └── ...
├── ...
└── 13_아웃트로_따뜻한데로/
Phase 5: AI 영상 클립 생성
5-A: 프롬프트 설계 원칙
각 이미지별 영상 프롬프트를 영문 + 한글 이중으로 작성한다.
프롬프트 구조:
[스타일 지시] + [원본 이미지 참조] + [구체적 움직임] + [카메라 워크] + [감정/분위기] + [시간]
예시:
"Animate this Korean historical webtoon illustration.
The young king in white robe sits motionless on the throne,
then slowly stands up. His robe flows as he turns his back to camera.
Candlelight flickers. Melancholic dreamlike movement. 5 seconds."
핵심 지침:
- 반드시
"Animate this Korean historical webtoon illustration." 으로 시작
- 원본 이미지의 구도와 캐릭터를 유지하도록 명시
- 움직임은 3~5개 구체적 동작으로 기술
- 카메라 움직임 명시 (pan, zoom, orbit, static)
- 감정 키워드 포함
- 초 단위 길이 명시
5-B: Google Veo 3.0 API 영상 생성
from google import genai
from google.genai import types
import time
client = genai.Client(api_key=API_KEY)
with open(image_path, 'rb') as f:
img_data = f.read()
op = client.models.generate_videos(
model='veo-3.0-generate-001',
prompt=prompt_text,
image=types.Image(image_bytes=img_data, mime_type='image/jpeg'),
config=types.GenerateVideosConfig(
aspect_ratio='16:9',
number_of_videos=1,
)
)
while not op.done:
time.sleep(10)
op = client.operations.get(op)
if op.result and op.result.generated_videos:
vid = op.result.generated_videos[0]
video_bytes = client.files.download(file=vid.video)
with open(output_path, 'wb') as f:
f.write(video_bytes)
5-C: 모델 폴백 전략
Rate limit 발생 시 자동으로 대체 모델로 전환한다.
MODELS = [
"veo-3.1-generate-preview",
"veo-3.0-generate-001",
"veo-3.0-fast-generate-001",
"veo-2.0-generate-001",
]
MAX_RETRIES = 3
RETRY_DELAYS = [60, 90, 120]
폴백 로직 (실전 검증 2026-03-29):
veo-3.0 시도 → 429 에러 → 90초 대기 → 재시도
→ 다시 429 → 90초 대기 → 재시도
→ 다시 429 → veo-3.0-fast로 전환
→ 성공 시 완료 / 실패 시 fal.ai Wan2.2로 전환
fal.ai 폴백 (Veo 3회 이상 실패 시):
import fal_client, base64
with open(img_path, "rb") as f:
data_url = f"data:image/png;base64,{base64.b64encode(f.read()).decode()}"
result = fal_client.subscribe("fal-ai/wan-i2v", arguments={
"prompt": prompt_text,
"image_url": data_url,
"num_frames": 81,
"resolution": "480p",
})
fal.ai 주의사항:
- 해상도가 Veo(720x1280)와 다름 (480x832) → ffmpeg
pad 필터로 통일 필수
- SSL 인증서 오류 시
curl -sL 또는 subprocess 사용
.env의 FAL_KEY 환경변수 필요
5-D: 비용 추적
VEO3_COST_PER_CLIP = 0.50
gen_cost = {
"clips_generated": 0,
"session_clips": 0,
"session_cost_usd": 0.0,
"total_estimated_usd": 0.0,
"remaining_clips": 66,
"remaining_cost_usd": 33.0,
"per_clip_usd": 0.50,
}
5-E: 배치 생성 전략 (Rate Limit 대응)
실전 검증 결과 (2026-03-29): Veo 3.0은 동시 3~4개 작업까지 허용. 순차 1개씩은 비효율적.
권장 배치 전략:
def generate_videos_batch(filenames, batch_size=3, wait_between=90):
"""배치 제출 → 완료 대기 → 다음 배치"""
pending = [f for f in filenames if not os.path.exists(clip_path(f))]
for i in range(0, len(pending), batch_size):
batch = pending[i:i+batch_size]
operations = []
for fname in batch:
try:
op = submit_veo_job(fname)
operations.append((fname, op))
time.sleep(3)
except Exception as e:
if "429" in str(e):
break
for fname, op in operations:
wait_and_download(op, clip_path(fname))
if i + batch_size < len(pending):
time.sleep(wait_between)
스크립트 재실행 패턴:
- 기존 파일 자동 SKIP → 실패분만 재시도
- 90초 대기 후 재실행 → 점진적 완성
Phase 6: 대시보드 & 관리 웹앱
6-A: 서버 아키텍처
from http.server import HTTPServer, SimpleHTTPRequestHandler
class MVHandler(SimpleHTTPRequestHandler):
def do_GET(self):
if self.path == '/api/images':
elif self.path == '/api/status':
elif self.path.startswith('/img/'):
elif self.path.startswith('/clip/'):
def do_POST(self):
if self.path == '/api/generate':
HTTPServer(("", 8787), MVHandler).serve_forever()
6-B: API 엔드포인트
| 엔드포인트 | 메서드 | 응답 |
|---|
/api/images | GET | [{filename, prompt_en, prompt_ko, has_clip, status}] |
/api/status | GET | {status: {파일별상태}, cost: {비용정보}} |
/api/generate | POST | {status: "started", count: N} |
/img/{name} | GET | 원본 이미지 파일 |
/clip/{name} | GET | 생성된 영상 클립 |
6-C: 프론트엔드 UI 요구사항
- 10개씩 페이지네이션
- 이미지 + 영/한 프롬프트 표시
- 체크박스 선택 → "영상 생성" 버튼
- 실시간 상태 뱃지 (idle / generating / done / error)
- 비용 대시보드 (생성완료 / 누적비용 / 잔여예상 / 클립단가)
- 완료된 클립 미리보기 (인라인 비디오 플레이어)
Phase 7: 최종 MV 편집
7-A: 클립 시퀀싱
스토리보드 타임코드에 맞춰 클립을 배치한다.
ffmpeg -f concat -safe 0 -i filelist.txt \
-c copy mv_visual_only.mp4
7-B: 음원 합성
경고: -shortest 함정 (왕사님 실전 교훈)
클립 합계 > 음원 길이 시 뒤쪽 클립이 잘림.
블랙 프레임 삽입 시 전체 길이 증가 → 엔딩 클립이 잘릴 수 있음.
반드시 합성 전에 누적 타임라인을 계산하고 핵심 클립 위치를 확인할 것.
VIDEO_DUR=$(ffprobe -v error -show_entries format=duration -of csv=p=0 mv_visual_only.mp4)
MUSIC_DUR=$(ffprobe -v error -show_entries format=duration -of csv=p=0 music.mp3)
echo "영상: ${VIDEO_DUR}s / 음원: ${MUSIC_DUR}s"
ffmpeg -i mv_visual_only.mp4 -i music.mp3 \
-c:v copy -c:a aac -shortest \
mv_final.mp4
7-C: TTS 나레이션 (선택)
컴필레이션/코미디 포맷에서 검증된 나레이션 파이프라인 (funny_cats 실전 사례):
import edge_tts, asyncio
async def generate_tts(text, output_path, voice="ko-KR-HyunsuNeural"):
"""남성: ko-KR-HyunsuNeural / 여성: ko-KR-SunHiNeural"""
communicate = edge_tts.Communicate(text, voice)
await communicate.save(output_path)
ffmpeg -i clip.mp4 -i narration.wav \
-c:v copy -c:a aac -b:a 192k \
-filter_complex "[1:a]adelay=500|500[a1];[0:a][a1]amix=inputs=2" \
clip_with_narration.mp4
7-D: 가사 자막 (ASS 형식)
[Script Info]
Title: 강을 건너다
ScriptType: v4.00+
[V4+ Styles]
Style: Lyrics,Pretendard,28,&H00FFFFFF,&H000000FF,0,0,0,0,100,100,0,0,1,2,0,2,30,30,40,1
[Events]
Dialogue: 0,0:00:10.00,0:00:15.00,Lyrics,,0,0,0,,나는 이제 어디로 갑니까
ffmpeg -i mv_final.mp4 -vf "ass=subtitles.ass" mv_with_subs.mp4
Phase 8: ⚡검수 & 버전 태깅 & 기록 (신규)
교훈: 왕사님에서 306MB와 97MB 두 파일이 공존, 어느 것이 최종인지 불명확.
8-A: 최종 파일 명명 규칙
output/FINAL_{프로젝트명}_v{N}.mp4
예: output/FINAL_강을건너다_v1.mp4
- 수정할 때마다 v{N+1}로 새 파일 생성 (덮어쓰기 금지)
- 중간 산출물(merged, concat)은
output/_work/에 보관
8-B: 검수 체크리스트
- [ ] 영상 전체 재생 (끊김, 검은 화면 없음)
- [ ] 음원 싱크 확인 (가사와 씬 전환 일치)
- [ ] 해상도/비율 확인 (16:9 또는 9:16)
- [ ] 자막 가독성 (있는 경우)
- [ ] 최종 파일명 FINAL_v{N} 태깅
8-C: progress.md 업데이트
## 현재 상태
- Phase: 8 (완료)
- 최종 파일: output/FINAL_{프로젝트명}_v1.mp4
- 비용: ${총액}
8-D: 작업 로그 기록
work-logger 스킬 실행하여 /logs/에 기록.
빠른 실행 가이드
최소 요구사항
- Python 3.10+
- Google API Key (Imagen 4.0 + Veo 3.0 접근 권한)
- ffmpeg 설치
- Pillow (PIL) 라이브러리
- 음원 파일 (MP3)
12시간 퀵스타트 (핵심 원칙 3가지 적용)
bash scripts/init-video-project.sh MMDD_프로젝트명
yt-dlp -o "downloads/{ID}.mp4" "URL"
python3 scripts/generate_images.py {프로젝트} --dry-run
python3 scripts/generate_images.py {프로젝트}
프로젝트 파일 구조 (권장)
video_creator/ # 허브 루트
├── hub_server.py # 통합 서버 (python3 hub_server.py)
├── _wizard_temp/ # 위자드 임시 파일
│
├── {프로젝트 슬러그}/ # ← 각 MV 프로젝트
│ ├── project.json # ★ 허브 등록 (필수)
│ ├── prompts.json # ★ 영상 프롬프트 (필수)
│ ├── images/ # 웹툰/픽사 이미지 (최종)
│ │ ├── 01_scene_name.jpg
│ │ └── ...
│ ├── clips/ # AI 영상 클립 (Veo 생성물)
│ │ ├── 01_scene_name.mp4
│ │ └── ...
│ ├── downloads/ # 레퍼런스 영상
│ ├── storyboard/
│ │ └── mv_storyboard_v{N}.md
│ ├── lyrics.md # 최종 가사
│ ├── suno_package.md # Suno 입력 패키지
│ ├── music.mp3 # 음원
│ └── output/
│ └── mv_final.mp4 # 최종 결과물
│
├── 0320_왕사님/ # 프로젝트 예시 1
├── journey-to-cross/ # 프로젝트 예시 2
└── ...
허브 자동 인식 조건: 폴더 안에 project.json이 있으면 자동 등록.
웹 접근: http://localhost:8787/{slug}/ 에서 클립 생성기 UI 사용.
체크리스트
Phase 0: 프로젝트 초기화
Phase 1: 레퍼런스
Phase 2: 가사 & 음원
Phase 3: 스토리보드
Phase 4: 이미지
Phase 5: 영상 생성
Phase 6: 최종 편집
사용 가능한 모델 & 비용 (2026-04 기준)
이미지 생성
| 모델 | 단가 | 특성 | 검증 상태 |
|---|
| Google Imagen 4.0 | ~$0.04/장 | 안정적, 고품질, 캐릭터 일관성 우수 | 실전 검증 (왕사님, 파리대사관, demo) |
| Google Imagen 4.0 Ultra | ~$0.08/장 | 최고 품질, 복잡한 장면에 적합 | 부분 검증 |
| FLUX.2 Pro (fal.ai) | ~$0.10/장 | 고성능, 다양한 스타일, 정책 유연 | 실전 검증 (Ragnarok2) |
영상 생성
| 모델 | 단가 | 클립 길이 | 특성 | 검증 상태 |
|---|
| Google Veo 3.0 | ~$0.50/클립 | ~8초 | 시네마틱, 고품질, Rate Limit 주의 | 실전 검증 |
| Google Veo 3.0 Fast | ~$0.25/클립 | ~8초 | 빠른 생성, 약간 낮은 품질 | 실전 검증 |
| Google Veo 2.0 | ~$0.25/클립 | ~8초 | 폴백용, 안정적 | 검증됨 |
| fal.ai Wan 2.2 Turbo | ~$0.10/클립 | ~5초 | 저비용, 이미지→영상 전문, 480~720p | 실전 검증 (Ragnarok2) |
음원/음성
| 도구 | 비용 | 용도 |
|---|
| Suno AI | 무료~$10/곡 | AI 음악 생성 |
| Edge TTS | 무료 | 한국어 나레이션 (ko-KR-HyunsuNeural, ko-KR-SunHiNeural) |
비용 예측 (66클립 MV 기준)
| 항목 | 단가 | 수량 | 합계 |
|---|
| Suno AI 음원 | 무료~$10 | 1곡 | ~$10 |
| Imagen 4.0 이미지 | ~$0.04 | 80장 | ~$3 |
| Veo 3.0 영상 클립 | ~$0.50 | 66개 | ~$33 |
| 총 예상 비용 (Veo) | | | ~$46 |
| Wan 2.2 대안 | ~$0.10 | 66개 | ~$20 |
트러블슈팅
Veo 3.0 Rate Limit (429 에러)
- 원인: 일일/분당 API 할당량 초과
- 해결: 자동 폴백 로직 (v3.0 → v3.0-fast → v2.0)
- 대기: 30초 → 60초 → 120초 지수 백오프
ffmpeg scene detection 에러
- zsh에서
2> 리다이렉트 충돌 → /bin/bash -c '...'로 감쌈
- 콤마 이스케이프:
select=gt(scene\,0.3) (백슬래시 필수)
이미지 중복 생성
- Claude 대화형 생성 시 같은 이미지가 여러 번 다운로드됨
- MD5 해시 기반 중복 탐지 →
_duplicates/ 폴더로 분리
캐릭터 일관성 깨짐
- 모든 프롬프트에 CHARACTER_LOCK 프리픽스 강제 적용
- 타임라인별 character_lock 정의 사용 (Phase 4-A 참조)
- 앵커 이미지 선정 → 나머지와 비교 → 불일치분만 재생성
- 재생성 시 반드시
images_v1_backup/ 백업 (Phase 4-A2 참조)
- 레퍼런스 이미지를 함께 입력 (image-to-image 모드)
가사 분량이 런닝타임 초과
- 원인: 72 BPM 발라드에서 한 줄에 5초 소요되는데, 감으로 쓰면 44행까지 늘어남
- 해결: 작성 후 반드시 2-B2 검증 공식 적용. 행 수 × 행당 시간 + 인트로/간주/여운 = 목표 시간
- 팁: 서사적 가사(김이나 스타일)는 절제가 핵심. Verse 4행, Chorus 4행이 적정. 8행은 무조건 초과
영상 품질 불일치
- 프롬프트에
"preserving the exact composition and art style" 추가
- 움직임 최소화:
"very slow, subtle movement" 지시
- 리테이크 시 다른 모델(Kling, Grok 등) 병행 테스트
실전 비용 실적 (프로젝트별)
실제 제작에서 발생한 비용 데이터. 예산 계획 시 참고.
왕사님 MV (13씬, 41클립, 5분 9초)
| 항목 | 수량 | 비용 | 비고 |
|---|
| Imagen 4.0 이미지 | 69장 | $2.76 | 3회 분할 (57+9+3) |
| 테스트 이미지 | ~15장 | $0.60 | 스타일 탐색 |
| Kling AI 영상 (폐기) | 5클립 | $2.50 | 도구 비교 실패 → 폐기 |
| Veo 3.0 영상 | 42클립 | $21.00 | 메인 생성 |
| 실제 합계 | | ~$34 | 중복/테스트 포함 |
| 최적화 예상 | | ~$20 | 원칙 3가지 적용 시 |
교훈: Kling 2시간 낭비($2.50) + 이미지 3회 분할 → 원칙 적용 시 40% 절감
파리대사관 서연 (10씬, 18클립, 진행 중)
| 항목 | 수량 | 비용 | 비고 |
|---|
| Imagen 4.0 v1 | 18장 | $0.76 | 초기 생성 |
| Imagen 4.0 v2 | 9장 | $0.36 | 캐릭터 보정 재생성 |
| 테스트 | 4장 | $0.16 | character_lock 검증 |
| 이미지 합계 | | $1.28 | |
| Veo 3.0 (예정) | 18클립 | $9.00 | 0.50/클립 |
| 총 예상 | | ~$10 | |
교훈: character_lock 타임라인 정의로 재생성 9장만 (50%) → 사전 정의 시 0%
허브 서버 — 멀티 프로젝트 관리
개요
hub_server_template.py는 여러 MV 프로젝트를 하나의 웹 대시보드로 통합 관리하는 서버다.
하위 폴더의 project.json을 자동 탐색하여 프로젝트를 등록한다.
설치 & 실행
cp resources/hub_server_template.py /path/to/your/video_creator/hub_server.py
cp resources/init_project.sh /path/to/your/video_creator/
export GOOGLE_API_KEY='your-google-api-key'
cd /path/to/your/video_creator
python3 hub_server.py
허브 페이지 구조
| 페이지 | URL | 기능 |
|---|
| 허브 홈 | / | 전체 프로젝트 카드 + 통계 (이미지 수, 클립 수, 비용) |
| 프로젝트 상세 | /{slug}/ | 이미지 그리드 + 클립 생성 + 실시간 상태 모니터링 |
| 새 MV 위자드 | /new | YouTube URL → 프레임 추출 → 웹툰 변환 → 프로젝트 생성 |
프로젝트 상세 페이지 (스토리보드 뷰)
각 프로젝트 페이지에서 할 수 있는 것:
- 이미지 카드 그리드: 프롬프트와 함께 이미지 미리보기 (10개/페이지)
- 실시간 상태 뱃지: idle → queued → generating → done / error
- 선택 생성: 원하는 이미지만 선택 → "생성 시작" → Veo API 호출
- 미완성 전체생성: 클립이 없는 이미지 모두 한번에 생성
- 비용 대시보드: 완성 수, 전체 수, 누적 비용, 잔여 클립
- 폴링: 생성 중 3초 간격, 대기 시 15초 간격 자동 업데이트
API 엔드포인트
| Method | Path | 설명 |
|---|
| GET | / | 허브 홈 HTML |
| GET | /api/projects | 전체 프로젝트 JSON |
| GET | /{slug}/ | 프로젝트 상세 HTML |
| GET | /{slug}/api/images | 이미지 메타데이터 JSON |
| GET | /{slug}/api/status | 생성 상태 + 비용 JSON |
| POST | /{slug}/api/generate | 선택 이미지로 클립 생성 시작 |
| GET | /{slug}/img/{name} | 원본 이미지 서빙 |
| GET | /{slug}/clip/{name} | 생성된 클립 서빙 |
위자드 API (새 MV 만들기)
| Method | Path | 설명 |
|---|
| POST | /wizard/api/download | YouTube 영상 다운로드 |
| POST | /wizard/api/extract | 프레임 추출 (씬 감지 / 일정 간격) |
| POST | /wizard/api/convert | Imagen 4.0으로 웹툰 스타일 변환 |
| POST | /wizard/api/convert-status | 변환 진행 상태 |
| POST | /wizard/api/create-project | 프로젝트 폴더 생성 + 허브 등록 |
환경 변수
| 변수 | 기본값 | 설명 |
|---|
GOOGLE_API_KEY | (없음) | Google AI API 키 (Veo, Imagen) |
MV_PORT | 8787 | 서버 포트 |
의존성
pip install google-genai Pillow
brew install ffmpeg yt-dlp
주의사항
- 반드시 hub_server.py만 실행 — 개별 프로젝트의 server.py 실행 금지 (포트 충돌)
- 서버 재시작 시 프로젝트 자동 재탐색
_wizard_temp/ 폴더는 위자드 임시 파일 — 정리 가능
리소스 파일 목록
| 파일 | 용도 |
|---|
resources/hub_server_template.py | 멀티 프로젝트 허브 서버 (위자드 포함) |
resources/server_template.py | 단일 프로젝트 서버 (레거시, 허브 사용 권장) |
resources/init_project.sh | 프로젝트 초기화 스크립트 |
resources/project_template.json | project.json 템플릿 |
resources/prompts_template.json | prompts.json 템플릿 |
