API Reference

Toplevel API

phonemizer.phonemize(text, language: str = 'en-us', backend: Literal['espeak', 'espeak-mbrola', 'festival', 'segments']='espeak', separator: Separator | None = <phonemizer.separator.Separator object>, strip: bool = False, prepend_text: bool = False, preserve_empty_lines: bool = False, preserve_punctuation: bool = False, punctuation_marks: str | Pattern = ';:, .!?¡¿—…"«»“”(){}[]', with_stress: bool = False, tie: bool | str = False, language_switch: Literal['keep-flags', 'remove-flags', 'remove-utterance']='keep-flags', words_mismatch: Literal['warn', 'ignore', 'remove']='ignore', njobs: int = 1, logger: Logger | None = None)

Multilingual text to phonemes converter

Return a phonemized version of an input text, given its language and a phonemization backend.

Note

To improve the processing speed it is better to minimize the calls to this function: providing the input text as a list and calling phonemize() a single time is more efficient than calling it on each element of the list. The phonemization backend is cached between calls with the same parameters, but each call still has a cost, and the njobs option can only parallelize the lines of a single call.

Do this:

>>> text = [line1, line2, ...]
>>> phonemize(text, ...)

Not this:

>>> for line in text:
>>>     phonemize(line, ...)

Parameters:

text (str or list of str) – The text to be phonemized. Any empty line will be ignored. If text is an str, it can be multiline (lines being separated by \n). If text is a list, each element is considered as a separated line. Each line is considered as a text utterance.
language (str) – The language code of the input text, must be supported by the backend. If backend is ‘segments’, the language can be a file with a grapheme to phoneme mapping.
backend (str, optional) – The software backend to use for phonemization, must be ‘festival’ (US English only is supported, coded ‘en-us’), ‘espeak’, ‘espeak-mbrola’ or ‘segments’.
separator (Separator) –
string separators between phonemes, syllables and words, default to separator.default_separator. Syllable separator is considered only for the festival backend. Word separator is ignored by the ‘espeak-mbrola’ backend. Initialize it as follows:
```
>>> from phonemizer.separator import Separator
>>> separator = Separator(phone='-', word=' ')
```
strip (bool, optional) – If True, don’t output the last word and phone separators of a token, default to False.
prepend_text (bool, optional) – When True, returns a pair (input utterance, phonemized utterance) for each line of the input text. When False, returns only the phonemized utterances. Default to False
preserve_empty_lines (bool, optional) – When True, will keep the empty lines in the phonemized output. Default to False and remove all empty lines.
preserve_punctuation (bool, optional) – When True, will keep the punctuation in the phonemized output. Not supported by the ‘espeak-mbrola’ backend. Default to False and remove all the punctuation. The words around quotes and brackets are pronounced together, as without punctuation, whereas the other marks end an utterance.
punctuation_marks (str or re.Pattern, optional) – The punctuation marks to consider when dealing with punctuation, either for removal or preservation. Can be defined as a string or regular expression. Default to Punctuation.default_marks().
with_stress (bool, optional) – This option is only valid for the ‘espeak’ backend. When True the stresses on phonemes are present (stresses characters are ˈ’ˌ). When False stresses are removed. Default to False.
tie (bool or char, optional) – This option is only valid for the ‘espeak’ backend with espeak>=1.49. It is incompatible with phone separator. When not False, use a tie character within multi-letter phoneme names. When True, the char ‘U+361’ is used (as in d͡ʒ), ‘z’ means ZWJ character, default to False.
language_switch (str, optional) – Espeak can output some words in another language (typically English) when phonemizing a text. This option setups the policy to use when such a language switch occurs. Three values are available : ‘keep-flags’ (the default), ‘remove-flags’ or ‘remove-utterance’. The ‘keep-flags’ policy keeps the language switching flags, for example “(en) or (jp)”, in the output. The ‘remove-flags’ policy removes them and the ‘remove-utterance’ policy removes the whole line of text including a language switch. This option is only valid for the ‘espeak’ backend.
words_mismatch (str, optional) – Espeak can join two consecutive words or drop some words, yielding a word count mismatch between orthographic and phonemized text. This option setups the policy to use when such a words count mismatch occurs. Three values are available: ‘ignore’ (the default) which do nothing, ‘warn’ which issue a warning for each mismatched line, and ‘remove’ which remove the mismatched lines from the output.
njobs (int) – The number of parallel jobs to launch. The input text is split in njobs parts, phonemized on parallel instances of the backend and the outputs are finally collapsed.
logger (logging.Logger) – the logging instance where to send messages. If not specified, use the ‘phonemizer’ logger, whose messages are handled by the logging configuration of the application.

Returns:

phonemized text – The input text phonemized for the given language and backend. The returned value has the same type of the input text (either a list or a string), excepted if prepend_text is True where the output is forced as a list of pairs (input_text, phonemized text).

Return type:

str or list of str

Raises:

RuntimeError – if the backend is not valid or is valid but not installed, if the language is not supported by the backend, if any incompatible options are used.

phonemizer.phonemize.clear_backends_cache()

Free the backend instances cached by phonemize()

Called for its side effect only. The cache is repopulated on the next call to phonemize(). The backends cached by other threads are freed on their next call to phonemize().

class phonemizer.separator.Separator(word: str = ' ', syllable: str | None = None, phone: str | None = None)

Defines phone, syllable and word boundary tokens

input_output_separator(field_separator: str | bool) → str | bool

Returns a suitable input/output separator based on token separator

The input/output separator split orthographic and phonetic texts when using the –prepend-text option from command-line.

Parameters:: field_separator (bool or str) – If str, ensures it’s value is not already defined as a token separator. If True choose one of “|”, “||”, “|||”, “||||” (the first one that is not defined as a token separator)
Return type:: The input/output separator, or False if field_separator is False
Raises:: RuntimeError – if field_separator is a str but is already registered as token separator

property phone: Phones separator

property syllable: Syllables separator

property word: Words separator

class phonemizer.punctuation.Punctuation(marks: str | Pattern = ';:,.!?¡¿—…"«»“”(){}[]')

Preserve or remove the punctuation during phonemization

Backends behave differently with punctuation: festival and espeak ignore it and remove it silently whereas segments will raise an error. The Punctuation class solves that issue by “hiding” the punctuation to the phonemization backend and restoring it afterwards.

Parameters:: re.Pattern) (marks (str or) – (either removal or preservation). If a string, each mark must be made of a single character. Default to Punctuation.default_marks().

static can_align(sep: Separator) → bool

Returns True if the inline marks can be placed in context with sep

The marks are placed by counting the phonemized words, split on the word separator. It must not be empty nor found in the other separators.

static default_marks(): Returns the default punctuation marks as a string

inline_groups(lines: List[List[str | int]]) → List[List[int]]

Returns the chunks separated by inline marks only

lines is as returned by preserve(). Each group lists the indices of consecutive chunks of a line separated by inline marks (quotes or brackets, see is_inline()). The backends phonemize such a group as a whole as well, so that its words are pronounced in context, see restore().

static is_inline(mark: str) → bool

Returns True if mark does not break the utterance

Quotes and brackets are inline marks: the words on both sides of them are pronounced together. The other marks, such as commas or periods, end an utterance, as do the marks not known to be inline.

property marks: The punctuation marks as a string

preserve(text: List[str] | str) → Tuple[List[str], List[List[str | int]]]

Removes punctuation from text, allowing for further restoration

Returns the chunks of text between the punctuation marks, to be phonemized, and, for each line of text, its parts in order: the index of a chunk in chunks or a punctuation mark:

[‘hello, my world!’, ‘ok’] -> [‘hello’, ‘my world’, ‘ok’],
[[0, ‘, ‘, 1, ‘!’], [2]]

remove(text: str | List[str]) → str | List[str]

Returns the text with all punctuation marks replaced by spaces

The input text can be a string or a list and is returned with the same type and punctuation removed.

classmethod restore(text: str | List[str], lines: List[List[str | int]], sep: Separator, strip: bool, context: List[Tuple[List[int], str]] | None = None) → List[str]

Restore punctuation in a text.

This is the reverse operation of Punctuation.preserve(). It takes the phonemized chunks and the parts of each line, as well as the separator and strip parameters used by phonemize. It returns the punctuated text as a list:

[‘hello’, ‘my world’, ‘ok’], [[0, ‘, ‘, 1, ‘!’], [2]]
-> [‘hello, my world!’, ‘ok’]

The internal spaces of the marks are replaced by the word separator. context optionally gives, for groups of chunks as returned by inline_groups(), the group phonemized as a whole. It is used in place of the chunks phonemized alone when the inline marks can be placed in it for sure.

Backends

class phonemizer.backend.base.BaseBackend(language: str, punctuation_marks: str | Pattern | None = None, preserve_punctuation: bool = False, logger: Logger | None = None)

Abstract base class of all the phonemization backends

Provides a common interface to all backends. The central method is phonemize()

Parameters:

language (str) – The language code of the input text, must be supported by the backend. If backend is ‘segments’, the language can be a file with a grapheme to phoneme mapping.
preserve_punctuation (bool) – When True, will keep the punctuation in the phonemized output. Not supported by the ‘espeak-mbrola’ backend. Default to False and remove all the punctuation.
punctuation_marks (str) – The punctuation marks to consider when dealing with punctuation, either for removal or preservation. Can be defined as a string or regular expression. Default to Punctuation.default_marks().
logger (logging.Logger) – the logging instance where to send messages. If not specified, use the default system logger.

Raises:

RuntimeError – if the backend is not available of if the language cannot be initialized.

abstractmethod classmethod is_available(): Returns True if the backend is installed, False otherwise

classmethod is_supported_language(language: str)

Returns True if language is supported by the backend

Language codes are case insensitive: ‘en-US’ is supported as ‘en-us’.

property language: The language code configured to be used for phonemization

property logger: A logging.Logger instance where to send messages

abstractmethod static name(): The name of the backend

phonemize(text: List[str], separator: Separator | None = None, strip: bool = False, njobs: int = 1) → List[str]

Returns the text phonemized for the given language

Parameters:

text (list of str) – The text to be phonemized. Each string in the list is considered as a separated line. Each line is considered as a text utterance. Any empty utterance will be ignored.
separator (Separator) – string separators between phonemes, syllables and words, default to separator.default_separator. Syllable separator is considered only for the festival backend. Word separator is ignored by the ‘espeak-mbrola’ backend.
strip (bool) – If True, don’t output the last word and phone separators of a token, default to False.
njobs (int) – The number of parallel jobs to launch. The input text is split in njobs parts, phonemized on parallel instances of the backend and the outputs are finally collapsed.

Returns:

phonemized text – The input text phonemized for the given language and backend.

Return type:

list of str

Raises:

RuntimeError – if something went wrong during the phonemization

abstractmethod static supported_languages() → Dict[str, str]: Return a dict of language codes -> name supported by the backend

abstractmethod classmethod version(): Return the backend version as a tuple (major, minor, patch)

class phonemizer.backend.espeak.espeak.EspeakBackend(language: str, punctuation_marks: str | Pattern | None = None, preserve_punctuation: bool = False, with_stress: bool = False, tie: bool | str = False, language_switch: Literal['keep-flags', 'remove-flags', 'remove-utterance'] = 'keep-flags', words_mismatch: Literal['warn', 'ignore', 'remove'] = 'ignore', logger: Logger | None = None)

Espeak backend for the phonemizer

static name(): The name of the backend

classmethod supported_languages(): Return a dict of language codes -> name supported by the backend

class phonemizer.backend.espeak.mbrola.EspeakMbrolaBackend(language: str, logger: Logger | None = None)

Espeak-mbrola backend for the phonemizer

static name(): The name of the backend

classmethod supported_languages() → Dict[str, str]: Returns the list of installed mbrola voices

class phonemizer.backend.segments.SegmentsBackend(language: str, punctuation_marks: str | Pattern | None = None, preserve_punctuation: bool = False, logger: Logger | None = None)

Segments backends for the phonemizer

The phonemize method will raise a ValueError when parsing an unknown morpheme.

classmethod is_available(): Returns True if the backend is installed, False otherwise

classmethod is_supported_language(language: str) → bool

Returns True if language is supported by the backend

Language codes are case insensitive: ‘en-US’ is supported as ‘en-us’.

static name(): The name of the backend

static supported_languages()

Returns a dict of language: file supported by the segments backend

The supported languages have a grapheme to phoneme conversion file bundled with phonemizer. Users can also use their own file as parameter of the phonemize() function.

classmethod version(): Return the backend version as a tuple (major, minor, patch)

class phonemizer.backend.festival.festival.FestivalBackend(language: str, punctuation_marks: str | Pattern | None = None, preserve_punctuation: bool = False, logger: Logger | None = None)

Festival backend for the phonemizer

classmethod executable() → Path

Returns the absolute path to the festival executable used as backend

The following precedence rule applies for executable lookup:

As specified by FestivalBackend.set_executable()
Or as specified by the environment variable PHONEMIZER_FESTIVAL_EXECUTABLE
Or the default ‘festival’ binary found on the system with shutil.which('festival')

Raises:: RuntimeError – if the festival executable cannot be found or if the environment variable PHONEMIZER_FESTIVAL_EXECUTABLE is set to a non-executable file

classmethod is_available(): True if the festival executable is available, False otherwise

static name(): The name of the backend

classmethod set_executable(executable: str)

Sets the festival backend to use executable

If this is not set, the backend uses the default festival executable from the system installation.

Parameters:: (str) (executable) – backend. Set executable to None to restore the default.
Raises:: RuntimeError if executable is not an executable file. –

static supported_languages() → Dict[str, str]

A dictionnary of language codes -> name supported by festival

Actually only en-us (American English) is supported.

classmethod version()

Festival version as a tupe of integers (major, minor, patch)

Raises:: RuntimeError if FestivalBackend.is_available() is False or if the – version cannot be extracted for some reason.

Espeak library

class phonemizer.backend.espeak.wrapper.EspeakWrapper

Wrapper on espeak shared library

The aim of this wrapper is not to be exhaustive but to encapsulate the espeak functions required for phonemization. It relies on a espeak shared library (*.so on Linux, *.dylib on Mac and *.dll on Windows) that must be installed on the system.

Use the function EspeakWrapper.set_library() before instanciation to customize the library to use.

Raises:: RuntimeError if the espeak shared library cannot be loaded –

property data_path

The espeak data directory as a pathlib.Path instance

The following precedence rule applies for data path lookup:

As specified by EspeakWrapper.set_data_path()
Or as specified by the environment variable PHONEMIZER_ESPEAK_DATA_PATH
Or the data directory of the espeak library in use

Raises:: RuntimeError if the specified data path is not a readable directory –

classmethod library()

Returns the espeak library used as backend

The following precedence rule applies for library lookup:

As specified by BaseEspeakBackend.set_library()
Or as specified by the environment variable PHONEMIZER_ESPEAK_LIBRARY
Or the default espeak library found on the system

Raises:: RuntimeError if the espeak library cannot be found or if the – environment variable PHONEMIZER_ESPEAK_LIBRARY is set to a non-readable file

property library_path: The espeak library as a pathlib.Path instance

classmethod set_data_path(data_path: str)

Sets the path for the data to be used by the espeak backend.

If this is not set, the backend uses the default data path from the system installation.

Parameters:: data_path (str) – The path to the data to be used by the espeak backend. Set data_path to None to restore the default.

classmethod set_library(library: str)

Sets the espeak backend to use library

If this is not set, the backend uses the default espeak shared library from the system installation.

Parameters:: None) (library (str or) – backend. Set library to None to restore the default.

property version: Tuple[int, int, int]: The espeak version as a tuple of integers (major, minor, patch)

Logging

phonemizer.logger.default_logger() → Logger

Returns the logger used when none is given to the phonemizer

This is the ‘phonemizer’ logger, it is never configured by the phonemizer itself. Its messages propagate to the logging configuration of the application, which can set its level or handlers as usual, for instance logging.getLogger('phonemizer').setLevel(logging.ERROR).

phonemizer.logger.get_logger(verbosity: str = 'quiet', name: str = 'phonemizer') → Logger

Returns a configured logging.Logger instance

The logger is configured to output messages on the standard error stream (stderr). Its messages are not propagated to the logging configuration of the application, so that ‘quiet’ does not display anything. The returned logger is a child of name dedicated to the given verbosity, so that calling this function does not alter the configuration of the logger name itself.

Parameters:

(str) (name) – debug/info and warning messages), ‘normal’ (warnings only) or ‘quiet’ (do not display anything).
(str)

Raises:

RuntimeError if verbosity is not 'normal', 'verbose', or 'quiet'. –