name: tts-pronunciation
description: Canonical table of TTS pronunciation overrides for Adom tool names, acronyms, and product terms that neural TTS engines (edge-tts, piper, azure, eleven-labs) mispronounce. Use when writing narration for any demo / walkthrough / tour / voiceover — look up each Adom-ish term in the table and spell it phonetically in the narration column. Use BEFORE rendering any TTS audio, not after.
Trigger words: tts pronunciation, tts pronounce, mispronounce, how do I make TTS say, edge-tts pronounce, narration pronunciation, speak adom-tsci, demo narration phonetics.
Also fires automatically whenever another skill (demo-recording, video-post, voiceover-over-a-recording) is drafting narration text.

TTS pronunciation — canonical table

Single source of truth for how to write Adom tool names, acronyms, and product terms in narration so neural TTS engines voice them correctly. Every demo-recording / video-post / voiceover flow should consult this file at script-write time (not at render time — fixing mistakes after mux means re-rendering N clips).

🛑 The one rule

If the TTS engine would read a word as something other than what a listener expects, rewrite it in the narration. The most common fix is spelling an acronym out as individual letters separated by spaces — adom-tsci → adom t s c i. Edge-TTS and Piper both read letter-space-letter as individual letter names. No-space gets parsed as a single word and butchered.

Captions and on-screen text always use the real name (adom-tsci). Only the narration column gets phoneticized.

The table

Source-of-truth data file: pronunciations.json (same dir). This table is rendered from that file; update the JSON and this section regenerates on skill install.

How to add an entry

Anyone can propose a new entry — the table lives in gallia and deploys via gallia/install.mjs. Contribution flow:

1. Verify the problem. Render the current pronunciation to confirm it's actually wrong:

   edge-tts --voice en-US-AndrewMultilingualNeural \
     --text "this is <your term> version one" \
     --write-media /tmp/_tts-before.mp3
   # Listen: does the TTS say the term the way a human would?
   

2. Find a spelling that fixes it. Common patterns:

   • Acronym → individual letters with spaces: JLCPCB → J L C P C B
   • Word with silent/weird letters → phonetic: KiCad → kai cad
   • Number pattern → words: 1.3.7 → one point three point seven
   • Hyphenated brand name → space-or-phonetic: adom-tsci → adom t s c i

3. Verify the fix. Render with the new spelling:

   edge-tts --voice en-US-AndrewMultilingualNeural \
     --text "this is <your phonetic spelling> version one" \
     --write-media /tmp/_tts-after.mp3
   # Confirm it now reads correctly.
   

4. Add to pronunciations.json. One entry per term:

   {
     "written": "JLCPCB",
     "narration": "J L C P C B",
     "engines_confirmed": ["edge-tts", "azure"],
     "reason": "Acronym; reads as garbled single word",
     "added_by": "john",
     "added_date": "2026-04-23"
   }
   

5. Commit + publish. git commit the change; if you want wiki users to pick up the new entry, re-run adom-wiki publish on this skill's page (see ## Publishing below).

Engines we've tested against

• edge-tts (Microsoft Edge neural) — default on the platform, invoked as edge-tts --voice <voice> --text <text> --write-media <file>. Voice table:
  • en-US-AndrewMultilingualNeural — default for Adom demos (clear, neutral-male)
  • en-US-AriaNeural — polished female
  • en-US-GuyNeural — warm neutral-male
• piper — local offline TTS, fires on the platform when no network.
• azure-tts — via Microsoft Azure Speech SDK.
• eleven-labs — premium quality, used for hero demos.

Each engine has slightly different parsing rules. If a spelling works in one but not another, add a per-engine note in the pronunciations.json entry and pick the most permissive spelling (or provide per-engine overrides).

Integration — skills that consult this table

The following skills (should) look up terms here before drafting narration. If you spot drift between their embedded tables and this one, this file wins:

• demo-recording — Step 2 (write the demo script with narration column)
• video-post — storyboard review phase, narration validation
• voiceover (when that flow ships) — pre-render check
• Any custom narration script a user writes

One-liner verify in your own narration

Before rendering a whole 13-clip tour, pipe each scene's narration column through a verifier:

for narration in "$(jq -r '.scenes[].narration' demo/<name>-demo-script.json)"; do
  tmp=$(mktemp --suffix=.mp3)
  edge-tts --voice en-US-AndrewMultilingualNeural --text "$narration" --write-media "$tmp"
  echo "play: $tmp"
  # Listen or pipe to ffprobe for duration check
done

Cheap pre-flight; catches pronunciation and duration issues before you burn render time.

Publishing to wiki

This skill is published to the Adom Wiki so every container gets it on install. Publish with:

adom-wiki publish skills/tts-pronunciation \
  --file /home/adom/project/gallia/skills/tts-pronunciation/SKILL.md \
  --data-file /home/adom/project/gallia/skills/tts-pronunciation/pronunciations.json \
  --caption "Canonical TTS pronunciation table — add your term if the engine gets it wrong"

Users pick up the latest version via adom-cli skills install tts-pronunciation or gallia/install.mjs on next sync.