Snapcast Multi-Room Audio Setup with Music Assistant and Home Assistant

README.md

Snapcast Multi-Room Audio Setup with Music Assistant and Home Assistant

This guide documents setting up Snapcast for multi-room audio with Music Assistant integration on a home network.

Architecture

• Snapserver: Docker container on Ubuntu VM (10.0.0.4)
• Snapclients: Raspberry Pi devices with USB speakers
• Control: Home Assistant (10.0.0.3) with Music Assistant integration

Snapserver Docker Setup

docker-compose.yml

services:
  snapserver:
    image: ivdata/snapserver:latest
    container_name: snapserver
    restart: unless-stopped
    network_mode: host  # IMPORTANT: Required for Music Assistant dynamic port allocation
    volumes:
      - snapcast-data:/var/lib/snapserver
      - ./snapserver.conf:/etc/snapserver.conf:ro
    environment:
      - TZ=Asia/Jerusalem

volumes:
  snapcast-data:

Key Point: Use network_mode: host

Music Assistant dynamically creates TCP streams on random ports (e.g., 4997, 5121, 5126) for each player. Using network_mode: host instead of explicit port mappings allows these dynamic ports to work without configuration.

Symptom if not using host networking: Playback instantly pauses when you try to play to a Snapcast client.

snapserver.conf

# Snapserver Configuration

[stream]
# Default stream (optional fallback)
source = tcp://0.0.0.0:4953?name=default&mode=server

# TTS stream for Home Assistant announcements
source = tcp://0.0.0.0:4954?name=TTS&mode=server

[http]
enabled = true
port = 1780
doc_root = /usr/share/snapserver/snapweb

[tcp]
enabled = true
port = 1705

[logging]
filter = *:info

Snapclient Configuration

/etc/default/snapclient

SNAPCLIENT_OPTS="-h 10.0.0.4 -p 1704 -s hw:2,0"

Parameters:

• -h: Snapserver host IP
• -p: Snapserver streaming port (1704)
• -s: ALSA sound device (use aplay -l to find correct device)

Common Mistake: Wrong Device Syntax

Wrong:

SNAPCLIENT_OPTS="-h 10.0.0.4 -p 1704 --player alsa:device=hw:2,0"

Correct:

SNAPCLIENT_OPTS="-h 10.0.0.4 -p 1704 -s hw:2,0"

The --player alsa:device= syntax may cause the client to fall back to the default audio device instead of the specified one.

Finding the Correct Audio Device

aplay -l

Example output:

card 0: audiocodec [audiocodec], device 0: CDC PCM Codec-0
card 1: HDMI [HDMI], device 0: ahub_plat-i2s-hifi
card 2: USBSpeaker [USB Audio Device], device 0: USB Audio

For the USB speaker, use hw:2,0 (card 2, device 0).

Ports Reference

Port	Purpose
1704	Client streaming (snapclients connect here)
1705	TCP control / JSON-RPC (Home Assistant connects here)
1780	HTTP / Snapweb UI
4953+	TCP audio input streams (Music Assistant uses dynamic ports)

Music Assistant Integration

In Music Assistant:

1. Go to Settings → Providers
2. Add Snapcast provider
3. Set server: <snapserver-ip> port: 1705 (control port)

Music Assistant communicates via the control port and dynamically creates audio streams as needed.

Troubleshooting

Playback Instantly Pauses

• Cause: Docker port mapping blocking dynamic ports
• Fix: Use network_mode: host in docker-compose.yml

No Audio on Client

• Check logs: journalctl -u snapclient -n 30
• Verify device: Look for PCM name: in logs - should match your USB speaker
• Fix device syntax: Use -s hw:X,Y not --player alsa:device=hw:X,Y

Client Shows "No chunks available"

• Cause: No audio being sent to the stream, or client assigned to wrong stream
• Check: Use Snapweb (http://snapserver:1780) to verify stream assignments

Service Commands

# Restart snapclient
sudo systemctl restart snapclient

# Check snapclient status
sudo systemctl status snapclient

# View logs
journalctl -u snapclient -f

# Restart snapserver (Docker)
docker restart snapserver

# View snapserver logs
docker logs snapserver --tail 50

---

Generated by Claude Code. Please validate this information against your specific setup and the official Snapcast documentation.