ElevenLabs TTS to MP3
ElevenLabs Text-to-Speech API를 통해 스크립트 텍스트를 MP3 음성 해설로 변환합니다.
기본값
- 음성 ID:
K7ewtjKRNtwwt3lKQ6M0(Hoang의 브랜드 음성 — 고정) —ELEVENLABS_VOICE_ID환경 변수 또는--voice_id로 재정의 가능 - 모델:
eleven_v3(가장 표현력이 뛰어나며, [excited], [whisper], [laugh] 같은 오디오 태그 지원, 스토리텔링 콘텐츠에 최적) —--model_id로 재정의 가능. 대안:eleven_multilingual_v2(고품질, 느림),eleven_turbo_v2_5(빠름, 다소 평범함),eleven_flash_v2_5(가장 빠름) - 출력 형식:
mp3_44100_128(44.1 kHz / 128 kbps) —--output_format으로 재정의 가능 - 음성 설정:
stability=0.5,similarity_boost=0.75,style=0,use_speaker_boost=true(ElevenLabs 기본값) - 발음 맵:
assets/vn-pronunciation-map.json에서 자동 로드 —--no-pronounce-map으로 비활성화하거나--pronounce-map path.json으로 다른 파일 지정 가능 - 문자 제한: 요청당 5000자 (ElevenLabs 하드 제한). 5000자 초과 시 스크립트가 오류와 함께 종료되며 사용자에게 수동 분할을 요청합니다.
빠른 사용법
파일에서 읽기
uv run .claude/skills/mkt-elevenlabs-tts-to-mp3/scripts/text_to_mp3.py \
--file path/to/script.txt \
-o workspace/content/YYYY-MM-DD/voiceover.mp3
인라인 텍스트에서 읽기
uv run .claude/skills/mkt-elevenlabs-tts-to-mp3/scripts/text_to_mp3.py \
"Xin chào các bạn, hôm nay mình chia sẻ về AI Agent" \
-o workspace/assets/elevenlabs/sample.mp3
사용자 정의 음성 / 모델
uv run .claude/skills/mkt-elevenlabs-tts-to-mp3/scripts/text_to_mp3.py \
--file script.txt \
--voice_id K7ewtjKRNtwwt3lKQ6M0 \
--model_id eleven_turbo_v2_5 \
-o output.mp3
음성 표현력 조정
uv run .claude/skills/mkt-elevenlabs-tts-to-mp3/scripts/text_to_mp3.py \
--file script.txt \
--stability 0.4 \
--similarity_boost 0.8 \
--style 0.2 \
-o output.mp3
음성 설정 — 조정 시기
| 설정 | 범위 | 효과 |
|---|---|---|
stability | 0.0–1.0 | 높을수록 단조롭고 예측 가능; 낮을수록 감정적이고 다양함. 0.5가 내레이션에 최적. 캐주얼한 훅에는 0.3–0.4로 낮추고, 공식적인 설명에는 0.7 이상으로 높이세요. |
similarity_boost | 0.0–1.0 | 참조 음성을 얼마나 가깝게 복제할지. 기본값 0.75. 음성이 원본과 "다르게" 들리면 0.9 쪽으로 높이세요. |
style | 0.0–1.0 | 스타일 과장. 기본값 0. 0보다 크면 지연 시간이 추가됨. 표현력이 풍부한 콘텐츠에 유용(0.1–0.3). |
use_speaker_boost | bool | 화자 유사성을 선명하게 함. 브랜드 음성 일관성을 위해 true로 유지하세요. |
발음 맵 (영어 단어 수정)
ElevenLabs 다국어 모델은 전체 텍스트를 지배적인 언어로 읽으려고 합니다. 베트남어 스크립트에서 doc, chat, git 같은 영어 단어는 베트남어 음절로 발음되어 잘못 들립니다. 모든 스크립트를 수동으로 편집하지 않고 이 문제를 해결하기 위해, 스킬은 assets/vn-pronunciation-map.json에서 전체 단어 대소문자 구분 없는 대체 맵을 자동 로드하여 API에 텍스트를 보내기 전에 적용합니다.
기본 매핑:
{
"doc": "đóc",
"chat": "chát",
"git": "gít"
}
작동 방식: 각 키는 \b...\b 경계를 사용해 대소문자 구분 없이 일치시킨 후 베트남어 발음 값으로 대체합니다. 모델은 "doc" 대신 "đóc"를 보고 /dɒk/에 가깝게 발음합니다. 이는 오디오에만 영향을 미치며, 소스 스크립트는 그대로 유지됩니다.
사전 큐레이션 — 먼저 듣고, 그 다음에 추가하세요:
- 후보 단어가 포함된 짧은 테스트 스크립트로 스킬을 실행하세요
- 모델이 이미 올바르게 읽는다면 추가하지 마세요 (과적합은 문제를 일으킵니다)
- 충돌을 주의하세요:
"code"를 추가하면Claude Code(브랜드 이름)의Code도 다시 쓰게 됩니다 → 절대 그렇게 하지 마세요 - 보호해야 할 브랜드 이름은 완전히 제외하세요
재정의 / 비활성화:
# 특정 프로젝트에 사용자 정의 맵 사용
uv run scripts/text_to_mp3.py --file s.txt --pronounce-map workspace/.../map.json -o out.mp3
# 대체를 완전히 건너뛰기
uv run scripts/text_to_mp3.py --file s.txt --no-pronounce-map -o out.mp3
스크립트는 적용된 모든 대체를 stderr로 출력합니다(예: 'doc' -> 'đóc' (4x)).
워크플로우
- 프로젝트
.env에서ELEVENLABS_API_KEY로드 --file또는 위치 인자에서 텍스트 읽기, 공백 제거- 발음 맵 적용(
--no-pronounce-map이 아닌 경우) — 전체 단어 대소문자 구분 없는 대체 len(text) <= 5000검증POST https://api.elevenlabs.io/v1/text-to-speech/{voice_id}?output_format=mp3_44100_128- 헤더:
xi-api-key: <key>,Content-Type: application/json,Accept: audio/mpeg - 본문:
{ "text": "...", "model_id": "eleven_v3", "voice_settings": { "stability": 0.5, "similarity_boost": 0.75, "style": 0, "use_speaker_boost": true } }
- 헤더:
- 오디오 바이트를 출력 MP3로 직접 스트리밍 (트랜스코딩 불필요 — 서버가 MP3 반환)
output_path,size_mb,char_count,voice_id,model_id출력
출력 규칙
- 짧은/테스트:
workspace/assets/elevenlabs/<name>.mp3 - 비디오 제작:
workspace/content/YYYY-MM-DD/video-short/<project>/voiceover.mp3
요구 사항
- 프로젝트
.env의ELEVENLABS_API_KEY(헤더 인증:xi-api-key) .env의 선택적ELEVENLABS_VOICE_ID(다른 기본 음성 고정)- Python 종속성은 PEP 723 인라인 메타데이터를 통해 관리됨(
uv run으로 자동 설치):requests,python-dotenv ffmpeg불필요 — ElevenLabs가 MP3를 직접 반환함
청크 분할 없는 이유
ElevenLabs는 요청을 5000자로 제한합니다. 스킬은 자동 분할 대신 제한을 초과하면 빠르게 실패합니다:
- 단일 음성 해설은 일관된 청크여야 함 — 스크립트 중간에서 분할하면 연결 경계에서 운율 점프가 발생함
- 사용자 콘텐츠(훅, 짧은 스크립트, 비디오 세그먼트)는 일반적으로 5000자 미만으로 잘 맞음
- 사용자가 실제로 더 긴 오디오가 필요한 경우, 스크립트를 의미적으로(문단 나누기) 분할하고 이 스킬을 청크별로 호출한 후 자체 파이프라인에서 ffmpeg로 연결해야 함
API 참조
- 엔드포인트:
POST https://api.elevenlabs.io/v1/text-to-speech/{voice_id} - 인증:
xi-api-key: <api_key>헤더 - 모델 카탈로그: https://elevenlabs.io/docs/models
- 음성 카탈로그 (음성 ID 찾기/둘러보기): https://elevenlabs.io/app/voice-library
- API 문서: https://elevenlabs.io/docs/api-reference/text-to-speech/convert
- 속도 제한: 구독 tier에 따라 다름 — https://elevenlabs.io/pricing 참조
- 출력 형식:
mp3_44100_128(기본값),mp3_44100_192(고품질, 유료 전용),pcm_44100,ulaw_8000(전화)