Phonebox

Train grapheme-to-phoneme (G2P) models, generate pronunciations, and review pronunciation lexicons through a shared Python API and command-line interface. Phonebox provides compact CART decision trees and n:m multigram models, with saved locale preprocessing for repeatable inference.

• Train and predict: learn from your lexicon, preserve or remove stress, and generate single or n-best pronunciations.
• Review dictionaries: score pronunciation variants, inspect low-support entries, and reorder variants by model likelihood with TSV or JSON output.
• Process orthography: resolve locale names and use versioned ICU/CLDR exemplar data and spelling policies. Orthographic inventories are separate from the phone inventory you choose for training.
• Deploy compact trees: export a standalone Python predictor that uses only the standard library. The full training package has dependencies; multigram models use the full package.
• Measure results: compare CART and multigram models on held-out CMUdict with recorded data, settings, admission counts, and model sizes.

Phonebox is alpha. Each 0.X.0 release may break APIs, commands, or model workflows; patch releases within a minor line are intended to remain compatible. See the 0.2.0 changes and upgrade guide.

Install

Requires Python 3.11 or newer:

pip install phonebox

The full package uses cartlet and ICU. Installation requires compatible backend wheels for your Python and platform; see installation scope. Generated standalone tree bundles use only the Python standard library.

Optional extras:

pip install 'phonebox[config]'          # YAML training configuration
pip install 'phonebox[sklearn]'         # Optional scikit-learn trainer

Train an English model and bundle it

This recipe downloads CMUdict, trains a decision tree, and writes a standalone predictor. Training takes time; this is not a download of a pretrained model. The PocketSphinx preset removes stress. The tts preset retains primary stress; add --keep-secondary to retain secondary stress too.

phonebox recipe cmudict pocketsphinx -o g2p.py
python g2p.py "Hello, world!"

Use the generated predictor from Python:

from g2p import G2PPredictor

predictor = G2PPredictor.from_embedded()
for word, phones in predictor.pronounce_text("Hello, world!"):
    print(word, " ".join(phones))

See data preparation for CMUdict licensing and French liaison annotation requirements, and bundling for deployment details.

Train from your own lexicon

Dictionary lines contain a spelling followed by whitespace-separated phones. Choose the phone inventory to match your data. For CMU/ARPAbet input:

phonebox train --locale en --phoneset cmu \
  --lexicon words.dict -o model.g2p.gz
phonebox pronounce hello world -m model.g2p.gz

The equivalent Python workflow uses the same training defaults:

from phonebox import G2P, train_g2p

training = train_g2p(
    "words.dict", locale="en", phoneset="cmu", output="model.g2p.gz"
)
predictor = G2P(model="model.g2p.gz")
print(predictor.pronounce("hello"))

Primary training preserves stress, uses the native serial CART trainer, and prunes with a 5% validation split. Pass --remove-stress or remove_stress=True when desired. The default phone inventory is IPA; select cmu explicitly for CMU stress syntax. Locale names accept bare language codes and case-insensitive hyphen or underscore forms such as en, en-US, and en_US. See locale resolution and ICU data.

For n:m alignment and decoding:

phonebox train-multigram --locale en --phoneset cmu \
  --lexicon words.dict -o multigram.g2p.gz
phonebox pronounce hello -m multigram.g2p.gz

Keep the exported multigram sidecars together. See library and CLI workflows for structured training results and the corresponding train_multigram API.

Review and reorder pronunciations

Review an existing lexicon against a trained CART model:

# Numeric TSV, lowest support first
phonebox dict review words.dict -m model.g2p.gz -o review.tsv

# Each spelling's variants most likely first, with CMUdict-style numbering
phonebox dict review words.dict -m model.g2p.gz --format dict -o ranked.dict

# Repeat bare spellings instead of numbering variants
phonebox dict review words.dict -m model.g2p.gz --format dict \
  --no-number-senses -o ranked-bare.dict

Scores measure compatibility with the selected model, not pronunciation correctness. A model trained on the reviewed words can memorize them; the review guide explains model choice, unsupported sequences, TSV sorting, JSON provenance, and the shared review APIs. General dictionary phone mapping and deduplication are documented in dictionary processing.

Accuracy and model choice

CART uses spelling-context features and decision trees; multigram learns joint n:m spelling/phone units and decodes sequences. Their accuracy and export sizes depend on the lexicon, preprocessing, and training settings. The reproducible CMUdict comparison reports both models with and without stress, held-out error rates, and exact snapshot provenance. It is a measurement of the recorded revision, not a claim that every future release has the same results.

Documentation and help

Start with the documentation guide for tutorials, API/CLI workflows, evaluation, and historical experiments.

phonebox --help
phonebox train --help
phonebox dict review --help

The CLI includes training, prediction, bundling, dictionary processing, validation, evaluation, and prepared alignment/vector workflows. Command help is the authoritative option list.

Development

git clone https://github.com/lenzo-ka/phonebox.git
cd phonebox
pip install -e '.[dev]'

See the release checks for validation. Contributions should include tests for behavior changes and keep Python APIs, CLI help, and documentation consistent.

Credits and license

Phonebox is by Kevin Lenzo, building on CMU G2P research.

Source code uses the BSD 2-Clause License. Generated ICU/CLDR locale data uses the Unicode License v3. Third-party notices record the source, modifications, and pinned data versions.