Skip to content

feat: spell out dev acronyms espeak mispronounces in normalize#37

Merged
StuBehan merged 1 commit into
mainfrom
feat/dev-term-pronunciations
Jul 10, 2026
Merged

feat: spell out dev acronyms espeak mispronounces in normalize#37
StuBehan merged 1 commit into
mainfrom
feat/dev-term-pronunciations

Conversation

@StuBehan

@StuBehan StuBehan commented Jul 10, 2026

Copy link
Copy Markdown
Collaborator

Summary

espeak mispronounces several common dev acronyms — it reads them as a word instead of spelling them out (CLI→"kligh", CI→"sigh", IDE→"eyed", AWS→"awz", URI→"yuri", IAM→"eeyam") and mangles CI/CD into "sigh slash C-D". This adds a small, curated pronunciation map applied by default in normalize, so read-aloud output says "C-L-I", "A-W-S", "C-I-C-D", etc.

Changes

  • _DEV_PRONUNCIATIONS map in stackvox/text.py, applied by default via a new dev_terms=True parameter on normalize_for_speech. Whole-word and case-insensitive (reusing apply_pronunciations), so lowercase cli is fixed too. Caller-supplied --pronunciations still override the defaults.
  • --no-dev-terms flag on the normalize / say / speak subcommands to opt out.
  • Curated to only the terms espeak gets wrong. Acronyms it already voices correctly — API, URL, JSON ("jason"), YAML, HTTP, SDK, nginx ("engine-x"), CRUD, REST — are deliberately left untouched. Plus a few said-as-a-word fixes: SaaS→"sass", PaaS→"pass", TUI, postgresql→"postgres", kubectl→"kube control".
  • Doc reconciliation (docs/speech-normalization.md): clarifies that generic pronunciation corrections live in core, while domain/org dictionaries (StackOne, Redis, …) stay per-consumer.

No change to correctly-voiced text; opt-out preserves the old behaviour exactly.

Testing

  • pytest — 181 passed; ruff check . clean.
  • Pronunciations were chosen empirically via Kokoro().tokenizer.phonemize(term, "en-us") (no audio needed): confirmed the six target acronyms read as words before and spell out after, and that API/URL/JSON/HTTP/SDK were already correct (hence excluded).
  • End-to-end:
    $ stackvox normalize "Use the CLI to deploy to AWS. The CI/CD pipeline parses the URI for IAM."
    Use the C L I to deploy to A W S. The C I C D pipeline parses the U R I for I A M.
    $ stackvox normalize --no-dev-terms "Use the CLI to deploy to AWS."
    Use the CLI to deploy to AWS.
    

Related issues

None.

@StuBehan StuBehan force-pushed the feat/dev-term-pronunciations branch from 963fa6b to 62403d4 Compare July 10, 2026 10:24
@StuBehan StuBehan merged commit 15de2e7 into main Jul 10, 2026
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant