ovos-tts-plugin-kokoro

POC status — experimental, not for production, may be abandoned. No API stability promise.

OVOS TTS plugin for Kokoro — an 82M parameter multilingual TTS model by hexgrad. Same engine used by VoiceMode, now wired up for the standard OVOS voice assistant.

Install

pip install ovos-tts-plugin-kokoro

espeak-ng is required for the underlying G2P stack:

# Debian/Ubuntu
sudo apt-get install espeak-ng
# macOS
brew install espeak-ng

English voices also need spaCy's en_core_web_sm model. Misaki (the Kokoro G2P library) attempts to download it on first use but does not reload it in the same process, so you'll want to install it ahead of time:

python -m spacy download en_core_web_sm

For Japanese or Chinese voices, install the optional G2P extras:

pip install "ovos-tts-plugin-kokoro[ja,zh]"

Linux: CPU-only torch (saves ~2GB)

On Linux, pip defaults to the CUDA torch wheel (~2.5GB). If you don't need GPU support, install torch from the CPU index first:

pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install ovos-tts-plugin-kokoro

On macOS, this is not needed — PyPI torch is already CPU-only (~60MB). With uv, torch automatically resolves to the CPU-only wheel via the tool.uv.sources block in pyproject.toml.

Configuration

{
  "tts": {
    "module": "ovos-tts-plugin-kokoro",
    "ovos-tts-plugin-kokoro": {
      "voice": "af_bella"
    }
  }
}

Voice options

Kokoro ships 56 built-in voices across 9 languages. The voice id encodes language + gender:

The voice id determines which Kokoro language pipeline is used, regardless of the OVOS active language. Picking bm_george will speak through the British pipeline even if lang is en-US.

See the full hexgrad/Kokoro-82M VOICES.md for samples.

Language support

The plugin maps the active OVOS language (BCP-47, e.g. fr-FR) to a Kokoro single-letter language code:

Lookup tries the full BCP-47 tag first (e.g. en-gb), then falls back to the base subtag, then to American English. Unknown languages fall back to American English with a log line. The voice id always wins over the language map — a voice prefixed bm_ always uses the British pipeline.

Override the language map

{
  "tts": {
    "module": "ovos-tts-plugin-kokoro",
    "ovos-tts-plugin-kokoro": {
      "voice": "af_bella",
      "speed": 1.0,
      "language_aliases": {
        "en": "b"
      },
      "preload_languages": ["en", "fr"]
    }
  }
}

Memory note: Each loaded language pipeline holds the 82M parameter model + a g2p stack. The plugin caches one pipeline per (language, device) pair, so leaving preload_languages empty and letting the cache warm on demand keeps the resident set small.

Apple Silicon note: Despite MPS being available on M-series Macs, CPU is the fastest device for Kokoro on Apple Silicon. The vocoder leans heavily on torch.stft/istft, which are weak spots on the Metal backend — measured RTF on an M3 Max was ~0.08 on CPU vs ~0.40 on MPS. The default of "cpu" is intentional; only set device to "cuda" if you actually have a discrete NVIDIA GPU.

Lip sync (visemes)

The plugin returns phoneme timing alongside the audio, so enclosures with a mouth (the Mark 1 and the virtual Mark 1) animate in sync with the voice without a G2P plugin.

Kokoro's model predicts a duration for every phoneme it speaks. The plugin converts those predictions into the OVOS phoneme:end_time format (lowercase ARPAbet keys, cumulative seconds), including the leading silence the model adds before speech. ovos-audio turns that into enclosure.mouth.viseme_list messages.

This is more accurate than the G2P fallback path, which guesses a constant duration per phoneme. If timing is ever unavailable the plugin returns no phonemes and OVOS falls back to the configured G2P plugin, if any.

Non-English voices work too: every sound in Kokoro's phoneme alphabet maps to the nearest English mouth shape.

License

Apache-2.0