Custom Home Assistant integration that uses an OVOS TTS Server as a text-to-speech backend. Use any OpenVoiceOS TTS plugin (Piper, Mimic, Coqui, etc.) as a Home Assistant TTS engine.
Built to the Home Assistant integration quality scale Platinum standard; see quality_scale.yaml for the rule-by-rule accounting. (The official scale badge only applies to core integrations.)
- Automatic v2/v1 API detection with caching
- Language discovery from the server's
/statusendpoint - Optional voice selection passed through to the TTS plugin
- SSL verification toggle for self-signed certificates
- Config flow with connection validation, reconfiguration support, and diagnostics
Any OVOS TTS Server (or ovos-tts-server-plugin compatible endpoint), regardless of which TTS plugin it wraps. Both the modern /v2/synthesize API and the legacy /synthesize/<utterance> API are supported; the integration probes v2 once and remembers the result.
- Open HACS in your Home Assistant instance
- Click the three dots in the top right corner and select Custom repositories
- Add
https://github.com/OscillateLabsLLC/ha-ovos-ttsas an Integration - Search for "OVOS TTS Server" and install it
- Restart Home Assistant
- Copy the
custom_components/ovos_ttsdirectory into your Home Assistantconfig/custom_componentsdirectory - Restart Home Assistant
- Go to Settings > Devices & Services > Add Integration
- Search for OVOS TTS Server
- Enter your server details (validated before the entry is created):
| Parameter | Required | Default | Description |
|---|---|---|---|
| Host | Yes | — | Hostname, IP, or full URL of the server (e.g. 192.168.1.100 or https://tts.example.com) |
| Port | Yes | 9666 |
Ignored when the host is an HTTPS URL on port 443 or already contains a port |
| Voice | No | server default | Default voice passed to the TTS plugin |
| Language | No | server default | Override the default language; must be one the server supports |
| Verify SSL certificate | No | on | Disable to allow self-signed certificates |
To change settings later, use the entry's Reconfigure option (⋮ menu on the integration card). Multiple servers can be added as separate entries.
There is no polling. Supported languages and the active plugin name are read from the server's /status endpoint when the entry is set up (and again on reload/reconfigure); audio is fetched on demand for each TTS request. If the server is unreachable at startup, setup retries automatically until it comes back.
Once configured, the OVOS TTS entity appears as a TTS service. Use it in:
- Automations — select the OVOS TTS entity in any TTS action
- Developer Tools — call
tts.speakwith the entity - Voice pipelines — set it as your TTS engine in Assist
action: tts.speak
target:
entity_id: tts.ovos_tts_piper
data:
media_player_entity_id: media_player.living_room
message: "The garage door has been open for ten minutes."
options:
voice: en_US-lessac-mediumThe voice option is optional and overrides the configured default for that call.
- "Unable to connect" during setup — verify the server is reachable from the Home Assistant host:
curl http://<host>:9666/statusshould return JSON. Check firewalls and that the port matches your server config. - Setup succeeds but speech fails — download diagnostics from the integration page (Settings > Devices & Services > OVOS TTS Server > ⋮ > Download diagnostics) and check the Home Assistant log for
custom_components.ovos_ttsentries. A failing synthesis raises a visible error in the calling automation/action. - Self-signed certificates — disable Verify SSL certificate in the config/reconfigure flow.
- Wrong or missing voices — voices are defined by the TTS plugin running on the server, not by this integration. Confirm the voice name against your server plugin's documentation.
- The OVOS TTS Server API is unauthenticated; put it behind a reverse proxy if you need access control.
- Available voices are not enumerable through the server API, so the voice field is free text rather than a dropdown.
- Language list is refreshed only at setup/reload, not continuously.
- Go to Settings > Devices & Services > OVOS TTS Server
- Open the ⋮ menu on the entry and select Delete
- If installed via HACS, remove the repository from HACS to delete the code, then restart Home Assistant
Removal leaves nothing behind on the OVOS TTS server (the integration is a pure client).
uv sync # install dev dependencies
uv run pytest # unit tests (100% coverage enforced at >=95%)
uv run ruff check .
uv run mypy # strict typing
python test_integration.py --tts-host http://<server> # optional end-to-end test in a Docker HA instance- A running OVOS TTS Server accessible from your Home Assistant instance
- Home Assistant 2024.11.0 or newer