Hathora Voice for Home Assistant

A Home Assistant custom integration that provides Text-to-Speech (TTS) and Speech-to-Text (STT) capabilities using Hathora's hosted voice models.

Features

• Text-to-Speech (TTS): Convert text to natural-sounding speech using Hathora's Kokoro TTS model
• Speech-to-Text (STT): Transcribe audio to text using Hathora's Parakeet STT model
• Voice Assistant Integration: Works seamlessly with Home Assistant's Assist voice assistant
• Multiple Voices: Choose from various voice options for TTS
• Configurable Speed: Adjust speech speed from 0.25x to 4x

Requirements

• Home Assistant 2024.1.0 or newer
• A Hathora account with API access (get your token at models.hathora.dev)

Installation

HACS (Recommended)

1. Open HACS in your Home Assistant instance
2. Click on "Integrations"
3. Click the three dots in the top right corner
4. Select "Custom repositories"
5. Add the repository URL: https://github.com/hathora/ha-hathora-voice
6. Select "Integration" as the category
7. Click "Add"
8. Search for "Hathora Voice" and install it
9. Restart Home Assistant

Manual Installation

1. Download the latest release from the releases page
2. Extract the custom_components/hathora_voice folder to your Home Assistant's custom_components directory
3. Restart Home Assistant

Configuration

1. Go to Settings → Devices & Services
2. Click + Add Integration
3. Search for "Hathora Voice"
4. Enter your configuration:
   • API Token: Your Hathora API bearer token
   • TTS API Base URL: Default is https://model-marketplace-api-dev.fly.dev
   • STT API Base URL: Your Hathora STT endpoint URL
5. Configure TTS settings:
   • TTS Model: Select the TTS model (default: hexgrad-kokoro-82m)
   • Voice: Select your preferred voice (default: af_bella)
   • Speed: Set speech speed multiplier (default: 1.0)

Usage with Assist

Once configured, you can use Hathora Voice with Home Assistant's Assist voice assistant:

1. Go to Settings → Voice assistants
2. Create or edit an assistant
3. Select "Hathora TTS" for Speech-to-text and Text-to-speech

Available Voices

Voice ID	Description
af_bella	American Female - Bella
af_nicole	American Female - Nicole
af_sarah	American Female - Sarah
af_sky	American Female - Sky
am_adam	American Male - Adam
am_michael	American Male - Michael
bf_emma	British Female - Emma
bf_isabella	British Female - Isabella
bm_george	British Male - George
bm_lewis	British Male - Lewis

Troubleshooting

Common Issues

"Invalid API token" error

• Verify your API token is correct and hasn't expired
• Get a fresh token from models.hathora.dev

"Failed to connect to Hathora API" error

• Check your internet connection
• Verify the API endpoints are correct
• Ensure the Hathora service is available

No audio output from TTS

• Check Home Assistant logs for errors
• Verify your media player supports WAV audio
• Try a different voice option

Debug Logging

To enable debug logging, add the following to your configuration.yaml:

logger:
  default: info
  logs:
    custom_components.hathora_voice: debug

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Hathora for providing the voice model APIs
• The Home Assistant community for their excellent documentation and examples

hacs-hathora-voice