Announcements Without Ruining the Music: Snapshot, Pause/Resume, Music Assistant, and Priority

Module 22 · Lesson 6

Announcements Without Ruining the Music: Snapshot, Pause/Resume, Music Assistant, and Priority

The scripts from Lesson 5 work fine on a silent speaker. What happens when a speaker is playing music at full volume and an announcement comes in? Without the right handling, TTS either doesn't play at all, or plays in the middle of a track, drowned out by the music.

Budget around 70 minutes. This requires the Lesson 5 scripts as a starting point.

A Real-Life Problem: TTS Drowned Out by Loud Music

A speaker is playing music at 80% volume. An announcement, "laundry is done," comes in through tts.speak from Lesson 5. Depending on the integration, one of two things happens: either the announcement layers over the music and is barely audible, or it interrupts playback with no resume, leaving silence instead of the song. Neither behavior is satisfying.

The Pattern: Snapshot, Mute, Speak, Restore

The classic pattern for an announcement that doesn't lose the music's context is four steps: save the speaker's current state (what's playing, at what volume), pause it, play the announcement, restore the saved state. Music Assistant makes this easier by offering a dedicated announcement service that handles it automatically.

script:
  home_announcement_with_music_ducking:
    alias: "Home announcement with music ducking"
    icon: mdi:bullhorn-outline
    mode: queued
    max: 5
    fields:
      message:
        description: "The message to speak"
        example: "Someone's at the gate"
      speaker:
        description: "The target speaker's media_player entity"
        example: "media_player.living_room_speaker"
    sequence:
      - condition: state
        entity_id: input_boolean.house_silence
        state: "off"
      - variables:
          was_playing: "{{ is_state(speaker, 'playing') }}"
          volume_before: "{{ state_attr(speaker, 'volume_level') }}"
      - if:
          - condition: template
            value_template: "{{ was_playing }}"
        then:
          - action: media_player.media_pause
            target:
              entity_id: "{{ speaker }}"
      - action: media_player.volume_set
        target:
          entity_id: "{{ speaker }}"
        data:
          volume_level: "{{ states('input_number.announcement_volume_home') | float / 100 }}"
      - action: tts.speak
        target:
          entity_id: tts.piper
        data:
          media_player_entity_id: "{{ speaker }}"
          message: "{{ message }}"
          language: "en"
      - wait_for_trigger:
          - trigger: state
            entity_id: "{{ speaker }}"
            to: "idle"
        timeout: "00:00:20"
        continue_on_timeout: true
      - action: media_player.volume_set
        target:
          entity_id: "{{ speaker }}"
        data:
          volume_level: "{{ volume_before }}"
      - if:
          - condition: template
            value_template: "{{ was_playing }}"
        then:
          - action: media_player.media_play
            target:
              entity_id: "{{ speaker }}"

The was_playing and volume_before variables are the snapshot: they remember the state before the announcement. After the message is spoken, the script waits for the speaker to return to idle (TTS finished), restores the volume, and resumes playback only if something was actually playing before. continue_on_timeout: true guards against the script hanging if the speaker doesn't change state in time for some reason.

The Music Assistant Variant: the announce Service

Music Assistant offers a dedicated announcement service, handling the mute and restore automatically with no manual snapshot in your automation, which significantly simplifies the code for players compatible with the feature:

script:
  announcement_via_music_assistant:
    alias: "Announcement via Music Assistant"
    mode: queued
    max: 5
    fields:
      message:
        description: "The message to speak"
        example: "Laundry is done"
    sequence:
      - condition: state
        entity_id: input_boolean.house_silence
        state: "off"
      - action: music_assistant.play_announcement
        target:
          entity_id: media_player.living_room_speaker
        data:
          url: "media-source://tts/tts.piper?message={{ message | urlencode }}&language=en"
          use_pre_announce: true

use_pre_announce: true plays a short signal chime before the announcement: this directly solves the "clipped first word" problem from Lesson 5, built into the service itself instead of manually adding a chime sound. If your speakers are supported by Music Assistant, this variant is simpler to maintain than a manual snapshot: keep the manual pause/resume script as a fallback for players outside MA.

Priorities: What Happens With Several Announcements at Once

mode: queued in script.home_announcement from Lesson 1 matters here
Thanks to queued mode (with the max: 5 limit), several home announcements triggered close together play one after another, each with its own snapshot and restore. The critical announcement runs in parallel mode and doesn't wait in line behind home ones: if both types of announcements can hit the same speaker, the critical one should be able to interrupt a home announcement currently playing, not just music. That's an advanced scenario, beyond this lesson's basic pattern: if your house generates a lot of simultaneous announcements, consider adding a priority queue built on a numeric helper.

Announce in Music Assistant: An Alternative to a Manual Snapshot

The snapshot, mute, speak, restore pattern works universally on any media_player, but needs manual code handling every step. If you have Music Assistant configured, there's a more convenient route: a dedicated announce service that saves the player's current state itself, briefly mutes or stops playback, plays the announcement, and restores the previous state, with no need to write your own snapshot logic.

A custom snapshot/restore script: full control, works on any media_player, but you have to maintain it yourself.

The Music Assistant announce service: less code, consistent behavior across every player MA supports, but requires the add-on itself.

Some manufacturers' native announce: Sonos and some Google speakers have their own built-in announcement API that interrupts playback only for the duration of the message.

Prioritizing Multiple Announcements Fired at Once

What happens when two announcements (a doorbell and a low-temperature alert, say) fire almost simultaneously? Without extra queuing logic, the second announcement can interrupt the first mid-sentence, creating an unintelligible mess. The fix is a simple semaphore in the form of an input_boolean.announcement_in_progress helper, set at the start of the home_announcement script and cleared at the end, with a condition at the start of the script checking that the previous announcement has already finished before the next one begins.

Testing the Snapshot/Resume Pattern in Practice: Common Pitfalls

Volume after restoring differs from before the announcement: some integrations don't save the exact volume value in the snapshot, it's worth verifying this manually.

Playback doesn't resume after the announcement: some players need an explicit media_play call after switching the audio source to TTS and back.

The announcement plays on the wrong speaker after a group changes: if speaker grouping changes dynamically, a snapshot taken before the group change can refer to an outdated configuration.

Duck (Ducking) as an Alternative to Full Pausing

Instead of the full snapshot/pause/resume pattern described in this lesson's main content, some players (especially those supported by Music Assistant) support ducking: temporarily lowering the background music's volume during an announcement, instead of stopping it entirely, with an automatic return to the original volume once the announcement finishes. That's a more subtle and often more natural approach than fully stopping and resuming, especially for short, frequent informational announcements.

Testing the Announcement Pattern on Different Speaker Types

Snapshot/resume and ducking behavior differs between speaker manufacturers: what works flawlessly on one model can behave unexpectedly on another (losing group sync after an announcement, for example). Before rolling out a final announcement pattern across the whole house, it's worth testing it on each unique speaker type separately, instead of assuming behavior verified on one device will carry over identically to another.

Advanced Ducking Patterns With a Volume Curve

The basic ducking from the previous section lowers the volume to one fixed level for the duration of the announcement, but a more polished implementation can use a volume curve: a smooth, gradual fade over half a second before the announcement, and an equally smooth fade back up once it ends, instead of a sudden jump in either direction. That effect, though subtle, noticeably improves how announcements feel, like a natural part of the home's audio experience rather than a technical interruption.

Documenting Priority Logic in One Clear Place

As the home_announcement script grows to include more priority levels and ducking patterns, it's worth keeping a simple table in your smart-home notebook explaining exactly what happens for each combination of priorities, instead of relying solely on the YAML code as your only source of truth. That documentation makes it much easier to debug unexpected behavior months after the original setup, once the logic's details have long faded from memory.

Debugging the home_announcement Script Step by Step

When the home_announcement script behaves unexpectedly, it's worth stepping through it from the script editor, watching exactly which step (snapshot, mute, TTS, restore) the problem shows up at, instead of guessing based on the final result alone. The script's run history, available under Settings, Automations & Scenes, the Scripts tab, shows the exact trace of every execution, making diagnosis much easier.

How to Test This Lesson

1. Play music on a speaker, trigger an announcement, and check that the music comes back at the same volume afterward.

2. If you have a speaker supported by MA, compare both variants: the manual snapshot and music_assistant.play_announcement.

3. Trigger two home announcements close together and check they play one after another, not on top of each other.

Common Mistakes

No volume restore after the announcement: the music comes back much quieter than it was before.

No timeout on wait_for_trigger: the script hangs forever if the speaker never returns to idle.

Resuming playback when nothing was playing before: the speaker suddenly starts playing for no reason.

Practical Task

☐ Build an announcement script with full snapshot/pause/resume.

☐ If you have compatible hardware, test music_assistant.play_announcement.

☐ Verify the behavior with two announcements triggered close together.

Key Takeaways

Snapshot, mute, speak, restore: the announcement pattern that doesn't ruin the music.

music_assistant.play_announcement simplifies this for compatible players.

Queuing prevents multiple announcements from overlapping.

What's Next

Next lesson: The Tablet as a Home Communicator: Dashboard, Sound, TTS, Screen, Camera, Night Mode, and Locks. We extend announcements to include displaying content on screen.

Finished this lesson?