README.md

---

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
• 🚀 Streaming synthesis — speech starts on the first sentence, while a conversation agent is still writing
• 🎙️ Voice selection with per-call overrides
• 🎛️ Voice blending — combine multiple personas (equal or weighted) into a custom voice
• 🔧 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

🎛️ Voice Blending

Kokoro FastAPI supports blending multiple voices into a single custom voice. Instead of picking a persona from the dropdown during setup or options configuration, type a custom value into the Persona field:

Syntax	Result
af_bella+af_sky	Equal blend of Bella and Sky
af_bella(2)+af_sky(1)	Weighted blend — 67% Bella, 33% Sky

The same syntax works for the per-call persona option (see Per-call option overrides). Blending works best between voices of the same language, since the lang_code sent to the API is derived from the first voice's prefix (or from the language you've configured).

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. Filter Voices — choose a model and narrow the list before you see it:

   • 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)
   • Click Next — this is a separate step because Home Assistant's setup forms don't live-filter as you change a dropdown; submitting is what applies the filter.

4. Select Persona — pick from the list filtered by the previous step:

   • Voice/Persona: Select from the 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

Kokoro gets used in two different ways, and it's worth knowing which is which:

• Conversation replies - you talk to Home Assistant's voice assistant, and an AI conversation agent writes a reply on the spot.
• Triggered/predefined text — a script, automation, or notification calls the tts.speak action with text you already wrote yourself, e.g. "Front door opened."

Triggered action (predefined text)

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

Conversation Agent

For conversation replies specifically, Kokoro starts speaking almost immediately instead of waiting for the AI to finish writing its whole answer - the longer the reply, the more time this saves. It works automatically and there's nothing to turn on, and nothing to configure.

One thing to know, however, if your audio format is set to wav or flac during the setup process, these don't work for streaming voice replies due to how they are generated, so Kokoro automatically uses mp3 for them instead. This means, that your setup will work exactly as you want for triggered/predefined text, but the conversation agent will automatically switch to use mp3 in this specific case.

---

🛠 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. Configure is a two-step form — a "Filter Voices" step (Model/Voice Accent/Sex) followed by a "Select Persona" step. Changing Voice Accent or Sex only takes effect once you click Next on that first step; the Persona list on the second step is filtered accordingly. If the voice doesn't change:

1. Go to Settings → Devices & Services → Kokoro TTS → Configure
2. On "Filter Voices", change the accent/sex as needed and click Next
3. On "Select Persona", pick the new persona and click Submit
4. 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