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:
| Piece | Installed in | What it does |
|---|---|---|
| Home Assistant Integration | HA | MA players show up in HA as media_player entities |
| Home Assistant Plugin | MA | Drives an MA player’s power, volume, and mute from an HA entity (wake an amp from standby) |
| Home Assistant Media Players provider | MA | HA 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:
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=infoKeep 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:
| Protocol | In sync? | Notes |
|---|---|---|
| AirPlay | Yes | Lossless. Mixes AirPlay 1 (RAOP) and AirPlay 2 devices. Per-device sync correction up to ±500 ms. |
| Google Cast | Only inside a Cast group made in the Google Home app | Up to 192 kHz/24-bit single player, 96 kHz for a Cast group. A group of only a stereo pair does not work. |
| Snapcast | Yes | Built-in Snapserver. About 1 s delay on play/pause/skip. |
| Sendspin | Yes | Open protocol from the Open Home Foundation. Technical preview. |
| Squeezelite | Yes, with per-player correction of ±500 ms | Software clients such as piCorePlayer. No native mute. |
| HA media players | Fallback only | Lower 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:
- 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. - 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.
- 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:
snapclient --hostID kitchen tcp://192.168.1.10:1704The 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:
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:
- 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: replacemedia_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:
- 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: 70Prefer 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:
- 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: trueFor a quick temporary group, use the standard HA action with the leader as the target:
- 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.patiomedia_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
- HomePod refuses to play. In the HomeKit “AirPlay (Speaker & TV)” setting, do not select “Only people in this home”. Also, MacBooks cannot be played to, because RAOP was removed.
- LMS conflict. The Squeezelite provider uses port 3483. Do not run Logitech Media Server on the same machine with the provider enabled, and do not run the HA slimproto integration at the same time.
- Cast stereo pairs. A Cast group that contains only a stereo pair does not work.
- Stable vs beta. Do not switch between them by changing the image tag. Do not copy the database between beta and stable instances. MA 2.11 is in beta, and 2.10.12 is the stable release.
- That 1 second Snapcast lag. It comes from the 1000 ms default buffer (adjustable from 200 to 6000). Pause, skip, and play feel slow on Snapcast clients. That is the design.
- External Snapserver. It must be 0.27.0 or later, and 0.30.0 cannot be used.
- Sendspin is a technical preview. It has sync, auto discovery, per-player EQ and volume, and a 0-5000 ms static delay. A Sendspin device plays for one server at a time, and many ask for 16-bit audio. ESPHome ESP32 builds need at least 2 MB PSRAM and 4 MB flash. Fun to test, but do not make it your only path to sound in the house yet.
- AirPlay 2 is new in MA. Password pairing and PTP timing are not supported yet, and some devices need PIN pairing.
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.