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>]>)[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>. This is useful when
google.com
might be blocked within a network but a local or different Google host (e.g.google.cn
) is not. Default iscom
.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 toTrue
, aValueError
is raised iflang
doesn’t exist. Settinglang_check
toFalse
skips Web requests (to validate language) and therefore speeds up instanciation. Default isTrue
.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
See also
- Raises
AssertionError – When
text
isNone
or empty; when there’s nothing left to speak after pre-precessing, tokenizing and cleaning.ValueError – When
lang_check
isTrue
andlang
is not supported.RuntimeError – When
lang_check
isTrue
but there’s an error loading the languages dictionary.
-
get_urls
()[source]¶ Get TTS API request URL(s) that would be sent to the TTS API.
- Returns
A list of TTS API request URLs to make.
This is particularly useful to get the list of URLs generated by
gTTS
but not yet fullfilled, for example to be used by an external program.- Return type
list
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
(tld='com')[source]¶ Languages Google Text-to-Speech supports.
- Parameters
tld (string) – Top-level domain for the Google Translate host to fetch languages from. i.e https://translate.google.<tld>. Default is
com
.- Returns
A dictionary 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 dictionary 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(f)
Instead of writing to disk, get URL for ‘hello’ in English:
>>> from gtts import gTTS
>>> tts = gTTS('hello', lang='en')
>>> tts.get_urls()
['https://translate.google.com/translate_tts?ie=UTF-8&q=hello&tl=en&ttsspeed=1&total=1&idx=0&client=tw-ob&textlen=5&tk=316070.156329']
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.
Note
Starting with gTTS
2.1.0, the
gtts.tts.gTTS.get_urls
method can be used to obtain the list of
generated URLs requests (whithout fullfilling them) which could be used
for playback in another program. See Examples above.