phonemizer

library3.3.0pypypi✓ verified 85d ago

phonemizer is a simple yet powerful Python library that converts text to phonetic representations (phones) for multiple languages. It supports various backends like eSpeak, Festival, and Mbrola. The current version is 3.3.2, and it maintains an active, though somewhat irregular, release cadence, addressing bugs and adding improvements.

ai-ml data

pip install phonemizer

github ↗package ↗homepage ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · PHONEMIZER

phonemizer

ai-mlpythonv3.3.0

Install

4.8s avg

Import

1684ms

Disk

69MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.3.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 1.750s · 69.1MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 4.8s · import 1.617s · 70MB

69MB installed

● package 69MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

phonemize

✓ from phonemizer import phonemize

✗ from phonemizer.phonemize import phonemize

The direct import from `phonemizer` is preferred since v2.2.1, though the old path still works for compatibility.

This quickstart demonstrates phonemizing a list of strings using the 'espeak' backend. It's crucial to have 'espeak' (or another chosen backend like 'festival') installed on your system, as they are external binaries, not Python packages. The language and backend are explicitly set for clarity and to avoid relying on default changes.

from phonemizer import phonemize # Note: This requires the 'espeak' external binary to be installed on your system. # For example, on Ubuntu: sudo apt-get install espeak text = ['Hello world!', 'How are you?'] phones = phonemize( text, language='en-us', backend='espeak', strip=True ) print(phones) # Expected output (may vary slightly based on espeak version): # ['hɛloʊ wɝld', 'haʊ ɑr ju']

phonemizer --version

Debug

Known issues

breakingStarting with v3.3.0, phonemizer requires Python 3.8 or newer. Previous versions supported Python 3.6+.

fix

Ensure your Python environment is 3.8 or newer before installing or upgrading phonemizer.

affects: >=3.3.0

gotchaphonemizer relies on external text-to-speech binaries like eSpeak or Festival. These backends are not installed via pip and must be separately installed on your operating system for phonemizer to function.

fix

Install your desired backend (e.g., `sudo apt-get install espeak` on Debian/Ubuntu, `brew install espeak` on macOS, or follow instructions for Festival/Mbrola) before using phonemizer.

affects: All versions

breakingThe default backend for the `phonemize` function changed from `festival` to `espeak` in v3.0.

fix

Explicitly specify the `backend` argument (e.g., `backend='festival'` or `backend='espeak'`) to ensure consistent behavior, especially if migrating from versions prior to 3.0.

affects: >=3.0

breakingEmpty lines in the input text are no longer automatically removed from the output starting with v3.0. This changes the length and structure of the output list if empty lines were present.

fix

If you rely on empty lines being removed, filter your input list or process the output list accordingly. For example, `[line for line in phonemize(...) if line]`.

affects: >=3.0

breakingThe environment variable `PHONEMIZER_ESPEAK_PATH` was renamed to `PHONEMIZER_ESPEAK_LIBRARY` and the `--espeak-path` command-line option to `--espeak-library` in v3.0.

fix

Update any scripts or system configurations that use the old environment variable or command-line option name to the new `_LIBRARY` suffix.

affects: >=3.0

breakingThe `BaseBackend.phonemize` method (and consequently the `phonemize` function) now raises a `RuntimeError` if a single `str` is passed as input instead of an expected `list` of `str`s. Previously, it would only log an error message.

fix

Always pass a list of strings to `phonemize`, even if it's a single item (e.g., `phonemize(['my text'])` instead of `phonemize('my text')`).

affects: >=3.0.1

Errors

Common errors & fixes

RuntimeError: espeak not installed on your system

The underlying `espeak-ng` command-line tool or its associated library is not found in the system's PATH, or its path is not explicitly configured for the `phonemizer` library. This is a common issue on Windows and macOS where `espeak-ng` is not a default system package.

fix

First, install `espeak-ng` on your operating system (e.g., `sudo apt-get install espeak-ng` on Debian/Ubuntu, `brew install espeak` on macOS). On Windows, use the `.msi` installer. If `espeak-ng` is still not found, especially on Windows or if it's in a non-standard location, explicitly set the path to its library using `PHONEMIZER_ESPEAK_LIBRARY` environment variable or in Python: `from phonemizer.backend.espeak.wrapper import EspeakWrapper; EspeakWrapper.set_library('C:\Program Files\eSpeak NG\libespeak-ng.dll')` (adjust path for your system).

ValueError: No phonemizer found for language [lang_code]

The specified language code is either not supported by the chosen `phonemizer` backend (e.g., `espeak`, `festival`, `segments`), or the necessary external dependency (like `espeak-ng` for most languages) is not properly installed or configured to support that specific language.

fix

Ensure `espeak-ng` is correctly installed and updated on your system, as it supports a wide range of languages. Verify that the language code you are using is accurate and is listed as supported by your selected backend. You can programmatically check supported languages for the eSpeak backend using `from phonemizer.backend.espeak import EspeakBackend; EspeakBackend.supported_languages()`.

ModuleNotFoundError: No module named 'segments'

The `segments` Python package, which is a dependency for the `phonemizer.backend.segments` backend, is not installed in your Python environment.

fix

Install the `segments` Python package using pip: `pip install segments`.

ValueError: Unknown morpheme

This error occurs when the `phonemize` method encounters a word or sub-word unit (morpheme) that its internal rules or dictionaries, specific to the chosen backend and language, cannot convert into a phonetic representation.

fix

Pre-process the input text to handle or remove words that are likely to be unphonemizable (e.g., highly unusual proper nouns, non-standard spellings). For backends that support it, you can configure the behavior for unknown words (e.g., 'ignore', 'warn', or 'remove' mismatched lines) using parameters like `with_words_count_mismatch`. If using the `segments` backend, ensure a comprehensive grapheme-to-phoneme mapping is provided.

Upgrade

Version history

3.3.0latest on PyPI · released Aug 1, 2024

Audit

Dependencies

No dependency data recorded yet.

Agent activity

22 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/bootphon/phonemizer ↗

packagehttps://pypi.org/project/phonemizer/ ↗

homepagehttps://phonemizer.github.io/phonemizer ↗

docshttps://bootphon.github.io/phonemizer/ ↗

changeloghttps://github.com/bootphon/phonemizer/blob/master/docs/source/changelog.rst ↗