Model card: document the espeak-ng 1.52 /ʊɐ fix and the ç phonemizer-patch note

README.md

@@ -45,16 +45,28 @@ The result loads and synthesizes in sherpa-onnx with the weights unchanged.
 
 - `model.onnx` — the Martin ONNX with sherpa-onnx Kokoro metadata injected
 - `voices.bin` — the voice style vector (510×1×256 float32)
-- `tokens.txt` and `espeak-ng-data/` — from the k2-fsa sherpa-onnx Kokoro release
-
-## Known limitation
-
-sherpa-onnx phonemizes German with espeak-ng / piper-phonemize, whose G2P emits the German
-**ich-laut /ç/ decomposed** (`c` + combining cedilla, U+0327); the precomposed Kokoro token set
-drops it, so `ich`, `nicht` and `-lich` / `-ig` words don't render cleanly from raw text. This is
-a property of the sherpa-onnx Kokoro G2P pipeline, not of the voice, and affects any Kokoro voice
-run this way. The usual sherpa workaround applies: supply the affected words through a lexicon so
-their phonemes bypass the runtime G2P.
+- `tokens.txt` — from the k2-fsa sherpa-onnx Kokoro release
+- `espeak-ng-data/` — from **espeak-ng 1.52** (see the pronunciation note below)
+
+## Pronunciation notes (German G2P)
+
+sherpa-onnx phonemizes German with espeak-ng / piper-phonemize, and two properties of that
+pipeline affect raw-text rendering. Both are properties of the sherpa-onnx Kokoro G2P, not of the
+voice weights.
+
+- **`ʊɐ` ("ur") vowel — fixed in this package.** The espeak-ng-data shipped by k2-fsa's base
+  Kokoro release is stale and emits a literal `?` for the vocalized-r `ʊɐ`, so `durch`, `kurz`,
+  `wurde`, … mispronounce. This package instead bundles current **espeak-ng 1.52** data, which
+  resolves `ʊɐ` correctly (`durch` → `dˈʊɐç`). A build-time check guards it.
+- **ich-laut `/ç/` — needs a phonemizer patch, not a lexicon.** piper-phonemize NFD-decomposes
+  `ç` into `c` + combining cedilla (U+0327), which the precomposed Kokoro token set drops, so
+  `ich`, `nicht`, `-lich` / `-ig` don't render cleanly. **Note the usual "add a lexicon entry"
+  workaround does _not_ apply here:** sherpa-onnx consults the Kokoro lexicon only for its
+  dictionary languages (en/zh); for espeak-driven languages (incl. German) it goes straight to
+  espeak and never reads the lexicon. The fix has to be in the phonemizer — recompose the pair
+  back to `ç` when that codepoint is a known token. The [Page Reader](https://github.com/) app
+  that consumes this package carries exactly that patch in its bundled sherpa-onnx build; if you
+  run this archive on **stock** sherpa-onnx, ç-words are still affected.
 
 ## How it was built