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>. 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.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_bodies()[source]¶
Get TTS API request bodies(s) that would be sent to the TTS API.
- Returns
A list of TTS API request bodiess to make.
- 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()[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 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 combinaisons of language codes and known localized Google domains. Feel free to add new combinaisons to this list via a Pull Request!
Local accent |
Language code ( |
Top-level domain ( |
---|---|---|
English (Australia) |
|
|
English (United Kingdom) |
|
|
English (United States) |
|
|
English (Canada) |
|
|
English (India) |
|
|
English (Ireland) |
|
|
English (South Africa) |
|
|
French (Canada) |
|
|
French (France) |
|
|
Mandarin (China Mainland) |
|
any |
Mandarin (Taiwan) |
|
any |
Portuguese (Brazil) |
|
|
Portuguese (Portugal) |
|
|
Spanish (Mexico) |
|
|
Spanish (Spain) |
|
|
Spanish (United States) |
|
|
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.