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

---
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`](pronunciations.json) (same dir). This table is rendered from that file; update the JSON and this section regenerates on skill install.

| Written in product / caption | Narration spelling (what the TTS sees) | Engines confirmed | Reason |
|---|---|---|---|
| `adom-tsci` | `adom t s c i` | edge-tts, piper | TTS reads `tsci` as "sci" / "ski"; letter-by-letter is the intended reading |
| `tscircuit` | `t s circuit` | edge-tts | "tscircuit" sometimes OK but inconsistent across voices; forcing letters is safe |
| `JLCPCB` | `J L C P C B` | edge-tts, azure | Acronym, always spell out |
| `PCB` | `P C B` | all | Acronym |
| `SMT` / `SMD` | `S M T` / `S M D` | all | Acronym |
| `KiCad` | `kai cad` | edge-tts | Some voices say "kee cad"; `kai cad` is the community pronunciation |
| `MPN` | `M P N` | all | Acronym |
| `BOM` | `B O M` or `bill of materials` | all | "bom" gets read as the word "bomb" by some voices; spelling out is safer |
| `FPGA` | `F P G A` | all | Acronym |
| `I²C` / `I2C` | `I squared C` or `I two C` | all | Superscript/digit both mangled |
| `SPI` | `S P I` | all | Acronym |
| `UART` | `you art` | all | Engines try to read as word (rhymes with "heart") which is wrong |
| `MCU` | `M C U` | all | Acronym |
| `GPIO` | `G P I O` | all | Acronym |
| 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 |
| Dates like `2026-04-23` | `April twenty third` (or "April twenty third twenty twenty six") | all | Hyphenated date gets mangled |
| Slugs / UUIDs | don't narrate them; reference as "the container" / "the workspace" | — | Never put a slug/UUID in a TTS stream |

## 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:

    ```bash
    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:

    ```bash
    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:

    ```json
    {
      "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.** This skill lives inside the adom-tts repo (skills/tts-pronunciation/). To ship a table change, bump adom-tts's version and publish it per publish-skills/adom-tts-publish — every installer gets the update with the app.

## 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:

```bash
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.