Skip to content
Go back

Music Assistant: Whole-Home Audio in HA

By KingPin 13 min read
Music Assistant: Whole-Home Audio in HA
Contents

Why Is the Kitchen Half a Second Behind?

You own a HomePod, a Chromecast speaker, a Sonos in the bedroom, and a Raspberry Pi hooked to some old bookshelf speakers. That is four vendors and at least three apps. It is 2 AM, you press play everywhere, and the kitchen echoes the living room like a bad conference call.

Here is the fix. Run Music Assistant (MA) as the music brain next to Home Assistant (HA). Put it on the same flat network as your speakers. Then pick ONE sync-capable protocol per room group: AirPlay or Sendspin/Snapcast for mixed DIY gear, Google Home groups for Cast. MA has a “Universal Group” that mixes player types, and it plays the same audio everywhere, but the docs say plainly that it is not in sync. Treat it as a party trick for rooms far apart, not as your whole-home setup.

Full example: Clone the working files at github.com/KingPin/sumguy-examples/home-automation/music-assistant-whole-home-audio

Versions in this post are current as of November 2026: MA 2.10.12 and Home Assistant 2026.11.x.

Who Does What: MA vs HA

MA is a music library manager and streaming server. It merges your sources (local files, Subsonic, Jellyfin, Plex, Spotify, Tidal, Qobuz and more) into one library and streams to many player types. HA stays the automation brain. They connect in three separate pieces, and each one points a different direction:

PieceInstalled inWhat it does
Home Assistant IntegrationHAMA players show up in HA as media_player entities
Home Assistant PluginMADrives an MA player’s power, volume, and mute from an HA entity (wake an amp from standby)
Home Assistant Media Players providerMAHA media players show up in MA as targets

The integration ships in HA core since 2024.12 and needs MA server 2.4 or later. No HACS, no custom component. The third piece is a fallback. If MA has a native provider for your device, use that. The HA route gets worse audio quality.

Install: App or Docker

Home Assistant now calls add-ons “apps” (Settings > Apps). The recommended path is the MA app on HAOS. Click install, done. The MA team supports exactly two setups: that app, or a standalone Docker container. Run it on Kubernetes or an orchestration stack and you are on your own.

If you run HA in a container, here is the official compose file, pinned to 2.10.12:

compose.yaml
services:
music-assistant-server:
image: ghcr.io/music-assistant/server:2.10.12
container_name: music-assistant-server
restart: unless-stopped
network_mode: host
volumes:
- ./data:/data/
- /path/to/your/music:/media:ro
environment:
- LOG_LEVEL=info

Keep network_mode: host. MA finds speakers with multicast (mDNS, uPnP), and a bridge network hides that traffic. A bridge with 8095:8095 and 8097:8097 published works only for software players that need no discovery, and it is unsupported. Macvlan also works if you like pain.

Your music on a NAS over SMB or NFS? Mount the share on the host and bind-mount it read-only, as above. Mounting from inside the container needs cap_add: SYS_ADMIN, DAC_READ_SEARCH and security_opt: apparmor:unconfined. That weakens isolation to save one fstab line. Skip it.

Two ports matter. The web UI lives on TCP 8095. The audio stream server uses TCP 8097 by default (if it is taken, MA tries the next port), and players must reach it by IP over HTTP.

Hardware: a 64-bit OS, and a Raspberry Pi 4 or newer. The minimum is 2 GB RAM, and the docs recommend 4 GB or more if the box runs anything else. The Smart Fades feature needs at least 4 GB. Queues or playlists over about 1000 items can make MA unresponsive. For scale, a one-off probe on my box showed about 510 MiB of idle RAM right after start for 2.10.12, with no providers and no library loaded.

After the container starts, add the integration in HA. HA usually auto-discovers MA (zeroconf _mass._tcp.local.), so click Configure. To do it by hand: Settings > Devices & services > Add integration > Music Assistant, then enter the server URL on port 8095. If MA is not an HA app, the integration asks you to log in to MA. Use an admin account.

The integration creates a media_player entity for every MA player and group, plus a “favorite current song” button per player. HA players that you import into MA show up twice, so hide the originals.

One more gotcha: MA installs no music sources by default, so the library stays empty until you add one in Settings. First sync of a big library can take a long time, because free artwork and metadata APIs have rate limits.

The Network Rule That Eats Your Weekend

MA must sit on the same layer 2 network as your players, with no VLANs between them. The docs call this the single most common cause of support requests. Discovery uses multicast, and multicast does not cross VLANs without help you do not want to build.

Firewalls that restrict ports are also unsupported, because AirPlay opens random TCP and UDP ports. So your IoT VLAN with a default-deny rule is exactly the setup that fails. If your speakers live there, MA does too, or the speakers move. Decide once, before you spend an evening staring at an empty player list.

Players and Sync: Pick One Protocol Per Room

On first install, MA adds the AirPlay, Chromecast, DLNA, Sendspin, and Sonos player providers automatically. All except Sendspin can be deleted. Here is how the main ones compare:

ProtocolIn sync?Notes
AirPlayYesLossless. Mixes AirPlay 1 (RAOP) and AirPlay 2 devices. Per-device sync correction up to ±500 ms.
Google CastOnly inside a Cast group made in the Google Home appUp to 192 kHz/24-bit single player, 96 kHz for a Cast group. A group of only a stereo pair does not work.
SnapcastYesBuilt-in Snapserver. About 1 s delay on play/pause/skip.
SendspinYesOpen protocol from the Open Home Foundation. Technical preview.
SqueezeliteYes, with per-player correction of ±500 msSoftware clients such as piCorePlayer. No native mute.
HA media playersFallback onlyLower audio quality than a native provider. Use only when MA has no provider for the device.

My opinion: if your gear speaks AirPlay, use AirPlay and stop reading this table. It keeps playing when you add a member to a running group. Snapcast and Sonos do too. Every other type pauses briefly to resync.

Group Types

MA has four group types, and the docs describe three:

  1. Temporary sync group. Link players in the player list, or with media_player.join. Only like player types that support synced playback can be joined. Only the leader holds the queue, so turn off the leader and the others stop.
  2. Sync group. A permanent group player, created in Settings with Add Group Player. It plays in perfect sync, and the group holds the queue no matter which members are off. Chromecast devices must be grouped in the Google Home app for that sync to hold.
  3. Universal group. Mixes different player types and plays the same audio, but not in sync. The docs say to use it only for players that are not in close range of each other. It is off by default (add the Universal Group provider). Output options are MP3 320 kbps (safest), FLAC 44.1/16, or FLAC 48/24. It cannot contain other groups.

When a group is powered on, you cannot play to its individual members. Plan for that before you wire up automations.

Want AirPlay and Cast speakers in the same synced group? Sendspin bridges link Sendspin with AirPlay and Google Cast. The AirPlay bridge “should always work”. Sendspin on Chromecast is experimental, off by default, turned on per speaker, and usually needs a manual “Static playback delay (ms)” tweak. If a speaker also supports AirPlay, join it to mixed groups over AirPlay and skip the experiment.

The Cheap DIY Room

A Raspberry Pi and a pair of old speakers make a fine room. You have two routes.

Snapcast first. MA ships a built-in Snapserver (add the Snapcast provider to start it), with ports 1704 for streams, 1705 for control, and 1780 for HTTP. The default is 48 kHz/16-bit FLAC with a 1000 ms buffer. For a quick test, point a browser or the Snapdroid app at http://192.168.1.10:1780 and keep that tab open. For a real room, run snapclient on the Pi:

Terminal window
snapclient --hostID kitchen tcp://192.168.1.10:1704

The url argument is tcp://<host>[:port]. The old -h/--host and -p options are deprecated. --hostID sets the client ID, -l lists soundcards, and -s picks the output.

The other route is Squeezelite, which speaks slimproto on port 3483:

Terminal window
squeezelite -n "Kitchen" -s 192.168.1.10

-n is the player name, -s is the server, -o picks the output device, and -l lists outputs. Use the ALSA build. The PulseAudio build has known sample-rate and sync problems on track change.

Automations That Earn Their Keep

All four examples use the action: syntax and the fields that exist in the 2026.11.2 release.

Morning playlist. Weekdays at 7:00, replace the kitchen queue with a playlist:

automations.yaml
- alias: "Morning playlist"
triggers:
- trigger: time
at: "07:00:00"
conditions:
- condition: time
weekday: [mon, tue, wed, thu, fri]
actions:
- action: music_assistant.play_media
target:
entity_id: media_player.kitchen
data:
media_id: "Morning Coffee"
media_type: playlist
enqueue: replace

media_id takes a name, an artist plus track name, a provider URI like spotify://artist/12345, or a list of items. enqueue takes play, replace, next, replace_next, or add. Do not add a shuffle field. It is not in the 2026.11.2 release.

Doorbell and dinner announcements. music_assistant.play_announcement plays a spoken or recorded message on a speaker. The target must be an MA speaker entity:

automations.yaml
- alias: "Dinner announcement"
triggers:
- trigger: state
entity_id: input_boolean.dinner_ready
to: "on"
actions:
- action: music_assistant.play_announcement
target:
entity_id: media_player.living_room
data:
message: "Dinner is ready!"
tts_entity_id: tts.piper
announce_volume: 70

Prefer a recorded chime? Swap message and tts_entity_id for url pointing at an audio file. use_pre_announce and pre_announce_url add an intro sound.

Follow me. Move the queue to whichever room just detected you:

automations.yaml
- alias: "Music follows me to the office"
triggers:
- trigger: state
entity_id: binary_sensor.office_motion
to: "on"
conditions:
- condition: state
entity_id: media_player.living_room
state: "playing"
actions:
- action: music_assistant.transfer_queue
target:
entity_id: media_player.office
data:
source_player: media_player.living_room
auto_play: true

For a quick temporary group, use the standard HA action with the leader as the target:

automations.yaml
- alias: "Party mode"
triggers:
- trigger: state
entity_id: input_boolean.party_mode
to: "on"
actions:
- action: media_player.join
target:
entity_id: media_player.living_room
data:
group_members:
- media_player.kitchen
- media_player.patio

media_player.unjoin undoes it. Remember that only the leader holds the queue in a temporary group.

Also available: music_assistant.search, music_assistant.get_library, and music_assistant.get_queue. And music_assistant.play_media can take a list of items, while the stock media_player.play_media cannot.

Gotchas Collected Painfully

The SumGuy Take

Treat MA like a forklift: great at moving one pallet of audio to many docks, bad at keeping those docks in step when each one speaks a different protocol. So buy for the protocol. One AirPlay room group, one Cast group built in the Google Home app, one Snapcast or Sendspin group for the Pi pile. Use sync groups inside each, and keep Universal Groups for the patio and the garage, far apart enough that nobody hears the gap.

Then let HA do what it is good at: triggers. Your 2 AM self will thank you when the music follows you to the kitchen and nothing echoes.

Common Questions

Does Music Assistant need Home Assistant?

No. Music Assistant runs as a standalone Docker container, and the HA app on HAOS is only the recommended install. The HA integration is optional and adds media_player entities and automation actions. Without it, you control playback from the Music Assistant web UI on port 8095.

Can Music Assistant sync Sonos and AirPlay speakers together?

Yes, if the Sonos supports AirPlay. Music Assistant switches that Sonos to AirPlay inside the group, with a short silence while the stream restarts. A Sonos without AirPlay can join through a Sonos that has it. S1 and S2 speakers cannot share a sync group; a Universal Group plays both, out of sync.

How much RAM does Music Assistant need?

Music Assistant needs a minimum of 2 GB of RAM, and the docs recommend 4 GB or more if the box runs other software. Smart Fades needs at least 4 GB. A one-off probe on my box showed about 510 MiB idle after start for 2.10.12 with no library loaded.

Can I run Music Assistant in Docker without host networking?

Barely. A bridge network with ports 8095 and 8097 published works only for software players that need no discovery, and it is unsupported. Music Assistant needs network_mode: host or macvlan for discovery and for AirPlay, Cast, DLNA, and Sonos players.

Does Music Assistant work across VLANs?

No. Music Assistant must be on the same layer 2 network as the players, with no VLANs between them. Discovery uses multicast (mDNS, uPnP), and AirPlay opens random TCP and UDP ports, so a firewall between VLANs breaks both. The docs call this the single most common cause of support requests.


Share this post on:

Send a Webmention

Written about this post on your own site? Send a webmention and it'll show up above once verified.


Next Post
When Your NVMe Falls Off the PCIe Bus

Discussion

Powered by Garrul . Sign in with GitHub or Google, or post anonymously.

Related Posts