/phoneticize

name: phoneticize
description: >
  Build pronunciation tables, generate text-to-speech (TTS) preview samples, and produce
  phoneticized scripts ready for narration. Use whenever a script is
  intended for text-to-speech rendering and the user wants to catch
  words the engine will mispronounce — proper nouns, Gaelic and Welsh
  names, brand names with idiosyncratic pronunciation (df12, Nginx),
  model names with embedded numerics (Atari 2600, ESP32), terms of art
  and acronyms (SaaS, OAuth, JWT), and document specifiers (ADR-0012,
  RFC 2119). Trigger on phrases like "phoneticize this script",
  "phonetecize this", "phonetize", "prep this for TTS", "build a
  pronunciation table", or any task involving text-to-speech narration
  where pronunciation consistency matters across takes. Drives a phased
  workflow: detect candidates, suggest phonetic respellings, render
  preview samples via the Higgsfield MCP TTS tool with Eleven v3,
  iterate with the user, and emit a final phoneticized script.

Phoneticize — TTS pronunciation prep

A workflow for identifying pronunciation hazards in a TTS script, agreeing phonetic renderings with the user via audio previews, and emitting a phoneticized script ready for narration.

Read first

| Reference | When to read | Path | |---|---|---| | Detection heuristics | Before Phase 1 — patterns that find candidates and how to combine them | `references/detection-heuristics.md` | | Respelling conventions | Before Phase 2 — how to write phonetic respellings that Eleven v3 actually obeys | `references/respelling-conventions.md` | | Eleven v3 format notes | Before Phase 3 and Phase 5 — what the engine accepts and silently ignores | `references/eleven-v3-notes.md` |

Governing principles

1. **Preview the fragment, not the word.** TTS prosody depends on surrounding context. A respelling that sounds right in isolation collapses inside a sentence. Render fragments throughout.

2. **Respelling is the primary output, not SSML.** Eleven v3 silently drops `<phoneme>` tags (see `references/eleven-v3-notes.md`). Inline respelling — `Siobhán` → `shi-VAWN` directly in the prose — is what actually changes the model's output. IPA goes in the table for archival precision; respelling goes in the script.

3. **Mark uncertainty, never guess.** A wrong respelling shipped with confidence is worse than an explicit `?` the user resolves. When the pronunciation isn't obvious, ask.

4. **Stable IDs across iterations.** Each candidate gets a row ID (`P01`, `P02`, …) on first pass and keeps it for the lifetime of the table. The user references rows by ID; regenerate only the rows that changed.

5. **Render once, accept once.** Never re-render an `accepted` row — it wastes Higgsfield calls and the user will assume something broke when the audio differs subtly between takes.

Phase 1 — Scan

Combine the regex helper with semantic reading. Neither alone catches everything: regex misses ordinary-looking words with non-obvious pronunciation (Worcester, Featherstonehaugh), and an LLM scan alone will miss tokens deep in long scripts.

Run the helper

python scripts/extract_candidates.py path/to/script.txt --out candidates.json

The helper applies the patterns documented in `references/detection-heuristics.md` and emits a JSON list of deduplicated candidates with category guesses, positions, and context fragments.

Add and prune

Read the script. For every candidate the helper found:

• **Confirm the category** — the helper guesses from token shape and

occasionally gets it wrong (a CamelCase brand name miscategorised as ART, etc.)

• **Drop false positives** — title-case words at sentence-initial

positions that aren't actually proper nouns, common acronyms the user clearly already pronounces a particular way

For everything the helper missed:

• English place names with silent letters (Worcester, Cholmondeley,

Featherstonehaugh)

• Loanwords with retained pronunciation (lingerie, pho, façade)
• Programmer jargon with contested pronunciation (Nginx, kubectl,

YAML, GIF)

• Multi-token model names — the helper catches `Atari` and `2600`

separately; merge them by hand into a single candidate `Atari 2600`

Capture per candidate

For each entry, the table needs:

• **Token**: surface form as it appears (preserve case)
• **Lemma**: canonical form for deduping (`Siobhán's` → `Siobhán`)
• **Category**: `NAM` / `CEL` / `BRA` / `MOD` / `ART` / `DOC` / `OTH`
• **Positions**: every offset where the lemma occurs in the script
• **Original fragment**: 5–6 word snippet around the first occurrence,

snapped to clause boundaries where possible

Phase 2 — Suggest respellings

Build the pronunciation table in this exact column order:

| Col | Meaning | |---|---| | `ID` | Stable identifier — `P01`, `P02`, … | | `Token` | The token as it appears in the script | | `Cat` | NAM / CEL / BRA / MOD / ART / DOC / OTH | | `Original fragment` | 5–6 word snippet, original spelling | | `Respelling` | Editable phonetic respelling — see conventions | | `IPA` | Archive form (optional; fill where confident) | | `Phoneticized fragment` | Same fragment with the respelling substituted in situ | | `Sample` | Path to rendered audio (filled in Phase 3) | | `Status` | `pending` / `accepted` / `revised` |

Respelling rules (full detail in `references/respelling-conventions.md`):

• **Hyphens between syllables**: `shi-VAWN`, never `shivawn`
• **Capitals mark stress**: `shi-VAWN` (stress on second), `LLAN-fair`

(stress on first)

• **English orthographic conventions, not IPA**: `oo` for /uː/, `ay`

for /eɪ/, `aw` for /ɔː/. The model reads letters, not symbols.

• **Disambiguate hard consonants**: `kat` not `cat` if the model is

reading the c soft; `gohl` not `goal` if the g is going wrong

• **Acronyms — letter or word**: decide and commit. `S-Q-L` (letters)

or `SEE-kwul` (word) — both are valid; pick one and tell the user.

• **Numerics — wr