gtts

O que é o gTTS?

gTTS é uma biblioteca Python open-source e ferramenta de linha de comando que transforma texto em áudio MP3 falado, usando o endpoint de ler texto em voz alta do Google Tradutor. Você pode gravar a saída em um arquivo, objeto similar a arquivo para tratamento posterior, ou direto no stdout. Foi criado por Pierre Nicolas Durette sob licença MIT, e é um dos pacotes mais baixados de ler texto em voz alta no PyPI, com cerca de 175.000 downloads semanais. Se você já precisou transformar uma string em MP3 em três linhas de Python, provavelmente o gTTS foi o primeiro resultado.

Mas é importante notar que gTTS não é o Google Cloud Text-to-Speech. Ele usa o mesmo backend não documentado que alimenta o botão “Ouvir” do Google Tradutor. Esse detalhe define tudo a seguir: para o que gTTS serve bem, onde ele falha e quando buscar outra solução.

Quando usar o gTTS?

Use o gTTS se você precisa de prototipagem rápida e gratuita, gerar MP3 a partir de texto com apenas uma linha, demos multilíngues, projeto de hobby, exemplo de sala de aula ou script de acessibilidade para ler exportações do Google Docs em voz alta. Não use o gTTS se você precisa de confiabilidade para produção, SLA documentado, clonagem de voz, controle SSML, vozes neurais/expressivas, áudio em streaming ou licenciamento comercial claro.

Como o gTTS funciona?

gTTS não sintetiza voz localmente. Ele faz uma requisição ao backend do recurso “Ouvir” do Google Tradutor, baixa o MP3 resultante e entrega os bytes para você. Isso exige conexão ativa com a internet, pois não há modo offline, e o áudio é gerado nos servidores do Google, não no seu computador. O endpoint também não é oficial. O projeto não é afiliado ao Google ou Cloud, podendo quebrar a qualquer momento por mudanças sem aviso.

Instalação

bash

pip install gTTS

gTTS exige Python 3.7 ou superior e funciona no macOS, Windows e Linux. A versão PyPI atual é a 2.5.4 (novembro de 2024). Em sistemas baseados em Debian (ex: Raspberry Pi OS), fique atento à diferença de caixa: o pacote pip é gTTS, enquanto pelo apt é python3-gtts. Se o pip install falhar com erro de ambiente gerenciado no SO mais recente, instale em um ambiente virtual.

Uso Básico

O menor exemplo possível:

python

from gtts import gTTS
tts = gTTS("Hello, world.")tts.save("hello.mp3")

Via Linha de Comando:

bash

gtts-cli "hello" --output hello.mp3

Escolhendo Idioma e Sotaque

python

tts = gTTS("Bonjour le monde", lang="fr")tts.save("bonjour.mp3")

gTTS também permite usar sub-tags regionais via parâmetro tld — por exemplo

tld="co.uk" para sotaque britânico ou tld="ca" para francês canadense, mudando o domínio do Google Tradutor utilizado.

Modo Lento

python

tts = gTTS("Read this slowly.", lang="en", slow=True)tts.save("slow.mp3")

Esse é basicamente todo o controle de voz disponível. Não há parâmetro de tom, apenas o slow=True, sem seleção de voz nem SSML.

Transmita para um Buffer Ao Invés do Disco

python

from io import BytesIOfrom gtts import gTTS
buf = BytesIO()gTTS("Stream me").write_to_fp(buf)buf.seek(0)# agora passe buf para pydub, ffmpeg, web, etc.

Pré-processamento e Texto Longo

Um dos destaques do gTTS é seu tokenizador. Ele divide textos longos em partes aceitas pelo backend (limite de cerca de 100 caracteres por requisição), preservando a entonação e lidando com abreviações, decimais e pontuação. É possível adicionar pré-processadores para corrigir pronúncias, como nomes de produtos e siglas.

Quais são os Prós do gTTS?

gTTS (Google Text-to-Speech) é popular entre desenvolvedores por ser leve, fácil de usar e se integrar bem em projetos Python. Gera arquivos MP3 e salva a saída direto em arquivos, objetos ou stdout, facilitando automação e scripts. Suporta cerca de 60 idiomas, dialetos e configuração de domínio, cobrindo aplicações simples multilíngues. Oferece também interface de linha de comando (gtts-cli), integração com scripts shell e tokenizadores personalizáveis para abreviações, números e substituições de texto. A API Python mínima facilita adicionar voz em notebooks Jupyter, apps Flask, bots Discord e projetos leves sem curva de aprendizado.

Quais são os Contras do gTTS?

Apesar da simplicidade, o gTTS tem limitações em relação a plataformas de voz IA modernas. As vozes são baseadas no áudio padrão do Google Tradutor — funcionais, mas sem a naturalidade, emoção e realismo das novas soluções neurais de ler texto em voz alta. Não há escolha de estilo de voz por idioma e faltam controles avançados como SSML, ajuste de tom ou velocidade. O gTTS exige baixar o MP3 antes do uso, sem streaming, o que aumenta a latência em apps interativos. Toda requisição é online — não há uso offline — tornando-o menos ideal onde confiabilidade e baixa latência são essenciais.

Quais são as Limitações do gTTS para Desenvolvedores?

1. Limite de requisições em endpoint não documentado

Esse é o maior problema ao passar do “olá mundo”. O gTTS não publica um limite porque o serviço original também não. Na prática, um IP consegue algumas dezenas de milhares de caracteres por hora antes do Google devolver HTTP 429; o limite exato varia com o tráfego. Se seu app gera áudio para muitos usuários de um único servidor, você vai atingir o limite sem SLA para recorrer.

2. O endpoint pode mudar sem aviso prévio

Como o gTTS usa uma rota interna do Google Tradutor e não uma API pública, o Google pode, e já mudou, a assinatura das requisições e respostas, quebrando o gTTS de um dia para o outro. O mantenedor publica uma correção, você

pip install -U gTTS e a vida segue. Isso serve para scripts de hobby, não para produção às 2h da manhã.

3. Frequência de manutenção

O projeto ainda recebe atualizações (ao menos uma nos últimos 12 meses), mas a triagem de issues é lenta e só há um responsável principal. Alguns sites classificam o repositório como “inativo”. Isso é comum para bibliotecas MIT gratuitas; mas em produtos pagos, é um ponto a considerar.

4. Ambiguidade comercial e dos Termos de Uso

Como o gTTS utiliza o Google Tradutor e não o Google Cloud TTS, o licenciamento do áudio gerado para uso comercial não está claro em nenhum lugar. A biblioteca é MIT; porém o áudio segue os termos do Google para um serviço não exposto oficialmente como ler texto em voz alta. Se o setor jurídico pede resposta clara, o gTTS não é a escolha.

5. Dados sensíveis saem do seu computador

Cada string sintetizada é enviada para os servidores do Google. Se você usa com documentos internos, PII de clientes ou conteúdo do Google Docs, pense bem na política de dados antes de usar.

Qual a Diferença Entre gTTS e Google Cloud Text-to-Speech?

Embora gTTS e Google Cloud Text-to-Speech sejam confundidos, não são o mesmo produto. As diferenças:

Se você precisa da voz do Google em produção, provavelmente deve optar pelo Google Cloud TTS, não pelo gTTS.

Quando Migrar para uma API Profissional de Leitura?

O momento certo de trocar o gTTS por uma API profissional de ler texto em voz alta depende da importância da qualidade do áudio, confiabilidade e personalização para o seu projeto. O gTTS é ótimo para protótipos, projetos pessoais, ferramentas experimentais ou de acessibilidade, pois é simples e gratuito. Mas se o produto é comercial, áudio de alta qualidade faz parte da experiência do usuário, ou você precisa de latência previsível com SLA, a solução profissional se torna necessária. Também vale migrar se precisa de várias vozes, clonagem de voz, SSML, streaming, controle do ritmo/pronúncia ou licenciamento comercial explícito. Conforme o projeto evolui, esses requisitos passam de opcionais a essenciais.

Devo usar o gTTS ou a API da Speechify?

A API de ler texto em voz alta da Speechify é um serviço pago oficial, com vozes neurais, várias opções por idioma, SSML e licenciamento comercial garantido — não é só um wrapper para endpoint não documentado. Se limites do gTTS, qualidade de voz ou incerteza nos termos estão travando seu projeto, vale considerar essa migração.

Perguntas Frequentes

O gTTS é grátis?

Sim, o gTTS é uma biblioteca Python grátis e MIT, mas para áudio licenciado e uso comercial, busque uma solução paga como a API Speechify.

O gTTS funciona offline?

Não, o gTTS exige conexão com a internet pois depende dos servidores do Google. O mesmo vale para a API Speechify, que é serviço em nuvem.

Posso usar o gTTS em produtos comerciais?

O licenciamento do áudio gerado pelo gTTS é ambíguo, pois depende de endpoint não documentado do Google, enquanto a API Speechify oferece licenciamento comercial explícito.

Como mudar de voz no gTTS?

Não há forma prática. O gTTS tem apenas uma voz por idioma, enquanto a API Speechify oferece catálogo de vozes neurais para escolha.

O gTTS aceita SSML?

Não, o gTTS não tem SSML, ajuste de tom ou controle avançado de velocidade, mas a API Speechify aceita SSML com controle total de prosódia.

Por que o gTTS retorna erro HTTP 429?

Você atingiu o limite não documentado do Google Tradutor, motivo comum para desenvolvedores migrarem para serviço com SLA, como a API Speechify.

O gTTS é igual ao Google Cloud Text-to-Speech?

Não, o gTTS usa endpoint não oficial do Google Tradutor, enquanto o Google Cloud TTS é um produto pago separado, assim como a API Speechify com vozes neurais.

Qual a melhor biblioteca Python para produção?

O gTTS serve para protótipos, não para produção; em cargas reais, a maioria dos desenvolvedores opta por APIs pagas como a API Speechify.

O gTTS pode clonar vozes?

Não, clonagem de voz não é suportada no gTTS, mas está disponível na API Speechify.

Como transmitir áudio com o gTTS?

O gTTS não permite streaming em tempo real: ele retorna MP3 pronto. Para streaming com baixa latência, use a API Speechify.