Kokoro Tts

Kokoro TTS (open-weight, self-hosted)

Kokoro is a small, fast, permissively licensed text-to-speech model. Its entire value proposition is that you run it yourself: no API key, no per-character billing, no audio leaving your machine. This skill helps an agent decide whether Kokoro fits a job, run it through the right runtime, and get acceptable output — and, just as importantly, recognize the jobs where Kokoro will disappoint the user and something else is the correct answer.

All version, license, voice-count, ranking, and performance facts below were verified on 2026-07-10 against the sources listed at the end. Treat them as volatile.

What Kokoro is (documented facts)

• Model. ~82 million parameters. Architecture is StyleTTS 2 (arXiv 2306.07691) with an ISTFTNet decoder (arXiv 2203.02395). The card describes it as "Decoder only: no diffusion, no encoder release." Source: hexgrad/Kokoro-82M model card.
• License. Apache 2.0, including the weights. v0.19 weights were released in full fp32 on 2024-12-25; v1.0 released 2025-01-27 and is the current default. Because weights are Apache-2.0 you may deploy commercially, redistribute, and fine-tune (subject to attribution). Source: model card.
• Training data & provenance. "Few hundred hrs" for v1.0, trained exclusively on permissive / non-copyrighted material: public-domain audio, Apache/MIT-licensed content, and synthetic audio generated by closed TTS models, plus <1 hr from Koniwa (CC BY 3.0) and <11 hrs from SIWIS (CC BY 4.0). Reported training cost ≈ $1000 (~1000 A100-80GB GPU-hours). The heavy reliance on synthetic data is the root cause of Kokoro's flat prosody and its uneven non-English quality — keep it in mind. Source: model card.
• Output. 24 kHz mono audio. Sample rate is fixed at 24000 Hz. Source: model card.
• Coverage. v1.0 ships 8 languages and 54 voices (American + British English count as one language). Sources: model card, VOICES.md.

When to use Kokoro vs. when not to

Reach for Kokoro when:

• You need cost-free, high-volume English narration (audiobooks, course/video voiceover, batch document-to-speech, screen readers). Marginal cost is electricity.
• The pipeline is offline or privacy-constrained — medical, legal, on-device, air-gapped — and no text may be sent to a cloud API.
• You want in-browser / on-device TTS with no server (kokoro-js + WebGPU/WASM).
• You are prototyping and want a good-enough voice today without provisioning a paid provider.

Do NOT use Kokoro (and tell the user so) when the job needs:

• Voice cloning / a specific person's voice. Kokoro has no speaker encoder and no zero-shot cloning. The encoder was deliberately not released. You cannot clone a reference voice. Route to a cloning-capable provider.
• Emotional or character performance — laughter, crying, shouting, sarcasm, dynamic delivery. Kokoro has no emotion/style tokens and a narrow prosodic range; output is competent but flat. Fine for a neutral narrator, wrong for a video-game character.
• High-fidelity non-English or many languages. Non-English voices are mostly C/D-graded and trained on little data (see quality grades below); several languages also truncate long text. English is the only tier-1 language.
• Conversational agents that need real-time bidirectional dialogue with barge-in and personality. Kokoro is a batch/streaming synthesizer, not a dialog voice.

If the request is voice cloning or emotional VO, do not try to fake it with blending or prompt tricks — state the limitation plainly and suggest a cloning/expressive provider.

Voices, language codes, and quality grades

Voice IDs follow [langprefix][gender]_[name], e.g. af_heart = American Female "Heart", bm_george = British Male "George", if_sara = Italian Female "Sara".

Language codes (pass as lang_code in Python; aliases en-us→a, en-gb→b):

Source: VOICES.md.

Quality is not uniform — pick by grade, not by name. VOICES.md assigns each voice an "Overall" grade combining a target-quality letter and how much training audio it received (more audio = higher grade). Documented highlights (verified 2026-07-10):

• Best English female: af_heart (grade A, the card's default), af_bella (A−), af_nicole (B−, breathy/ASMR), bf_emma (B−, British).
• Solid English: af_aoede, af_kore, af_sarah, am_fenrir, am_michael, am_puck (all C+). bm_fable, bm_george (C, British male).
• Avoid unless you have a reason: many voices grade C or below; e.g. am_adam (F+), af_jessica / af_river (D). Most non-English voices are C/D, trained on ~minutes of synthetic data.

Production heuristic: default to af_heart (lang a). For a project the user should audition 3–4 A/B-graded voices before committing — grades predict, they do not guarantee, per-sentence quality.

Text length, chunking, and long-form synthesis

Documented limit: Kokoro processes at most 510 phonemized tokens per forward pass (512 with boundary tokens). VOICES.md notes voices "perform best on a goldilocks range of 100–200 tokens," are weak on very short utterances (<10–20 tokens)**, and **rush on long ones (>400). Source: model card / VOICES.md.

Consequences for production:

• Never feed a whole chapter as one string. Split into sentences/paragraphs and stitch.
• The Python KPipeline splits automatically; its split_pattern defaults to r'\n+' for English and returns one (graphemes, phonemes, audio) result per chunk, which you concatenate. Source: pipeline.py.
• Non-English chunking is not fully implemented. Long non-English text can be truncated unless you pre-split it yourself (insert \n at sentence boundaries). This is a common silent-failure trap — verify non-English output length.
• Heuristic for clean long-form: chunk to roughly 100–250 tokens at sentence boundaries (≈ one to three sentences), synthesize each, and concatenate with a short silence pad. Kokoro-FastAPI's defaults (~175 target / 250 / 450 absolute max tokens) are a reasonable starting point if you build your own splitter.

Pronunciation control (misaki + espeak-ng)

Kokoro does not read graphemes directly — text is converted to phonemes by misaki, hexgrad's G2P library, then fed to the model. English uses misaki's dictionary (spaCy + num2words). Out-of-dictionary words fall back to espeak-ng (EspeakFallback, on by default); espeak-ng is also the backbone for non-English G2P. Install espeak-ng as a system dependency or OOV words degrade to letter-by-letter spelling. Documented example: with fallback, eBook → ˈi bˈʊk; without it, → ˈiː bˈi ˈoʊ ˈoʊ kˈeɪ (spelled out). Source: misaki README.

To fix a mispronounced word (proper noun, brand, acronym, number read wrong):

1. Inline phoneme override — misaki accepts a markdown-like syntax [word](/phonemes/), e.g. [Misaki](/misˈɑki/) or [Kokoro](/kˈOkəɹO/). Put the IPA/Kokoro phonemes between the slashes; stress marks like ˈ matter.
2. Phonemize once, reuse — generate phonemes with misaki, hand-correct, and pass phonemes directly to the model so a batch job stays consistent.
3. Spell it out in text — reword ("A-P-I", "twenty twenty-six") when phonemes are overkill.

Heuristic: always dry-run domain jargon, names, and numbers before a long batch — these are Kokoro's most common error class, and each is a one-line phoneme fix.

Voice blending (mixing)

A Kokoro "voice" is a style vector (voicepack tensor). Blending is a weighted average of two style vectors, which produces a new usable voice. The documented mechanism is a weighted numpy add, style1*(w0/100) + style2*(w1/100), with weights normalized if they don't sum to 100; several tools cap blending at exactly two voices. Source: nazdridoy/kokoro-tts voice-blending docs.

• In Kokoro-FastAPI, request a blend by combining voice IDs: voice="af_sky+af_bella" (equal), or weighted per that server's syntax. Source: remsky/Kokoro-FastAPI.
• In native Python you can load two voicepack tensors and average them yourself for full control (any ratio; nothing forces a 2-voice cap if you write the math).

Use blending to: nudge timbre/pitch between two graded voices, or build a house voice that isn't any single shipped one. It does not add emotion, create a new speaker identity from a reference, or rescue a low-grade voice — averaging two C-grade voices yields a C-grade blend.

Runtimes — pick by deployment target

1. Python kokoro package (default for servers/batch)

Best for narration pipelines, audiobooks, and anything on your own box. PyTorch backend; GPU optional. Example (labeled example — adapt paths/voices):

# pip install kokoro>=0.9.2 soundfile   ; plus system espeak-ng
from kokoro import KPipeline
import soundfile as sf
import numpy as np

pipeline = KPipeline(lang_code='a')          # 'a' = American English
text = "The quarterly report is ready.\nRevenue rose twelve percent."

chunks = []
for graphemes, phonemes, audio in pipeline(text, voice='af_heart', speed=1.0):
    chunks.append(audio)                     # one result per split (default r'\n+')

sf.write('out.wav', np.concatenate(chunks), 24000)   # 24 kHz mono

Why structured this way: KPipeline does G2P + chunking + inference; iterating yields per-chunk audio you concatenate, which is exactly the long-form pattern above. speed (~0.8–1.3) trades pace for naturalness. For lower-level control, KModel runs a single already-phonemized chunk. Source: model card, Python API.