Enhance pronunciation scoring: add Hebrew transliteration support and update tips with Hebrew context

.gitignore

@@ -1 +1,3 @@
 *__pycache__**/
+*.mp3
+*.pcm

app/scorer.py

@@ -12,6 +12,7 @@ import numpy as np
 
 from .align import GopConfig, ctc_viterbi, edit_distance, greedy_decode, score_tokens
 from .tips import VOWELS, tip_for
+from .translit import to_hebrew
 
 log = logging.getLogger("ihki.scorer")
 
@@ -115,6 +116,7 @@ class Scorer:
 
         phonemes, tips, seen = [], [], set()
         ar_words = ar.split()
+        tr_words = to_hebrew(ipa, ar)
         for tok, sc in zip(toks, scores):
             heard_ph = "_" if sc.deleted else (self.vocab.i2t.get(sc.competitor) if sc.competitor is not None else None)
             flagged = bool(sc.score < self.cfg.flag_below) and tok.phoneme not in VOWELS
@@ -125,13 +127,14 @@ class Scorer:
                 if tip and tip["key"] not in seen:
                     seen.add(tip["key"])
                     tip["word"] = ar_words[tok.word] if tok.word < len(ar_words) else ""
+                    tip["word_tr"] = tr_words[tok.word]
                     tips.append(tip)
 
         n_words = len(ipa.split("|"))
         words = []
         for w in range(n_words):
             ws = [p["score"] for p in phonemes if p["word"] == w]
-            words.append({"ar": ar_words[w] if w < len(ar_words) else "",
+            words.append({"ar": ar_words[w] if w < len(ar_words) else "", "tr": tr_words[w],
                           "score": round(min(ws), 1) if ws else 0.0,
                           "phonemes": [p for p in phonemes if p["word"] == w]})
 
@@ -141,7 +144,7 @@ class Scorer:
         overall = 0.5 * phone_mean + 0.5 * word_mean  # one wrong consonant must pull the sentence down
         if unrelated:
             overall = min(overall, 30.0)
-        return {"score": round(overall), "variant": {"ar": ar, "ipa": ipa}, "heard_ipa": heard,
+        return {"score": round(overall), "variant": {"ar": ar, "tr": " ".join(tr_words), "ipa": ipa}, "heard_ipa": heard,
                 "unrelated": unrelated, "words": words, "tips": tips[:4]}
 
 

app/tips.py

@@ -3,6 +3,7 @@
 Keys are (expected phoneme, heard phoneme); "_" means the expected phoneme was missing.
 Phonemes are in the IPA used by phrases.py; HEARD_ALIASES maps model outputs onto those symbols.
 """
+import re
 
 NAMES = {
     "ħ": "ח (ح)", "ʕ": "ע (ع)", "x": "ח' (خ)", "ɣ": "ע' (غ)", "r": "ר (ر)",
@@ -46,6 +47,15 @@ TIPS = {
     ("ðˤ", "ð"): "נהגתה בלי הדגשה. ظ היא עיצור מודגש: " + _EMPH,
 }
 
+# bare Arabic letter in a tip text -> "Hebrew (Arabic)", so Arabic never appears without a Hebrew reading
+_PAIRED = {name[name.index("(") + 1]: name for name in NAMES.values() if "/" not in name}
+_BARE_AR = re.compile(r"(?<!\()[\u0621-\u064a](?![\u0621-\u064a])")
+
+
+def with_hebrew(text: str) -> str:
+    return _BARE_AR.sub(lambda m: _PAIRED.get(m.group(), m.group()), text)
+
+
 VOWELS = {"a", "i", "u", "e", "o", "aː", "iː", "uː", "eː", "oː"}
 # the urban glottal stop is often dropped by natives too; don't nag about it
 NO_DELETION_TIP = {"ʔ"}
@@ -61,7 +71,7 @@ def tip_for(expected: str, heard: str | None) -> dict | None:
     name = NAMES.get(expected, expected)
     text = TIPS.get((expected, heard))
     if text:
-        return {"title": name, "text": text, "key": f"{expected}>{heard}"}
+        return {"title": name, "text": with_hebrew(text), "key": f"{expected}>{heard}"}
     if heard == "_":
         return {"title": name, "text": "לא נשמעה בבירור.", "key": f"{expected}>_"}
     text = f"נשמעה כמו {NAMES[heard]}." if heard in NAMES else "נשמעה אחרת מהצפוי."

app/translit.py

@@ -0,0 +1,68 @@
+"""Hebrew transliteration generated from the IPA in phrases.py.
+
+Used wherever Arabic is shown for a specific variant or word, so every variant gets a reading
+without hand-writing one. Follows the conventions of the hand-written `tr` hints: pointed Hebrew,
+geresh for sounds Hebrew lacks (ח' ע' ג' ד' ט'), dagesh for geminates.
+"""
+
+CONSONANTS = {
+    "ʔ": "א", "b": "בּ", "t": "ת", "dʒ": "ג'", "ħ": "ח", "x": "ח'", "d": "ד", "r": "ר", "z": "ז",
+    "s": "ס", "ʃ": "ש", "sˤ": "צ", "dˤ": "ד'", "tˤ": "ט", "ðˤ": "ט'", "ʕ": "ע", "ɣ": "ע'", "f": "פ",
+    "q": "ק", "k": "כּ", "g": "ג", "l": "ל", "m": "מ", "n": "נ", "h": "ה", "w": "ו", "j": "י",
+}
+# vowel -> ((mark on the consonant, letter after it) mid-word, (same) word-finally)
+VOWELS = {
+    "a": (("ַ", ""), ("ַ", "א")), "i": (("ִ", ""), ("ִ", "י")), "u": (("ֻ", ""), ("", "וּ")),
+    "e": (("ֶ", ""), ("ֶ", "ה")), "o": (("", "וֹ"),) * 2,
+    "aː": (("ַ", "א"),) * 2, "iː": (("ִ", "י"),) * 2, "uː": (("", "וּ"),) * 2,
+    "eː": (("ֵ", "י"),) * 2, "oː": (("", "וֹ"),) * 2,
+}
+FINALS = {"מ": "ם", "נ": "ן", "צ": "ץ", "פ": "ף"}
+NO_DAGESH = set("אהחער")
+DAGESH, SHVA = "ּ", "ְ"
+
+
+def _letter(base: str, marks: str) -> str:
+    """Points go on the letter itself, before a geresh."""
+    return base[0] + marks + base[1:] if base.endswith("'") else base + marks
+
+
+def word_to_hebrew(ipa_word: str, ar_word: str = "") -> str:
+    """The Arabic spelling, when given, settles what the IPA cannot: an urban ʔ that is written ق
+    stays ק (as in the hand-written hints), and a final a written ة/ه ends in ה."""
+    phs = ipa_word.split()
+    if "ق" in ar_word:
+        phs = ["q" if ph == "ʔ" else ph for ph in phs]
+    final_a = "ה" if ar_word.endswith(("ة", "ه")) else "א"
+    out, i = [], 0
+    while i < len(phs):
+        ph = phs[i]
+        if ph in VOWELS:  # vowel with no consonant before it (word-initial): carry it on an alef
+            base, marks = "א", ""
+        else:
+            base, marks = CONSONANTS.get(ph, ph), ""
+            i += 1
+            if i < len(phs) and phs[i] == ph:  # geminate
+                if base[0] not in NO_DAGESH and DAGESH not in base:
+                    marks += DAGESH
+                i += 1
+        if i < len(phs) and phs[i] in VOWELS:
+            vowel = phs[i]
+            i += 1
+            mark, after = VOWELS[vowel][i == len(phs)]
+            if vowel == "a" and after:
+                after = final_a
+            out.append(_letter(base, marks + mark) + after)
+        elif i < len(phs):
+            out.append(_letter(base, marks + SHVA))
+        else:
+            out.append(FINALS.get(base, base) if not marks else _letter(base, marks))
+    return "".join(out)
+
+
+def to_hebrew(ipa: str, ar: str = "") -> list[str]:
+    """One Hebrew word per IPA word (words are separated by "|")."""
+    ipa_words, ar_words = ipa.split("|"), ar.split()
+    if len(ar_words) != len(ipa_words):
+        ar_words = [""] * len(ipa_words)
+    return [word_to_hebrew(w, a) for w, a in zip(ipa_words, ar_words)]

static/index.html

@@ -63,7 +63,7 @@ header{display:flex;align-items:baseline;gap:4px 12px;flex-wrap:wrap}
 .words{display:flex;flex-wrap:wrap;gap:4px 14px;direction:rtl}
 .word{display:flex;flex-direction:column;align-items:center}
 .word .w{font:700 26px/1.3 var(--f-ar)}
-.word .n{font-size:12px;line-height:1;color:var(--muted);font-variant-numeric:tabular-nums}
+.word .n{font-size:14px;line-height:1.5;color:var(--muted);font-variant-numeric:tabular-nums}
 .word .w.bad{background:none;color:var(--sumac)} .word .w.mid{background:none;color:var(--amber)} .word .w.good{background:none;color:var(--ink)}
 .tips{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:6px}
 .tips li{padding:6px 10px;border-radius:10px;border:1px solid var(--line);font-size:15px;line-height:1.4}
@@ -163,7 +163,7 @@ function render(r){
   for(const w of r.words){
     const box=document.createElement("div"); box.className="word";
     const ar=document.createElement("div"); ar.className="w "+band(w.score); ar.lang="ar"; ar.textContent=w.ar;
-    const n=document.createElement("div"); n.className="n"; n.textContent=Math.round(w.score);
+    const n=document.createElement("div"); n.className="n"; n.textContent=`${w.tr} · ${Math.round(w.score)}`;
     box.append(ar,n); words.appendChild(box);
   }
 
@@ -177,7 +177,7 @@ function render(r){
     const li=document.createElement("li");
     const what=document.createElement("span"); what.className="what";
     what.append(t.title+" במילה ");
-    const w=document.createElement("span"); w.className="ar"; w.textContent=t.word; what.append(w);
+    const w=document.createElement("span"); w.className="ar"; w.lang="ar"; w.textContent=t.word; what.append(w); if(t.word_tr) what.append(` (${t.word_tr})`);
     const body=document.createElement("span"); body.textContent=t.text;
     li.append(what,body); tips.appendChild(li);
   }