Module (gtts)

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)

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 domains can produce different localized ‘accents’ for a given language. This is also useful when google.com might be blocked within 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) to read 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 are called to transform (pre-process) text before tokenizing. Those functions 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 and returns a list of string (tokens). Defaults to:

  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 to send 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()

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)

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()

Do the TTS API request(s) and stream bytes

Raises:

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

write_to_fp(fp)

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)

Exception that uses context to present a meaningful error message

infer_msg(tts, rsp=None)

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

Languages (gtts.lang)

Note

The easiest way to get a list of available languages is to print them with gtts-cli --all

gtts.lang.tts_langs()

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 as English 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 and present different dialects or accents.

Localized ‘accents’

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

Note

This is an incomplete list. Try different combinations of language codes and known localized Google domains. Feel free to add new combinations to this list via a Pull Request!

Note

The default tld is com which will use the local language accent (according to Google), if available, based on your geographical network location. For example, lang="en" with the default tld will sound British English.

Local accent	Language code (lang)	Top-level domain (tld)
English (Australia)	en	com.au
English (United Kingdom)	en	co.uk
English (United States)	en	us
English (Canada)	en	ca
English (India)	en	co.in
English (Ireland)	en	ie
English (South Africa)	en	co.za
English (Nigeria)	en	com.ng
French (Canada)	fr	ca
French (France)	fr	fr
Mandarin (China Mainland)	zh-CN	any
Mandarin (Taiwan)	zh-TW	any
Portuguese (Brazil)	pt	com.br
Portuguese (Portugal)	pt	pt
Spanish (Mexico)	es	com.mx
Spanish (Spain)	es	es
Spanish (United States)	es	us

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 object to 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

Note

See Issue #26 for a discussion and examples of direct playback using various methods.

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