Home / Ops / More in this area

Name Pronunciation - spec v1

Updated Jul 12, 2026 · Affirmology_NamePronunciation_Spec_v1.md

Name Pronunciation - spec v1

Jeff, 2026-07-12. "We need a tool in the app to help adjust the pronunciation our app uses of their name. It's going to get some people's incorrect. It was mispronouncing Affirmology at first."

The problem

Our system says the person's name back to them, in first person, dozens of times per audio, and a choir sings it. If we say it wrong, the whole spell breaks. Worse, mispronouncing someone's name is a small insult that lands hard, and it lands hardest on people with non-Anglo names, which is a large share of our best customers.

We already hit this on our own word. The engine mispronounced "Affirmology" until Jeff corrected it by hand. That fix was a one-off. It needs to be a system.

Two layers, both needed

1. THE GLOBAL LEXICON (admin) - words we always say

An admin-managed list of term -> pronunciation, applied to every render for everybody. Seed it with the words we already know we get wrong or will get wrong: - Affirmology (already corrected by hand; put the fix in the lexicon so it never regresses) - The oracle names: Ix Chel, Sri Agastya, Persephone, Hypnos, Orpheus, Concordia, Hestia, Prometheus, Taliesin, Siddhartha, Oshun, Hildegard - System vocabulary: Gene Keys gate/line terms, Manifesting Generator, Ajna, Sacral, Vedic and Sanskrit terms across the corpus - Anything a human hears wrong once. There must be a one-minute path from "that sounded wrong" to "it is fixed for everyone, forever."

2. THE PER-PERSON NAME OVERRIDE (in-app) - the name we say to them

Their name, their call. Nobody else's pronunciation should change because of it.

The in-app tool (the UX that actually works)

Do NOT ship a box that asks people for IPA. Almost nobody knows IPA, and the ones who do will find the advanced option anyway.

The flow: 1. Hear it. Play our current pronunciation of their name. A single tap. 2. "Did we get it right?" [ Yes, that's me ] [ Not quite ] 3. If "Not quite," offer three ways to fix it, easiest first: - Pick from variants. We generate three or four plausible pronunciations and they tap the right one. This solves the large majority with zero effort and zero jargon. (Javier: ha-vee-AIR vs HAV-ee-er vs kha-BYEHR.) - Say it yourself. They record their name once. This is the ground truth and it is also a lovely moment: the app asks to hear them say who they are. We derive the phonetics from the recording, and we KEEP the recording. - Spell it how it sounds. A plain respelling box: "sounds like: ha-vee-AIR." Capitals for stress. No IPA required. (IPA available behind an "advanced" toggle for the linguists.) 4. Confirm. Play the fixed version back. Lock it.

Sung is not spoken

The chant needs its own treatment. A sung name stretches vowels, carries stress differently, and may need explicit syllable breaks for the melisma. Store the spoken and sung forms separately if they diverge. Test the chant specifically, because a name that speaks fine can sing badly.

Data model

Add to the person: - name_pron_spoken - the phoneme string / SSML / lexicon key used by the TTS - name_pron_sung - the sung form, when it differs - name_pron_recording_url - their own recording, if given. Keep it. It is ground truth and it is theirs. - name_pron_source - one of: default | variant_picked | user_recorded | user_respelled | admin - name_pron_confirmed_at

Where it fires

• The chant reads name_pron_sung (falling back to spoken).
• Every audio render that speaks the name reads name_pron_spoken.
• Changing pronunciation re-renders the chant automatically and OFFERS (never forces) a re-render of their existing audios. Offering it is a re-engagement moment: "We've got your name right now. Want us to remake your Origin Soul Song with it?"

Guardrails

• Never let a pronunciation override change the SPELLING shown on screen. Sound only.
• The global lexicon must not stomp a personal name. If someone is actually named a word in the lexicon, their personal override wins.
• Whole-token matching in the lexicon. Do not substring-replace inside people's names.

Proactive, not just reactive

Do not wait for people to complain; most will not, they will just quietly feel unseen. Ask. The first time we are about to sing their name, the confirm screen already exists ("We'll sing: Rob Hartline"). Put a small "Not how I say it" link right there. That single link will catch most of the problem at the exact moment the person cares most.

Front end vs back end

• FRONT END (Cowork can build): the confirm screen, the "did we get it right" flow, the variant picker, the respelling box, the recording UI, the admin lexicon table.
• BACK END (app/engine chat): the phoneme pipeline into the TTS (SSML phoneme tags or lexicon substitution depending on the model), deriving phonetics from a user recording, the sung-form handling in the chant renderer, storing the fields, and the re-render triggers.