mbrola#

A Python front-end to MBROLA.

The MBROLA class provides all necessary features to install MBROLA and MBROLA voices, specify the string of phonemes in a desired speech synthesis, their duration, their pitch, and to generate the resulting audio file locally.

References:: Dutoit, T., Pagel, V., Pierret, N., Bataille, F., & Van der Vrecken, O. (1996, October). The MBROLA project: Towards a set of high quality speech synthesizers free of use for non commercial purposes. In Proceeding of Fourth International Conference on Spoken Language Processing. ICSLP’96 (Vol. 3, pp. 1393-1396). IEEE. https://doi.org/10.1109/ICSLP.1996.607874

Functions

`install_mbrola`([path])	Install MBROLA.
`install_voice`([voice, path])	Download and install MBROLA voices from numediart/MBROLA-voices.
`is_wsl`([version])	Evaluate if function is running on Windows Subsystem for Linux (WSL).
`make_pho`(x)	Generate PHO file.
`mbrola_cmd`()	Get MBROLA command for system command line.
`mbrola_path`()	Retrieve (or get default '~/.mbrola') path to MBROLA installation folder, validate, and save in Python environment.
`set_mbrola_path`(path)	Validate, then set MBROLA directory path in Python environment.
`validate_durations`(...)	Validate argument durations.
`validate_mbrola_path`(path)	Validate MBROLA path.
`validate_outer_silences`(outer_silences)	Validate argument outer_silences.
`validate_pitch`(-> list[list[tuple[float, ...)	Validate argument pitch.
`validate_voice`(voice)	Checks that provided voice is available in MBROLA folder.
`wsl_available`()	Check if Windows Subsystem for Linux (WSL is available).

Classes

MBROLA(phon[, durations, pitch, outer_silences])

A class for generating MBROLA sounds.

Exceptions

`MBROLAInstallException`	Unrecoverable error; mirrors exit 1 in the original bash script.
`MissingMBROLAException`	Could not find mbrola file in specified location.
`MissingVoiceException`	Voice not found in voices folder.
`PlatformException`()	Raise error platform is not Linux or Windows Subsystem for Linux.
`VoiceInstallException`	Unrecoverable error; mirrors exit 1 in the original bash script.

exception mbrola.MissingMBROLAException[source]#

Bases: RuntimeError

Could not find mbrola file in specified location.

exception mbrola.MissingVoiceException[source]#

Bases: Exception

Voice not found in voices folder.

Bases: object

A class for generating MBROLA sounds.

An MBROLA class contains the necessary elements to synthesise an audio using MBROLA.
Args:
phon (str | list[str]): list of phonemes. durations (float | list[float], optional): phoneme duration in milliseconds. Defaults to 100. If an integer is provided, all phonemes in phon are assumed to be the same length. If a list is provided, each element in the list indicates the duration of each phoneme. pitch (float | list[float] | list[float | list[float | tuple[float, float]]]): pitch in Hertz (Hz). If an integer is provided, the pitch contour of each phoneme is assumed to be constant within and across phonemes (e.g., all phonemes will have a pitch of 200 Hz). If a list is provided, each element provides the pitch specification of the piecewise linear pitch curve of each phoneme. This list should have same length as phon. Each element in this list should be a list of an arbitrary number of tuples. Each tuple indicates the time (in percentage of the audio) at which the pitch should be modified, and the pitch value (in Hertz) that should be set. outer_silences (tuple[float, float], optional): duration in milliseconds of the silence interval to be inserted at onset and offset. Defaults to (1, 1).

Attributes:
phon (list[str]): list of phonemes. durations (list[float] | float, optional): phoneme duration in milliseconds. Defaults to 100. If an integer is provided, all phonemes in phon are assumed to be the same length. If a list is provided, each element in the list indicates the duration of each phoneme. pitch (float | list[float] | list[tuple[float, float]]): pitch in Hertz (Hz). If an integer is provided, the pitch contour of each phoneme is assumed to be constant within and across phonemes (e.g., all phonemes will have a pitch of 200 Hz). If a list is provided, each element provides the pitch specification of the piecewise linear pitch curve of each phoneme. This list should have same length as phon. Each element in this list should be a list of an arbitrary number of tuples. Each tuple indicates the time (in percentage of the audio) at which the pitch should be modified, and the pitch value (in Hertz) that should be set. outer_silences (tuple[float, float], optional): duration in milliseconds of the silence interval to be inserted at onset and offset. Defaults to (1.0, 1.0).

Examples:
>>> house = MBROLA(
        phon = ["h", "a", "U", "s"],
        durations = 100,
        pitch = 200
    )

Initiate MBROLA instance.

copy()[source]#

Make deep copy of MBROLA instance.

Returns:

MBROLA: Deep copy of original MBROLA instance.

Examples:

>>> house = MBROLA(phon = ["h", "a", "U", "s"])
>>> house_1 = house.copy()
>>> house == house_1
True
>>> house is house_1
False

export_pho(file: str | Path) → None[source]#

Save PHO file.

Args:

file (str): Path of the output PHO file.

Examples:

>>> house = MBROLA(phon = ["h", "a", "U", "s"])
>>> house.export_pho("sample.pho")

make_sound(file: str | Path, voice: str = 'it4', f0_ratio: float = 1.0, dur_ratio: float = 1.0, remove_pho: bool = True) → None[source]#

Generate MBROLA sound WAV file.

Args:

file (str): Path to the output WAV file. voice (str, optional): MBROLA voice to use. Defaults to “it4”. Note phoneme symbols may be specific to voices. f0_ratio (float, optional): Constant to multiply the fundamental frequency of the whole sound by. Defaults to 1.0 (same fundamental frequency). dur_ratio (float, optional): Constant to multiply the duration of the whole sound by. Defaults to 1.0 (same duration). remove_pho (bool, optional): Should the intermediate PHO file be deleted after the sound is created? Defaults to True.

Examples:

>>> house = MBROLA(phon = ["h", "a", "U", "s"])
>>> house.make_sound("sound.wav", voice="en1")
>>> house.make_sound("sound.wav", f0_ratio=0.5, voice="en1") # reduce F0 to half the original Hz.
>>> house.make_sound("sound.wav", dur_ratio=2.0, voice="en1") # make audio double as fast
>>> house.make_sound("sound.wav", remove_pho=False, voice="en1") # keep pho file in same directory

mbrola.make_pho(x: MBROLA) → list[str][source]#

Generate PHO file.

A PHO (.pho) file contains the phonological information of the speech sound in a format that MBROLA can read. See more examples in the MBROLA documentation (numediart/MBROLA).

Arguments:: x (MBROLA): MBROLA object to make a PHO file for.
Returns:: list[str]: Lines in the PHO file.

mbrola.validate_voice(voice: str) → str[source]#

Checks that provided voice is available in MBROLA folder.

Check available voices here numediart/MBROLA-voices, and isntall them using install_voices().

Args:: voice (str): Voice to check.
Raises:: MissingVoiceException: If provided voice is not available.
Returns:: str: Path to validated voice.

mbrola.validate_durations(durations: float | int | list[float | int], phon: list[str]) → list[float][source]#

mbrola.validate_durations(durations: float | int, phon: str | list[str]) → list[float]

mbrola.validate_durations(durations: list, phon: str | list[str]) → list[float]

Validate argument durations.

Args:: durations (float | list[float], optional): phoneme duration in milliseconds. Defaults to 100. phon (list[str]): string or list of phonemes.
Raises:: ValueError: if length of durations is different than length of phon. TypeError: if durations is not a float or a list of floats.
Returns:: list[float]: Phoneme durations.

mbrola.validate_pitch(pitch: float | int, phon: list[str]) → list[list[tuple[float, float]]]

mbrola.validate_pitch(pitch: list, phon: list[str]) → list[list[tuple[float, float]]]

Validate argument pitch.

Args:: pitch (float | list[float] | list[float | list[float | tuple[float, float]]]): pitch in Hertz (Hz). If an integer is provided, the pitch contour of each phoneme is assumed to be constant within and across phonemes (e.g., all phonemes will have a pitch of 200 Hz). If a list is provided, each element provides the pitch specification of the piecewise linear pitch curve of each phoneme. This list should have same length as phon. Each element in this list should be a list of an arbitrary number of tuples. Each tuple indicates the time (in percentage of the audio) at which the pitch should be modified, and the pitch value (in Hertz) that should be set. phon (str | list[str]): string or list of phonemes.
Raises:: ValueError: if pitch is a list of different length as phon. TypeError: pitch is not an float or a list[tuple[float, float]]”
Returns:: float | list[float] | list[float | list[float | tuple[float, float]]]: validated pitch.

mbrola.validate_outer_silences(outer_silences: tuple[float | int, float | int]) → tuple[float | int, float | int][source]#

Validate argument outer_silences.

Args:: outer_silences (tuple[float, float]): duration in milliseconds of the silence intervals to be inserted at onset and offset. Defaults to (1, 1).
Raises:: TypeError: if outer_silences is not a tuple of float of length 2.
Returns:: tuple[float, float]: validated outer silences.

mbrola.mbrola_path() → Path[source]#

Retrieve (or get default ‘~/.mbrola’) path to MBROLA installation folder, validate, and save in Python environment.

Returns:: Path: PAth to MBROLA installation folder.

mbrola.validate_mbrola_path(path: Path) → Path[source]#

Validate MBROLA path.

Args:: path (Path): Path to MBROLA installation.
Raises:: MissingMBROLAException: If path does not exists, if path is not a directory, or if path does not contain a MBROLA file in ‘Bin/’.
Returns:: Path: Validated path.

mbrola.set_mbrola_path(path: Path | str) → None[source]#

Validate, then set MBROLA directory path in Python environment.

Args:: path: Path to MBROLA installation.

mbrola.mbrola_cmd() → str[source]#

Get MBROLA command for system command line.

Returns:: str: Validated path to MBROLA file.

mbrola.is_wsl(version: str = '6.17.0-1022-azure') → bool[source]#

Evaluate if function is running on Windows Subsystem for Linux (WSL).

Returns:: bool: returns True if Python is running in WSL, otherwise False.

mbrola.install_voice(voice: str | list[str] | None = None, path: Path | None = None) → bool[source]#

Download and install MBROLA voices from numediart/MBROLA-voices.

voice (str | list[str] | None, optional): Voice names to install, e.g. [“es1”, “de1”]. If None (default) or empty, installs every voice. path (Path | None, optional): Destination folder for MBROLA voices. Defaults to ~/.mbrola/voices.

Returns:

bool: True if voices were installed, False if the user declined to replace an existing destination directory.

Examples:

>>> install_voices("it4") # installs single voice
>>> install_voices(["it4", "us1"]) # installs selected voices
>>> install_voices() # installs all available voices
>>> install_voices(path = Path("sounds")) # installs voices in folder "sounds"

mbrola.install_mbrola(path: Path | str | None = None) → None[source]#

Install MBROLA.

This function downloads and compiles MBROLA from numediart/MBROLA.

Args:: path (Path | str | None, optional): Desintatino path of MBROLA installation folder. Defaults to ~/.mbrola/.
Raises:: MBROLAInstallException: If MBROLA repository cannot be reached, if download fails, or if compilation fails.

exception mbrola.PlatformException[source]#

Bases: Exception

Raise error platform is not Linux or Windows Subsystem for Linux.

Args:: Exception (Exception): A super class Exception.

__init__()[source]#

exception mbrola.VoiceInstallException[source]#

Bases: RuntimeError

Unrecoverable error; mirrors exit 1 in the original bash script.

exception mbrola.MBROLAInstallException[source]#

Bases: RuntimeError

Unrecoverable error; mirrors exit 1 in the original bash script.