TTS Pronunciation — Canonical Table

{
  "schema_version": 1,
  "type": "skill",
  "slug": "tts-pronunciation",
  "title": "TTS Pronunciation — Canonical Table",
  "brief": "Shared pronunciation rules for Adom tool names, acronyms, and product terms so every demo / walkthrough / tour pronounces them consistently. Contribute when your TTS engine butchers a term.",
  "version": "1.0.0",
  "tags": [],
  "license": "MIT",
  "discovery_triggers": [
    "tts pronunciation",
    "tts pronounce",
    "how do I make tts say",
    "edge-tts pronounce",
    "mispronounce",
    "narration pronunciation",
    "speak adom-tsci",
    "demo narration phonetics",
    "tts says the wrong thing"
  ],
  "discovery_pitch": "tts-pronunciation is the canonical shared table of phonetic overrides for Adom tool names, acronyms, and product terms. Consult BEFORE rendering narration; contribute when you hit a term your engine butchers. Used by demo-recording, video-post, and any narration-adjacent skill.",
  "source_path": "SKILL.md",
  "readme": "---\nname: tts-pronunciation\ndescription: 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.\n  Trigger words: tts pronunciation, tts pronounce, mispronounce, how do I make TTS say, edge-tts pronounce, narration pronunciation, speak adom-tsci, demo narration phonetics.\n  Also fires automatically whenever another skill (demo-recording, video-post, voiceover-over-a-recording) is drafting narration text.\n---\n\n# TTS pronunciation — canonical table\n\nSingle 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).\n\n## 🛑 The one rule\n\n**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.\n\nCaptions and on-screen text always use the real name (`adom-tsci`). Only the narration column gets phoneticized.\n\n## The table\n\nSource-of-truth data file: [`pronunciations.json`](pronunciations.json) (same dir). This table is rendered from that file; update the JSON and this section regenerates on skill install.\n\n| Written in product / caption | Narration spelling (what the TTS sees) | Engines confirmed | Reason |\n|---|---|---|---|\n| `adom-tsci` | `adom t s c i` | edge-tts, piper | TTS reads `tsci` as \"sci\" / \"ski\"; letter-by-letter is the intended reading |\n| `tscircuit` | `t s circuit` | edge-tts | \"tscircuit\" sometimes OK but inconsistent across voices; forcing letters is safe |\n| `JLCPCB` | `J L C P C B` | edge-tts, azure | Acronym, always spell out |\n| `PCB` | `P C B` | all | Acronym |\n| `SMT` / `SMD` | `S M T` / `S M D` | all | Acronym |\n| `KiCad` | `kai cad` | edge-tts | Some voices say \"kee cad\"; `kai cad` is the community pronunciation |\n| `MPN` | `M P N` | all | Acronym |\n| `BOM` | `B O M` or `bill of materials` | all | \"bom\" gets read as the word \"bomb\" by some voices; spelling out is safer |\n| `FPGA` | `F P G A` | all | Acronym |\n| `I²C` / `I2C` | `I squared C` or `I two C` | all | Superscript/digit both mangled |\n| `SPI` | `S P I` | all | Acronym |\n| `UART` | `you art` | all | Engines try to read as word (rhymes with \"heart\") which is wrong |\n| `MCU` | `M C U` | all | Acronym |\n| `GPIO` | `G P I O` | all | Acronym |\n| Version numbers like `1.3.7` | `one point three point seven` | all | `1.3.7` gets read as \"one three seven\" or mangled decimals; always spell |\n| Dates like `2026-04-23` | `April twenty third` (or \"April twenty third twenty twenty six\") | all | Hyphenated date gets mangled |\n| Slugs / UUIDs | don't narrate them; reference as \"the container\" / \"the workspace\" | — | Never put a slug/UUID in a TTS stream |\n\n## How to add an entry\n\nAnyone can propose a new entry — the table lives in gallia and deploys via `gallia/install.mjs`. Contribution flow:\n\n1. **Verify the problem.** Render the current pronunciation to confirm it's actually wrong:\n\n    ```bash\n    edge-tts --voice en-US-AndrewMultilingualNeural \\\n      --text \"this is <your term> version one\" \\\n      --write-media /tmp/_tts-before.mp3\n    # Listen: does the TTS say the term the way a human would?\n    ```\n\n2. **Find a spelling that fixes it.** Common patterns:\n    - Acronym → individual letters with spaces: `JLCPCB` → `J L C P C B`\n    - Word with silent/weird letters → phonetic: `KiCad` → `kai cad`\n    - Number pattern → words: `1.3.7` → `one point three point seven`\n    - Hyphenated brand name → space-or-phonetic: `adom-tsci` → `adom t s c i`\n\n3. **Verify the fix.** Render with the new spelling:\n\n    ```bash\n    edge-tts --voice en-US-AndrewMultilingualNeural \\\n      --text \"this is <your phonetic spelling> version one\" \\\n      --write-media /tmp/_tts-after.mp3\n    # Confirm it now reads correctly.\n    ```\n\n4. **Add to `pronunciations.json`.** One entry per term:\n\n    ```json\n    {\n      \"written\": \"JLCPCB\",\n      \"narration\": \"J L C P C B\",\n      \"engines_confirmed\": [\"edge-tts\", \"azure\"],\n      \"reason\": \"Acronym; reads as garbled single word\",\n      \"added_by\": \"john\",\n      \"added_date\": \"2026-04-23\"\n    }\n    ```\n\n5. **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).\n\n## Engines we've tested against\n\n- `edge-tts` (Microsoft Edge neural) — default on the platform, invoked as `edge-tts --voice <voice> --text <text> --write-media <file>`. Voice table:\n    - `en-US-AndrewMultilingualNeural` — default for Adom demos (clear, neutral-male)\n    - `en-US-AriaNeural` — polished female\n    - `en-US-GuyNeural` — warm neutral-male\n- `piper` — local offline TTS, fires on the platform when no network.\n- `azure-tts` — via Microsoft Azure Speech SDK.\n- `eleven-labs` — premium quality, used for hero demos.\n\nEach 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).\n\n## Integration — skills that consult this table\n\nThe following skills (should) look up terms here before drafting narration. If you spot drift between their embedded tables and this one, this file wins:\n\n- `demo-recording` — Step 2 (write the demo script with narration column)\n- `video-post` — storyboard review phase, narration validation\n- `voiceover` (when that flow ships) — pre-render check\n- Any custom narration script a user writes\n\n## One-liner verify in your own narration\n\nBefore rendering a whole 13-clip tour, pipe each scene's narration column through a verifier:\n\n```bash\nfor narration in \"$(jq -r '.scenes[].narration' demo/<name>-demo-script.json)\"; do\n  tmp=$(mktemp --suffix=.mp3)\n  edge-tts --voice en-US-AndrewMultilingualNeural --text \"$narration\" --write-media \"$tmp\"\n  echo \"play: $tmp\"\n  # Listen or pipe to ffprobe for duration check\ndone\n```\n\nCheap pre-flight; catches pronunciation and duration issues before you burn render time.\n\n## Publishing to wiki\n\nThis skill is published to the Adom Wiki so every container gets it on install. Publish with:\n\n```bash\nadom-wiki publish skills/tts-pronunciation \\\n  --file /home/adom/project/gallia/skills/tts-pronunciation/SKILL.md \\\n  --data-file /home/adom/project/gallia/skills/tts-pronunciation/pronunciations.json \\\n  --caption \"Canonical TTS pronunciation table — add your term if the engine gets it wrong\"\n```\n\nUsers pick up the latest version via `adom-cli skills install tts-pronunciation` or `gallia/install.mjs` on next sync.\n",
  "author": {
    "id": "695820315b5f1e4db2fcf602",
    "name": "Kyle Bergstedt",
    "email": "[email protected]"
  },
  "visibility": {
    "public": true
  },
  "hero": null,
  "sample_prompts": [],
  "metadata": {},
  "created_at": "2026-05-28T05:29:47.964Z",
  "updated_at": "2026-05-28T05:29:47.964Z",
  "sub_skills": [],
  "parent_app": null
}