---

A Home Assistant custom integration for connecting to Kokoro FastAPI, enabling high-quality local Text-to-Speech. Easily send TTS audio to your speakers or media players directly from Home Assistant.

🎧 Listen to a preview: ▶ Play

---

📑 Quick Links

• 📑 Quick Links
• ✨ Features
• 📦 Installation
  • HACS (recommended)
  • Manual
• ⚙️ Configuration
  • Configuration Options
  • 👨👩 Personas
  • Setup Steps
  • YAML Configuration (Legacy)
• ▶️ Usage
• 🛠 Troubleshooting
  • Connection errors during setup
  • Voice/persona not changing after options update
  • Per-call option overrides
• 🙏 Credits

---

✨ Features

• 🔊 Convert text to speech using Kokoro FastAPI
• ⚡ Low-latency responses for near real-time playback
• 🎙️ Voice selection with per-call overrides
• 🔧 Configurable server URL and parameters
• 🏠 Works with any Home Assistant media_player entity
• ✅ Connection test during setup — validates server reachability before configuring
• 🔄 Options changes take effect immediately — no restart required
• 🌐 Automatic lang_code detection for optimal multilingual support

---

📦 Installation

HACS (recommended)

1. Go to HACS → Integrations → Custom repositories.

2. Add this repository: https://github.com/beecho01/Kokoro-TTS with category Integration.

3. Either search for Kokoro-TTS in HACS or tap the below button:

   

4. Tap Download and then Install.

5. Then tap next setup quick-link below to complete the setup configuration:

   

6. Configure the Kokoro TTS integration as desired.

Manual

1. Download the latest release from Releases.
2. Copy the folder custom_components/kokoro_tts into your Home Assistant custom_components directory.
3. Restart Home Assistant.
4. Go to Settings → Devices & services.
5. Click the Add Configuration button.
6. Search for Kokoro TTS and select it.
7. Configure the Kokoro TTS integration as desired.

---

⚙️ Configuration

The integration can be configured through Home Assistant's UI with automatic discovery of available models and voices from your Kokoro FastAPI server.

Configuration Options

Option	Description	Default	Range/Options
base_url	Kokoro FastAPI server URL	Required	Valid HTTP/HTTPS URL
api_key	Authentication key	"not-needed"	Any string
model	TTS model to use	"kokoro"	Auto-discovered or custom
language	Language filter for voices	"All Languages"	All Languages, American English, British English, Japanese, etc.
sex	Sex filter for voices	"All"	All, Female, Male
persona	Voice persona/character	Required	Auto-discovered from server
speed	Speech speed multiplier	1.0	0.25 - 4.0
format	Audio format	"mp3"	mp3, wav, opus, flac, pcm
sample_rate	Audio sample rate	24000	22050, 24000, 44100

👨👩 Personas

Language	Sex	Name	Preview	Persona Code
American English 🇺🇸	Female	Heart	▶ Play	af_heart
American English 🇺🇸	Female	Alloy	▶ Play	af_alloy
American English 🇺🇸	Female	Aoede	▶ Play	af_aoede
American English 🇺🇸	Female	Bella	▶ Play	af_bella
American English 🇺🇸	Female	Jessica	▶ Play	af_jessica
American English 🇺🇸	Female	Kore	▶ Play	af_kore
American English 🇺🇸	Female	Nicole	▶ Play	af_nicole
American English 🇺🇸	Female	Nova	▶ Play	af_nova
American English 🇺🇸	Female	River	▶ Play	af_river
American English 🇺🇸	Female	Sarah	▶ Play	af_sarah
American English 🇺🇸	Female	Sky	▶ Play	af_sky
American English 🇺🇸	Male	Adam	▶ Play	am_adam
American English 🇺🇸	Male	Echo	▶ Play	am_echo
American English 🇺🇸	Male	Eric	▶ Play	am_eric
American English 🇺🇸	Male	Fenrir	▶ Play	am_fenrir
American English 🇺🇸	Male	Liam	▶ Play	am_liam
American English 🇺🇸	Male	Michael	▶ Play	am_michael
American English 🇺🇸	Male	Onyx	▶ Play	am_onyx
American English 🇺🇸	Male	Puck	▶ Play	am_puck
American English 🇺🇸	Male	Santa	▶ Play	am_santa
British English 🇬🇧	Female	Alice	▶ Play	bf_alice
British English 🇬🇧	Female	Emma	▶ Play	bf_emma
British English 🇬🇧	Female	Isabella	▶ Play	bf_isabella
British English 🇬🇧	Female	Lily	▶ Play	bf_lily
British English 🇬🇧	Male	Daniel	▶ Play	bm_daniel
British English 🇬🇧	Male	Fable	▶ Play	bm_fable
British English 🇬🇧	Male	George	▶ Play	bm_george
British English 🇬🇧	Male	Lewis	▶ Play	bm_lewis
Japanese 🇯🇵	Female	Alpha	▶ Play	jf_alpha
Japanese 🇯🇵	Female	Gongitsune	▶ Play	jf_gongitsune
Japanese 🇯🇵	Female	Nezumi	▶ Play	jf_nezumi
Japanese 🇯🇵	Female	Tebukuro	▶ Play	jf_tebukuro
Japanese 🇯🇵	Male	Kumo	▶ Play	jm_kumo
Mandarin Chinese 🇨🇳	Female	Xiaobei	▶ Play	zf_xiaobei
Mandarin Chinese 🇨🇳	Female	Xiaoni	▶ Play	zf_xiaoni
Mandarin Chinese 🇨🇳	Female	Xiaoxiao	▶ Play	zf_xiaoxiao
Mandarin Chinese 🇨🇳	Female	Xiaoyi	▶ Play	zf_xiaoyi
Mandarin Chinese 🇨🇳	Male	Yunjian	▶ Play	zm_yunjian
Mandarin Chinese 🇨🇳	Male	Yunxi	▶ Play	zm_yunxi
Mandarin Chinese 🇨🇳	Male	Yunxia	▶ Play	zm_yunxia
Mandarin Chinese 🇨🇳	Male	Yunyang	▶ Play	zm_yunyang
Spanish 🇪🇸	Female	Dora	▶ Play	ef_dora
Spanish 🇪🇸	Male	Alex	▶ Play	em_alex
Spanish 🇪🇸	Male	Santa	▶ Play	em_santa
French 🇫🇷	Female	Siwis	▶ Play	ff_siwis
Hindi 🇮🇳	Female	Alpha	▶ Play	hf_alpha
Hindi 🇮🇳	Female	Beta	▶ Play	hf_beta
Hindi 🇮🇳	Male	Omega	▶ Play	hm_omega
Hindi 🇮🇳	Male	Psi	▶ Play	hm_psi
Italian 🇮🇹	Female	Sara	▶ Play	if_sara
Italian 🇮🇹	Male	Nicola	▶ Play	im_nicola
Brazilian Portuguese 🇧🇷	Female	Dora	▶ Play	pf_dora
Brazilian Portuguese 🇧🇷	Male	Alex	▶ Play	pm_alex
Brazilian Portuguese 🇧🇷	Male	Santa	▶ Play	pm_santa

Setup Steps

1. Add Integration: Go to Settings → Devices & services → Add Integration → Search for "Kokoro TTS"

2. Server Connection (validated automatically):

   • Base URL: Your Kokoro FastAPI server URL (e.g., http://localhost:8880)
   • API Key: Optional authentication key (leave as not-needed if not required)
   • The integration will test the connection before proceeding — if it fails, you'll see a specific error message

3. Voice & Model Selection:

   • Model: Automatically discovered from /v1/models endpoint (defaults to "kokoro")
   • Language Filter: Filter personas by language (All Languages, American English, British English, etc.)
   • Sex Filter: Filter personas by sex (All, Female, Male)
   • Voice/Persona: Select from filtered list of available personas
   • Speed: Playback speed (0.25x to 4.0x, default: 1.0)
   • Format: Audio format (mp3, wav, opus, flac, pcm)
   • Sample Rate: Audio sample rate (22050, 24000, 44100 Hz)

Changing options? Any changes made via Settings → Devices & Services → Configure take effect immediately — no Home Assistant restart is required.

YAML Configuration (Legacy)

⚠️ YAML configuration is no longer supported. Please use the UI configuration flow instead. If you previously used YAML, remove the kokoro_tts entry from your configuration.yaml and set up the integration through the UI.

---

▶️ Usage

Voice Assistant

Note

Work in Progress

Triggered action

action: tts.speak
data:
  media_player_entity_id: media_player.living_room_speaker
  message: 'Hello from Kokoro Text-to-Speech!'
  cache: false
  language: en
target:
  entity_id: tts.kokoro

---

🛠 Troubleshooting

Connection errors during setup

Error	Cause	Fix
Cannot connect to the server	Server not reachable	Check the URL, ensure the server is running, and verify network connectivity
Connection timed out	Server too slow to respond	Check server load; increase timeout if server is slow to start
SSL error	Certificate issue	Check your reverse proxy / SSL certificate settings
Server not found	URL points to wrong endpoint	Ensure the URL points to the Kokoro FastAPI root (e.g. http://192.168.0.1:8880)
Authentication failed	Wrong API key	Check your API key matches the server's configured key

Voice/persona not changing after options update

Options changes take effect immediately without a restart. If the voice doesn't change, try:

1. Go to Settings → Devices & Services → Kokoro TTS → Configure
2. Change the persona and click Submit
3. The TTS entity reloads automatically with the new settings

Per-call option overrides

You can override the default persona, speed, format, and volume on a per-call basis:

action: tts.speak
data:
  media_player_entity_id: media_player.living_room_speaker
  message: "Hello from Kokoro!"
  options:
    persona: af_bella
    speed: 1.5
    format: mp3
    volume_multiplier: 1.5
target:
  entity_id: tts.kokoro

Option	Description	Default	Range
persona	Voice persona code	Config default	Any discovered persona
speed	Speech speed multiplier	1.0	0.25 – 4.0
format	Audio format	mp3	mp3, wav, opus, flac, pcm
sample_rate	Audio sample rate (Hz)	24000	22050, 24000, 44100
volume_multiplier	Volume multiplier	1.0	Any positive float

---

🙏 Credits

Kokoro FastAPI backend: @remsky