Setting Up Her Voice¶

File: configs/tts.yaml
Command: kenzy-tts [config_path]

This service is Kenzy's voice — text in, speech out. Out of the box it uses a cloud voice (OpenAI's TTS) because it needs zero downloads and sounds good on day one — but the voice can live entirely in your house: the Kokoro provider runs locally on your own hardware, and only what Kenzy says (never what you say) goes to a cloud provider in the default setup anyway.

provider: "openai"    # or "kokoro" — the local voice, no third party

Switching is a dropdown in the dashboard (Services → tts), and Running Fully Local walks the local path end to end, including the one system package Kokoro needs.

Pulled from the server

kenzy-tts pulls this config from the server at boot — it discovers the server via mDNS (or KENZY_SERVER_URL) and blocks until it answers, so start the server first. Edit it from the dashboard's Services tab (writes configs/services/tts.yaml on the server and restarts the service). Passing an explicit path loads locally instead (dev/offline). log_level (console) and log_capture_level (dashboard viewer depth, default debug) work like every service. See central config for backend services.

Advanced¶

Everything below is the full reference.

Service¶

Key	Default	Description
`host`	`"127.0.0.1"`	Bind address
`port`	`8769`	HTTP port

Provider selection¶

Key	Default	Description
`provider`	`"openai"`	TTS backend: `openai` or `kokoro`

OpenAI provider¶

Requires: OPENAI_API_KEY in .env

Long responses are automatically split at sentence boundaries and concatenated, so there is no effective limit on response length.

Key	Default	Description
`openai.model`	`"gpt-4o-mini-tts-2025-03-20"` (shipped config)	OpenAI TTS model
`openai.voice`	`"sage"`	Voice persona (see below)
`openai.speed`	`1.0`	Playback speed multiplier, 0.25–4.0
`openai.fallback`	`true`	On a cloud failure, silently retry with local Kokoro — only takes effect when the `kokoro` extra is installed (see below); otherwise the failure surfaces as the error cue.

Available voices¶

alloy · ash · ballad · coral · echo · fable · nova · onyx · sage · shimmer

Example¶

provider: "openai"

openai:
  model: "gpt-4o-mini-tts"
  voice: "nova"
  speed: 1.1

Kokoro provider¶

Requires: - The kokoro extra: pip install 'kenzy[kokoro]' (or pip install -e ".[kokoro]" in a source checkout) — installs the kokoro package and PyTorch - sudo apt-get install espeak-ng (system phonemization library) - Run kenzy-setup after install to pre-download model weights

Kokoro runs entirely locally with no API key or internet connection required at runtime. It produces high-quality speech and outputs at 24 kHz mono — the same format as the OpenAI provider, so nothing downstream changes.

Note

The voice_prompt style instruction generated by the LLM (e.g. "speak warmly at a conversational pace") is an OpenAI-specific feature. It is silently ignored when using Kokoro.

Key	Default	Description
`kokoro.voice`	`"af_heart"`	Kokoro voice name (see below)
`kokoro.device`	`"auto"`	Inference device (see below)
`kokoro.speed`	`1.0`	Playback speed multiplier, 0.5–2.0
`kokoro.lang_code`	(from voice)	Language code. Derived automatically from the first character of the voice name if omitted.

Device options¶

Value	Description
`auto`	Detects the best available device at startup: CUDA → MPS → CPU (recommended)
`cpu`	Always use CPU
`cuda`	NVIDIA GPU. Also covers AMD GPUs when using a ROCm-enabled PyTorch build.
`mps`	Apple Silicon GPU (M1/M2/M3/M4)

Voice names and languages¶

The voice name prefix determines the language:

Prefix	Language	Example voices
`af_`	American English (female)	`af_heart`, `af_bella`, `af_sky`
`am_`	American English (male)	`am_adam`, `am_michael`
`bf_`	British English (female)	`bf_emma`, `bf_isabella`
`bm_`	British English (male)	`bm_lewis`, `bm_george`

The lang_code is derived from the first character of the voice name (af_heart → 'a', bf_emma → 'b'). Set it explicitly only if you need to override this.

Example¶

provider: "kokoro"

kokoro:
  voice: "af_heart"
  device: "auto"
  speed: 1.0

Installation¶

# System dependency
sudo apt-get install espeak-ng

# Python package (or `pip install -e ".[kokoro]"` in a source checkout)
pip install 'kenzy[kokoro]'

# Pre-download model weights
kenzy-setup

Wyoming listener (Home Assistant voice pipelines)¶

Expose this service as a native HA text-to-speech provider, so Assist replies on your phone are spoken in Kenzy's actual voice — see On Your Phone for the full setup.

Key	Default	Description
`wyoming.enabled`	`false`	Start the Wyoming protocol listener alongside the HTTP service. Uses the exact same synthesis path (provider, voice, fallback chain) as `/speak`. Requires the `wyoming` package (included in the `tts` extra).
`wyoming.port`	`10200`	Listener port (the Piper convention, so HA operators guess right).

Wyoming is plain, unauthenticated TCP — the listener follows the service bind, so it stays loopback-only unless you've deliberately opened the service to the LAN (KENZY_BIND=0.0.0.0 / --listen-all).