Gemini Text-to-Speech (Texto para Fala)
Gere fala natural e expressiva a partir de texto usando o Google Gemini TTS. Suporta mais de 70 idiomas, 30 vozes pré-definidas e controle de estilo através de prompts em linguagem natural e tags de áudio.
Requisitos: Node.js 18+, ffmpeg, pacote npm
@google/genai, variável de ambienteGEMINI_API_KEY.
Scripts Disponíveis
scripts/generate-tts.mjs— Gerador TTS completo com consistência em requisição única, divisão baseada em silêncio e corte automático.
Início Rápido
Texto único para fala
npm install @google/genai
GEMINI_API_KEY=sua-chave node scripts/generate-tts.mjs \
--text "Olá, bem-vindo ao nosso produto!" \
--output-dir public/vo \
--voice Kore
Voiceover multi-segmento (voz consistente)
Crie um arquivo segments.json:
[
{ "id": "intro", "text": "Bem-vindo ao lançamento do nosso produto." },
{ "id": "features", "text": "Aqui estão as três funcionalidades que você vai adorar." },
{ "id": "close", "text": "Comece hoje mesmo em nosso site." }
]
Execute:
GEMINI_API_KEY=sua-chave node scripts/generate-tts.mjs \
--segments segments.json \
--output-dir public/vo \
--voice Kore \
--director-notes "Tom: Caloroso, confiante, inspirador. Estilo: Narrador profissional com um sorriso vocal. Sotaque: Inglês americano neutro. Ritmo: Moderado."
Saída (JSON no stdout):
{
"success": true,
"segments": [
{ "id": "intro", "file": "public/vo/vo-intro.mp3", "duration": 3.25 },
{ "id": "features", "file": "public/vo/vo-features.mp3", "duration": 4.10 },
{ "id": "close", "file": "public/vo/vo-close.mp3", "duration": 2.80 }
],
"totalDuration": 10.15,
"fullAudioFile": "public/vo/vo-full.wav"
}
Opções do Script
| Flag | Padrão | Descrição |
|---|---|---|
--segments ARQUIVO | — | Arquivo JSON com definições de segmento [{id, text}] |
--text TEXTO | — | Texto único para gerar (alternativa a --segments) |
--output-dir DIR | — | Diretório de saída para arquivos de áudio (obrigatório) |
--voice NOME | Kore | Nome da voz pré-definida (consulte tabela Vozes) |
--model NOME | gemini-3.1-flash-tts-preview | ID do modelo Gemini TTS |
--director-notes TEXTO | — | Diretrizes de performance: estilo, ritmo, sotaque, respiração, articulação. Não controla gênero/idade (use --voice para isso). |
--retries N | 3 | Número máximo de tentativas para erros de API |
--trim / --no-trim | --trim | Cortar silêncio das bordas dos segmentos |
--format FORMATO | mp3 | Formato de saída: mp3 ou wav |
Códigos de Saída
| Código | Significado |
|---|---|
| 0 | Sucesso |
| 1 | Argumentos ou variáveis de ambiente obrigatórios ausentes |
| 2 | Erro de API após todas as tentativas esgotadas |
| 3 | ffmpeg não instalado ou falha no processamento |
| 4 | Erro de E/S de arquivo |
Como Funciona (Multi-Segmento)
O Gemini TTS NÃO garante consistência de voz entre requisições separadas à API. O script resolve isso:
- Combinando todos os segmentos em UM ÚNICO prompt com marcadores de
[pausa de 3 segundos]entre eles - Gerando um único arquivo de áudio contínuo em uma única chamada de API
- Detectando lacunas de silêncio com ffmpeg
silencedetectusando limites adaptativos (começa em noise=-35dB, d=1.5s, relaxa progressivamente). Se uma correspondência exata for encontrada, usa diretamente. Se ocorrer um salto de limite (muito poucos → muitos demais), regenera o áudio com ritmo de fala mais rápido para tornar as pausas entre segmentos mais distintas, então tenta a detecção novamente. - Dividindo nos pontos médios do silêncio em arquivos de segmento individuais
- Cortando o silêncio residual (~1.5s de cada lado) de cada segmento, mantendo 0.15s de margem para respiração
Modelos
| Modelo | Melhor Para |
|---|---|
gemini-3.1-flash-tts-preview | Mais recente, mais controlável, 200+ tags de áudio (padrão) |
gemini-2.5-flash-preview-tts | Rápido, boa qualidade, uso geral |
gemini-2.5-pro-preview-tts | Qualidade mais alta, performances complexas |
Vozes
30 vozes pré-definidas:
| Voz | Gênero | Personalidade | Tom |
|---|---|---|---|
| Achernar | Feminino | Suave | Mais agudo |
| Achird | Masculino | Amigável | Médio-grave |
| Algenib | Masculino | Grave | Grave |
| Algieba | Masculino | Suave | Grave |
| Alnilam | Masculino | Firme | Médio-grave |
| Aoede | Feminino | Descontraída | Médio |
| Autonoe | Feminino | Brilhante | Médio |
| Callirrhoe | Feminino | Tranquila | Médio |
| Charon | Masculino | Informativo | Grave |
| Despina | Feminino | Suave | Médio |
| Enceladus | Masculino | Ofegante | Grave |
| Erinome | Feminino | Clara | Médio |
| Fenrir | Masculino | Empolgado | Médio-grave |
| Gacrux | Feminino | Madura | Médio |
| Iapetus | Masculino | Clara | Médio-grave |
| Kore | Feminino | Firme | Médio |
| Laomedeia | Feminino | Otimista | Mais agudo |
| Leda | Feminino | Jovial | Mais agudo |
| Orus | Masculino | Firme | Médio-grave |
| Puck | Masculino | Otimista | Médio |
| Pulcherrima | Masculino | Direto | Médio |
| Rasalgethi | Masculino | Informativo | Médio |
| Sadachbia | Masculino | Animado | Grave |
| Sadaltager | Masculino | Conhecimento | Médio |
| Schedar | Masculino | Equilibrado | Médio-grave |
| Sulafat | Feminino | Calorosa | Médio |
| Umbriel | Masculino | Tranquilo | Médio-grave |
| Vindemiatrix | Feminino | Gentil | Médio |
| Zephyr | Feminino | Brilhante | Mais agudo |
| Zubenelgenubi | Masculino | Casual | Médio-grave |
Notas do Diretor (--director-notes)
Diretrizes de performance para a voz selecionada. Defina apenas o que importa — especificar demais limita a criatividade do modelo e pode piorar os resultados.
As três orientações mais comuns são Estilo, Ritmo e Sotaque, mas você pode incluir quaisquer instruções personalizadas relevantes para a performance.
- Estilo — Qualidade emocional e caráter da entrega. Seja descritivo:
"Entusiasmo contagiante — o ouvinte deve sentir que faz parte de algo emocionante"funciona melhor do que apenas"energético". Você pode combinar características e usar termos do setor de locução como "sorriso vocal". - Ritmo — Velocidade geral e variação de ritmo. Pode variar de
"Fale o mais rápido possível"a"Incrivelmente lento e fluido, palavras se misturam, zero urgência". - Sotaque — Seja específico.
"Inglês britânico como falado em Croydon, Inglaterra"funciona muito melhor do que"sotaque britânico".
--director-notes "Estilo: YouTuber de beleza GenZ entusiasmada e atrevida. Ritmo: Extremamente rápido, entrega acelerada como influenciadores de vídeos curtos. Sotaque: Valley girl do sul da Califórnia de Laguna Beach."
Tags de Áudio
Use [colchetes] inline no texto do segmento para controle por palavra. Sobrescreve as notas do diretor localmente.
[sussurros] [gritos] [animado] [sério] [pausa curta] [risos] [muito rápido] [muito lento] [sarcástico] [curioso]
Tags criativas também funcionam: [como drácula], [sussurrando conspiradoramente]
Exemplo: "[animado] Isso muda tudo! [pausa curta] Deixe-me mostrar como."
Referências
- Guia de Prompting — Engenharia de prompt avançada para estilo, emoção e sotaque