vocx

vocx transcribes Esperanto text into phonetic Polish for use in professional text-to-speech (TTS) engines.

Background

Commercial TTS engines tend not to support minority languages, particularly constructed languages such as Esperanto. It turns out Esperanto shares lots of sounds with Polish. By transcribing Esperanto to Polish, we can make commercial TTS engines give us a good approximation for spoken Esperanto.

This is a Python port of the original Go library.

Installation

pip install vocx

Usage

Library

from vocx import Transcriber

t = Transcriber()
t.transcribe("Ĉu vi ŝatas Esperanton? Esperanto estas facila lingvo.")
# "czu wij szatas esperanton? esperanto estas fatssila lijngwo."

Custom rules

To override the default rules used during transcription, call load_rules, passing a custom JSON rules document. See src/vocx/default_rules.py for the correct structure.

from vocx import Transcriber

t = Transcriber()
t.load_rules(my_rules_json)

A rules document has four sections:

• letters — single-character substitutions (applied lowercased).
• fragments — ordered regular-expression replacements applied to each word.
• overrides — whole-word replacements (surrounding punctuation is preserved).
• numbers — the words used when transcribing numeric tokens.

Command line

# Transcribe arguments
vocx "Saluton, kiel vi fartas?"
# saluton, kijel wij fartas?

# Transcribe stdin
echo "Saluton" | vocx

# Use a custom rules file
vocx --rules my_rules.json "Saluton"

Development

uv sync
uv run pytest