One container that turns a Raspberry Pi into a speaker almost anything can play to — AirPlay 2, Sendspin, Bluetooth, Spotify Connect and DLNA — sharing one sound card, with a single web page and one Home Assistant device showing whatever is playing.

The upstream badges show the latest released versions. The versions this image is pinned to live in versions.env; a daily job opens a pull request whenever upstream moves ahead of them.

🤖 Built with AI assistance

This repository — the Dockerfile, the entrypoint and service scripts, the web UI, the GitHub Actions workflows and this README — was generated with Claude Code and then reviewed and tested by a human. The image builds and the container was exercised end to end, but treat it the way you would any code you didn't write yourself: read it before you run it.

The upstream software it packages — Shairport Sync, nqptp and Sendspin — is not AI-generated. See Credits.

git clone https://github.com/romkey/hackstack-sendspin-shairport-sync.git
cd hackstack-sendspin-shairport-sync
cp .env.example .env
aplay -l                                        # find your card, e.g. hw:Headphones,0
$EDITOR .env                                    # set AIRPLAY_NAME and ALSA_PCM
docker compose -f docker-compose.prod.yml up -d

Then open http://<pi>/ — that is the whole thing for AirPlay and Sendspin.

Everything is one variable in .env. Set it to 1 to turn a piece on, 0 to turn it off:

Already set in the compose file, and needed: host networking, SYS_NICE, /dev/snd, and the two Avahi socket mounts. Don't remove them unless you know why.

Two things that commonly need attention:

• The web UI listens on port 80. With host networking that port must be free on the Pi; set WEB_PORT if something else has it.
• ALSA_PCM must match your actual card. Everything plays through one shared device, so if that value is wrong, nothing makes sound.

Five ways to play to it, all sharing one sound card:

They coexist rather than compete: ALSA dmix puts them all on the same output, so you never have to choose one, and if two play at once you hear both.

Two ways to see what's playing, whichever source it came from:

• A web page at http://<pi>/ — cover art, title, artist, album and progress, updated live over server-sent events.
• Home Assistant (optional) — MQTT auto-discovery registers one device with 20 entities: track and source sensors, cover art, a volume control, transport and restart buttons, and CPU/memory/temperature diagnostics.

Multi-arch images (linux/amd64, linux/arm64) are published to GitHub Container Registry on every push, tag and upstream release.

Shairport Sync and the Sendspin daemon both speak MPRIS, the standard Linux media-player D-Bus interface. The container runs a private D-Bus session bus, points both players at it, and the web UI is simply an MPRIS observer:

                  ┌──────────────────── container ─────────────────────┐
  iPhone ───────► │  shairport-sync ─┐                                 │
  (AirPlay 2)     │  + nqptp         │                                 │
                  │                  │                                 │
  Music           │  sendspin ───────┼─► session bus (MPRIS) ─┐        │
  Assistant ────► │                  │                        │        │
                  │  spotifyd ───────┘                        │        │
  Spotify app ──► │        │                                  ▼        │
                  │        │                      nowplaying web UI ───┼──► :80  
  Phone ────────► │  bluetoothd + bluealsa ─► system bus ──►   ▲       │
  (Bluetooth)     │        │                       (AVRCP)     │       │
                  │        │                                   │       │
  BubbleUPnP ───► │  gmediarender ──────────► HTTP/SOAP ───────┘       │
  (DLNA)          │        │                    (AVTransport)          │
                  │        ▼                                           │
                  │   ALSA dmix ──────────────────────────────────────►│──► 3.5mm jack / DAC
                  └────────────────────────────────────────────────────┘

Three of the five speak MPRIS, so they need no special handling — anything exporting org.mpris.MediaPlayer2.* on the session bus shows up in the UI automatically. The other two are adapted: BlueZ publishes AVRCP metadata as org.bluez.MediaPlayer1 on the system bus, and gmediarender has no bus interface at all, so the UI queries its UPnP AVTransport service over SOAP exactly as any DLNA controller would.

Requires a 64-bit OS (Raspberry Pi OS Bookworm/Trixie 64-bit, or Ubuntu) on a Pi 3 or newer. 32-bit and ARMv6 (Pi Zero W, Pi 1) are not supported — see Limitations.

sudo apt install -y docker.io docker-compose-plugin
sudo usermod -aG docker "$USER"   # log out and back in

Find your output device:

aplay -l

The 3.5 mm jack is usually hw:Headphones,0, a HAT DAC typically hw:sndrpihifiberry,0. Whatever it is goes in ALSA_PCM — everything plays through it.

Then pull the repo (or just docker-compose.prod.yml and .env.example), set ALSA_PCM and AIRPLAY_NAME, and start it:

git clone https://github.com/romkey/hackstack-sendspin-shairport-sync.git
cd hackstack-sendspin-shairport-sync
cp .env.example .env
$EDITOR .env
docker compose -f docker-compose.prod.yml up -d

That runs the published image from GHCR. Open http://<pi-address>/, and the speaker appears in AirPlay pickers and in Music Assistant.

To update later:

docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d

There are two compose files: docker-compose.prod.yml pulls the published image and reads everything from .env, while docker-compose.yml builds from this checkout with the settings inline — use that one when you are changing the image itself.

Host networking is required. AirPlay 2 needs mDNS on the LAN and nqptp needs UDP ports 319/320. Bridge networking will not work.

Everything is environment variables. Copy .env.example to .env — it lists every variable below with notes — and mount /config for persistence and file-level overrides.

Set AIRPLAY_NAME and you are done naming things. Sendspin, Bluetooth, Spotify, DLNA and the Home Assistant device all fall back to it, so the speaker appears under one name everywhere. Each can still be overridden individually. The exception is AVAHI_HOST_NAME, which is the machine's mDNS host name rather than the speaker's name and so follows the hostname instead.

When the environment variables aren't enough, drop a config file into the mounted config/ directory and the entrypoint uses it verbatim instead of generating one. Annotated starting points ship in config/:

• config/shairport-sync.conf — full Shairport Sync configuration. If you write your own, keep mpris_service_bus = "session"; or the web UI will lose AirPlay metadata.
• config/asound.conf — your own ALSA routing, including softvol and bit-perfect variants.

cp config/shairport-sync.conf.example config/shairport-sync.conf
docker compose -f docker-compose.prod.yml restart

Sendspin's own persistent settings live in config/sendspin/. See config/README.md for the details, including which .env variables a config file overrides.

AirPlay, Spotify Connect and DLNA all announce themselves over mDNS, and with host networking there is only one network stack to announce on. Raspberry Pi OS runs avahi-daemon by default, so if the container starts a second one the two fight over the machine's .local name and rename each other in a loop:

Host name conflict, retrying with heavy-metal-5
Host name conflict, retrying with heavy-metal-6

The compose files therefore mount the host's Avahi and D-Bus sockets:

volumes:
  - /var/run/dbus:/var/run/dbus
  - /var/run/avahi-daemon:/var/run/avahi-daemon

With both present the container detects them and uses the host's daemon instead of starting its own — services register against the host's Avahi and the name stays heavy-metal.local. AVAHI_MODE controls this:

If something else is already doing mDNS. Some systems answer mDNS with systemd-resolved rather than Avahi. Two responders cannot share one IP address: they collide on the reverse record for it, which Avahi reports as a host name conflict and tries to fix by renaming itself — heavy-metal-shareplay-2, -3, -4, without ever settling, because renaming cannot resolve an address collision.

When the container detects another responder on port 5353 it starts Avahi with publish-addresses=no and points its services at the host's existing name. Services are then published by our Avahi and the address is answered by the stack that already owns it, so clients browse and resolve normally. AVAHI_PUBLISH_ADDRESSES=yes|no|auto overrides the detection.

That works, but it is a workaround for a host that is running two mDNS stacks. The cleaner fix is to pick one — either install avahi-daemon on the host and mount its sockets, or turn off systemd-resolved's mDNS:

sudo apt install avahi-daemon && sudo systemctl enable --now avahi-daemon
printf '[Resolve]\nMulticastDNS=no\n' | sudo tee /etc/systemd/resolved.conf.d/no-mdns.conf
sudo systemctl restart systemd-resolved

Detection asks the system bus whether org.freedesktop.Avahi has an owner, rather than just checking that the sockets exist — a mounted socket with nothing behind it is exactly the case that made Shairport Sync exit with Could not establish mDNS advertisement! in a restart loop. When the sockets are mounted but Avahi does not answer, the container falls back to running its own under a distinct <hostname>-shareplay name, so it still advertises without colliding with the host.

Docker bridge addresses. In container mode Avahi would otherwise announce every interface it can see, including docker0, br-* and veth*. An AirPlay client that picks 172.17.0.1 out of that list simply fails to connect. The entrypoint therefore restricts announcements to the machine's real interfaces — everything except loopback and the ones Docker creates — so a Pi on both Ethernet and Wi-Fi advertises on eth0,wlan0 and nothing else. Override with AVAHI_INTERFACES=wlan0 to narrow it further. If the host's own Avahi has the same problem, fix it in the host's /etc/avahi/avahi-daemon.conf — that one is outside this container's control.

A sound card can normally only be opened by one program at a time, so by default the container puts an ALSA dmix device in front of it and points both players at it. That means AirPlay and Sendspin can both be connected at once — and if two sources play simultaneously you will hear both, mixed.

dmix fixes the output at 16-bit stereo at ALSA_RATE, and resamples anything else. For bit-perfect output to a good DAC, set AUDIO_SHARING=exclusive — then only one player can hold the card, and the other will fail to start playback until it's free.

Off by default. Turning it on adds a third source: a phone pairs with the Pi and plays straight to it over A2DP, mixed into the same output as AirPlay and Sendspin, and showing up in the same web UI via AVRCP metadata.

Not verified on real hardware. Docker has no radio to give it, so this is the least-proven feature here. What has been verified, against the stand-in BlueZ in scripts/fake_bluez.py: the web UI's AVRCP reader, and the pairing agent's full startup — it registers with NoInputNoOutput capability, becomes the default agent, powers the adapter, sets its name, turns on pairable and discoverable, and marks a paired device trusted. bluetoothd and bluealsa are only checked as far as starting and taking their D-Bus names.

What is still unproven is everything that needs a radio: pairing over the air, reconnecting, and the audio path. Treat this feature as beta.

One real bug has already been found and fixed this way — the agent used -> None return annotations, which dbus-fast rejects when the class is defined, so it could never have started at all. That is what web/tests/test_bt_agent.py now guards against.

It needs three things beyond ENABLE_BLUETOOTH=1:

1. NET_ADMIN on the container, and /dev/rfkill — both are commented out in the compose file, under cap_add and devices. NET_ADMIN lets bluetoothd open the management socket; /dev/rfkill lets the container clear a soft block, without which the adapter cannot be powered on at all.

2. Host networking, which you already have. Bluetooth adapters belong to a network namespace, so the container sees hci0 only because it shares the host's.

3. The host's Bluetooth stack stopped. Only one bluetoothd can own an adapter, and it has to be the container's:

   sudo systemctl disable --now bluetooth

That third point is the real cost: the Pi then has no Bluetooth of its own — no BT keyboards, no host pairing. If you need Bluetooth on the host for anything else, leave this off.

Pairing is automatic. There is no screen or keypad on a headless Pi, so the container runs an agent that accepts every pairing request and trusts the device afterwards so it can reconnect on its own. That means anyone in radio range can pair while the Pi is discoverable. Once your own devices are paired, set BLUETOOTH_DISCOVERABLE=0 to stop advertising. Pairing keys are stored in config/bluetooth/, so they survive a rebuild.

What to expect:

• SBC only, so quality sits below AirPlay and Sendspin.
• No cover art. AVRCP 1.6 can carry it but BlueZ does not expose it, so Bluetooth tracks show the placeholder, same as Sendspin.
• 2.4 GHz contention is real. The Pi's Bluetooth and WiFi share silicon and an antenna path. On 2.4 GHz WiFi you should expect audible dropouts during Bluetooth playback. On 5 GHz or Ethernet it is largely a non-issue.

Off by default. With ENABLE_SPOTIFY=1 the Pi shows up in the Spotify app's device picker, and playback is handed off to it the same way as to any Connect speaker.

This runs spotifyd, built from source in the image. Spotify removed username/password logins, so there are no credentials to configure — you claim the speaker from the app over the local network. As with any Connect device, a Premium account is required.

Metadata comes over MPRIS, so title, artist, album, duration and position all appear in the web UI. Cover art does not: spotifyd's MPRIS interface doesn't publish an art URL.

Not verified against a real account. The daemon builds, starts and advertises itself over zeroconf, but with no Premium account to claim the speaker with, the audio path is unproven. Note that spotifyd registers its MPRIS name only once a session is active — while idle it is absent from the bus, so it will not appear in the web UI until a phone hands playback to it, the same way Sendspin behaves.

Off by default. With ENABLE_DLNA=1 the Pi becomes a UPnP media renderer via gmediarender, which is the most useful of the optional sources if you have Android devices: AirPlay covers iOS, Spotify Connect covers only Spotify, and DLNA covers a long tail of Android apps, BubbleUPnP, foobar2000, Plex, Jellyfin and most NAS media servers.

It advertises as audio-only by default, so controllers don't offer it as a video display. Its UUID is generated once and kept in config/dlna-uuid, so restarts don't look like a brand-new device to controllers.

DLNA is the one optional source that gives you cover art — controllers send it in the track metadata, so the UI shows real artwork rather than the placeholder.

Unlike Bluetooth and Spotify, this one was tested end to end: a simulated controller pushes a track and the UI renders it.

Home Assistant's DLNA DMR integration usually finds renderers by itself over SSDP. When it doesn't, it asks for the URL of the device description rather than an address — that URL is:

http://<pi-ip>:49494/description.xml

Adjust the port if you changed DLNA_PORT. Check it first from any machine on the network:

curl -s http://<pi-ip>:49494/descripti

Read the rest on GitHub