[christopherthompson81]

Kokoro's G2P is eSpeak-ng, inside the session. A caller that already has phonemes — from its own G2P, a lexicon, or a hand correction — has no way to use them, and no way to fix a pronunciation the built-in frontend gets wrong.

This adds a phonemes request option, using the string_list transport from #566.

const char *chunks[] = { "həlˈO", "wˈɜɹld" };
audiocpp_request_set_option_array(req, "phonemes", chunks, 2);

Why a list rather than one delimited string

Kokoro's context is 510 symbols, so long input has to be split, and the caller is the only one who knows where the splits can go — it has the word boundaries, the prosody and the punctuation that its own G2P just produced. A delimited string would make the engine re-guess a decision the caller had already made, and would need an escape convention for whatever delimiter was chosen.

Entries are rendered in order and merged into one result, so one call still produces one buffer.

Behaviour

• phonemes absent → unchanged; the built-in eSpeak-ng G2P runs as before.
• phonemes present → the supplied stream is synthesized directly, and text is still required with a language matching the voice.
• Each entry must be at most 510 symbols; exceeding it names the chunk and tells the caller to split further.

Unknown symbols: skipped for our G2P, rejected for the caller's

#564 made the encoder skip phonemes the 114-symbol vocab has no id for, matching KModel's filter(None, map(vocab.get, phonemes)). That is right for the engine's own output — eSpeak glottalises /t/ before a syllabic nasal, so "button" carries a U+0329 the vocab does not hold, and dropping it gives a correct reading.

It is the wrong answer for a caller's phonemes: silently dropping symbols would hide the caller's bug. So encode_input_ids_and_count takes a reject_unknown flag, and the supplied path reports:

Kokoro vocab is missing phoneme symbol: R; supplied phonemes must be in Kokoro's own
114-symbol vocabulary, which is not canonical IPA -- a diphthong is one symbol there
and two in IPA, so an off-glide is a common cause

That message is load-bearing. Kokoro's alphabet is not IPA — O is one symbol for the GOAT diphthong, ʤ is one symbol — and "I passed IPA and it rejected it" is the predictable first mistake. It was mine while testing this.

Published packages take it too

A GGUF's embedded schema-v1 contract is authoritative, so the shipped kokoro-82m-q8_0.gguf — written before this option existed — would reject phonemes as an unknown request option, and a published package cannot be edited in place. The engine serves the request either way; only the validation disagreed.

So the key is dropped from the validation copy when the contract does not declare it, following irodori_tts.codec_backend and the Parakeet TDT VAD controls, which are older options in exactly this position. Unrelated unknown options still fail, and a contract that does declare phonemes validates it as before.

Verified

Built CPU-only and driven through the C ABI against the shipped package with no spec override, and against the same package with model_specs/kokoro_tts.json as an override — so both sides of that branch ran:

package declares a 'phonemes' request option: no          |  yes

== supplied phonemes, one chunk ==     ok  1.52s @ 24000Hz  |  ok  1.52s
== supplied phonemes, three chunks ==  ok  5.10s @ 24000Hz  |  ok  5.10s
== no phonemes, built-in G2P ==        ok  1.52s @ 24000Hz  |  ok  1.52s

supplied 'R'                    -> Kokoro vocab is missing phoneme symbol: R; ...
supplied 'not_a_kokoro_option'  -> unknown Kokoro TTS request option: not_a_kokoro_option

The text was "placeholder" in every run. Three chunks give 5.10 s where the same text alone gives 1.52 s — the supplied phonemes drive synthesis rather than being accepted and ignored — and the built-in path is byte-for-byte the same code as before. Both rejections are identical on both sides, so relaxing the contract check did not relax anything else.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EkxqpYvUbjCpRDnFiNiVfx

[0xShug0]

Haven't tested it yet. But I think Kokoro can follow the existing patterns used by other models, such as Irodori TTS, which explicitly allows the newer irodori_tts.codec_backend option even when an older published GGUF’s embedded v1 spec does not declare it.

[christopherthompson81]

Good call — done in 2b22e7d, following irodori_tts.codec_backend exactly.

The key is dropped from the validation copy when the package's contract does not declare it, so a published GGUF whose embedded v1 spec predates the option can still be given phonemes. Same shape as the Parakeet TDT VAD controls in the same position. Unrelated unknown options still fail.

Driven through the C ABI against the shipped kokoro-82m-q8_0.gguf with no spec override, and against the same package with model_specs/kokoro_tts.json as an override, so both sides of that branch ran:

package declares a 'phonemes' request option:  no   |  yes

== supplied phonemes, one chunk ==      ok  1.52s   |  ok  1.52s
== supplied phonemes, three chunks ==   ok  5.10s   |  ok  5.10s
== no phonemes, built-in G2P ==         ok  1.52s   |  ok  1.52s

supplied 'R'                    -> Kokoro vocab is missing phoneme symbol: R; ...
supplied 'not_a_kokoro_option'  -> unknown Kokoro TTS request option: not_a_kokoro_option

Identical on both, including the two rejections — so relaxing the contract check for this one key did not relax anything else. Text was "placeholder" in every run; three chunks give 5.10 s against 1.52 s for the text alone, so the supplied phonemes are what is being synthesized.

The PR description's "note for whoever regenerates the package" is gone, since there is nothing to wait for now.

🤖 Generated with Claude Code

[0xShug0]

@christopherthompson81 One small issue: ... std::vector<runtime::TaskRequest>(supplied_phonemes.size(), request);
Creates one full copy of request per chunk. Every copy includes the entire option_arrays["phonemes"] list.

Another one I'm not sure it's an issue or not. With text="placeholder",

["həlˈO"] produces 1.425 s supplied speech
["həlˈO", ""] produces 2.950 s, including unintended placeholder speech.

So empty entries synthesize the placeholder text. Of course, the issue won't occur if the user provides a correct list.

[christopherthompson81]

Both real, fixed in 567f84e — and the second one was worse than the symptom suggested.

The blank entry. build_kokoro_synthesis_input decided whether an override had been given with !phoneme_override.empty(), so an empty entry was the "no override" sentinel and that chunk fell through to the built-in G2P. That is where your placeholder speech came from. The override is now std::optional<std::string_view>, so absent and empty are different things, and an empty entry is refused by index rather than substituted.

The same hole existed one level up: an empty list left supplied_phonemes.empty() true and the whole request was spoken from text. The C ABI accepts count == 0 and stores the key, so a caller whose G2P stage produced nothing got the source text read aloud with no error. Refused too.

The copies. You are right that it was one full TaskRequest per chunk, each carrying the whole list — the caller's input copied once per entry in it. With supplied phonemes every chunk runs the same request, so it is now used directly. Reviewing that turned up two more of the same shape: the cache key concatenated the entire document per chunk, and the option-array validation copied every phoneme string just to drop one key from the map. The key's text half is built once now, and validation copies key names only.

While there: a supplied-entry failure names its entry, matching the empty-entry message. A bad symbol in entry 200 of 201 used to report only the symbol.

Against the shipped package, and against the same package with model_specs/kokoro_tts.json as an override — identical on both:

["həlˈO"]                   ok 1.40s            (your 1.425 s)
["həlˈO", ""]               entry 1 is empty; every entry is rendered as its own chunk ...
[""]                        entry 0 is empty; ...
count=0                     'phonemes' was set but holds no entries; pass the phonemes ...
201 entries, last one bad   entry 200: vocab is missing phoneme symbol: R      (failed in 0.00s)
not_a_kokoro_option         unknown Kokoro TTS request option

Sizing in prepare() covers every entry, so a bad entry is still reported before anything is rendered — hence 0.00 s on that last one rather than 200 chunks of wasted synthesis. One chunk 1.52 s, three chunks 5.10 s and the built-in G2P path are unchanged; kokoro_cpu_kernel_test passes. The option description now states the non-empty requirement.

🤖 Generated with Claude Code

[0xShug0]

@christopherthompson81 Thanks for the quick turnaround! PR merged.

I plan to release 0.8.1 tomorrow as a checkpoint. After that, there could be major GGML kernel changes, so I won’t take new improvements or features until those changes are stable.

If you have any PRs for critical bugs that should be fixed and included in 0.8.1, please let me know.