Home Assistant TTS Announcements: Setup and Music Playback

Start with speech, then decide how music should behave

For Home Assistant TTS announcements, first connect a speech provider and a compatible speaker, then run tts.speak with a short test message. TTS means text-to-speech: turning written words into audio. Piper is a local option that generates that audio on your own hardware.

Choose a room speaker you already own. It must be able to play the generated audio through its Home Assistant integration, the connection that exposes its controls. An entry called media_player is not by itself proof of that capability. Test speech before building the household routine.

For a first version, skip announcements while that speaker is busy. If you want speech over music, use the separate playback paths below. The Play specified media documentation warns that an unsupported announcement request can play the new audio without resuming the interrupted media.

Researched from current Home Assistant and Music Assistant documentation and Home Assistant 2026.9.4 source code on September 29, 2026. YAML syntax, the player-state condition and the media address were checked locally. This guide was not tested on physical speakers or in a running Home Assistant installation. The cover is an AI-generated household illustration, not a product photograph.

Set up one working announcement

1. Connect the speaker and choose a voice

Under Settings → Devices & services, check that the speaker’s integration is configured. Copy its entity ID, the internal name used by actions, such as media_player.dining_room. Use one player rather than a speaker group for the first test.

On Home Assistant OS, install the Piper app, select a voice in its configuration and start it, then add the discovered Wyoming Protocol integration. Wyoming connects Home Assistant to the speech service. Older installations may label Apps as Add-ons. The official local-voice setup includes this installation path. For a fixed spoken message, you do not need Whisper, wake-word detection or a microphone.

Home Assistant Container has no built-in Apps store. Run a compatible Piper service separately and connect it through Wyoming, or use a TTS provider you already configured. Copy the resulting tts. entity ID; the examples assume tts.piper, but your name may differ. Home Assistant Cloud TTS is another option with a Home Assistant Cloud subscription and internet dependence.

2. Speak a harmless test sentence

Set a comfortable low volume using the speaker’s normal control and stop any music. Open Settings → Tools → Actions; older releases use Developer tools → Actions. Select Speak. Its target is the TTS provider; the Media player entity field selects the speaker. This distinction is shown in the Speak action reference.

YAML is Home Assistant’s text configuration format. In YAML mode, use the following with your two IDs. On a phone, scroll code blocks sideways to read each complete line.

action: tts.speak
target:
  entity_id: tts.piper
data:
  media_player_entity_id: media_player.dining_room
  message: "This is an announcement test."

Expected result: the selected speaker says the sentence once. If it stays silent, use the troubleshooting table before adding quiet hours or button logic. An action completing without an error is only one part of this check.

Worked example: a considerate dinner announcement

This version speaks only between 8 am and 9 pm, while a household switch is on and the player reports idle or off. A script is a saved sequence you can call from a dashboard or automation. Here, skipping speech is intentional whenever the room’s player appears busy.

1. Go to Settings → Devices & services → Helpers → Create helper → Toggle. Name it Spoken announcements, confirm its ID, and turn it on. A Toggle helper gives the household a simple pause switch.
2. Open Settings → Automations & scenes → Scripts, create a new empty script and choose Edit in YAML from its menu. Paste the complete script below without an outer script: line.
3. Replace the helper, TTS and speaker IDs. The speaker appears twice: in the condition and the speech action. Keep the indentation, then save.
4. Run the whole saved script during the allowed hours with the speaker idle. Keep its volume at the level you checked. This version sends no explicit volume change; the playback integration’s announcement behavior still applies.

alias: "Dinner announcement"
description: "Speak during daytime, only on an idle or off player"
mode: single
sequence:
  - condition: state
    entity_id: input_boolean.spoken_announcements
    state: "on"
  - condition: time
    after: "08:00:00"
    before: "21:00:00"
  - condition: template
    value_template: >-
      {{ states('media_player.dining_room') in ['idle', 'off'] }}
  - action: tts.speak
    target:
      entity_id: tts.piper
    data:
      media_player_entity_id: media_player.dining_room
      message: "Dinner is ready. Please come to the table."
  - delay: "00:00:10"

The conditions stop the sequence when a check fails. Single mode rejects another call while this script is still running. The ten-second delay is a repeat guard after sending the message, not a measurement of speech duration. It does not coordinate other scripts or survive a Home Assistant restart.

The player’s reported state matters: paused, playing, buffering, unavailable and unknown all skip speech here. Some resting speakers report paused rather than idle. Do not broaden the condition until you decide whether interrupting that paused session is acceptable. An off player also needs to support starting playback from that state.

This is a check, not a lock on the speaker. Someone could start music immediately afterward, or the integration could report an old state. Use a dedicated announcement speaker or a verified native announcement path if preserving playback is essential.

Illustrative checks, not reported hardware test results. Scroll the table sideways on a phone.

For a harmless check now, turn the helper off and run the script: it should remain silent, with its trace—the saved record of the steps that ran—showing the first failed condition. Turn the helper back on afterward. To check quiet hours without changing the system clock, temporarily choose an allowed time window that excludes now, run the whole script, inspect the trace and restore the intended hours.

Once this behaves as expected, call the saved script from a dashboard button or a physical button automation. The scenes versus scripts guide explains how a button and an automation can share one sequence. Turning the helper off blocks future runs; it does not retract audio already sent.

Choose what happens while music is playing

Choose the row matching how your speaker plays music. Scroll sideways on a phone.

Sonos: use its announcement path

The Sonos integration documents an overlay that lowers music during the message and restores its volume. It requires the UPnP device discovery and control setting enabled in the Sonos app; this is not a recommendation to enable internet port mapping on your router. Older hardware and S1 support vary.

After the basic test, try this action on one supported speaker with nonessential music. Replace the Sonos ID and tts.piper inside the media address. The spaces in the message are encoded as %20.

action: media_player.play_media
target:
  entity_id: media_player.dining_room_sonos
data:
  announce: true
  media_content_type: music
  media_content_id: >-
    media-source://tts/tts.piper?message=Dinner%20is%20ready.
  extra:
    volume: 20

Here extra.volume: 20 sets the Sonos announcement level. It uses the Sonos audio-clip 0–100 scale, unlike the ordinary volume_set action’s 0–1 scale. Sonos applies minimum and maximum clip-level limits, so use the helper to suppress announcements rather than relying on volume zero. Verify a comfortable level in the room. Only after the overlay test succeeds should you replace the dinner script’s Speak step and remove its idle/off condition; keep the time and helper checks.

Music Assistant: keep the playback path consistent

Music Assistant needs its own running server plus the Home Assistant integration. Target the MA player entity with Speak, rather than a separate native Cast or Sonos entry for the same hardware.

MA documents restoring music that MA was managing after an announcement. This depends on correct player state and playback-position reports. Do not assume it can recover arbitrary music started by another app. Its group guidance warns that announcements to native Google Cast, Sync and Universal groups can interrupt an independently playing child speaker without resuming it. Test a single player first, then each real group scenario before removing the starter script’s busy-player guard.

Assist satellites: select the satellite action

For a compatible assist_satellite entity, use Announce on satellite with your message. It uses the TTS configured for that satellite’s assistant and normally plays a chime first; preannounce: false disables the chime. An announcement is separate from starting a listening conversation. If you still need the underlying assistant, follow the local voice setup guide.

Find the failed step before changing the routine

Home Assistant’s TTS troubleshooting recommends automatic local-URL configuration under Settings → System → Network. Cast devices can fail on local-only hostnames and self-signed certificates. Preserve a custom network configuration until you understand why it exists; changing a hostname does not create a firewall allowance.

Separate device discovery, HA-to-speaker control and speaker-to-HA audio retrieval. The Sonos network requirements additionally require HA to reach TCP 1443 on the speaker for announcements. Check the integration’s directions and existing rules rather than opening everything between networks. Test with one harmless message; no factory reset or router outage is needed.

Keep spoken messages useful and private

Use short, ordinary messages such as “Dinner is ready.” Avoid announcing private calendar details or security codes in shared rooms. Piper keeps synthesis local, but the selected speaker, music service and any cloud TTS provider have their own data paths. TTS also caches generated audio by default; local processing does not mean nothing is stored.

Keep spoken reminders supplementary to important phone alerts or purpose-built alarms. For a coordinated household setup, Tara’s home automation kit and shared routines page explains the broader planning path.

Common questions