Mastering Local Text-to-Speech in Home Assistant: Integrating Piper and Wyoming

While cloud-based text-to-speech (TTS) services like Google Cloud TTS or Amazon Polly are easy to use and offer high-quality voices, they come with inherent downsides: dependency on an internet connection, potential latency, privacy concerns (sending your text to a third party), and potential costs depending on usage.

For many Home Assistant users, the desire for a fully local, private, and reliable smart home extends to voice output. This is where local TTS engines shine. One prominent solution that has gained traction recently is Piper, a fast and lightweight neural text-to-speech system, integrated into Home Assistant via the innovative Wyoming protocol.

Why Choose Local TTS with Piper and Wyoming?

• Privacy: Your text never leaves your local network.
• Speed: Announcements are often faster as there's no round trip to the cloud.
• Reliability: Works even if your internet connection is down.
• Cost-Effective: No usage fees.
• Customization: Access to various voices (though selection is more limited than commercial cloud services).

The Wyoming protocol is a relatively new standard specifically designed for connecting voice assistants and services (like TTS, STT, Wake Word detection) locally. Home Assistant's voice features are increasingly leveraging this protocol.

Setting Up Piper and Wyoming in Home Assistant

Integrating Piper typically involves two main steps: running the Piper service (which implements the Wyoming protocol) and configuring the Wyoming integration in Home Assistant to connect to it.

Step 1: Run the Piper Service (Wyoming Server)

There are several ways to run the Piper service:

Option A: Home Assistant Add-on (Recommended for Home Assistant OS/Supervised)

This is the easiest method if you're running a supervised version of Home Assistant (like Home Assistant OS, Home Assistant Supervised):

1. Navigate to Settings > Add-ons.
2. Click on the Add-on Store button (bottom right).
3. Search for 'Piper'.
4. Install the official 'Piper' add-on.
5. (Optional but Recommended) Go to the Configuration tab of the add-on. You can specify which voices to download. This saves disk space compared to downloading all voices. For example, to download a US English voice, add something like:yaml
tts:
voices:
- name: en-us-amy-medium
Check the add-on documentation for available voice names.
6. Go to the Info tab and Start the add-on.
7. Enable 'Watchdog' and 'Auto update' for reliability.

Option B: Docker Container

If you're running Home Assistant Container or want to run Piper on a separate machine:

1. Ensure you have Docker installed.
2. Pull the Piper image (often available from repositories like 'rhasspy/piper-wyoming'). The exact command might vary; check the latest documentation for the specific image you're using (e.g., docker pull rhasspy/piper-wyoming).
3. Run the container. You'll need to expose the Wyoming protocol port (typically 10200) and potentially mount a volume for voices if you don't bake them into your custom image. A basic run command might look like:bash
docker run -d --name piper --restart unless-stopped -p 10200:10200 ghcr.io/rhasspy/piper-wyoming:latest
Refer to the container image's documentation for specifying voices during startup or configuration.

Option C: Manual Installation

For advanced users, you can install Piper and its dependencies manually on a compatible system and run the piper-record-tts or similar script as a service, ensuring it listens on a TCP socket using the Wyoming protocol on port 10200. This requires more technical expertise and service management.

Step 2: Configure the Wyoming Integration in Home Assistant

Once the Piper service is running and accessible on your network (default port 10200), you need to tell Home Assistant where to find it:

1. In Home Assistant, go to Settings > Devices & Services.
2. Click the '+ Add Integration' button.
3. Search for 'Wyoming'.
4. Select the 'Wyoming' integration.
5. Enter the IP address and port of the machine running the Piper service (e.g., a0d7b954-piper and 10200 if using the official add-on running on the same Home Assistant instance, or 192.168.1.10:10200 if running on another machine).
6. Click 'Submit'.
7. If the connection is successful, Home Assistant will discover the capabilities provided by the Piper service (in this case, TTS).
8. Click 'Finish'.

Home Assistant should now have a new TTS entity available, typically named something like tts.piper (or based on the add-on/service name).

Integration Tips and Usage

Now that Piper is integrated, you can use it throughout Home Assistant.

Using the TTS Service

The primary way to use TTS is via the tts.speak service. You can call this service from Developer Tools -> Services, or within automations and scripts.

Replace media_player.your_media_player with the actual entity ID of a media player device in your home (e.g., a Google Home speaker integrated via Google Cast, a Sonos speaker, a DLNA renderer, or even Home Assistant's built-in audio output if configured). The options: voice: parameter is used if your Piper instance supports multiple voices and you want to choose a specific one.

Setting a Default TTS Entity

You can set your Piper TTS entity as the default TTS provider in Home Assistant's configuration.yaml:

After setting this up and restarting Home Assistant, you can often omit the entity_id: tts.piper in service calls, as Home Assistant will use the default.

Using Templating in Messages

As shown in the example above, you can use Home Assistant's powerful templating engine within your TTS messages to announce dynamic information like sensor readings, states of devices, or greetings based on presence.

Multiple Voices

If your Piper installation provides multiple voices (either via the add-on configuration or how you set up the Docker/manual install), you can specify the desired voice in the options: voice: part of the tts.speak service call.

Best Practices for a Reliable Local TTS System

• Resource Management: Piper is generally efficient, but generating speech requires CPU resources, especially for longer messages or multiple simultaneous requests. Monitor the resource usage of the machine or add-on running Piper. If you experience delays or stutters, consider running Piper on more powerful hardware or optimizing your setup.
• Network Reliability: Ensure the network connection between your Home Assistant instance and the machine running Piper is stable. Wired connections are preferable for reliability, especially if running on a separate device.
• Voice Management: Only download and keep the voices you actually use. Voice files can be large and consume significant disk space.
• Caching: Use the cache: true option in your tts.speak service calls. Home Assistant will store the generated audio file and reuse it for identical messages, significantly reducing the load on the Piper service and speeding up repeated announcements (e.g., 'The front door is open').
• Fallback (Advanced): For critical announcements, you might consider having a cloud TTS service configured as a secondary option and use automation logic to fall back to it if the local Piper service is unavailable (e.g., ping the Piper host before calling the service).
• Alias the Integration: If you set up the Wyoming integration manually via YAML, you can give it a friendly alias using the alias: key. This can make your tts.speak service calls more readable (e.g., entity_id: tts.local_piper).

Conclusion

Integrating Piper via the Wyoming protocol provides Home Assistant users with a robust, private, and fast local text-to-speech capability. Whether you're announcing the laundry cycle completion, notifying yourself when a door is left open, or integrating voice feedback into complex automations, local TTS ensures your smart home communicates effectively and reliably, without relying on external services. By following these steps and best practices, you can master local speech generation and elevate your Home Assistant automation game.