ElevenLabs TTS para MP3

O que ElevenLabs TTS para MP3 faz?

Converte texto de roteiro em voz MP3 via API ElevenLabs Text-to-Speech.

Padrões

• ID da Voz: K7ewtjKRNtwwt3lKQ6M0 (voz da marca do Hoang — fixa) — substituível via env ELEVENLABS_VOICE_ID ou --voice_id
• Modelo: eleven_v3 (mais expressivo, suporta tags de áudio como [excited], [whisper], [laugh]; melhor para conteúdo narrativo) — substituível via --model_id. Alternativas: eleven_multilingual_v2 (alta qualidade, mais lento), eleven_turbo_v2_5 (rápido, levemente plano), eleven_flash_v2_5 (mais rápido)
• Formato de saída: mp3_44100_128 (44,1 kHz / 128 kbps) — substituível via --output_format
• Configurações de voz: stability=0.5, similarity_boost=0.75, style=0, use_speaker_boost=true (padrões ElevenLabs)
• Mapa de pronúncia: carregado automaticamente de assets/vn-pronunciation-map.json — desative com --no-pronounce-map, ou aponte para outro arquivo com --pronounce-map path.json
• Limite de caracteres: 5000 por requisição (limite fixo da ElevenLabs). Texto > 5000 caracteres → script sai com erro e pede para o usuário dividir manualmente.

Uso Rápido

A partir de arquivo

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

A partir de texto inline

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

Voz / modelo personalizado

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

Ajustar expressividade da voz

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

Configurações de voz — quando ajustar

Configuração	Faixa	Efeito
stability	0,0–1,0	Maior = mais monótono/previsível; menor = mais emocional/variável. 0,5 é o ponto ideal para narração. Reduza para 0,3–0,4 para ganchos casuais; aumente para 0,7+ para explicações formais.
similarity_boost	0,0–1,0	O quão próximo clonar a voz de referência. 0,75 padrão. Aumente para ~0,9 se a voz soar "diferente" da original.
style	0,0–1,0	Exagero de estilo. 0 padrão. Adiciona latência quando > 0. Útil (0,1–0,3) para conteúdo expressivo.
use_speaker_boost	bool	Acentua a similaridade do locutor. Mantenha true para consistência da voz da marca.

Mapa de Pronúncia (Correção de palavras em inglês)

Os modelos multilíngues da ElevenLabs tentam ler todo o texto no idioma dominante. Em um roteiro vietnamita, palavras em inglês como doc, chat, git são pronunciadas como sílabas vietnamitas e soam errado. Para corrigir isso sem editar manualmente cada roteiro, a skill carrega automaticamente um mapa de substituição de palavras inteiras, insensível a maiúsculas/minúsculas, de assets/vn-pronunciation-map.json e o aplica antes de enviar o texto para a API.

Mapeamento padrão:

{
  "doc": "đóc",
  "chat": "chát",
  "git": "gít"
}

Como funciona: cada chave é correspondida de forma insensível a maiúsculas/minúsculas com limites \b...\b, e depois substituída pelo valor fonético vietnamita. O modelo vê "đóc" em vez de "doc" e o pronuncia perto de /dɒk/. Isso afeta apenas o áudio — seu roteiro fonte permanece limpo.

Cuidando do dicionário — ouça primeiro, adicione depois:

• Execute a skill em um script de teste curto contendo a palavra candidata
• Se o modelo já a ler corretamente, não a adicione (overfitting quebrará as coisas)
• Cuidado com colisões: adicionar "code" também reescreveria Code em Claude Code (nome da marca) — nunca faça isso
• Para nomes de marcas que precisam de proteção, deixe-os de fora completamente

Substituir / desativar:

# Usar um mapa personalizado para um projeto específico
uv run scripts/text_to_mp3.py --file s.txt --pronounce-map workspace/.../map.json -o out.mp3

# Omitir a substituição completamente
uv run scripts/text_to_mp3.py --file s.txt --no-pronounce-map -o out.mp3

O script imprime cada substituição aplicada em stderr (ex.: 'doc' -> 'đóc' (4x)) para que você possa verificar o que mudou.

Fluxo de Trabalho

1. Carregar ELEVENLABS_API_KEY do .env do projeto
2. Ler texto de --file ou argumento posicional, remover espaços em branco
3. Aplicar mapa de pronúncia (a menos que --no-pronounce-map) — substituição de palavra inteira insensível a maiúsculas
4. Validar len(text) <= 5000
5. POST https://api.elevenlabs.io/v1/text-to-speech/{voice_id}?output_format=mp3_44100_128
   • Cabeçalho: xi-api-key: <key>, Content-Type: application/json, Accept: audio/mpeg
   • Corpo:

     {
       "text": "...",
       "model_id": "eleven_v3",
       "voice_settings": {
         "stability": 0.5,
         "similarity_boost": 0.75,
         "style": 0,
         "use_speaker_boost": true
       }
     }
     

6. Transmitir bytes de áudio diretamente para o MP3 de saída (sem necessidade de transcodificação — o servidor retorna MP3)
7. Imprimir output_path, size_mb, char_count, voice_id, model_id

Convenção de Saída

• Curto/teste: workspace/assets/elevenlabs/<nome>.mp3
• Produção de vídeo: workspace/content/YYYY-MM-DD/video-short/<projeto>/voiceover.mp3

Requisitos

• ELEVENLABS_API_KEY no .env do projeto (autenticação por cabeçalho: xi-api-key)
• Opcional ELEVENLABS_VOICE_ID no .env para fixar uma voz padrão diferente
• Dependências Python gerenciadas via metadados inline PEP 723 (instaladas automaticamente por uv run): requests, python-dotenv
• Não precisa de ffmpeg — ElevenLabs retorna MP3 diretamente

Por que sem divisão em partes

ElevenLabs limita requisições a 5000 caracteres. A skill falha rapidamente acima desse limite em vez de dividir automaticamente porque:

• Uma narração única deve ser um bloco coerente — dividir no meio do roteiro causa saltos de prosódia nos limites da concatenação
• O conteúdo do usuário (ganchos, roteiros curtos, segmentos de vídeo) normalmente cabe bem abaixo de 5000 caracteres
• Se o usuário realmente precisar de áudio mais longo, deve dividir o roteiro semanticamente (quebras de parágrafo) e chamar esta skill por parte, depois concatenar com ffmpeg em seu próprio pipeline

Referência da API

• Endpoint: POST https://api.elevenlabs.io/v1/text-to-speech/{voice_id}
• Autenticação: cabeçalho xi-api-key: <api_key>
• Catálogo de modelos: https://elevenlabs.io/docs/models
• Catálogo de vozes (navegar / obter IDs de voz): https://elevenlabs.io/app/voice-library
• Documentação da API: https://elevenlabs.io/docs/api-reference/text-to-speech/convert
• Limites de taxa: dependem do plano de assinatura — veja https://elevenlabs.io/pricing
• Formatos de saída: mp3_44100_128 (padrão), mp3_44100_192 (qualidade superior, apenas pago), pcm_44100, ulaw_8000 (telefonia)