Kokoro TTS in Node.js
@micdrop/kokoro runs Kokoro TTS, a local text to speech model, for
@micdrop/server inside your Node process, so the voice is
generated on your machine without an API key or a separate server. The
package loads Kokoro through
kokoro-js,
Transformers.js and ONNX Runtime.
Kokoro is an 82 million parameter model, small enough to download in seconds and to sit next to an LLM in memory, with a quality well above what its size suggests. It only turns text into speech, so the answers of a call come from a separate language model, which you can run locally with Ollama.
Installation
npm install @micdrop/kokoroUsage with MicdropServer
import { KokoroTTS } from '@micdrop/kokoro'import { MicdropServer } from '@micdrop/server'
const tts = new KokoroTTS({ voice: 'britishFemale',})
// Use with MicdropServernew MicdropServer(socket, { tts, // ... other options})Usage without MicdropServer
import { KokoroTTS } from '@micdrop/kokoro'import { Readable } from 'stream'
const tts = new KokoroTTS({ voice: 'britishFemale',})
// Audio is raw PCM, 16 bits, 16 kHz, monotts.on('Audio', (chunk) => console.log('Audio:', chunk.length, 'bytes'))tts.on('Failed', (texts) => console.error('Failed:', texts))
tts.speak(Readable.from(['Hello! ', 'What can I do for you?']))Events
| Event | Payload | Description |
|---|---|---|
Audio | Buffer | A chunk of audio, PCM 16 bits, 16 kHz, mono, ready to be played. |
Failed | string[] | Synthesis gave up after its retries, with the text that stayed unspoken. |
See the TTS interface for the full contract.
Options
| Option | Type | Default | Description |
|---|---|---|---|
model | string | 'onnx-community/Kokoro-82M-v1.0-ONNX' | Repository holding the ONNX export |
voice | string | 'americanFemale' | Shorthand or Kokoro voice id |
speed | number | 1 | Speech rate, above 1 to speak faster |
dtype | string | 'q8' | Weight precision |
device | string | 'cpu' | Execution provider passed to Transformers.js |
warmup | boolean | true | Synthesizes one word at startup |
Voices
Kokoro TTS holds 28 English voices in one checkpoint, so switching voice costs
nothing at runtime. The first two letters of a voice id give the accent and the
gender: af and am are American female and male, bf and bm British
female and male.
Hexgrad, who trained Kokoro, grades every voice from A to F. The table lists
the ids of each group from the best grade to the lowest. Each shorthand resolves
to a top graded voice of its group: af_heart, am_michael, bf_emma and
bm_george.
| Group | Shorthand | Voice ids and grades |
|---|---|---|
| American female | americanFemale | af_heart A, af_bella A-, af_nicole B-, af_aoede C+, af_kore C+, af_sarah C+, af_alloy C, af_nova C, af_sky C-, af_jessica D, af_river D |
| American male | americanMale | am_michael C+, am_fenrir C+, am_puck C+, am_echo D, am_eric D, am_liam D, am_onyx D, am_santa D-, am_adam F+ |
| British female | britishFemale | bf_emma B-, bf_isabella C, bf_alice D, bf_lily D |
| British male | britishMale | bm_george C, bm_fable C, bm_lewis D+, bm_daniel D |
Any id of the table works as voice. KOKORO_VOICE_IDS exports the full
list.
import { KOKORO_VOICE_IDS, KokoroTTS } from '@micdrop/kokoro'
const tts = new KokoroTTS({ voice: 'am_michael' })Kokoro speaks English only in Micdrop
The upstream model also holds French, Italian, Japanese, Portuguese and Chinese
voices, which @micdrop/kokoro leaves out. Kokoro takes phonemes as input.
kokoro-js produces them with English rules only, American for the a voices
and British for the b voices, so a French voice would read French text with
an English pronunciation.
For a call in another language, use Phonon, which speaks French, German, Spanish and Portuguese inside Node, or Piper, which covers 53 languages.
Latency
Synthesis runs at roughly half to three quarters of real time on a MacBook Pro
M2, so a three second sentence takes about two seconds to generate and a short
greeting comes back in about one second. On that machine, the first sentence
of an answer takes 900 to 1300 ms. In a full turn with Whisper base and
Qwen3 4B, the user hears the first word 1.4 to 1.9 seconds after they stop
talking. Piper and Pocket TTS take 250 to 430 ms for the same first sentence, and
Phonon 30 to 100 ms.
We measured every step of a local turn for each
model.
Kokoro sounds better than Piper in English, so the choice comes down to voice quality against latency between Kokoro, Piper and Pocket TTS.
Micdrop cuts the answer into sentences and synthesizes each one as soon as it is complete, so the user hears the opening while the rest is still being written. The sentences are synthesized one at a time. The model is single threaded, so running two sentences in parallel slows both down and brings the first word no sooner.
Devices
cpu is the default and, on a Mac, the fastest option, since Transformers.js
exposes no GPU device on macOS. On Windows, dml runs Kokoro through
DirectML. On Linux with an NVIDIA card, try cuda and
compare it with the CPU on your own server.
Choosing a dtype
dtype picks which ONNX export of the weights kokoro-js downloads from
onnx-community/Kokoro-82M-v1.0-ONNX.
dtype | Download | Effect |
|---|---|---|
q8 | 92 MB | The default. 8 bit weights, the smallest file and the fastest load on the CPU |
fp32 | 326 MB | Full precision. Loads several times slower than q8 for a nearly identical synthesis speed |
fp16 | 163 MB | Half precision, half the size of fp32 |
q4 | 305 MB | 4 bit weights on part of the graph only, so the file stays close to fp32 |
q4f16 | 155 MB | 4 bit weights with the rest in half precision |
Keep q8 on a CPU. Once loaded, Kokoro takes about 80 MB of memory, so a
lower precision would save almost nothing next to the LLM of the call.
Memory and startup
The model is loaded once per configuration and shared by every call. Loading
takes about a second and a half in q8. The first synthesis is slower while
the graph warms up, which is why warmup runs one word through the model while
the call is being set up.
Documentation
Kokoro also fits in a voice agent that runs entirely on local models, with a local LLM and local speech to text.
License
Kokoro TTS is free, commercial use included. The model is released under the Apache 2.0 license and runs on your own machine, so the only cost of a call is your own hardware.