Media Audio Gen

---
name: media-audio-gen
description: |
  통합 오디오 생성 스킬. ElevenLabs MCP 기반 TTS(32개국어), 보이스 클로닝(1분 샘플), 다국어 더빙(립싱크), 효과음 생성을 지원.
  "목소리 생성", "TTS", "음성 합성", "보이스 클로닝", "더빙", "나레이션", "효과음", "AI 음성" 요청 시 사용.
version: "1.3.0"
---

# media-audio-gen

## 개요

AI 기반 오디오 생성을 위한 통합 스킬입니다. ElevenLabs의 고성능 TTS 엔진을 활용하여 32개국어(한국 포함)의 자연스러운 음성을 생성하고, 단 1분의 샘플로 개인/브랜드 보이스를 클로닝합니다. 또한 비디오 다국어 더빙(립싱크 자동), 효과음 생성, 실시간 대화형 AI 보이스 에이전트 구축을 지원합니다.

### 주요 기능

- **TTS (Text-to-Speech)**: 32개국어 자연스러운 음성 생성 (한국어 최적화)
- **보이스 클로닝**: 1분 샘플로 개인/브랜드 보이스 복제
- **다국어 더빙**: 한국어 비디오 → 영어/일본어 등 (립싱크 자동 조정)
- **효과음 생성**: 영화, 게임, 콘텐츠용 사운드 이펙트
- **ConvAI**: 실시간 대화형 보이스 에이전트 (챗봇, AI 상담원)

---

## 트리거 키워드

다음 요청 시 이 스킬을 사용하세요:

- **음성 생성 관련**: "목소리 만들어줘", "TTS", "음성 합성", "나레이션 녹음", "AI 성우"
- **보이스 클로닝**: "내 목소리 복제", "브랜드 보이스 만들기", "보이스 클로닝", "샘플 음성으로 학습"
- **더빙 관련**: "영어 더빙", "일본어 번역+녹음", "외국어 자막+음성", "다국어 버전"
- **효과음**: "효과음 생성", "사운드 이펙트", "배경음", "비디오 소리"
- **대화형 AI**: "AI 상담원", "보이스봇", "실시간 음성 대화", "전화 자동 응답"

---

## 워크플로우

### 1. 기본 TTS (Text-to-Speech)

```
1. 텍스트 입력 (한국/영어/32개국어)
2. 보이스 프리셋 선택 또는 커스텀 보이스 ID 지정
3. 모델 선택 (eleven_multilingual_v2 기본)
4. 합성 전 견적 확인  ← 아래 §유료 합성 견적 게이트
5. 오디오 생성 (MP3/WAV)
```

### 1-1. 유료 합성 견적 게이트 (TTS·더빙·효과음 공통)

ElevenLabs 할당량은 **문자 수로 소진되고 되돌아오지 않는다.** 장문 나레이션 한 번이 무료 플랜 월 한도(10,000자)를 통째로 쓸 수 있다. 그래서 합성 전에 얼마가 나가는지 보여주고 승인을 받는다.

- **[HARD] 크레딧이 나가는 합성 전에는 견적을 보여주고 승인을 받는다.** 보이스 목록 조회·잔여 할당량 조회 같은 무료 호출은 대상이 아니다.
- **[HARD] 요약하지 말고 실제로 넘어가는 것을 그대로 보여준다:**

| 보여줄 것 | TTS | 더빙 | 효과음 |
|---|---|---|---|
| 합성될 **원문 전문**과 문자 수 | ✓ | ✓ (원문 + 번역문 양쪽) | 프롬프트 |
| 보이스 이름·ID (클로닝 보이스면 그 사실도) | ✓ | ✓ | — |
| 모델 (`eleven_multilingual_v2` 등) | ✓ | ✓ | — |
| 대상 언어 목록 | — | ✓ | — |
| 출력 개수 · 길이 | ✓ | ✓ | ✓ |
| **소진되는 문자 수 / 할당량**과 잔여분 | ✓ | ✓ | ✓ |

- **[HARD] 대상 언어가 여럿이면 언어별 소진분과 합계를 함께 보여준다.** 합계만 보여주면 언어 하나를 빼는 판단을 할 수 없다. 더빙은 언어 수만큼 배수로 나간다.
- **[HARD] 한국어 나레이션은 합성 전에 ⟨한국어 감사 3단⟩을 통과시킨다.** 음성으로 굳은 뒤 고치면 할당량을 다시 쓴다.

```
  moai-coworker:ai-slop-reviewer     1차 일반 슬롭 정리
→ moai-writer:korean-spell-check     2차 맞춤법 — 제안 수집 (미공개 정보가 섞였으면 건너뜀)
→ moai-writer:korean-humanize        3차 정밀 윤문 + 맞춤법 반영 + Phase 6 최종 검수
```

  감사 뒤에 **문자 수를 다시 센다** — 감사가 문장을 고치므로 이전 견적은 무효다.

승인 선택지는 이렇게 구성한다:

| 선택지 | 뜻 |
|--------|-----|
| 이대로 합성 (권장) | 보여준 견적 그대로 실행 |
| 고쳐 쓰기 / 언어·개수 줄이기 | 원문을 다듬거나 범위를 줄여 견적을 다시 |
| 취소 | 합성하지 않고 종료. 할당량 소진 없음 |

- **[HARD] 실패해도 자동 재합성하지 않는다.** 애매하게 실패하면(타임아웃·응답 없음) 재시도하지 않는다. 성공 신호가 없다는 것은 할당량이 소진되지 않았다는 증거가 아니며, 블라인드 재시도는 같은 문장에 두 번 낸다. **이 스킬은 소진 여부를 조회할 수단이 있다고 전제하지 않는다** — 잔여 할당량을 조회할 도구가 실제로 노출돼 있으면 그것으로 확인하고, 없으면 사용자에게 ElevenLabs 대시보드(Usage)에서 직접 확인해 달라고 요청한다. 어느 쪽이든 **소진되지 않았다는 확인을 받은 뒤에만** 다시 실행한다.
- **[HARD] 대량 배치는 배치 단위로 승인한다.** 여러 문단·여러 언어를 한 요청으로 처리하면 건별로 묻지 않고 **전체 계획 + 최대 총 소진분**을 한 번에 승인받는다.

### 2. 보이스 클로닝

목소리는 되돌릴 수 없는 개인정보입니다. 한 번 업로드하면 복제 보이스가 계정에 남고, **API 키를 가진 쪽은 누구나 그 보이스로 음성을 만들 수 있습니다** — 목소리 주인이 한 적 없는 말을 그 사람 목소리로. 그래서 이 스킬은 **업로드하기 전에** 멈춰서 승인을 받습니다. 승인 없이는 샘플을 올리지 않습니다.

#### 2-1단계: 업로드 전 승인 게이트

- **[HARD] 승인은 §승인 요청 계약의 경로로 받는다.** 산문으로 "올릴까요?"라고 묻지 않습니다 — 업로드는 되돌릴 수 없으므로 사용자가 명시적으로 고르게 합니다. **물을 수 없다는 이유로 게이트를 건너뛰지 않습니다** — 경로 선택은 §승인 요청 계약을 따릅니다.
- **[HARD] 요약하지 말고 실제로 넘어가는 인자 전부를 그대로 보여준다.** 아래 여섯 가지를 빠짐없이 제시합니다. 하나라도 빠지면 사용자는 무엇이 올라가는지 모르는 채 승인하게 됩니다.

| 보여줄 것 | 왜 필요한가 |
|---|---|
| 샘플 파일명 · 파일 크기 · 재생 길이 | 어떤 음원이 나가는지 파일 단위로 확인 |
| 보이스 이름 · 설명 | 계정 보이스 목록에 이 이름으로 남습니다 |
| 저장될 ElevenLabs 계정 | 개인 계정인지 회사·공용 계정인지 |
| 보존·공유 범위 | 계정 내 보존, 파일로 내려받기 불가, **API 키를 가진 외부 서비스도 이 보이스로 음성 생성 가능** |
| 소진되는 크레딧과 플랜 조건 | 클로닝은 유료 플랜 기능입니다 |
| 목소리 주인이 누구인지 | 아래 동의 확인 문항으로 이어집니다 |

승인 선택지는 이렇게 구성합니다:

| 선택지 | 뜻 |
|--------|-----|
| 이대로 클로닝 (권장) | 위에 보여준 인자 그대로 업로드 → 보이스 생성 |
| 샘플·이름 바꾸기 | 인자를 고친 뒤 게이트를 다시 통과 |
| 취소 | 아무것도 업로드하지 않고 종료 |

- **[HARD] 목소리 주인의 동의는 별도 문항으로 확인한다.** "이 파일을 올려도 되는가"와 "이 목소리를 복제해도 되는가"는 다른 질문입니다. 파일 승인 하나로 동의까지 받은 것으로 처리하지 않습니다.

| 선택지 | 뜻 |
|--------|-----|
| 내 목소리다 (권장) | 본인 음성 — 그대로 진행 |
| 제3자 목소리이고 동의를 받았다 | 동의 근거(서면·녹취·계약 등)를 한 줄로 남기고 진행 |
| 아직 동의를 못 받았다 | **중단** — 동의를 확보하기 전에는 업로드하지 않습니다 |

> ElevenLabs 역시 클로닝을 저장하기 전에 "복제할 권리와 동의가 있음"을 확인받습니다. 이 문항은 그 확인을 서비스에 도달하기 전에 사용자에게 먼저 되묻는 것입니다 — 클릭 한 번으로 넘어가는 체크박스가 아니라, 근거를 말하게 하는 질문으로.

#### 2-2단계: 클로닝 실행 (승인 시)

```
1. 승인된 참조 오디오 업로드 (1~2분 권장, 무음 구간 최소화)
2. 승인된 보이스 이름/설명으로 등록
3. 클로닝 실행 → 보이스 ID 발급
4. TTS에서 클로닝된 보이스 사용
```

- **[HARD] 실패해도 자동 재시도하지 않는다.** 클로닝이 애매하게 실패하면(타임아웃·응답 없음) **재시도하지 않고 멈춥니다.** 성공 신호가 없다는 것은 보이스가 만들어지지 않았다는 증거가 아닙니다. 확인 없이 다시 올리면 같은 목소리가 계정에 두 개 남고 크레딧도 두 번 나갑니다.
- 애매한 실패 뒤에는 **계정의 보이스 목록을 조회해 실제로 생성됐는지 먼저 확인**합니다. 조회할 수단이 없으면 사용자에게 ElevenLabs 대시보드(Voices)에서 직접 확인해 달라고 요청하고, **만들어지지 않았다는 사용자의 확인을 받은 뒤에만** 다시 실행합니다. 스킬이 혼자 판단하지 않습니다.

### 3. 다국어 더빙

**더빙도 음성 복제입니다.** ElevenLabs 더빙은 원본 화자의 목소리 특성을 살려 다른 언어로 말하게 만듭니다 — 결과물은 그 사람이 한 적 없는 외국어 발화가 그 사람 목소리로 나오는 것입니다. 보이스 클로닝과 같은 위험이고, 오히려 더 위험합니다: 클로닝은 저장 전에 ElevenLabs가 "복제할 권리와 동의"를 확인받지만, 더빙 경로에는 그 확인이 없습니다.

- **[HARD] 영상 속 화자가 사용자 본인이 아니면, 업로드 전에 2-1단계 승인 게이트를 그대로 통과시킨다.** 인자만 더빙에 맞게 바꿉니다 — 샘플 파일명 대신 원본 영상 파일명·길이, 보이스 이름 대신 대상 언어 목록, 그리고 **영상 속 화자가 누구이고 그 사람의 동의를 받았는지**를 같은 3개 선택지로 확인합니다.
- 화자가 사용자 본인이면 첫 문항에서 "내 목소리다"를 고르고 그대로 진행합니다.
- **[HARD] 인터뷰이·고객·행사 참석자 등 제3자가 화자로 등장하는 영상은 동의 없이 더빙하지 않는다.** 영상을 촬영할 때 받은 동의는 "촬영·게시" 동의이지 "목소리를 다른 언어로 합성해도 좋다"는 동의가 아닙니다.

```
1. 원본 비디오 업로드  ← 제3자 화자면 2-1단계 게이트 먼저
2. 원본 언어 감지 (예: 한국어)
3. 타겟 언어 선택 (예: 영어, 일본어, 스페인어)
4. 언어별 소진분 견적 확인  ← 1-1단계 견적 게이트 (언어 수만큼 배수)
5. 자동 번역 + 보이스 생성 + 립싱크 매칭
6. 더빙된 비디오 다운로드
```

> 더빙은 **두 게이트를 모두** 지난다 — 화자 동의(2-1단계)와 할당량 견적(1-1단계). 앞의 것은 목소리 주인을 위한 것이고, 뒤의 것은 계정 주인을 위한 것이다.

### 4. 효과음 생성

```
1. 효과음 설명 프롬프트 작성 (예: "천둥소리, 폭풍우")
2. 지속시간 설정 (1~30초)
3. 견적 확인  ← 1-1단계 견적 게이트 (개수 × 길이만큼 소진)
4. 생성 및 다운로드
```

여러 개를 한 번에 요청하면(예: 게임용 효과음 3종) 개별이 아니라 **묶음 견적**으로 승인받는다.

---

## 사용 예시

### 예시 1: 한국어 나레이션 생성

```
"이 블로그 글을 한국어 나레이션으로 읽어줘.
여성 차분한 톤으로, 3분 분량."
→ 보이스: Rachel (여성 차분)
→ 모델: eleven_multilingual_v2
→ 출력: MP3 파일
```

### 예시 2: 브랜드 보이스 클로닝 (승인 게이트 포함)

```
"우리 CEO의 1분 연설 음원이 있어.
이 목소리를 클로닝해서 신제품 발표 나레이션을 만들어줘."

→ 업로드 전 승인 게이트 (AskUserQuestion)
   샘플: ceo_sample.wav · 4.2MB · 1분 12초
   보이스 이름: "CEO 브랜드 보이스"
   저장 계정: <ElevenLabs 계정 식별자>
   보존·공유: 계정 내 보존 · 파일 다운로드 불가
              · API 키를 가진 외부 서비스도 이 보이스로 생성 가능
   크레딧: <클로닝 소진분> (유료 플랜 필요)
   목소리 주인: 제3자 (CEO)

→ 동의 확인 (별도 문항)
   "제3자 목소리이고 동의를 받았다" 선택 + 동의 근거 한 줄
   → 동의 미확보 선택 시 여기서 중단, 업로드하지 않음

→ 승인 후 실행
→ 출력: 클로닝된 보이스 ID + 나레이션 MP3
```

> CEO의 목소리는 CEO의 것이지 계정 주인의 것이 아닙니다. 본인 목소리라면 첫 문항에서 "내 목소리다"를 고르면 그대로 진행됩니다.

### 예시 3: 유튜브 영상 영어 더빙

```
"이 한국어 교육 영상을 영어와 일본어로 더빙해줘.
원본 자막은 유지하고, 립싱크도 맞춰줘."
→ 입력: korean_tutorial.mp4
→ 출력: english_dub.mp4, japanese_dub.mp4
```

### 예시 4: 효과음 생성

```
"판타지 게임용 마법 시전 효과음 3개 만들어줘.
1. 화염구 (2초)
2. 얼음 폭발 (3초)
3. 치유 빛 (2.5초)"
→ 출력: fireball.wav, ice_explosion.wav, heal_light.wav
```

---

## 출력 형식

### TTS 출력

- **파일 형식**: MP3 (기본), WAV, FLAC
- **샘플레이트**: 44.1kHz, 48kHz
- **채널**: 모노/스테레오 선택 가능
- **최대 길이**: 무제한 (사용 플랜에 따라 문자 수 한정)

### 보이스 클로닝

- **보이스 ID**: `voices/xxxxx` 형식
- **보존**: 클로닝된 보이스는 계정 내에 남습니다. 오디오 파일로 내려받을 수는 없습니다.
- **공유 범위**: 보이스 ID로 다른 프로젝트에서 재사용할 수 있고, **해당 계정의 API 키를 가진 외부 서비스도 이 보이스로 음성을 생성할 수 있습니다.** 클로닝 승인 화면에서 이 범위를 그대로 알려드립니다(워크플로 2-1단계).
- **삭제**: 더 이상 쓰지 않는 보이스는 ElevenLabs 대시보드(Voices)에서 지웁니다. 목소리 주인이 철회를 요청하면 지우는 것이 원칙입니다.

### 더빙 출력

- **비디오 형식**: MP4 (원본 품질 유지)
- **오디오 트랙**: 다국어 오디오 트랙 추가
- **자막**: SRT 자막 파일 자동 생성
- **싱크**: 립싱크 자동 조정 (±100ms 정밀도)

---

## 주의사항

### API 키 필수

**ELEVENLABS_API_KEY** 환경변수가 필요합니다.

1. [elevenlabs.io](https://elevenlabs.io) 가입
2. Settings → API Keys → Create API Key
3. `.env` 또는 시스템 환경변수에 등록:
   ```bash
   export ELEVENLABS_API_KEY="your_api_key_here"
   ```

### 요금 안내

| 플랜 | 가격 | 문자 수 | 사용처 |
|------|------|---------|--------|
| Free | $0 | 10,000자/월 | 테스트, 개인 프로젝트 |
| Starter | $5/월 | 30,000자/월 | 소규모 콘텐츠 |
| Creator | $22/월 | 100,000자/월 | 유튜버, 프리랜서 |
| Pro | $99/월 | 500,000자/월 | 앱 통합, 상업적 사용 |

### 제한사항

- **보이스 클로닝**: 최소 1분 샘플 필요 (무음 구간 최소화)
- **더빙**: 10분 초과 영상은 별도 협의 필요
- **상업적 사용**: Pro 플랜 이상 필요 (라이선스 조건 확인)
- **속도 제한**: Free 플랜은 RPM(분당 요청) 제한 있음

### 모델 선택 가이드

| 모델 | 성격 | 용도 | 비고 |
|------|------|------|------|
| `eleven_multilingual_v2` | 최고 품질 | 브랜딩, 광고, 나레이션 | 한국어 최적화, 권장 |
| `eleven_flash_v2_5` | 초저지연 | 실시간 대화, 게임 | 200ms 미만 |
| `eleven_turbo_v2_5` | 비용 효율 | 장문 나레이션, 대량 생성 | 50% 저렴 |

### 기본(ElevenLabs prebuilt) 보이스 프리셋 — eleven_multilingual_v2로 한국어 합성 가능

| 코드 | 성격 | 톤 | 사용처 |
|------|------|-----|--------|
| Rachel | 여성 차분 | 내레이터 | 다큐, 뉴스, 교육 |
| Antoni | 남성 친근 | 대화형 | 인터뷰, 팟캐스트 |
| Bella | 여성 발랄 | 에너지틱 | 광고, 홍보영상 |
| Callum | 남성 중립 | 전문·내레이터 | 보고서, 프레젠테이션 |

---

## 승인 요청 계약 (런타임 중립)

[HARD] 이 스킬의 게이트는 **특정 도구 이름에 묶이지 않는다.** `AskUserQuestion`은 Claude 런타임의 수단일 뿐이고, Codex를 비롯한 다른 런타임에는 그 도구가 없다. 도구 이름으로 계약을 쓰면 그 도구가 없는 런타임에서 게이트가 **영구 blocker**가 되어, 승인이 필요한 모든 작업이 그냥 멈춘다. 그건 안전이 아니라 고장이다.

승인은 아래 순서로 구한다. 위에서부터 **실제로 가능한 첫 번째**를 쓴다.

**승인의 정의는 수단이 아니라 결과다: 승인서를 사용자에게 그대로 보여주고, 그에 대한 명시적 응답을 받는 것.** 아래는 그 결과를 만드는 경로들이며, 위에서부터 가능한 첫 번째를 쓴다.

| 순위 | 경로 | 조건 |
|---|---|---|
| 1 | 런타임의 구조화 질문 도구 (`AskUserQuestion` 등) | 그 도구가 현재 세션에 노출돼 있을 때 |
| 2 | **일반 대화로 승인서를 제시하고 다음 턴에서 응답을 받는다** | 사용자와 직접 대화 중일 때. 도구가 없어도 이 경로는 언제나 열려 있다 |
| 3 | 구조화 blocker 반환 → 상위 오케스트레이터가 물어봄 | 서브에이전트로 실행 중일 때 |

**[HARD] 런타임의 도구 실행 권한 프롬프트는 승인이 아니다.** 그 프롬프트는 "이 도구를 호출해도 되는가"를 물을 뿐, 게이트가 보여주기로 한 인자·견적·동의 문항을 표시하지 않는다. 승인서 전체와 선택지를 실제로 표시하는 경우에만 2번 경로로 인정한다.

**[HARD] 2번 경로가 있으므로 "물을 수단이 없다"는 상황은 사실상 없다.** 대화가 가능한 곳에서는 언제나 승인서를 글로 제시할 수 있다. fail-closed는 **대화도 blocker 반환도 불가능한 완전 무인 실행**에만 해당한다 — 그 경우에만 실행하지 않고 멈춘다.

**[HARD] 3번을 쓸 때 blocker는 그 자체로 승인 요청서여야 한다.** 상위가 무엇을 물어야 할지 모르면 되물을 수 없고, 그러면 교착된다. 다음을 모두 담는다:

- 승인받을 **행위** 한 줄 (무엇이 되돌릴 수 없는지 / 얼마가 나가는지)
- 게이트가 요구하는 **인자 전부** (요약하지 않은 값)
- **선택지 목록** — 상위가 그대로 사용자에게 제시할 수 있는 형태
- **재개 방법** — 어떤 답을 받으면 무엇을 이어서 실행하는지

**[HARD] 세 경로가 모두 불가능한 무인 실행에서는 실행하지 않는다(fail-closed).** 물을 수단이 없다는 것은 승인을 받았다는 뜻이 아니다. 이때는 "승인 수단이 없어 진행하지 못했다"고 기록하고 멈춘다 — 조용히 진행하지 않는다. 반대로 **대화가 가능한데 도구가 없다는 이유로 멈추는 것도 잘못**이다. 2번 경로를 쓴다.

> 이 계약은 `CLAUDE.local.md` §범용성 원칙(OS 2종 × 런타임 2종에서 동일 동작)의 게이트 쪽 적용이다. 한 런타임에서만 도는 게이트는 미완성으로 본다.

---

## 관련 스킬

- **media-higgsfield-video**: TTS 오디오를 AI 비디오와 결합
- **media-higgsfield-image**: 앨범 아트·썸네일 등 오디오 콘텐츠용 이미지 생성
- **moai-marketer:content-blog**: 블로그 글 → 나레이션 스크립트 변환
- **moai-marketer:content-copywriting**: 광고 카피 → 광고 보이스 생성

---

## MCP 서버 설정

이 스킬은 **ElevenLabs MCP** (stdio)를 사용합니다.

```json
{
  "elevenlabs": {
    "command": "uvx",
    "args": ["elevenlabs-mcp"],
    "env": {
      "ELEVENLABS_API_KEY": "${ELEVENLABS_API_KEY}"
    }
  }
}
```

MCP 서버 등록 절차: 프로젝트 `.mcp.json`에 서버 설정을 추가한 뒤 필요한 인증(API 키 또는 OAuth)을 완료합니다.