gTTS (Google Text-to-Speech)

2.5.4 · active · verified Sat Apr 11

gTTS (Google Text-to-Speech) is an active Python library and command-line interface (CLI) tool that interacts with Google Translate's text-to-speech API. It converts text into spoken audio, which can be saved as an MP3 file or streamed to a file-like object. The library provides features for customizable text pre-processing and tokenization, enabling flexible and natural-sounding speech generation. As of its current version, 2.5.4, it continues to be actively maintained, with its latest release in November 2024.

Warnings

breaking gTTS relies on an undocumented Google Translate API, meaning breaking upstream changes can occur without notice from Google, potentially causing the library to malfunction.
Fix: Monitor for updates and new releases of gTTS to incorporate fixes for upstream API changes. Report issues to the gTTS GitHub repository.
gotcha An active internet connection is strictly required for gTTS to function, as it sends text to Google's servers for audio generation.
Fix: Ensure the environment where gTTS is run has a stable internet connection. Offline operation is not supported.
breaking Prior to version 2.0, gTTS attempted to fetch language lists dynamically. As of gTTS 2.x, languages are pre-generated and shipped with the library, removing the automatic download feature which had become unreliable.
Fix: Upgrade to gTTS >=2.0 for more reliable language support. If custom language handling was implemented, review `gtts.lang` for supported options.
deprecated The `debug` parameter of the `gTTS` constructor was removed in favor of Python's standard `logging` module (around gTTS 2.0).
Fix: Replace usage of the `debug` parameter with Python's standard `logging` configuration. Import `logging` and configure the 'gtts' logger directly.
breaking For the `gtts-cli` command-line tool, the long option name for specifying the output file was changed from `--destination` to `--output` (around gTTS 2.0).
Fix: Update CLI scripts to use `--output` instead of `--destination` when specifying the output file path for `gtts-cli`.
breaking Since gTTS 2.0, `gTTS()` will raise a `ValueError` instead of an `AssertionError` for unsupported languages when `lang_check` is enabled (which is the default behavior).
Fix: Update error handling code to catch `ValueError` instead of `AssertionError` when dealing with potentially unsupported language codes. Refer to `gtts.lang.tts_langs()` for a list of supported languages.
gotcha While gTTS automatically handles long texts by tokenizing them, the underlying Google Translate API has a character limit for individual segments (typically around 100 characters). Very complex or extremely long single 'tokens' might still encounter issues, though this is rare with gTTS's built-in tokenizers.
Fix: For exceptionally long or complex single phrases, consider breaking them down manually or reviewing `gtts` tokenization options (`pre_processor_funcs`, `tokenizer_func`) for advanced control.

Install

pip install gTTS Install gTTS

Imports

gTTS
```
from gtts import gTTS
```

Quickstart

This quickstart demonstrates how to initialize `gTTS` with a string and a language, then save the generated speech as an MP3 file. The `slow` parameter can be set to `True` for slower speech.

from gtts import gTTS

# The text that you want to convert to audio
text_to_speak = "Hello world, this is a test of the gTTS library."

# Language in which you want to convert
language = 'en'

# Pass the text and language to the gTTS object
tts = gTTS(text=text_to_speak, lang=language, slow=False)

# Save the converted audio to a file
tts.save("hello_world.mp3")

print("Audio saved as hello_world.mp3")

view raw JSON →