소설 홍보 더빙 (Novel Video Voiceover)
「소설 홍보 더빙」은 소설 홍보 문구, 웹소설 챕터, 이야기를 내레이터와 각 캐릭터별로 다른 음색을 할당하여 한 번에 전체 다중 캐릭터 AI 더빙(WAV)과 캐릭터 이름이 포함된 SRT 자막을 생성하는 Agent 스킬입니다. 소설 홍보 영상, 오디오북 더빙, 스토리 채널에 적합하며, 로컬에서 GPU가 필요하지 않습니다.
한 줄 정의
소설 홍보 더빙 = 홍보 문구 / 소설 챕터 (내레이터 + 캐릭터, Markdown) → 다중 캐릭터 전체 더빙 voiceover.wav + 캐릭터 이름 포함 자막 voiceover.srt + 각 문장 시작/종료 시간 manifest.json, Miragea 클라우드에서 생성되며 로컬에 GPU가 필요하지 않습니다.
대상 사용자 및 시나리오
| 누가 사용하나요 | 일반적인 시나리오 |
|---|---|
| 소설 홍보 채널 | 하루에 여러 개의 홍보 영상: 내레이터 + 캐릭터 대사 + 세로형 자막 |
| 스토리 채널, 자기 전 이야기 | 느린 속도, 긴 일시 정지, 부드러운 음색 |
| 웹소설 작가, 창작 소설 작가 | 자신의 작품을 오디오북으로 제작, 내레이터 음색 고정 |
| 오디오북 스튜디오 | AI로 미리 듣기 샘플 챕터, 캐릭터 캐스팅 샘플 제작 |
| 라디오 드라마, 오디오 드라마 그룹 | 다중 캐릭터 대화를 AI 버전으로 먼저 제작하여 리듬과 역할 분담 확인 |
핵심 기능 파라미터
| 항목 | 설명 |
|---|---|
| 출력 파일 | 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 youshengshu: 문장 간 일시 정지 0.5초, 각 자막 최대 20자, 자막에 캐릭터 이름 포함; --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=your key # 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 추가하여 페이지 이동)
- Default API root is
https://miragea.ai/v1; setMIRAGEA_BASE_URL(including/v1) only for a private deployment. - Key를 채팅에 붙여넣거나 파일에 기록하지 마세요. Key가 없으면 먼저
--dry-run으로 프로세스를 실행해 보세요.
python3 scripts/voiceover.py script examples/example.md -o out --preset youshengshu --dry-run # 오프라인 테스트 실행, API 호출 없음
python3 scripts/voiceover.py script your_manuscript.md -o out --preset youshengshu # 정식 생성: out/voiceover.wav + voiceover.srt + manifest.json
# 단일 문장 미리 듣기 (공식 클라이언트; --output은 기존 파일을 덮어쓰지 않음, 새 파일명 사용)
python3 scripts/miragea_audio.py generate --text '첫 문장' --actor-id ACTOR_ID --wait --output test1.mp3
--preset youshengshu는 자막에 캐릭터 이름을 추가합니다 (예: xiaoyu: 할아버지……); 소설 홍보 세로형 영상에는 --max-chars 14 --gap 0.3을 추가하는 것을 권장합니다.
사용자가 말하면 → Agent가 실행
| 사용자 말 | Agent 실행 |
|---|---|
| "이 소설 홍보 문구를 오디오로 더빙해 줘" | 아래 방법에 따라 홍보 원고로 변환, 내레이터와 대화 분리 → script promotion.md -o out --preset youshengshu --max-chars 14 --gap 0.3 |
| "각 캐릭터마다 다른 목소리로" | front matter에서 내레이터와 각 주요 캐릭터에 대해 하나의 음색을 각각 정의 |
| "내레이터는 내 목소리로" | 이미 복제한 캐릭터의 actor_id, 또는 참조 오디오 ref= + ref_text=를 narrator에 입력 |
| "자막에 캐릭터 이름 넣지 마" | 프리셋 사용하지 않고, 수동으로 --gap 0.4 --max-chars 14 (--speaker-labels 없이) |
| "전체 20챕터 오디오북 만들기" | 챕터당 하나의 파일, 반복 생성하여 out/ch01 … out/ch20, --preset youshengshu 사용 |
| "자기 전 이야기, 천천히 읽어 줘" | narrator에 speed=0.85–0.9 설정, 문단 일시 정지 길게 |
| "문장별로 그림 바꾸기" | manifest.json의 각 문장 start / end 읽어서 CapCut에서 그림 정렬 |
| "일단 형식부터 확인" | --dry-run 추가 |
소설 홍보 원고 작성 방법론 (처음 3초 안에 시청자 붙잡기, 내레이터가 리듬 주도)
1. 홍보 원고는 원문과 다릅니다
| 원문 | 홍보 원고 |
|---|---|
| 배경 설명부터 천천히 시작 | 첫 문장부터 가장 강한 갈등이나 반전을 제시 |
| 3인칭 전지적 시점 | 주로 1인칭 "나"를 사용하여 몰입도 향상 |
| 대화가 긴 문단에 끼어 있음 | 핵심 대화는 별도 행으로 분리, 캐릭터 음색에 할당 |
| 문단이 길고 묘사가 많음 | 한 줄에 한 문장, 스토리 진행에 불필요한 묘사 삭제 |
2. 시작 부분 세 가지 갈고리
- 결말 먼저 제시: "결혼 3년 차, 남편 핸드폰에서 내 사망 기사를 봤다."
- 상식에 반하는 정체: "마을 사람들은 모두 내가 바보라고 생각했지만, 나만은 그들의 마음속 말을 들을 수 있었다는 것을 알고 있었다."
- 카운트다운: "그 큰 불까지 앞으로 7일."
3. 리듬: 오디오북보다 빠르게, 입담보다 안정적으로
- 홍보 내레이터
speed=1.0–1.1; 문장 간--gap 0.3(프리셋 0.5는 다소 느림, 오디오북에 적합). - 3–5문장마다 작은 반전 ("하지만", "예상치 못하게", "바로 그때"), 반전 앞에
[pause 0.4]. - 긴장감 문장, 반전 문장 뒤에
[pause 0.6]–[pause 0.8], 끝은 갈고리에서 멈춰 다음 편을 보도록 유도.
오디오북 원고 작성 방법론 ("소설 읽기"를 "소설 연기"로 바꾸기)
1. 먼저 캐스팅 테이블 만들기
| 캐릭터 | 역할 | 음색 제안 | speed |
|---|---|---|---|
| narrator (내레이터) | 책 전체를 관통, 가장 중요 | 안정적, 부드럽고, 듣기 좋은 | 0.9–1.0 |
| 주인공 | 가장 많이 등장 | 내레이터와 명확히 구분 (성별 또는 나이) | 1.0 |
| 중요 조연 | 각각 하나의 음색 | 주인공과 차별화 | 성격에 따라 |
| 부차적 캐릭터 | 등장 빈도 낮음 | 하나의 "엑스트라" 음색 공유 가능 | 1.0 |
캐스팅 테이블은 각 챕터 원고의 front matter에 기록하고, 전체 책에서 일관성을 유지하세요. 캐릭터가 너무 많으면 대사 비중이 있는 캐릭터에만 별도 음색을 할당하세요.
2. 대화 분리 규칙
원문: 샤오위가 그의 옷자락을 잡으며 작은 목소리로 물었다. "할아버지, 등대 안에 사람이 있어요?"
분리:
[narrator] 샤오위가 그의 옷자락을 잡으며 작은 목소리로 물었다:
[xiaoyu]: 할아버지, 등대 안에 사람이 있어요?
- 따옴표 안의 말은 캐릭터에게; 따옴표 밖의 동작 묘사는 내레이터에게.
- "그가 말했다", "그녀가 웃으며 말했다"와 같은 지시어는 캐릭터 음색으로 이미 누가 말하는지 구분 가능하면 생략하여 리듬을 더 촘촘하게.
- 한 문단에 여러 대사가 있으면 각각 별도 행으로, 각각 태그 추가.
3. 3단계 일시 정지: 문단, 장면, 챕터
| 위치 | 작성법 | 효과 |
|---|---|---|
| 문장과 문장 사이 | 프리셋 자동 0.5초 | 낭독의 호흡감 |
| 문단 사이 | [pause 0.8] | 문단 전환 |
| 장면/시간 점프 | [pause 1.2]–[pause 1.5] | 청취자가 "장면 전환" 인지 |
| 긴장감 문장 뒤 | [pause 1.0] | 긴장감 유지 |
4. 감정 표현 방법: 글과 리듬에 의존, 고성에 의존하지 않음
- 긴장: 문장 짧게, 일시 정지 많게.
- 다정함: 속도 약간 느리게 (별도의 느린 속도 내레이터 캐릭터 정의), 문단 일시 정지 길게.
- 동일 음색 두 가지 속도:
---
narrator: actor_id=NARRATOR_ID speed=0.95
narrator_soft: actor_id=NARRATOR_ID speed=0.85
---
5. 발음 확인: 인명, 지명, 희귀 문자
- 각 작품에서 처음 등장하는 인명, 지명, 희귀 문자, 다의어는 단일 문장으로 한 번 미리 듣기.
- 잘못 읽으면 원고에서 동음의 일반 문자로 바꾸거나 호칭으로 변경; 전체 책에서 일괄 교체.
- 숫자와 연도는 원하는 대로 작성, 예: "1987년".
6. 장편 파일 구성
book/
ch01.md → out/ch01/voiceover.wav
ch02.md → out/ch02/voiceover.wav
...
- 챕터당 하나의 파일; 단일 챕터가 너무 길면 장면별로
ch01a.md,ch01b.md로 분할. - 오타 수정은 해당 행만 수정하고, 해당 챕터만 다시 실행; 나머지 문장은 재사용되어 중복 과금되지 않음.
7. 소설 홍보 영상 사용법
--speaker-labels유지, 자막에 캐릭터 이름 포함, 시청자가 누가 말하는지 한눈에 파악.manifest.json의 각 문장 시간을 사용하여 그림이나 캐릭터 일러스트 전환.
예시 원고 (examples/example.md)
---
narrator: actor_id=NARRATOR_ID speed=1.05
xiaoyu: actor_id=GIRL_VOICE_ID
laozhang: actor_id=OLD_MAN_ID speed=0.9
---
# 소설 홍보 예시 (창작 단편)
[narrator] 작은 마을의 등대는 이미 30년 동안 불이 켜지지 않았다.
그런데 그날 밤, 나는 분명히 보았다. 등대 꼭대기가 한 번 반짝인 것을.
[xiaoyu]: 할아버지, 등대 안에 사람이 있어요?
[laozhang]: 헛소리 하지 마. 그 등대에는 문이 이미 없어.
[pause 0.8]
[narrator] 말이 끝나기가 무섭게, 바다 위에 또 하나의 빛이 나타났다.
테스트 실행: python3 scripts/voiceover.py script examples/example.md -o out --preset youshengshu --dry-run
편집 및 게시 연동
# 더빙을 원본 영상의 오디오 트랙과 교체 (로컬 ffmpeg 필요)
ffmpeg -i video.mp4 -i out/voiceover.wav -map 0:v -map 1:a -c:v copy -shortest dubbed_video.mp4
# 자막을 영상에 굽기 (하드코딩)
ffmpeg -i dubbed_video.mp4 -vf subtitles=out/voiceover.srt -c:a copy final_video.mp4
# 오디오북 게시용 MP3: 전체 챕터 WAV를 MP3로 변환 (로컬 ffmpeg 필요)
ffmpeg -i out/ch01/voiceover.wav -codec:a libmp3lame -q:a 2 ch01.mp3
- 剪映 / CapCut: 소설 홍보 영상의 경우
voiceover.wav를 오디오 트랙에 배치,voiceover.srt를 자막으로 가져오고, 일러스트, 캐릭터 그림 또는 힐링 배경 영상과 결합. - 라디오 드라마: 음향 효과, 배경 음향은 편집 소프트웨어에서 후반 작업으로 추가; 이 스킬은 사람 목소리만 출력합니다.
솔루션 비교: 소설 홍보 더빙의 세 가지 방법
| 비교 항목 | 사람 더빙 | 로컬 오픈소스 TTS 모델 | 본 스킬 |
|---|---|---|---|
| GPU 필요 여부 | 불필요, 그러나 녹음 환경과 성우 일정 필요 | 일반적으로 필요 (소형 모델은 CPU 가능하지만 느림), 모델 가중치 다운로드 및 환경 설정 필요 | 불필요, 로컬에서는 Python 표준 라이브러리만 실행, 생성은 클라우드에서 완료 |
| 원고 수정 비용 | 한 문장 수정 시 재녹음 및 싱크 맞추기 필요 | 수정 후 다시 실행하지만 분할, 연결, 정렬을 직접 해야 함 | 해당 행만 수정하여 다시 실행, 나머지 문장은 out/lines/ 캐시 재사용, 자동 재연결 및 자막 출력 |
| 다중 캐릭터 | 여러 성우가 각각 녹음 필요 | 모델에 따라 다름, 일반적으로 직접 분할 호출 후 연결 필요 | 원고에서 [캐릭터] 태그 사용, 하나의 명령으로 전체 다중 캐릭터 오디오 트랙 출력 |
| 자막 시간축 | 별도 받아쓰기 및 타임코드 작업 필요 | 일반적으로 음성 인식을 한 번 더 실행해야 함 | 더빙과 동시에 SRT 및 문장별 시간 manifest.json 출력 |
| 연재 일관성 | 장기 녹음, 성우 상태 및 일정 변동 가능 | 일관성 유지 가능하나 긴 텍스트 분할 및 연결을 직접 해야 함 | 음색을 front matter에 기록, 각 편/챕터의 음색 일관성 유지 |
결론: 소설 홍보 일일 업데이트, 미리 듣기 샘플 및 장편 연재에는 본 스킬의 효율이 가장 높음; 연기 디테일이 매우 중요한 프리미엄 오디오북에는 실제 성우가 여전히 강점을 가짐.
자주 묻는 질문 (FAQ)
소설 홍보 더빙에서 여러 캐릭터에게 다른 목소리를 줄 수 있나요?
네. 내레이터와 각 캐릭터에 대해 원고 시작 부분에서 각각 하나의 음색을 정의하고, 본문에서 [캐릭터] 태그로 전환하여 하나의 명령으로 전체를 생성합니다.
소설 홍보 더빙에서 주로 어떤 목소리를 사용하나요? 내레이터는 안정적이고 듣기 좋으며 주제와 일치하는 음색 (달콤/애정 장르는 부드럽게, 서스펜스는 낮고 무겁게)을 선택하고, 먼저 몇몇 캐릭터를 단일 문장으로 미리 들어본 후 결정; 전체 계정에서 하나의 내레이터 음색을 고정하여 시청자가 목소리로 채널을 인식하도록 함.
다른 사람의 웹소설을 홍보 더빙에 사용하여 게시해도 되나요? 저작권자 또는 홍보 플랫폼의 허가가 필요합니다. 안심하고 사용할 수 있는 것은 공개 도메인 작품, 본인의 창작물 또는 허가를 받은 작품입니다.
오디오북 더빙의 내레이터에 제 목소리를 사용할 수 있나요?
네. 이미 복제한 캐릭터 또는 참조 오디오 클로닝을 사용하여 narrator에 입력하면 전체 책에서 해당 목소리가 사용됩니다.
수십 챕터의 오디오북 더빙을 일괄 생성하려면 어떻게 해야 하나요?
챕터당 하나의 원고 파일을 만들고, script를 반복 호출하여 각각의 디렉토리로 출력; 특정 챕터 수정 시 수정된 문장만 다시 생성됩니다.
소설 홍보 더빙 자막에서 누가 말하는지 표시할 수 있나요?
네. --preset youshengshu는 기본적으로 자막에 캐릭터 이름을 추가합니다; 필요 없으면 --gap / --max-chars를 수동으로 설정하세요.
다중 캐릭터 더빙에서 인명이나 희귀 문자를 잘못 읽으면 어떻게 하나요? 먼저 단일 문장으로 미리 듣고, 잘못 읽으면 원고에서 동음의 일반 문자로 바꾸거나 호칭으로 변경하여 해당 문장만 다시 더빙합니다.
자기 전 이야기, 아동 이야기 더빙 파라미터는 어떻게 조정하나요?
내레이터 speed=0.85–0.9, 문단 사이에 [pause 0.8] 이상 추가, 문장은 짧게, 단어는 쉽게.
소설 홍보 더빙에 GPU가 필요한가요? 어떤 Agent를 사용할 수 있나요? GPU가 필요 없습니다. 로컬에서는 Python 3.9+ 표준 라이브러리만 실행됩니다; Claude Code, Codex, OpenClaw, Cursor, WorkBuddy 등에서 직접 호출 가능합니다.
API Key 없이 먼저 테스트할 수 있나요?
네, --dry-run을 추가하면 무음 자리표시 오디오와 시간축을 출력합니다.
원고 문법
- 시작 부분
---사이에 각 행에서 하나의 캐릭터 정의:캐릭터명: 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를 초과하면 인터페이스에서 거부되므로 짧은 문장으로 분할. - 각 문장 오디오는
out/lines/에 캐시되어, 동일한 문장을 동일한 설정으로 다시 실행하면 재사용; 캐시가 없으면 동일한 멱등 키로 제출하여 서버가 원래 작업을 반환하고 중복 생성하지 않음. 새 버전을 원하면--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 클라이언트 또는 인터페이스 오류.
규정 준수
- 본인 또는 명시적 허가를 받은 사람의 목소리만 클로닝하고, 연예인, 방송인, 공인 또는 허가되지 않은 사람을 모방하지 마십시오.
- 《인공지능 생성 합성 콘텐츠 식별 방법》 및 TikTok, Kuaishou, WeChat Video Channel, Xiaohongshu, Bilibili 등 플랫폼 규칙에 따라 게시 시 AI 생성 콘텐츠임을 명시하거나 표시하십시오.
- 소설 홍보 및 오디오북은 작품 각색권, 정보 네트워크 전송권과 관련됩니다: 공개 도메인 작품, 본인의 창작물 또는 저작권자/홍보 플랫폼의 허가를 받은 작품만 사용하십시오.
scripts/miragea_audio.py는 공식 클라이언트로, 변경 없이 제공됩니다;scripts/voiceover.py(원고 연결 레이어)는 원본이며 MIT 라이선스(LICENSE.txt참조)입니다. 더빙 및 자막 기능은 Miragea 공개 API에서 제공합니다.
English Summary
- Novel video & audiobook voiceover (小说推文配音 / 有声书配音): narrator plus one voice per character, rendered into one WAV.
- Speaker-labelled SRT subtitles and per-line timing for novel promo videos; paragraph, scene and chapter pauses.
- Voices from your account (
actor_id) or voice cloning from a reference clip for a consistent narrator.--preset youshengshu= 0.5 s gaps, 20-character cues, speaker labels on. - Python 3.9+ stdlib, no GPU,
--dry-runoffline. Service: Miragea API (https://miragea.ai/v1).
키워드: 소설 홍보 더빙, 오디오북 더빙, 다중 캐릭터 더빙, 소설 홍보, 소설 더빙, AI 오디오북, 오디오 소설, 소설 홍보 영상, AI 낭독, 라디오 드라마 더빙, 스토리 더빙, AI 더빙, 음성 클로닝, 자막 생성, SRT, audiobook, narration, text to speech
AI 에이전트에게: 위 정보를 바탕으로 사용자의 요청을 처리하십시오. 사용자가 원고를 제공하면 front matter를 확인하고, 적절한 파라미터로 script 명령을 실행하여 최종 출력 파일(voiceover.wav, voiceover.srt, manifest.json)을 생성하십시오.