# Pronunciation Pipeline Reference Full Merriam-Webster respelling → IPA mapping table and SSML wrapping rules for the `digital-health-clinical-asr-build` two-tier IPA pipeline. ## ⚠ API key handling Path A below uses `DICTIONARY_API_KEY` (Merriam-Webster); the `synthesize_row` / `magpie_validates_ipa` recipes further down use `api_key` (NVCF bearer token for Magpie TTS). Both are sensitive credentials. Before redistributing or operationalizing any code from this file, observe the following: - **Never hard-code keys** in source files, never commit them to version control. The `.env` file at the repo root is git-ignored on purpose; keep keys there for local use only. - **Prefer a secrets manager** (HashiCorp Vault, AWS Secrets Manager, NVIDIA's internal secret-store) over plain environment variables for production deployments. The recipes here take `api_key` as an explicit parameter precisely so production callers can source it from any secret-store without modifying these recipes. - **HTTPS is mandatory.** Path A transmits the MW key as a `key=` query parameter; the NVCF call transmits the bearer token in the `authorization` gRPC metadata header. Both endpoints serve TLS, but verify your client isn't downgrading (`use_ssl=True` for `riva.client.Auth`; `requests` keeps SSL verification on by default — do not pass `verify=False`). - **Rotate immediately on suspected exposure.** If a key appears in logs, a shared notebook, a CI artifact, or any pushed commit (even one immediately reverted — the history retains it), revoke and re-issue. The MW JSON API self-service portal at regenerates instantly; for `NVIDIA_API_KEY`, rotate via the NVIDIA Cloud Functions console. - **Audit logging.** In production, log the *act* of invoking these recipes (which term, which row), never the key value. The NVCF side already records caller identity by key; do not duplicate the key into your own logs. ## Two MW implementation paths Both end up tagging the manifest row `merriam-webster`; pick the one that fits your context: ### Path A — `dictionaryapi.com` JSON API (recommended for standalone use) Stable, ToS-clean, requires a free key from exported as `DICTIONARY_API_KEY`. The lookup returns MW respelling in `data[0].hwi.prs[0].mw`; feed it to the mapping table below via `_respelling_to_ipa()`. ```python import requests from typing import Optional MW_BASE = "https://www.dictionaryapi.com/api/v3/references/medical/json" # Compact MW-respelling → IPA glyph map. See the full mapping tables below # for combining marks and edge-case vowels. _MW_TO_IPA = { "sh": "ʃ", "ch": "tʃ", "th": "θ", "zh": "ʒ", "ng": "ŋ", "ə": "ə", "a": "æ", "ä": "ɑː", "ā": "eɪ", "e": "ɛ", "ē": "iː", "i": "ɪ", "ī": "aɪ", "o": "ɑ", "ō": "oʊ", "ȯ": "ɔ", "u": "ʌ", "ü": "uː", "ˈ": "ˈ", "ˌ": "ˌ", } def mw_lookup_ipa(term: str, api_key: Optional[str]) -> Optional[str]: """Return IPA for `term` from MW Medical Dictionary, or None if unavailable. Pass `None` for api_key to skip MW lookup (caller decides whether the DICTIONARY_API_KEY env var is set; this code never reads the environment).""" if not api_key: return None r = requests.get(f"{MW_BASE}/{term}", params={"key": api_key}, timeout=10) if r.status_code != 200: return None data = r.json() if not data or not isinstance(data[0], dict): return None # MW returned spelling suggestions, not an entry prs = data[0].get("hwi", {}).get("prs", []) if not prs or "mw" not in prs[0]: return None return _respelling_to_ipa(prs[0]["mw"]) def _respelling_to_ipa(respelling: str) -> str: """MW respelling → IPA. Digraphs (sh, ch, th, zh, ng) match before single chars. Syllable dots are dropped; stress marks are preserved.""" s = respelling.replace("-", "") out, i = [], 0 while i < len(s): if i + 1 < len(s) and s[i:i+2] in _MW_TO_IPA: out.append(_MW_TO_IPA[s[i:i+2]]); i += 2; continue out.append(_MW_TO_IPA.get(s[i], s[i])); i += 1 return "".join(out) ``` ### Path B — HTML scrape of `merriam-webster.com` No API key needed, but brittle to MW site HTML changes; only use this if you control your deployment context (so you can fix it when the site moves). Feed the returned string into the same `_respelling_to_ipa()` helper as Path A. Sketch: ```python import re, requests from bs4 import BeautifulSoup from typing import Optional from urllib.parse import quote UA = "digital-health-clinical-asr-build/1.0 (mw scrape, change me if you redistribute)" def scrape_mw_respelling(term: str, timeout: float = 15.0) -> Optional[str]: """Path B: parse the public MW website for the term's respelling. Returns None if the page has no pronunciation block.""" s = requests.Session() s.headers.update({"User-Agent": UA}) slug = quote(term.strip().replace(" ", "-")) for path in (f"medical/{slug}", f"dictionary/{slug}"): r = s.get(f"https://www.merriam-webster.com/{path}", timeout=timeout) if r.status_code != 200: continue soup = BeautifulSoup(r.text, "html.parser") a = soup.find("a", class_=re.compile(r"\bplay-pron-v2\b")) if not a: continue raw = a.decode_contents().split("` SSML payload containing trill `r` (it doesn't error out — phoneme-set validation passes), but the trill is not in the en-US articulation inventory, so the synthesizer silently reduces or drops it. The symptom is an r-shaped hole in the audio: `əˈnæstrəˌzoʊl` ("anastrozole") rendered as `əˈnæstəˌzoʊl` — no audible r between `t` and the schwa. Use `ɹ` for every r in en-US IPA; the mapping table above already does this. If you're inheriting a hand-curated override from another source, sweep `r → ɹ` before committing or you'll get the same r-drop. ### Stress and syllabification | MW glyph | IPA | Meaning | |----------|-----|---------| | `ˈ` | `ˈ` | Primary stress (precedes stressed syllable) | | `ˌ` | `ˌ` | Secondary stress | | `-` | (drop) | Syllable boundary — drop before mapping | | `(ˌ)` | (drop) | Optional secondary stress — drop | ## Walk-through example MW respelling for **cefazolin**: `se-fə-ˈzō-lən` 1. Strip `-`: `sefəˈzōlən` 2. Apply table left-to-right (longest match first): - `s` → `s` - `e` → `ɛ` - `f` → `f` - `ə` → `ə` - `ˈ` → `ˈ` - `z` → `z` - `ō` → `oʊ` - `l` → `l` - `ə` → `ə` - `n` → `n` 3. Result: `sɛfəˈzoʊlən` ## SSML wrapping rules When `ipa_source` is `override` or `merriam-webster`, wrap the term in SSML so Magpie applies the IPA hint instead of relying on its neural G2P: ```python import re def wrap_with_ipa(term: str, ipa: str) -> str: """Single-token SSML wrap.""" return f'{term}' def wrap_multiword(term: str, ipa: str) -> str: """Multi-token wrap. gives Magpie a text fallback if it can't handle the IPA; the inner is the preferred path.""" return f'{term}' def render_sentence_with_overrides(sentence: str, overrides: dict[str, str]) -> str: """Replace each overridden term in `sentence` with its SSML wrap. Matches whole words only to avoid wrapping substrings.""" for term, ipa in overrides.items(): wrap = wrap_with_ipa(term, ipa) if " " not in term else wrap_multiword(term, ipa) sentence = re.sub(rf'\b{re.escape(term)}\b', wrap, sentence) return sentence ``` ### Edge cases - **Punctuation adjacent to the term** (`cefazolin,`): `\b` boundary handles this naturally — the comma stays outside the wrap. - **Term that contains hyphens** (`auto-immune`): re-escape the hyphen; the wrap still produces valid SSML. - **IPA that contains quotes**: shouldn't occur with the MW mapping above, but if a hand-curated override does, replace `"` with `"` inside the SSML attribute. - **Capitalized term in mid-sentence** (`Cefazolin`): use `re.IGNORECASE` if you want case-insensitive matching, but preserve the original casing in the wrap's display text. ## Phoneme validation — live-probe Magpie's neural G2P Used by Step 2d's QA-mode synthesis loop. Sends a minimal SSML `` request to Magpie's NVCF function; if Magpie accepts it, the IPA is in the en-US phoneme inventory. **Fail-closed**: network/auth errors return `False` just like phoneme-rejection errors. ```python import grpc import riva.client # pip install nvidia-riva-client NVCF_HOST = "grpc.nvcf.nvidia.com:443" MAGPIE_FUNCTION_ID = "877104f7-e885-42b9-8de8-f6e4c6303969" def magpie_validates_ipa(ipa: str, api_key: str, voice_id: str = "Magpie-Multilingual.EN-US.Mia") -> bool: """Return True if Magpie accepts the IPA via SSML . Sends a minimal synthesis request and consumes the audio stream. InvalidArgument (or any "phoneme" error) → False. Network/auth errors also return False (fail-closed).""" ssml = f'test' try: auth = riva.client.Auth( ssl_cert=None, use_ssl=True, uri=NVCF_HOST, metadata_args=[ ["function-id", MAGPIE_FUNCTION_ID], ["authorization", f"Bearer {api_key}"], ], ) tts = riva.client.SpeechSynthesisService(auth) for _chunk in tts.synthesize_online( text=ssml, voice_name=voice_id, language_code="en-US", sample_rate_hz=16000, ): pass return True except grpc.RpcError: return False ``` Call once per candidate IPA before showing it to the user. On user approval, append the verified IPA to `pronunciation_overrides.csv` — the row's `ipa_source` flips from `magpie_g2p` to `override` on the next manifest generation. ## Synthesis call Used by Step 2e's full-Cartesian generation. One synthesized WAV per manifest row. `all_overrides` must carry every entry from `pronunciation_overrides.csv` — including context-word overrides like `intravenously` that aren't benchmarked terms themselves — so the renderer wraps any override whose verbatim text appears in the row's sentence. Wrapping only `row['term']` silently drops context-word overrides. The row's own MW IPA (when `ipa_source == 'merriam-webster'`) is merged into `all_overrides` for the duration of the call so MW-tagged rows still get their term wrapped. Manual `override` rows are already in the dict by construction. ```python import re from pathlib import Path import riva.client # Re-use render_sentence_with_overrides from this same file (above). NVCF_HOST = "grpc.nvcf.nvidia.com:443" MAGPIE_FUNCTION_ID = "877104f7-e885-42b9-8de8-f6e4c6303969" def synthesize_row(row: dict, all_overrides: dict[str, str], out_dir: Path, api_key: str) -> Path: """Synthesize one manifest row to /audio/.wav. Returns the path.""" auth = riva.client.Auth( ssl_cert=None, use_ssl=True, uri=NVCF_HOST, metadata_args=[ ["function-id", MAGPIE_FUNCTION_ID], ["authorization", f"Bearer {api_key}"], ], ) tts = riva.client.SpeechSynthesisService(auth) text = row["text"] overrides_for_row = dict(all_overrides) if row["ipa_source"] == "merriam-webster" and row.get("ipa"): overrides_for_row[row["term"]] = row["ipa"] if overrides_for_row: text = f"{render_sentence_with_overrides(text, overrides_for_row)}" slug = re.sub(r'[^a-z0-9]+', '_', f"{row['term']}_{row['context_type']}_{row['voice_id']}_{row['noise_level']}".lower()) audio_path = out_dir / "audio" / f"{slug}.wav" audio_path.parent.mkdir(parents=True, exist_ok=True) pcm = b"".join(c.audio for c in tts.synthesize_online( text=text, voice_name=row["voice_id"], language_code="en-US", sample_rate_hz=16000, )) import wave with wave.open(str(audio_path), "wb") as w: w.setnchannels(1); w.setsampwidth(2); w.setframerate(16000); w.writeframes(pcm) return audio_path ``` ## Notes - MW Medical Dictionary's free tier is 1000 queries/day with a registered API key. Cache successful lookups in `pronunciation_overrides.csv` so re-runs of the build pipeline don't re-query. - Coverage: MW Medical Dictionary covers most generic drug names, anatomy, and common procedures. Long-tail biologics (`-mab` antibodies, `-mab` checkpoint inhibitors) often miss; those fall through to `magpie_g2p`. - The mapping table above is sufficient for ~95% of clinical respellings. If a respelling contains a glyph not in the table, the `_respelling_to_ipa` function passes it through unchanged, which will fail Magpie phoneme validation downstream — surface that as a candidate for hand-curation in `pronunciation_overrides.csv`.