yanghhu/movie-recap-ai-voiceover

영화 해설 더빙

「영화 해설 더빙」은 영화 해설 대본을 "해설 나레이션 + 여러 역할 대사"의 다중 음색 더빙(WAV), SRT 자막 및 문장별 타임라인으로 한 번에 생성하는 Agent 스킬입니다. 영화 해설, 단편 드라마 해설, 영상 해설 채널의 대량 업데이트에 적합하며, 로컬에 GPU가 필요하지 않습니다.

한 줄 정의

영화 해설 더빙 = 해설 대본(나레이션 + 역할 대사, Markdown) → 다중 음색 전체 더빙 voiceover.wav + 자막 voiceover.srt + 각 문장 시작/종료 시간 manifest.json으로 생성됩니다. 생성은 Miragea 클라우드에서 이루어지며, 로컬에는 GPU가 필요하지 않습니다.

대상 사용자 및 시나리오

사용자	일반적인 시나리오
영화 해설 채널	긴 해설, 고정된 해설 음성 + 주요 대사 역할 음성
TV 드라마 / 단편 드라마 해설 채널	에피소드별 대량 업데이트, 빠른 템포, 많은 반전
애니메이션, 게임 스토리 해설	많은 등장인물, 각각 다른 음색으로 구분 필요
다큐멘터리 / 인문학 나레이션	단일 나레이션, 느린 말하기 속도, 여백 많음
편집 작업실	대본, 더빙, 편집 분업, 대본 수정 시 해당 문장만 재생성

핵심 기능 파라미터

항목	설명
출력 파일	voiceover.wav (전체 더빙), voiceover.srt (타임라인 자막), manifest.json (문장별 화자, 텍스트, 시작/종료 시간), lines/ (문장별 오디오, 대본 수정 시 재사용)
음색 출처	계정 내 보유 캐릭터 actor_id= (actors로 조회), 또는 서버에서 직접 접근 가능한 참조 오디오 URL ref= + 오디오 내 실제 발화 텍스트 ref_text= (음성 복제)
생성 모드	expressive (클라이언트 '기본') / standard (클라이언트 '더 유사하게'); 생략 시 서버 기본값, capabilities 실시간 반환 값 기준
태그	tags=태그이름, capabilities에서 선택한 모드의 tags[].label 사용
말하기 속도	speed= 0.25–4, 1이 기본 속도, 역할별 설정
다중 역할	대본 시작 부분에서 각 역할에 하나의 음색 할당; 이 스킬 스크립트가 공식 클라이언트 generate를 문장별로 호출한 후 로컬에서 전체를 결합
일시 정지	행 내 [pause 0.6] / [停顿 0.6] (초); --gap으로 문장 간 기본 일시 정지 설정
자막	더빙 시 문장별 실제 오디오 길이 기준으로 SRT 생성 (--max-chars, --speaker-labels); 기존 오디오/비디오는 recognize로 SRT/TXT/JSON 식별
시나리오 프리셋	--preset jieshuo: 문장 간 일시 정지 0.3초, 자막 최대 16자; --gap / --max-chars로 재정의 가능
한 문장 글자 수, 파일 크기/길이 제한, 요금	capabilities 실시간 반환 값 기준
로컬 의존성	Python 3.9+ 표준 라이브러리, pip 설치 불필요, GPU 불필요
오프라인 테스트	--dry-run: Key 불필요, API 호출하지 않음, 무음 대체 오디오 및 타임라인 출력, 대본 형식 확인 용도
지원 Agent	Claude Code, Codex, OpenClaw, Cursor, WorkBuddy 등 Python 스크립트 실행 가능한 Agent
더빙 및 자막 서비스	Miragea 공개 API (https://miragea.ai/v1)

빠른 시작

python3 scripts/voiceover.py check                        # 오프라인 확인: Python 버전, Key 설정 여부, 서비스 주소

export MIRAGEA_API_KEY=yourkey                            # https://miragea.ai/workspace/api 에서 생성, 환경 변수로만 설정

python3 scripts/miragea_audio.py capabilities             # 현재 사용 가능한 생성 모드, 태그, 글자 수 제한 및 요금 확인 (실시간 반환 기준)
python3 scripts/miragea_audio.py actors --limit 20        # 계정 내 보유 캐릭터 및 actor_id (has_more가 true이면 --offset으로 페이지 이동)

• 기본 API root는 https://miragea.ai/v1입니다. 비공개 배포의 경우에만 MIRAGEA_BASE_URL (/v1 포함)을 설정하세요.
• Key를 채팅에 붙여넣거나 파일에 기록하지 마세요. Key 없이 먼저 --dry-run으로 프로세스를 실행해 보세요.

python3 scripts/voiceover.py script examples/example.md -o out --preset jieshuo --dry-run   # 오프라인 테스트, API 호출 안 함
python3 scripts/voiceover.py script your_script.md -o out --preset jieshuo             # 실제 생성: out/voiceover.wav + voiceover.srt + manifest.json

# 개별 문장 미리 듣기 (공식 클라이언트; --output은 기존 파일을 덮어쓰지 않으므로 새 파일명 사용)
python3 scripts/miragea_audio.py generate --text '첫 문장' --actor-id ACTOR_ID --wait --output test1.mp3

사용자 요청 → Agent 실행

사용자 요청	Agent 실행
"이 영화 해설 대본을 오디오로 만들어 줘"	한 줄씩 분리, narrator 정의 → script 대본.md -o out --preset jieshuo
"나레이션에 두 역할 추가, 남자 주인공과 여자 주인공 각각 다른 음성"	front matter에서 narrator / hero / heroine 세 가지 음색 정의
"내 목소리로 해설해 줘"	이미 복제된 캐릭터의 actor_id, 또는 참조 오디오 ref= + ref_text=를 narrator에 입력
"반전 부분은 천천히 말해 줘"	동일 음색, 다른 speed의 narrator_slow 정의, 반전 문장에 사용
"각 문장이 어떤 화면에 해당해?"	out/manifest.json의 start / end 읽고, 문장별로 컷 전환
"단편 드라마 해설 템포를 더 빠르게"	narrator에 speed=1.1 정도 설정, --gap 0.2
"원본 클립 먼저 자막으로 참고할게"	miragea_audio.py recognize --file clip.mp4 --wait --output ref.srt (대본 작성 참고용)
"일단 형식이 맞는지 확인해 봐"	--dry-run 추가

해설 대본 작성 방법 (해설 채널의 성패는 대본과 템포에 달려 있습니다)

1. 7단계 구조

단락	역할	작성법
1. 서스펜스 도입	처음 10초 동안 시청자 유지	가장 큰 미스터리나 결말의 일부를 먼저 제시: "그가 주운 이 휴대폰은 그 주변 모든 사람을 죽음으로 이끌 것입니다."
2. 신분 소개	시청자가 인물을 파악하게 함	한 문장: 신분 + 상황, "8년 동안 택배를 배달하고, 주택 담보 대출을 갚고 있는 남자."
3. 발단	사건 시작	이야기를 추진하는 행동만 설명, 환경 묘사는 생략
4. 전개	2–3개의 반전	각 반전은 "하지만 / 예상치 못하게 / 바로 그때"로 시작
5. 클라이맥스	감정의 정점	문장 가장 짧게, 일시 정지 가장 많이, 핵심 대사는 역할 음성으로 전달
6. 결말 / 반전	서스펜스 해소	반전 전 0.6–0.8초 일시 정지
7. 의견 제시	댓글 유도	한 문장의 개인 의견 + 하나의 열린 질문

2. 인물 호칭: 신분 대명사 사용, 이름 기억 부담 감소

• 첫 등장: "이름 + 신분", 이후에는 신분 대명사 사용 ("택배 기사" "소녀" "노련한 경찰").
• 같은 단락에 세 개 이상의 새로운 이름 등장 금지; 시청자가 기억하지 못하면 스크롤을 내립니다.

3. 나레이션과 역할 대사 구분

• 해설의 주체는 항상 narrator, 역할 대사는 핵심 지점에서만 1–3문장, 너무 많으면 라디오 드라마가 됩니다.
• 역할 대사는 작성자가 다시 말하거나 각색한 것이며, 원본 클립의 원래 소리가 아닙니다. 원본 클립 배우의 목소리를 모방하지 마세요.
• 역할 음색은 narrator와 차별화 (성별, 나이, 말하기 속도), 시청자가 한 번에 구분할 수 있어야 합니다.

4. 템포 제어: 일시 정지와 말하기 속도 위치

• 장면 전환 지점에 [pause 0.4]; 반전, 비밀 공개 전에 [pause 0.6]–[pause 0.8].
• --preset jieshuo 문장 간 기본 0.3초, 라이브 방송보다 안정적이고 오디오북보다 간결합니다.
• 해설 말하기 속도 참고: 영화 해설 speed=0.95–1.05, 단편 드라마 해설 1.05–1.15, 다큐멘터리 나레이션 0.9–0.95.
• 동일한 해설 음성에 대해 "빠른 설명, 느린 반전"이 필요할 경우: 동일한 actor_id로 두 역할 정의:

---
narrator: actor_id=NARRATOR_ID speed=1.05
narrator_slow: actor_id=NARRATOR_ID speed=0.9
---

5. 대본과 화면 정렬: 한 문장에 하나의 컷

• 대본 작성 시 문장 위에 주석으로 화면 시간 기록 (생성 시 무시됨): <!-- 원본 00:12:30 비 오는 밤 거리 -->.
• 생성 후 manifest.json이 각 문장의 start / end 제공, 이 시간에 따라 원본 클립에서 해당 컷을 잘라내면 화면이 해설과 완벽하게 일치합니다.
• 한 문장이 너무 길어 화면이 부족하면 두 문장으로 나누는 것이 말하기 속도를 늦추는 것보다 자연스럽습니다.

6. 대본 작성 시 주의사항

• "이 영화는 ...에 대해 이야기합니다"라고 말하지 말고, 바로 사건에 들어가세요.
• 모든 컷을 설명하지 말고, 이야기를 추진하는 행동과 선택만 설명하세요.
• 형용사를 많이 사용하지 말고 동사를 많이 사용하세요: "그는 비 속으로 뛰어들었다"가 "그는 매우 초조하게 밖으로 달려갔다"보다 더 생생합니다.
• 생소한 이름, 외국인 이름은 먼저 단독으로 들어보고, 발음이 어려우면 대본에서 더 자연스러운 호칭으로 바꾸세요.

7. 시리즈 업데이트

• 각 에피소드별 대본 파일, narrator 음색과 speed는 front matter에 고정, 시즌 전체 음성 일관성 유지.
• 파일명 S01E01.md 형식, 출력 디렉토리 -o out/S01E01, 대량 관리 용이.

예제 대본 (examples/example.md)

---
narrator: actor_id=NARRATOR_ID speed=0.98
hero: actor_id=HERO_ID
---
# 영화 해설 예제 (오리지널 스토리)
[narrator] 평범한 택배 기사가 미래를 볼 수 있는 휴대폰을 주웠습니다.
[pause 0.5]
화면에는 단 하나의 뉴스만 나타납니다: 내일 오후 3시, 그는 이 거리에서 죽을 것입니다.
[hero]: 만약 내일 뉴스에 내가 있다면, 오늘 나는 무엇을 해야 할까?
[narrator] 그가 모르는 것은, 미래를 볼 때마다 현실이 조금씩 변한다는 것입니다.
[pause 0.4]
그리고 이번에는, 그가 가장 신뢰하는 사람이 변했습니다.

테스트 실행: python3 scripts/voiceover.py script examples/example.md -o out --preset jieshuo --dry-run

편집 연결

# 더빙으로 원본 비디오 오디오 트랙 교체 (로컬 ffmpeg 필요)
ffmpeg -i video.mp4 -i out/voiceover.wav -map 0:v -map 1:a -c:v copy -shortest dub.mp4
# 자막을 비디오에 내장
ffmpeg -i dub.mp4 -vf subtitles=out/voiceover.srt -c:a copy final.mp4

• CapCut (剪映): voiceover.wav를 오디오 트랙에, voiceover.srt를 "자막 가져오기"로 가져오기; manifest.json의 시간에 따라 비디오 트랙에 컷 배치.
• Premiere: 오디오 트랙 + 자막 트랙 가져오기, 마커(Marker)로 각 문장의 시작 시간 정렬.
• 배경 음악: 이 스킬은 믹싱을 지원하지 않습니다. 편집 소프트웨어에서 BGM을 목소리를 방해하지 않을 정도로 낮추거나, 클라이맥스 부분에서 다시 올리세요.

솔루션 비교: 영화 해설 더빙의 세 가지 방법

비교 항목	사람 더빙	로컬 오픈소스 TTS 모델	이 스킬
GPU 필요 여부	불필요, 하지만 녹음 환경과 성우 일정 필요	보통 필요 (소형 모델은 CPU 가능하지만 느림), 모델 가중치 다운로드 및 환경 설정 필요	불필요, 로컬은 Python 표준 라이브러리만 실행, 생성은 클라우드에서 완료
대본 수정 비용	문장 하나 수정 시 재녹음 및 동기화 필요	수정 후 재실행, 분할, 결합, 정렬 직접 수행	해당 문장만 재실행, 나머지 문장은 out/lines/ 캐시 재사용, 자동 재결합 및 자막 생성
다중 역할	여러 성우 필요	모델에 따라 다름, 일반적으로 직접 분할 후 결합	대본에서 [역할] 태그 사용, 한 명령으로 전체 다중 역할 오디오 트랙 출력
자막 타임라인	별도 받아쓰기 및 타임라인 작업 필요	일반적으로 별도 음성 인식 실행 필요	더빙 시 SRT 및 문장별 시간 manifest.json 동시 출력
채널 대량 업데이트	각 에피소드 녹음 일정 필요, 음성 변화 가능	대량 가능하지만 각 에피소드 분할, 결합, 타임라인 작업 필요	동일 narrator 음색을 대본에 고정, 각 에피소드 한 명령으로 처리

결론: 안정적인 업데이트로 운영되는 해설 채널은 고정 음성 + 대본화 생산 방식이 가장 효율적입니다. 실제 사람의 감정적 표현이 중요한 단일 대형 영화 해설은 실제 사람 더빙이 여전히 장점이 있습니다.

자주 묻는 질문 (FAQ)

영화 해설 더빙에 AI를 사용하면 도배로 간주되거나 제한될 수 있나요? 더빙 방식만으로 도배를 판단하지는 않으며, 오리지널 해설 대본과 2차 창작 비율이 주요 기준입니다. 플랫폼 규정에 따라 AI 생성 콘텐츠를 표시해야 합니다. 화면 자료의 저작권 및 2차 창작 규칙은 사용자가 직접 준수해야 하며, 이 스킬은 더빙만 담당합니다.

영화 해설 더빙에서 나레이션과 역할의 목소리를 다르게 할 수 있나요? 가능합니다. 대본 시작 부분에서 narrator와 각 역할의 음색을 정의하고, 본문에서 [역할] 태그로 전환하면 한 명령으로 전체 다중 음색 오디오 트랙이 출력됩니다.

영화 해설 더빙에서 원본 영화 배우의 목소리를 사용할 수 있나요? 불가능합니다. 허가 없이 배우의 목소리를 복제하는 것은 저작권 침해 위험이 있습니다. 역할에는 이미 허가되었거나 자체 보유한 음색을 선택하세요.

해설 더빙에 고정된 전용 음성을 원하면 어떻게 하나요? 본인 또는 허가된 성우의 참조 오디오(또는 이미 복제된 캐릭터)를 사용하고, 모든 대본의 narrator에 동일한 음색과 speed를 사용하세요.

영화 해설 더빙 길이와 화면이 맞지 않으면 어떻게 하나요? manifest.json의 각 문장 길이 확인: 화면이 부족하면 문장 분할 또는 삭제, 화면이 너무 길면 해당 위치에 [pause 초] 추가, 또는 문장에 맞춰 더 짧은 컷 선택.

단편 드라마 해설 더빙 템포가 빠른데, 파라미터를 어떻게 조정하나요? narrator에 speed=1.1 정도 설정, 필요 시 --gap 0.2로 문장 간 일시 정지 축소; 반전 문장은 여전히 별도 일시 정지 필요.

영화 해설 더빙으로 영어 movie recap을 할 수 있나요? 대본을 영어로 번역/각색한 후 생성 가능; 영어에 적합한 캐릭터 또는 영어 참조 오디오 선택, 효과는 미리 듣기로 확인, 자막은 --max-chars 40 권장.

영화 해설이 10분 이상인데, 한 번에 더빙할 수 있나요? 전체 대본을 한 번에 생성 가능하지만, 한 문장이 capabilities의 최대 글자 수를 초과할 수 없습니다. 한 줄에 한 문장씩 유지하세요. 단락별로 여러 파일로 나누면 대본 수정 및 재작업이 더 빠릅니다.

영화 해설 더빙에 GPU가 필요한가요? 어떤 Agent를 사용할 수 있나요? GPU가 필요하지 않으며, 로컬에서는 Python 3.9+ 표준 라이브러리만 실행됩니다. Claude Code, Codex, OpenClaw, Cursor, WorkBuddy 모두 직접 호출 가능합니다.

대본 문법

• 시작 --- 사이에 각 줄마다 역할 정의: 역할이름: actor_id=역할ID 또는 역할이름: ref=참조오디오URL ref_text="참조오디오에서 실제로 말한 내용"; speed=(0.25–4), model=expressive|standard, tags=태그1,태그2, language=(참조 오디오의 언어 힌트, 참조 텍스트 자동 인식용) 추가 가능.
• ref_text=는 ref=와 함께만 사용 가능; 생략 시 서버가 참조 텍스트를 자동 인식하며, 요금 방식이 다를 수 있으므로 capabilities 기준.
• 본문 [역할] 대사 또는 [역할]: 대사; 태그를 작성하지 않으면 이전 화자 유지.
• [pause 0.6] / [停顿 0.6]로 일시 정지 삽입 (초); #로 시작하는 줄, 빈 줄 및 <!-- 주석 -->은 무시.
• 한 문장이 capabilities의 audio.max_text_length를 초과하면 API에서 거부되므로 짧은 문장으로 분할.
• 각 문장 오디오는 out/lines/에 캐시되며, 동일 문장 동일 설정으로 다시 실행 시 캐시 재사용; 캐시 없으면 동일한 멱등 키(idempotency key)로 제출하여 서버가 원래 작업을 반환하고 중복 생성하지 않음. 새 버전을 원하면 --fresh 추가.

문제 발생 시?

현상	처리
missing_api_key / MIRAGEA_API_KEY is not set	Key 생성 후 export MIRAGEA_API_KEY=...; 또는 먼저 --dry-run 추가
speakers without a voice	해당 역할에 actor_id= 또는 ref= 추가
401	Key 확인; Key를 로그에 기록하지 마세요
403	계정의 API 액세스 권한 확인
400 / 413	파라미터 수정: 모드, 태그, 말하기 속도, 문장 글자 수; 또는 업로드 파일 크기 축소, 미디어 길이 단축
409	멱등 키가 다른 입력에 사용되었거나 자막 요금이 변경됨: 다시 확인 후 제출
429	할당량 부족 또는 속도 제한, 대기 또는 할당량 충전
대기 시간 초과 / 네트워크 중단	작업이 계속 실행 중일 수 있음: 동일 명령어를 다시 실행 (동일 멱등 키로 원래 작업을 가져옴), 또는 miragea_audio.py task / wait 작업ID로 계속 조회, 키를 변경하여 재전송하지 마세요
결합 시 WAV 형식 불일치	각 문장 오디오는 out/lines/에 저장되어 있으며, 편집 소프트웨어 또는 ffmpeg로 결합 가능

공식 클라이언트 종료 코드: 0 요청 성공 (--wait 없으면 대기 중일 수 있음), 1 작업 실패, 2 클라이언트 또는 인터페이스 오류.

규정 준수

• 본인 또는 명시적 허가를 받은 사람의 목소리만 복제하고, 유명인, 방송인, 공인 또는 허가되지 않은 사람의 목소리를 모방하지 마세요.
• "인공지능 생성 합성 콘텐츠 식별 방법" 및 Douyin, Kuaishou, WeChat Channels, Xiaohongshu, Bilibili 등 플랫폼 규정에 따라 게시 시 AI 생성 콘텐츠임을 명시하거나 표시하세요.
• 영상 자료 및 원본 클립 대사에는 저작권이 있습니다: 이 스킬은 사용자가 직접 작성한 해설 더빙만 생성하며, 원본 클립 배우의 소리를 추출하거나 모방하지 않습니다. 영화 자료 사용 시 저작권자 및 플랫폼의 2차 창작 규정을 준수하세요.
• scripts/miragea_audio.py는 공식 클라이언트로서 변경 없이 제공되며, scripts/voiceover.py(대본 결합 레이어)는 오리지널로 MIT 라이선스 하에 제공됩니다 (자세한 내용은 LICENSE.txt 참조). 더빙 및 자막 기능은 Miragea 공개 API에서 제공합니다.

---

English Summary

• Movie recap voiceover (영화 해설 더빙): narrator + character lines in different voices, rendered into one voiceover WAV.
• Outputs SRT subtitles and manifest.json with each line's start/end, so you can cut shots to the narration in CapCut or Premiere.
• Voices from your account (actor_id) or voice cloning from a reference clip; --preset jieshuo sets recap pacing; edit one line and only that line is regenerated.
• Python 3.9+ stdlib only, no GPU, --dry-run offline. Service: Miragea API (https://miragea.ai/v1).

키워드: 영화 해설 더빙, 해설 더빙, 단편 드라마 해설, 영상 해설, 단편 드라마 해설 더빙, 영상 해설 더빙, 영화 해설, AI 더빙, 다중 역할 더빙, 나레이션 더빙, 음성 복제, 텍스트 음성 변환, 자막 생성, SRT, movie recap, voiceover, narration