Building Your First Home Assistant App and Custom Playback Script for Music Assistant

A homelab mini-PC sending synchronized audio waveforms to multi-room smart speakers

Starting multi-room music in Home Assistant often takes five separate taps across three menus: grouping speakers, fixing uneven room volumes, clearing yesterday's queue, picking a station, and turning radio mode on. Packaging those steps into a self-contained Home Assistant app made of input helpers, a parameterized playback script, and one compact dashboard card turns the entire routine into a single tap that anyone in the house can use reliably.

In this guide, you will build a reusable Music Assistant playback controller with safe volume limits, era presets, and automatic speaker grouping. For the real-world story of how I used this setup to run an eight-hour multi-generational holiday soundtrack without a single repeat, read Curating an Eight-Hour Multi-Generational Holiday Playlist with AI Radio in Music Assistant on Frizzle Tech Blog.

Prerequisites

Before writing the script package, make sure you have a running Home Assistant instance with Music Assistant connected to your local audio library or streaming provider, a Git repository (on GitHub, GitLab, or a self-hosted GitLab server) if you version-control your Home Assistant YAML packages, and optionally an AI coding assistant such as Antigravity, Claude Code, or Codex to help validate entity IDs across rooms.

  • Home Assistant 2025.10 or newer with packages: enabled under homeassistant: in /path/to/git/ha-config/configuration.yaml.
  • Music Assistant Server (2.3 or newer) installed as an add-on or Docker container, with the Music Assistant integration active in Home Assistant.
  • Two or more network media player entities exposed by Music Assistant (for example, media_player.living_room_speaker and media_player.kitchen_speaker).
  • At least one saved playlist, artist URI, or radio seed URI inside Music Assistant (such as library://playlist/12).

Step 1: Define Input Helpers for Presets and Safe Volume Caps

In Home Assistant, the cleanest way to build a modular mini-app without writing custom Python integrations is a YAML package file. Storing your helpers and scripts in one dedicated file keeps your main configuration tidy and makes version control straightforward.

Confirm that /path/to/git/ha-config/configuration.yaml loads a packages directory:

homeassistant:
  packages: !include_dir_named packages

Create /path/to/git/ha-config/packages/music_curated_radio.yaml and define three helpers: a preset selector, a maximum startup volume slider, and an active session toggle:

input_select:
  curated_music_preset:
    name: Curated Music Preset
    icon: mdi:radio
    options:
      - Mid-Century Jazz & Standards
      - Acoustic 70s & 80s Warmth
      - Evening Instrumental Lounge
    initial: Mid-Century Jazz & Standards

input_number:
  curated_music_volume_cap:
    name: Startup Volume Cap
    icon: mdi:volume-medium
    min: 0.05
    max: 0.60
    step: 0.05
    mode: slider
    initial: 0.25

input_boolean:
  curated_music_session_active:
    name: Curated Music Session Active
    icon: mdi:music-circle

Reload input helpers from Developer Tools -> YAML so the entities register immediately.

Step 2: Build the Parameterized Music Assistant Playback Script

Calling media_player.play_media directly works for single files, but the dedicated music_assistant.play_media action unlocks native queue replacement and dynamic radio continuation (radio_mode: true). Append the script: block to /path/to/git/ha-config/packages/music_curated_radio.yaml so your script joins the room speakers, clamps each speaker's volume before audio starts, maps the chosen preset to a Music Assistant URI, and verifies playback:

script:
  start_curated_house_music:
    alias: Start Curated House Music
    icon: mdi:playlist-music
    mode: restart
    fields:
      lead_player:
        description: Primary Music Assistant media_player entity
        example: media_player.living_room_speaker
      member_players:
        description: Additional room speakers to join to the lead player
        example:
          - media_player.kitchen_speaker
          - media_player.dining_room_speaker
    variables:
      selected_preset: "{{ states('input_select.curated_music_preset') }}"
      vol_cap: "{{ states('input_number.curated_music_volume_cap') | float(0.25) }}"
      preset_map:
        "Mid-Century Jazz & Standards": "library://playlist/12"
        "Acoustic 70s & 80s Warmth": "library://playlist/19"
        "Evening Instrumental Lounge": "library://playlist/24"
      target_uri: "{{ preset_map.get(selected_preset, 'library://playlist/12') }}"
      target_lead: "{{ lead_player | default('media_player.living_room_speaker') }}"
      target_members: "{{ member_players | default(['media_player.kitchen_speaker']) }}"
    sequence:
      - action: media_player.volume_set
        target:
          entity_id: "{{ [target_lead] + target_members }}"
        data:
          volume_level: "{{ vol_cap }}"
      - action: media_player.join
        target:
          entity_id: "{{ target_lead }}"
        data:
          group_members: "{{ target_members }}"
      - delay:
          milliseconds: 400
      - action: music_assistant.play_media
        target:
          entity_id: "{{ target_lead }}"
        data:
          media_id: "{{ target_uri }}"
          media_type: playlist
          enqueue: replace
          radio_mode: true
      - wait_template: "{{ is_state(target_lead, 'playing') }}"
        timeout: "00:00:10"
        continue_on_timeout: true
      - action: input_boolean.turn_on
        target:
          entity_id: input_boolean.curated_music_session_active

Notice two important details in the sequence. First, mode: restart prevents overlapping service calls if someone taps the dashboard button twice. Second, clamping volume_level before music_assistant.play_media fires guarantees that a speaker left at 70 percent volume from an afternoon podcast never startles the room on startup.

Step 3: Add a Clean Shutdown and Speaker Ungroup Routine

Multi-room speaker groups often linger into the next day, causing an unsuspecting voice timer or bedtime track in one room to play across the entire kitchen and living room. Add a matching stop script right below start_curated_house_music in the same YAML package:

  stop_curated_house_music:
    alias: Stop Curated House Music
    icon: mdi:stop-circle-outline
    mode: single
    sequence:
      - action: media_player.media_stop
        target:
          entity_id: media_player.living_room_speaker
      - action: media_player.unjoin
        target:
          entity_id:
            - media_player.kitchen_speaker
            - media_player.living_room_speaker
      - action: input_boolean.turn_off
        target:
          entity_id: input_boolean.curated_music_session_active

Reload Scripts in Developer Tools -> YAML and inspect home-assistant.log (or run ha core check) to confirm zero syntax warnings.

Step 4: Wire a Single-Tap Dashboard Card and Verify State

Open any Home Assistant dashboard view, click Edit -> Add Card -> Manual, and paste a compact entities card that exposes your preset dropdown, volume cap, and start/stop actions in one place:

type: entities
title: House Radio Controller
show_header_toggle: false
entities:
  - entity: input_select.curated_music_preset
  - entity: input_number.curated_music_volume_cap
  - type: button
    name: Start Multi-Room Radio
    icon: mdi:play-network
    action_name: Play
    tap_action:
      action: perform-action
      perform_action: script.start_curated_house_music
      data:
        lead_player: media_player.living_room_speaker
        member_players:
          - media_player.kitchen_speaker
  - type: button
    name: Stop and Ungroup Speakers
    icon: mdi:speaker-off
    action_name: Stop
    tap_action:
      action: perform-action
      perform_action: script.stop_curated_house_music

Test the workflow by selecting a preset, setting the volume cap to 0.20, and clicking Play. Open Developer Tools -> States and verify that media_player.living_room_speaker transitions to playing, group_members lists both speakers, and input_boolean.curated_music_session_active turns on.

Hardware & Gear Used in This Guide

  • Homelab server: Compact x86-64 mini-PC running Home Assistant and Music Assistant Server on local NVMe storage
  • Network audio endpoints: Wi-Fi and Ethernet smart speakers supporting AirPlay, Cast, or SlimProto multi-room sync
  • Local music storage: NAS SMB/NFS share storing lossless FLAC and M4A tracks indexed by Music Assistant
  • Wired LAN backbone: Managed gigabit switch keeping multicast discovery and multi-room audio clock sync stable

What You Can Do Next

  • Trigger script.start_curated_house_music automatically when a calendar event or guest mode toggle turns on.
  • Pair time-of-day templates with input_select.curated_music_preset so afternoon acoustic playlists transition into quiet evening jazz after sunset.
  • Read Curating an Eight-Hour Multi-Generational Holiday Playlist with AI Radio in Music Assistant on Frizzle Tech Blog to see how Music Assistant's candidate scoring handled an eight-hour family holiday gathering.

Later,
     SteveO