Home Assistant Guide

Simple tutorials for powerful automations

What is Music Assistant?

Music Assistant is an open-source add-on and integration for Home Assistant that acts as a local music server and library manager. It combines your local files and streaming services into one place, letting you browse, queue, and play music on the speakers and players you already use.

Compared to controlling "media_player" devices directly, Music Assistant adds powerful queue management, multi-room groups, and announcement handling (pause → play sound/TTS → resume) that you can automate in Home Assistant.

Installing Music Assistant

Via Home Assistant Add-on Store

  1. Open Settings → Add-ons → Add-on Store.
  2. Search for "Music Assistant" and click Install.
  3. After installation, click Start. Optionally enable "Start on boot" and "Show in sidebar".

Once the add-on is running, the Music Assistant integration is often auto-discovered. Go to Settings → Devices & Services and look under "Discovered" to click Configure. If it doesn't appear, choose Add Integration, search for "Music Assistant", and if needed enter the server address (for example http://<your-HA-IP>:8095).

Via Docker (Advanced)

You can run the Music Assistant server as a container (for Home Assistant Container or a separate host). Map a persistent /data volume and ensure your music folders are accessible to the container. After it's up, open http://<server-ip>:8095.

Using the Interface

Open the Music Assistant web UI from the sidebar (Ingress) or via its port. You'll find:

  • Library – Artists, albums, tracks, playlists (merged from all providers).
  • Players – Your speakers/devices and any multi-room groups you create.
  • Queue – What's playing now; reorder, remove, or save to playlist.
  • Settings – Add music providers, add player providers, tweak playback/announcement options.

Adding Music Providers

In Settings → Providers, add your sources:

  • Local files – Folders or network shares.
  • Streaming – Spotify, Tidal, Qobuz, Apple Music, YouTube Music (availability varies by version).
  • Radio/Podcasts – Internet radio stations or podcast feeds.

Music Assistant merges duplicates across providers where possible so you don't see the same track twice (unless you want both versions).

Adding Players and Groups

In Settings → Providers → Player, enable player providers (e.g., Cast, AirPlay, DLNA, Sonos, or "Home Assistant Media Players") so your devices appear in Music Assistant. Detected players show up automatically; you can rename them, adjust latency, and form groups (e.g., "Living Room + Kitchen"). Groups act like a single player that stays in sync and shares one queue.

Spotify Setup (Detailed)

A Spotify Premium account is required. In the Music Assistant UI go to Settings → Music Providers → Add Music Provider → Spotify, then complete the sign-in/consent flow. After linking, MA will sync playlists, liked tracks, and albums (first sync can take a few minutes).

Troubleshooting

  • If you changed your Spotify password or revoked access, re-authenticate in MA.
  • If login appears to succeed but nothing shows, refresh the page or remove and re-add the provider.
  • Prefer Spotify when duplicates exist by adjusting provider order in Library preferences.

File System Setup (Detailed)

Where to store your music

  • HA OS / Add-on: Put files under /media (e.g., /media/music). With Samba enabled you can copy to \\homeassistant\media\music.
  • Docker/manual: Bind-mount your host folder into the container (e.g., /mnt/music → /media/music).
  • NAS share: Mount SMB/NFS on the host before starting MA or use the "Filesystem (remote share)" provider with credentials.

Add the Filesystem provider

  1. Open MA → Settings → Music Providers → Add Music Provider.
  2. Select Filesystem (local) or Filesystem (remote share).
  3. Enter the path (e.g., /media/music) or share details, then save and start a full scan.

Create playlists from local files

  1. Go to Library → Playlists → New Playlist.
  2. Browse albums/tracks and use the "Add to playlist" menu to build your list (you can mix local and streaming tracks).

Common pitfalls

  • Permissions: the MA process must be able to read the folder.
  • Startup order: ensure a NAS share is mounted before MA starts, or the scan will find an empty path.
  • Very large folders: scanning everything under your path can take time on first run.

Automation and Control

Music Assistant adds dedicated actions like music_assistant.play_media, music_assistant.search, music_assistant.play_announcement, and music_assistant.transfer_queue. Use these for MA's queue-aware features. Basic actions (pause, volume, simple TTS) also work with standard media_player services if you don't need MA's advanced logic.

Play media

Start or queue a track, album, artist, or playlist. You can pass a plain name, a library URI (e.g., library://playlist/<id>), a provider URI (e.g., a Spotify URI), or a numeric library ID. Set media_type (track, album, artist, playlist, radio). Omit it only if MA can clearly infer the type from the ID/URI. 

action: music_assistant.play_media
data:
  media_id: Evening Chill
  media_type: playlist
  enqueue: replace
target:
  entity_id: media_player.living_room_group

Queue multiple items

action: music_assistant.play_media
data:
  media_id:
    - Fleetwood Mac - Dreams
    - The Killers - Human
  media_type: track
  enqueue: add
target:
  entity_id: media_player.kitchen_speaker

Enqueue options

  • play – add and start immediately
  • replace – clear queue and start new selection
  • next – insert after the current track
  • replace_next – replace upcoming items but keep the currently playing track
  • add – append to the end of the queue

Shuffle (enable after starting playback)

Don't combine shuffle with the initial play action. Start/queue first, then toggle shuffle on the same player: 

- action: music_assistant.play_media
  data:
    media_id: library://playlist/42
    media_type: playlist
    enqueue: replace
  target:
    entity_id: media_player.home_music_group

- action: media_player.shuffle_set
  data:
    shuffle: true
  target:
    entity_id: media_player.home_music_group

- action: media_player.media_next_track
  target:
    entity_id: media_player.home_music_group
  • For grouped playback, send shuffle to the group entity.
  • If shuffle doesn't take immediately, add a 1–2s delay before shuffle_set, or skip once.

Announcements

Use music_assistant.play_announcement for short audio clips (chimes, tones). MA will pause, play the clip, then resume: 

action: music_assistant.play_announcement
data:
  media_id: http://homeassistant.local:8123/local/sounds/chime.mp3
target:
  entity_id: media_player.kitchen_speaker
  • Place files under config/www to serve them as /local/... URLs.
  • You can also reference a file on an external site or a web server on your LAN.

For spoken text, use a Home Assistant TTS service and target the same player: 

service: tts.google_say
data:
  entity_id: media_player.kitchen_speaker
  message: "This is a test."

Announcement volume/ducking behavior can be adjusted per player in the MA UI.

Search

music_assistant.search performs a global search across all providers and returns results in a response variable for use later in your script. 

script:
  ma_search_example:
    alias: "MA Smart Search"
    mode: queued
    sequence:
      - action: music_assistant.search
        data:
          name: "{{ states.input_text.search_query.state }}"
          limit: 5
        response_variable: results

      - action: input_text.set_value
        data:
          entity_id: input_text.result_title
          value: "{{ results.tracks[0].name }}"

Do I have to target "MA entities" specifically?

Not always. Use Music Assistant entities when you want MA's queue-aware features (playlists, multi-item queues, transfer_queue, announcements with resume, radio mode, shuffle after play, etc.). For simple tasks like pause, volume, or basic TTS, standard media_player services on your existing entities are fine.

Tips and Troubleshooting

  • If the add-on is running but you don't see the integration, check Settings → Devices & Services for a discovered card; otherwise click Add Integration and search for Music Assistant.
  • If local files don't appear, verify folder paths, permissions, and that the share is mounted before MA starts.
  • If playback doesn't start after enqueue: replace, add a final media_player.media_play step (some devices need an explicit play).
  • Send shuffle/next/previous to the same player or group you started playback on.
  • Large libraries take time to index on first scan; let MA finish the initial import.

Music Assistant is actively developed, so features and provider support evolve. If something doesn't behave as expected, check the add-on logs and the integration page for warnings or errors.