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
- レート制限: サブスクリプションプランに依存 — https://elevenlabs.io/pricing を参照
- 出力フォーマット:
mp3_44100_128(デフォルト)、mp3_44100_192(高品質、有料のみ)、pcm_44100、ulaw_8000(電話用)