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.

License

Apache-2.0