Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

tugaphone: dialect-aware Portuguese phonemizer

tugaphone turns Portuguese text into IPA, and it does it per Lusophone dialect. Give it a sentence and a dialect code, get back a phoneme string with stress marks.

O gato dorme.
pt-PT → o ˈɡatu ˈdɔɾmɨ
pt-BR → u ˈɡatu ˈdoɾmi
pt-AO → ʊ ˈɡatʊ ˈdɔʁmɨ
pt-MZ → u ˈɡatu ˈdɔrme
pt-TL → o ˈɡatʊ ˈdɔrme

Every IPA sample in these docs is the output of the orthography2ipa lect specs that tugaphone resolves at run time, so a spec change in orthography2ipa can change a sample.

Under the hood it drives the orthography2ipa candidate lattice: a dialect is an orthography2ipa lect spec, and the spec's grapheme table, allophone rules and cross-word sandhi produce that dialect's phonology directly. tugaphone adds the stages orthography2ipa leaves to the caller: a phonetic lexicon, meaning-based homograph resolution, and gender- and scale-aware number expansion, wired through orthography2ipa's own extension points. See docs/architecture.md.


Install

pip install tugaphone

Its runtime dependencies (orthography2ipa, o2i-lexicons, silabificador, tugalex, bifonia, ovos-number-parser) install automatically. The pt-PT and pt-BR lexicons ride in through o2i-lexicons.


30-second quick start

from tugaphone import TugaPhonemizer

ph = TugaPhonemizer()
print(ph.phonemize_sentence("O gato dorme.", "pt-PT"))
# o ˈɡatu ˈdɔɾmɨ

Construct TugaPhonemizer(), then call phonemize_sentence(text, lang) as often as you like. The first call for a lect builds that lect's engine, so it is slower than the calls after it. The result is a space-separated phoneme string, one token per word, with ˈ marking primary stress. lang selects the orthography2ipa lect spec, so it changes the phonology, not just the spelling.

Digits need no preparation. phonemize_sentence spells them out with gender agreement before it transcribes the sentence:

print(ph.phonemize_sentence("comprei 2 casas", "pt-PT"))
# kõˈpɾej ˈduɐʃ ˈkazɐʃ

Why tugaphone

Most Portuguese G2P you can reach for treats Portuguese as one or two varieties. tugaphone's reason to exist is dialect granularity: one API that spans the whole Lusophone space and, within European Portuguese, a set of sub-regional accents.

Tool Portuguese coverage Notes
espeak-ng pt (European) + pt-br (Brazilian) Small, fast, rule-based, about 100 languages, widely used as a TTS front-end. Two Portuguese varieties only, no African/Asian Lusophone, no sub-regional accents.
phonemizer (bootphon) via espeak-ng A backend wrapper, for Portuguese it delegates to espeak-ng, so the same two varieties. Needs the espeak binary.
Single-variety Portuguese toolkits (e.g. Brazilian-focused phonetic transcribers) one national variety Strong within their variety, not built to cover the full Lusophone range from one interface.
tugaphone every Portuguese-family orthography2ipa lect: five national standards + European, Brazilian, African, Asian and other varieties Pure Python, IPA output with stress, meaning-based homograph resolution, one API across the whole Lusophone space.

What tugaphone buys you over the coarse options:

  • Every Portuguese-family orthography2ipa lect reachable by BCP-47 code, the five national standards (pt-PT, pt-BR, pt-AO, pt-MZ, pt-TL) plus European and Brazilian sub-regional varieties and the African, Asian and other lects.
  • Meaning-based homograph resolution, sede thirst vs headquarters, gosto verb vs noun, via bifonia.
  • Gender- and scale-aware number expansion (long scale for pt-PT, short scale for pt-BR).
  • A phonology-accurate core, each dialect's sounds come from its orthography2ipa lect spec, not from a post-hoc string-edit layer.

Honest trade-offs: tugaphone is Portuguese-only and younger than espeak-ng, which covers far more languages and years of field use. Its accuracy against the per-lect gold is measured openly, see docs/benchmarking.md.


Features

Dialect coverage

The five national standards, plus European, Brazilian, African, Asian and other sub-regional lects. list_dialects() returns the full set:

Code Region
pt-PT European Portuguese, heavy vowel reduction, post-alveolar fricatives, uvular /ʁ/
pt-BR Brazilian Portuguese, fuller vowels, /t d/ palatalisation, l-vocalisation
pt-AO Angolan Portuguese, moderate reduction, alveolar trill, Bantu substrate
pt-MZ Mozambican Portuguese, similar to European with regional variation
pt-TL Timorese Portuguese, conservative pronunciation, Tetum substrate
for code in ["pt-PT", "pt-BR", "pt-AO", "pt-MZ", "pt-TL"]:
    print(code, "→", ph.phonemize_sentence("Choveu muito ontem.", code))
# pt-PT → ʃuˈvew ˈmũjtu ˈõtɐ̃j
# pt-BR → ʃoˈvew ˈmwĩtʊ ˈõtẽj
# pt-AO → ʃoˈvew ˈmũjntʊ ˈõntẽj
# pt-MZ → ʃoˈvew ˈmũjtu ˈõtẽj
# pt-TL → ʃoˈvew ˈmujtʊ ˈõntɐ̃j

The European sub-regional lects (pt-PT-x-porto, -braga, -tras-os-montes, -madeira, -acores, …), the Brazilian ones (pt-BR-x-sp, -rj, -caipira, -bahia, …) and the rest are all reachable the same way. See docs/dialects.md for the full list and the legacy aliases.

Homograph disambiguation

Heterophonic homographs are resolved by meaning via bifonia: sede thirst vs headquarters, forma mould vs shape, gosto noun vs verb. bifonia inserts open/closed-vowel diacritics during the pipeline's normalization stage, before the lattice transcribes the sentence, so the same spelling maps to different pronunciations depending on sentence context.

print(ph.phonemize_sentence("Eu gosto de música."))   # verb → ˈew ˈɡɔʃtu dɨ ˈmuzikɐ
print(ph.phonemize_sentence("Tenho bom gosto."))       # noun → ˈtɛɲu ˈbõ ˈɡoʃtu

Sub-regional accents

Sub-regional accents are lects like any other, select one by its BCP-47 private-use code. Its phonology (betacism, rising diphthongs, palatalization, /u/ fronting, coda-sibilant sandhi, …) is encoded in the orthography2ipa lect spec, so no extra argument is needed:

# Porto: rising diphthongs, betacism (/v/ → [b])
print(ph.phonemize_sentence("O vinho é muito bom.", "pt-PT-x-porto"))
# o ˈbiɲu ˈjɛ ˈmujtu ˈbõ

# Trás-os-Montes: <ch> → [tʃ], betacism
print(ph.phonemize_sentence("A chave.", "pt-PT-x-tras-os-montes"))
# ɐ ˈtʃabɨ

from tugaphone import list_dialects
print(list_dialects())   # every registered lect code

Legacy tugaphone accent codes and the old orthography2ipa keys resolve as aliases (pt-PT-x-azores → pt-PT-x-acores, pt-BR-x-sao-paulo → pt-BR-x-sp, pt-PT-x-trasosmontes → pt-PT-x-tras-os-montes, …). See docs/dialects.md.

Forcing an accent for a TTS

Selecting a lect describes an accent, force_accent forces one into a downstream voice. For a phoneme-input TTS (phoonnx-style) that is the target IPA, for a grapheme-input TTS (a fixed pt-PT voice) it is Portuguese text respelled so the base voice reads it as the target sounds, feed a pt-PT voice binho to force the Northern betacism of vinho.

from tugaphone import force_accent

# phoneme-input TTS: the target accent's IPA
force_accent("o vinho verde", "pt-PT-x-porto", mode="ipa")
# 'o ˈbiɲu ˈbjɛɾdɨ'

# grapheme-input pt-PT TTS: respelled text it will pronounce with the accent
force_accent("o vinho verde", "pt-PT-x-porto", mode="respell", base_lect="pt-PT")
# 'o binho berde'

The respeller is verification-gated (an edit is kept only if it moves the base voice's own reading toward the target), so it never makes a word worse and leaves unspellable contrasts alone. Ad-hoc per-voice tweaks live in a JSON-serialisable AccentOverlay, and examples/12_synthetic_corpus.py generates a parallel (sentence, lect, ipa, respelled_text) training corpus. See docs/accent_forcing.md.

Number normalization

phonemize_sentence spells digits out itself. normalize_numbers exposes that step on its own, for a TTS front-end that needs the text. It applies gender agreement and the long or short scale of the dialect:

from tugaphone.number_utils import normalize_numbers

normalize_numbers("vou comprar 1 casa")   # 'vou comprar uma casa'
normalize_numbers("vou adotar 1 cão")     # 'vou adotar um cão'
normalize_numbers("comprei 2 casas")      # 'comprei duas casas'
normalize_numbers("aprovou 1 lei")        # 'aprovou uma lei'
normalize_numbers("passou 1 dia")         # 'passou um dia'

A form with digits that tugaphone cannot read, such as "COVID-19" or "3D", gives an UnreadFormWarning that names the form and the text, because the phoneme lattice drops its digits.

Text normalization

Written text contains conventions that a phonemizer cannot read as they are: digit ranges, clock times, thousands separators, abbreviations, Roman numerals and acronyms. The tugaphone.text_normalization module rewrites each of them into words before the number rules run.

A dash between two numbers is a range. "1139-1185" reads as "1139 a 1185". A colon between digits is a clock time. "16:00" reads as "16 horas", "9:05" as "9 e 5" and "24:00" as "24 horas".

European number separators are kept. The dot in "92.073" groups thousands and is dropped. The comma in "10,4" is a decimal mark and reads as "10 vírgula 4".

Abbreviations expand in two ways. Common ones such as "vs.", "pág." and "Av." always expand, so "vs." reads as "versus". Honorifics such as "Sr." and "Dr." expand only before a capitalised name, so "Sr. Silva" reads as "Senhor Silva" and a lone "Sr." at the end of a sentence stays as it is.

A Roman numeral after a name or a century reads as an ordinal up to ten and as a cardinal above ten: "Afonso I" reads as "Afonso Primeiro" and "o século XIX" as "o século dezanove". The ordinal takes the gender of the name, so "D. Maria II" reads as "Dona Maria Segunda". A capital in a fixed expression such as "raio X" or "vitamina C" stays a letter. A letter-digit code reads as its letters and a number, so "T2" reads as "tê dois". Acronyms are spelled with Portuguese letter names, so "IA" reads as "i á", while lowercase words such as "ia" are left alone.

The numbers themselves are then spelled out by normalize_numbers in standard European Portuguese, for example "vinte e cinco". The full rule list with examples is in docs/text_normalization.md.

Syllabification and stress

Stress and the dialect's phonology come from the orthography2ipa lect spec. Syllabification comes from the bundled splitter of orthography2ipa, which reads the diphthongs and hiatus of the lect spec. The tugaphone.tokenizer token tree syllabifies with silabificador.

Command line

The package installs a tugaphone command:

tugaphone phonemize "o gato dorme" --lect pt-BR
tugaphone force-accent "o vinho verde" --lect pt-PT-x-porto --mode respell --base pt-PT
tugaphone list

phonemize defaults to --lect pt-PT. force-accent takes --mode ipa or --mode respell, and --overlay reads a JSON AccentOverlay. See docs/accent_forcing.md.

orthography2ipa pipeline

tugaphone.pipeline(lect) returns the orthography2ipa Pipeline that tugaphone runs for a lect: the packaged lexicon, the number expansion and the homograph marks. A program that already drives orthography2ipa.G2P gets tugaphone's output from it:

from orthography2ipa import G2P
import tugaphone

engine = G2P("pt-BR", pipeline=tugaphone.pipeline("pt-BR"))
print(engine.transcribe("o gato dorme"))   # u ˈɡatu ˈdoɾmi

The pipeline covers contact="none", the default. lect must be a code of list_dialects(); resolve a loose tag with resolve_lect first.


Architecture: relationship to orthography2ipa

tugaphone phonemizes by driving the shared o2i candidate lattice. A dialect is an o2i lect spec: phonemize_sentence(text, lang) resolves lang to a lect code and runs orthography2ipa.G2P(lect).transcribe(text). The spec's grapheme table, allophone_rules and cross-word sandhi_rules produce the dialect's phonology, including genuinely cross-word processes like coda-sibilant voicing sandhi, with no string-transform pass after transcription.

tugaphone contributes the stages o2i leaves to the caller, wired through o2i's own extension points, and relies on o2i for syllabification:

Concern Owner
Base phonology, dialect phenomena, sandhi, stress orthography2ipa lect spec
Number / ordinal verbalization tugaphone (number_utils, via Pipeline.expand)
Sense-based homograph marking tugaphone (bifonia, via Pipeline.mark)
pt-PT and pt-BR residual lexicons o2i-lexicons, passed by tugaphone through Pipeline
Syllabification orthography2ipa (the bundled splitter)

Only pt-PT and pt-BR take a lexicon. Each holds the words that the lect's rules get wrong. Every other lect runs on the rules alone.

tugaphone.tokenizer and tugaphone.dialects are a token-tree linguistic feature API (manner, place, voicing, syllable roles, CV skeletons) and the rules-only benchmark baseline, not the phonemization path. Both modules and registry.get_dialect_inventory are deprecated. They emit a DeprecationWarning and go in tugaphone 2.0.0. See docs/architecture.md and docs/tokenizer.md.


Sibling libraries

tugaphone is part of the TigreGotico Portuguese NLP stack:

Library Role
tugalex Phonetic lexicon
silabificador Syllabifier
bifonia Heterophone sense disambiguation
orthography2ipa The candidate lattice and the Portuguese lect specs

Documentation


Development

Set up a checkout with its test extra, then run the suite:

uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python --prerelease=allow -e ".[test]"
.venv/bin/python -m pytest tests

The test extra installs markovonnx. Without it, code-switch detection uses the orthographic fallback. tests/test_examples.py runs every script in examples/, so a broken example fails the suite.

Path Content
tugaphone/lattice_core.py The phonemization pipeline on the orthography2ipa lattice
tugaphone/registry.py Lect codes, legacy aliases, the lects that take a packaged lexicon
tugaphone/text_normalization.py, tugaphone/number_utils.py The expand step of the engine's Pipeline
tugaphone/codeswitch.py, tugaphone/langdetect.py Contact-language detection and nativization
tugaphone/accent.py, tugaphone/__main__.py Accent forcing and the command line
tugaphone/tokenizer.py, tugaphone/dialects.py The token-tree feature API and the rules-only baseline
scripts/ Benchmarks and code-switch model training

scripts/benchmark.py writes benchmarks/results.json and docs/scoreboard.md, so do not edit either by hand. A change that improves the score commits the regenerated baseline with it, and scripts/check_benchmark_regression.py is the CI gate. CI never uses the network: only a maintainer refreshes the gold fixtures, with scripts/benchmark.py --refresh-fixtures. See docs/benchmarking.md.


Acknowledgements

The clock-time, number-separator, abbreviation, and regnal-numeral reading rules in tugaphone/text_normalization.py are ported from tts_eu_pt, a European-Portuguese TTS front-end by Antonio Cruz, released under the Apache License 2.0. The rules were reimplemented in tugaphone's own idiom rather than copied verbatim.

The English loanword lexicon in tugaphone/data/loanwords.json (see docs/codeswitch.md) is likewise ported from tts_eu_pt. The word list is kept as upstream curated it, minus a handful of proper nouns and words that collide with an existing tugalex Portuguese pronunciation; the en-GB IPA upstream generated offline with espeak ships alongside it as reference/test-gold material, tugaphone's own en-US lattice and nativization produce the pronunciation actually spoken.

License

Apache License 2.0. See LICENSE.

Metadata

Release files for tugaphone 1.7.1a6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tugaphone 1.7.1a6
File Size Uploaded Provenance Actions
tugaphone-1.7.1a6.tar.gz 338.2 kB Without provenance Details for tugaphone-1.7.1a6.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tugaphone 1.7.1a6
File Interpreter ABI Platform Actions
tugaphone-1.7.1a6-py3-none-any.whl Python 3 none any Details for tugaphone-1.7.1a6-py3-none-any.whl

Total release size: 613.4 kB

Release files / tugaphone-1.7.1a6.tar.gz

Download URL tugaphone-1.7.1a6.tar.gz
Size 338.2 kB
Tags Source
SHA-256 checksum
How to use checksums
7a0d7fe0a155a9c78348dba022a2f96de071d17e9c80b990642b802fad7cb207
BLAKE2b-256 checksum
How to use checksums
a0066f286e69365eecef0cd47e483a53a206df43febc13c4462f7c179201dd36
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / tugaphone-1.7.1a6-py3-none-any.whl

Download URL tugaphone-1.7.1a6-py3-none-any.whl
Size 275.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
49cdf6163ebc77bc8043f018b2795b9405575a0e938056308dd6402423152796
BLAKE2b-256 checksum
How to use checksums
bc4bbcf3bff08d4145bc04fee29dcaf37fb232a9a0360f36826fc2eeaeb76334
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for tugaphone 1.7.1a6

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page