Module (gtts)

gTTS (gtts.gTTS)

class gtts.tts.gTTS(text, 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>]>)[source]

gTTS – Google Text-to-Speech.

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

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

  • lang (string, optional) – The language (IETF language tag) to read the text in. Defaults to ‘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. 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
    

Raises
  • AssertionError – When text is None or empty; when there’s nothing left to speak after pre-precessing, 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 dictionnary.

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.

write_to_fp(fp)[source]

Do the TTS API request 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)[source]

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 language is to print them with gtts-cli --all

gtts.lang.tts_langs()[source]

Languages Google Text-to-Speech supports.

Returns

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

Where <lang> is an IETF language tag such as en or pt-br, and <name> is the full English name of the language, such as English or Portuguese (Brazil).

Return type

dict

The dictionnary returned combines languages from two origins:

  • Languages fetched automatically from Google Translate

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

Examples

Write ‘hello’ in English to hello.mp3:

>>> from gtts import gTTS
>>> tts = gTTS('hello', lang='en')
>>> 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(p)

Playing sound directly

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

>>> from gtts import gTTS
>>> from io import BytesIO
>>>
>>> mp3_fp = BytesIO()
>>> tts = gTTS('hello', '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