docker-compose.yml

services:
  local-audio:
    build: .
    container_name: ma-local-audio
    restart: unless-stopped
    # Both halves of the player need the host's network namespace: mDNS to be
    # discovered, and port 8928 for the server to connect back in on.
    network_mode: host
    devices:
      - /dev/snd:/dev/snd
    volumes:
      - local-audio-data:/data
      # Host-Avahi mode. Bind-mount the host's system bus and the container
      # leaves its own dbus and avahi-daemon down, advertising through the
      # host's Avahi instead. Use it when the host already runs Avahi, which two
      # responders on port 5353 would otherwise fight with. Read-only is all a
      # bus client needs.
      # - /var/run/dbus:/var/run/dbus:ro
      # Native PulseAudio output. Bind-mount the host's PulseAudio socket and
      # set PULSE_SERVER below, then use `pulse` or `pulse:<sink>`. Reach for it
      # when the host runs PulseAudio: `-l` can then name the server's sinks,
      # the host's mixer sees a stream called sendspin-cli, and the sync figure
      # is the server's rather than an ALSA plugin's own buffering. The 0700 on
      # a per-user XDG_RUNTIME_DIR is not the obstacle it looks -- the daemon
      # resolves the mount as root and this container runs as root -- but on
      # Fedora or RHEL, SELinux is: add `:z` to the mount there. The cookie
      # authenticates the client, and is unnecessary only where the socket is
      # configured `auth-anonymous=1`.
      # - /run/user/1000/pulse/native:/run/pulse/native
      # - ${HOME}/.config/pulse/cookie:/root/.config/pulse/cookie:ro
      # Native PipeWire output. The same shape, for a host running PipeWire; use
      # `pipewire` or `pipewire:<node>`. It reaches the same server `pulse` does
      # through pipewire-pulse; what it adds is that only a native client can
      # name a *node*, and that nothing translates the audio path. It is the
      # only route where pipewire-pulse is not installed. PIPEWIRE_REMOTE takes
      # an absolute path; where that is ignored, mount the whole runtime
      # directory instead and set XDG_RUNTIME_DIR to it.
      # - /run/user/1000/pipewire-0:/run/pipewire-0
    environment:
      # Name shown in Music Assistant. Left unset every container is called
      # `Local Audio`, so name them when running more than one on a network.
      # SENDSPIN_NAME: Living Room
      # `default` follows /etc/asound.conf, `pulse` and `pipewire` reach a sound
      # server on the host through the native backends, a bare name that is none
      # of those is an ALSA PCM such as `hw:1,0`, and `null` discards the audio.
      # `docker exec ma-local-audio sendspin-cli -l` lists what this container
      # can actually see, sound-server sinks and nodes included.
      SENDSPIN_OUTPUT: default
      # Paired with the socket mounts above, and read by the client libraries
      # rather than by this image. PULSE_COOKIE goes with the cookie mount, and
      # is left out where the server takes anonymous clients. The XDG_RUNTIME_DIR
      # alternative to PIPEWIRE_REMOTE is in the mount comment above.
      # PULSE_SERVER: unix:/run/pulse/native
      # PULSE_COOKIE: /root/.config/pulse/cookie
      # PIPEWIRE_REMOTE: /run/pipewire-0
      # SENDSPIN_LOG_LEVEL: info
      # How much audio the output keeps buffered, 10 to 2000 milliseconds. Left
      # unset the player picks its own figure; raise it where the sound breaks
      # up on a busy or slow machine, at the cost of a longer wait when a track
      # starts or is seeked. Anything that is not a whole number in that range
      # stops the container with a line naming it -- with the restart policy
      # above, one that keeps retrying -- rather than reaching the player.
      # SENDSPIN_BUFFER_MS: 250
      # Move one format to the front of the list this player advertises, as
      # <codec>:<rate>:<depth>:<channels> -- for the DAC that is only happy in
      # one shape. A format the output cannot advertise stops the player from
      # starting rather than quietly playing something else -- with the restart
      # policy above, a container looping on the same refusal -- so set it only
      # against a device whose capabilities `sendspin-cli -l` has confirmed.
      # SENDSPIN_AUDIO_FORMAT: flac:48000:24:2
      # This player's stable identity, which a server files volume, group
      # membership and pairing under. Left unset it is derived from the network
      # interface MAC, so two containers on one host would share it and each
      # server-side setting would land on whichever connected last. Give each
      # its own only when running more than one on the same machine.
      # SENDSPIN_ID: living-room-left
      # Run a shell command when a stream starts and when it stops -- switching
      # an amplifier relay on and off again is what these are for. The value is
      # a command, not data: it is handed to `sh -c` inside the container and
      # runs with whatever that container can reach. The event's facts arrive as
      # SENDSPIN_EVENT (start|stop) and, where the server said so,
      # SENDSPIN_SERVER_ID, SENDSPIN_SERVER_NAME, SENDSPIN_SERVER_URL,
      # SENDSPIN_CLIENT_ID and SENDSPIN_CLIENT_NAME. Neither holds up playback,
      # and a non-zero exit is a warning in the log rather than a player failure.
      #
      # To read one of those in the command itself, write it `$$SENDSPIN_EVENT`.
      # A single `$` is expanded by `docker compose` before the container is
      # ever started, so the hook would be handed an empty string; the doubled
      # form is what reaches it. Neither example below has that problem, and a
      # command that quietly did nothing would be a hard one to work out.
      # SENDSPIN_HOOK_START: curl -fsS -X POST http://192.168.1.20/relay/0?turn=on
      # SENDSPIN_HOOK_STOP: curl -fsS -X POST http://192.168.1.20/relay/0?turn=off
      # Dial out to one specific server instead of waiting to be discovered.
      # Any value here suppresses the mDNS advertisement.
      # SENDSPIN_SERVER: 192.168.1.10:8927

volumes:
  local-audio-data: