Module (gtts) — gTTS documentation (2024)

gTTS (gtts.gTTS)

class gtts.tts.gTTS(text, tld='com', lang='en', slow=False, lang_check=True, pre_processor_funcs=[<function tone_marks>, <function end_of_line>, <function abbreviations>, <function word_sub>], tokenizer_func=<bound method Tokenizer.run of re.compile('(?<=\\?).|(?<=!).|(?<=？).|(?<=！).|(?<!\\.[a-z])\\. |(?<!\\.[a-z]), |(?<!\\d):|—|‥|\\)|：|…|。|¿|¡|\\[|、|\\\n|，|،|;|\\]|\\(', re.IGNORECASE) from: [<function tone_marks>, <function period_comma>, <function colon>, <function other_punctuation>]>, timeout=None)[source]

gTTS – Google Text-to-Speech.

An interface to Google Translate’s Text-to-Speech API.

Parameters:

• text (string) – The text to be read.

• tld (string) – Top-level domain for the Google Translate host,i.e https://translate.google.<tld>. Different Google domainscan produce different localized ‘accents’ for a givenlanguage. This is also useful when google.com might be blockedwithin a network but a local or different Google host(e.g. google.com.hk) is not. Default is com.

• lang (string, optional) – The language (IETF language tag) toread the text in. Default is en.

• slow (bool, optional) – Reads text more slowly. Defaults to False.

• lang_check (bool, optional) – Strictly enforce an existing lang,to catch a language error early. If set to True,a ValueError is raised if lang doesn’t exist.Setting lang_check to False skips Web requests(to validate language) and therefore speeds up instantiation.Default is True.

• pre_processor_funcs (list) –

  A list of zero or more functions that arecalled to transform (pre-process) text before tokenizing. Thosefunctions must take a string and return a string. Defaults to:

  [ pre_processors.tone_marks, pre_processors.end_of_line, pre_processors.abbreviations, pre_processors.word_sub]

• tokenizer_func (callable) –

  A function that takes in a string andreturns a list of string (tokens). Defaults to:

  See Also

  Text-to-Speech AI: Lifelike Speech Synthesis | Google CloudErste Schritte mit Google Text-to-Speech mit PythonPre-processing and tokenizing — gTTS documentationText to Speech in Python [With Code Examples] - Codefather

  Tokenizer([ tokenizer_cases.tone_marks, tokenizer_cases.period_comma, tokenizer_cases.colon, tokenizer_cases.other_punctuation]).run

• timeout (float or tuple, optional) – Seconds to wait for the server tosend data before giving up, as a float, or a (connect timeout,read timeout) tuple. None will wait forever (default).

See also

Pre-processing and tokenizing

Raises:

• AssertionError – When text is None or empty; when there’s nothing left to speak after pre-processing, tokenizing and cleaning.

• ValueError – When lang_check is True and lang is not supported.

• RuntimeError – When lang_check is True but there’s an error loading the languages dictionary.

get_bodies()[source]

Get TTS API request bodies(s) that would be sent to the TTS API.

Returns:

A list of TTS API request bodies to make.

Return type:

list

save(savefile)[source]

Do the TTS API request and write result to file.

Parameters:

savefile (string) – The path and file name to save the mp3 to.

Raises:

gTTSError – When there’s an error with the API request.

stream()[source]

Do the TTS API request(s) and stream bytes

Raises:

gTTSError – When there’s an error with the API request.

write_to_fp(fp)[source]

Do the TTS API request(s) and write bytes to a file-like object.

Parameters:

fp (file object) – Any file-like object to write the mp3 to.

Raises:

• gTTSError – When there’s an error with the API request.

• TypeError – When fp is not a file-like object that takes bytes.

exception gtts.tts.gTTSError(msg=None, **kwargs)[source]

Exception that uses context to present a meaningful error message

infer_msg(tts, rsp=None)[source]

Attempt to guess what went wrong by using knowninformation (e.g. http response) and observed behaviour

Languages (gtts.lang)

gtts.lang.tts_langs()[source]

Languages Google Text-to-Speech supports.

Returns:

A dictionary of the type { ‘<lang>’: ‘<name>’}

Where <lang> is an IETF language tag such as en or zh-TW,and <name> is the full English name of the language, such asEnglish or Chinese (Mandarin/Taiwan).

Return type:

dict

The dictionary returned combines languages from two origins:

• Languages fetched from Google Translate (pre-generated in gtts.langs)

• Languages that are undocumented variations that were observed to work andpresent different dialects or accents.

Localized ‘accents’

For a given language, Google Translate text-to-speech can speak in differentlocal ‘accents’ depending on the Google domain (google.<tld>) of the request,with some examples shown in the table below.

Examples

Write ‘hello’ in English to hello.mp3:

>>> from gtts import gTTS>>> tts = gTTS('hello', lang='en')>>> tts.save('hello.mp3')

Write ‘hello’ in Australian English to hello.mp3:

>>> from gtts import gTTS>>> tts = gTTS('hello', lang='en', tld='com.au')>>> tts.save('hello.mp3')

Write ‘hello bonjour’ in English then French to hello_bonjour.mp3:

>>> from gtts import gTTS>>> tts_en = gTTS('hello', lang='en')>>> tts_fr = gTTS('bonjour', lang='fr')>>>>>> with open('hello_bonjour.mp3', 'wb') as f:...  tts_en.write_to_fp(f)...  tts_fr.write_to_fp(f)

Playing sound directly

There’s quite a few libraries that do this. Write ‘hello’ to a file-like objectto do further manipulation::

>>> from gtts import gTTS>>> from io import BytesIO>>>>>> mp3_fp = BytesIO()>>> tts = gTTS('hello', lang='en')>>> tts.write_to_fp(mp3_fp)>>>>>> # Load `mp3_fp` as an mp3 file in>>> # the audio library of your choice

Logging

gtts does logging using the standard Python logging module. The following loggers are available:

gtts.tts

Logger used for the gTTS class

gtts.lang

Logger used for the lang module (language fetching)

gtts

Upstream logger for all of the above