kokoro-mlx

Kokoro TTS inference on Apple Silicon via MLX.

An MLX implementation of the Kokoro-82M text-to-speech pipeline, with no PyTorch or transformers dependency.

This package provides inference code only. Model weights are developed by hexgrad under the Apache 2.0 license and downloaded separately from HuggingFace Hub on first use.

Quick Start

Apple Silicon required. Python 3.10–3.12, MLX 0.32+.

pip install kokoro-mlx

from kokoro_mlx import KokoroTTS

tts = KokoroTTS.from_pretrained()
tts.speak("Hello, world.")

Model weights download automatically from HuggingFace Hub on first use.

Features

• On-device via MLX. No server, no network during inference.
• No PyTorch or transformers dependency.
• 48 kHz output from native 24 kHz via FFT upsampling.
• Mixed-precision vocoder: bf16 through the network, float32 for waveform reconstruction.
• Gapless streaming over a single persistent audio stream.
• 54 voices across American English, British English, and additional languages.
• Language-aware G2P inferred from the voice prefix, with explicit language override.
• WAV export in one call.
• Thread-safe with internal lock for concurrent callers.
• Context manager for resource cleanup.
• Speed control via a single multiplier.

API

KokoroTTS.from_pretrained(model_id_or_path)

Load a model from a local directory or the HuggingFace Hub.

tts = KokoroTTS.from_pretrained()
# or a specific repo
tts = KokoroTTS.from_pretrained("mlx-community/Kokoro-82M-bf16")
# or a local directory
tts = KokoroTTS.from_pretrained("/path/to/model")

tts.generate(text, voice, speed, sample_rate, language) -> TTSResult

Synthesize text and return a TTSResult.

tts.generate_stream(text, voice, speed, sample_rate, language) -> Iterator[np.ndarray]

Synthesize text and yield audio chunks sentence by sentence. Lower latency than generate for longer inputs.

tts.speak(text, voice, speed, stream, stop_event, sample_rate, language)

Synthesize and immediately play text through the speakers.

tts.save(text, path, voice, speed, sample_rate, language) -> TTSResult

Synthesize text and write audio to a WAV file.

result = tts.save("Hello, world.", "output.wav", sample_rate=48000)

Language Selection

Default behavior: kokoro-mlx infers G2P language from the voice prefix.

Japanese and Mandarin need their optional G2P extras:

pip install "kokoro-mlx[ja]"
pip install "kokoro-mlx[zh]"

Override language when the text and voice prefix intentionally differ:

tts.generate("Bonjour.", voice="ff_siwis", language="fr")

tts.list_voices() -> list[str]

Return a sorted list of all available voice names.

voices = tts.list_voices()
# ['af_alloy', 'af_aoede', 'af_bella', ...]

tts.close()

Release held resources. Called automatically when using the context manager.

with KokoroTTS.from_pretrained() as tts:
    tts.save("Hello, world.", "output.wav")

TTSResult

@dataclass
class TTSResult:
    audio: np.ndarray   # float32
    sample_rate: int    # 24000 or 48000
    duration: float     # seconds
    voice: str          # voice name used

Available Voices

Voice names follow a prefix convention: the first two characters identify the accent and gender.

American English (Female): af_alloy, af_aoede, af_bella, af_heart (default), af_jessica, af_kore, af_nicole, af_nova, af_river, af_sarah, af_sky

American English (Male): am_adam, am_echo, am_eric, am_fenrir, am_liam, am_michael, am_onyx, am_puck, am_santa

British English (Female): bf_alice, bf_emma, bf_isabella, bf_lily

British English (Male): bm_daniel, bm_fable, bm_george, bm_lewis

Architecture

Text Input
  │
  ▼
G2P / Phonemizer (misaki)
  │
  ▼
Phoneme Sequence
  │
  ▼
TextEncoder (PL-BERT / ALBERT, 12 layers, 768 hidden)
  │
  ▼
ProsodyPredictor (duration + pitch)
  │
  ├── Voice Style Vector (per-voice, 256-dim)
  │
  ▼
Decoder (StyleTTS2-style, AdaIN + residual blocks)
  │
  ▼
iSTFTNet Vocoder (harmonic source + inverse STFT → 24 kHz waveform)
  │
  ▼
Optional 2x FFT upsample (24 kHz → 48 kHz)
  │
  ▼
TTSResult { audio float32, duration, voice }

Inference runs in float32 end to end. Checkpoints and voices stored in bfloat16 or float16 are upcast on load, and the numerically sensitive steps (instance and layer normalization statistics, the harmonic source phase, and the inverse STFT) always compute in float32, so reduced-precision weights cannot turn the output into NaN or silence.

Requirements

• Apple Silicon Mac (M1 or later)
• macOS 13+
• Python 3.10–3.12
• MLX 0.32+

Development

git clone https://github.com/gabrimatic/kokoro-mlx.git
cd kokoro-mlx
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
python -m pytest tests/ -v
ruff check src/ tests/

Skip model-loading tests with -m "not slow".

Credits

Kokoro-82M by hexgrad · MLX by Apple · misaki G2P by hexgrad · MLX weights from mlx-community

License

This inference code is released under the MIT License. See LICENSE for details.

The model weights have their own license (Apache 2.0). See Model License above.

Created by Soroush Yousefpour