pycotovia

Pure-Python G2P (grapheme-to-phoneme) phonemizer for Galician and Spanish, based on the Cotovia TTS system.

Features

• Two languages: Galician (gl) and Spanish (es) with language-specific exception lists and rewrite rules.
• One tiny dependency: pure Python, no C extensions, no heavy ML models — scriptconv is the only requirement.
• Fast enough: single-word latency is well under 1 ms on modern hardware.
• Measured against the original: every mode is scored against the Cotovia C binary on a 5000-sentence Galician corpus. The numbers and the gaps are in docs/parity.md.
• Two oracles: the default reproduces the reference build (upstream plus two adjudicated bug fixes); keep_bugs=True reproduces the stock upstream binary byte for byte. See docs/oracles.md.
• Multi-alphabet output: native Cotovía notation, IPA, X-SAMPA, ARPABET, Lexique, Kirshenbaum, or RFE, picked with one argument.

Installation

pip install pycotovia

Requires Python >= 3.11.

Quick start

import pycotovia

# Galician (default)
print(pycotovia.phonemize("Ola, como estás?"))      # → "ola komo estajs"
print(pycotovia.phonemize("guerra", lang="gl"))      # → "gerra"

# Spanish
print(pycotovia.phonemize("México", lang="es"))      # → "meksiko"
print(pycotovia.phonemize("México", lang="gl"))      # → "meSiko"

# IPA mapping
print(pycotovia.cotovia_to_ipa("gerra"))              # → "ɣɛra"

Output alphabets

pycotovia's native output is Cotovía notation — the phoneme symbols of the original Cotovía TTS engine. The alphabet argument converts that native output to any alphabet supported by scriptconv:

import pycotovia

print(pycotovia.ALPHABETS)
# ('cotovia', 'ipa', 'arpa', 'x-sampa', 'lexique', 'kirshenbaum', 'rfe')

print(pycotovia.phonemize("guerra", lang="gl"))                        # → "gerra "  (native, default)
print(pycotovia.phonemize("guerra", lang="gl", alphabet="ipa"))        # → "ɡera "
print(pycotovia.phonemize("cantar", lang="gl", alphabet="x-sampa"))    # → "kanta4 "

The default stays the native Cotovía notation, so existing calls are unaffected. Conversion only applies at tra=1 (phonemes only) — the stress and syllable markers available at higher tra levels have no equivalent in the other notations.

A symbol with no equivalent in the target alphabet raises UnmappedSymbolError rather than being dropped or mistranslated. An unknown alphabet name raises AlphabetError, listing the accepted values.

CLI

# Galician
echo "Ola mundo" | pycotovia

# Spanish
echo "Hola mundo" | pycotovia -l es

# IPA output
echo "Ola mundo" | pycotovia -a ipa

# From file
cat words.txt | pycotovia -l gl > phonemes.txt

Differences from the Cotovia binary

On 5000 Galician Wikipedia sentences, pycotovia reproduces 96.7% of the reference build's words at tra=1 and 85.1% at tra=4. It is not a drop-in replacement for the binary. docs/parity.md gives the number for every mode, a module-by-module feature matrix, and the cause of each remaining gap.

Documentation

• docs/architecture.md: pipeline overview and module map
• docs/parity.md: verification against the Cotovia binary
• docs/oracles.md: the two reference builds and the case for each bug fix
• docs/api.md: public API reference

Examples

See the examples/ directory for:

• basic_usage.py: single words, phrases, IPA output
• spanish_usage.py: Spanish-specific examples
• phrase_processing.py: batch processing from a file

How this port was made, and its licence (please read)

This is an AI-assisted, human-guided, test-driven port. An AI assistant read the public Cotovia C++ source and reimplemented the G2P subsystem (transcription rules, syllabification, stress assignment, exception lists) in Python. A human guided the effort and validated results against the original Cotovia binary. The human collaborators never read the Cotovia C++ source themselves: they drove and checked the work through the binary.

Because the implementing AI read the GPL source, this is not a clean-room reimplementation and we make no such claim. It is a source-derived port. Cotovia is GPL-licensed, so to honour the original work this project is licensed GPL-3.0-or-later (see LICENSE).

Open questions we want to be transparent about (not legal advice):

• Was this clean-room? No: the implementing agent read the GPL source.
• Could it be relicensed permissively? Almost certainly not. A port derived from GPL source is a derivative work, so we keep GPL.
• Can an AI originate or "assign" a licence? Unsettled: authorship/copyright of AI-generated code is legally unclear. We apply GPL-3.0 as the conservative, upstream-respecting default rather than asserting any novel rights.

Acknowledgements

The Cotovia G2P rules, syllabification, stress assignment and exception lists this port derives from are the work of the Multimedia Technologies Group, University of Vigo and the Centro Ramón Piñeiro para a Investigación en Humanidades. This credit does not imply their endorsement.