Installation — Home Assistant Addon

Which addon should you install?

Addon	Best for	Ingress port	Default player-port base	Startup default
Stable	Everyday use	`8080`	`8928`	Auto
RC	Release-candidate testing	`8081`	`9028`	Manual
Beta	Earliest prerelease testing	`8082`	`9128`	Manual

Requirements

Home Assistant OS or Supervised
Bluetooth adapter accessible to the HA host
Music Assistant running on your network

Installation

Add the addon repository

Use the button to add the repository automatically:

Or manually: Settings → Add-ons → Add-on store → ⋮ → Repositories and add:
```
https://github.com/trudenboy/sendspin-bt-bridge
```
Choose the addon variant

Install Sendspin Bluetooth Bridge for the stable track. Install the RC or Beta variant only when you specifically want prerelease builds.

Configure the addon

On the Configuration tab:

sendspin_server: auto
sendspin_port: 9000
base_listen_port: 8928         # optional: base port for players without explicit listen_port
update_channel: stable         # controls update checks only; does not switch addon variant
bluetooth_devices:
  - mac: "AA:BB:CC:DD:EE:FF"
    player_name: "Living Room Speaker"
  - mac: "11:22:33:44:55:66"
    player_name: "Kitchen Speaker"
    adapter: hci1
    static_delay_ms: 0
    listen_port: 8935          # optional per-device Sendspin port override
    listen_host: 192.168.1.50  # optional advertised host/IP for URL display

Start the addon

Start the addon. The stable addon defaults to auto-start; RC and beta default to manual start so prerelease installs are easier to keep separate.
Connect to Music Assistant features

Open the web UI → Configuration → Music Assistant and click 🏠 Sign in with Home Assistant if you want MA metadata, transport controls, queue actions, and group-volume sync.

Port behavior in addon mode

Ingress port is dynamically assigned by Home Assistant Supervisor. All three addon tracks (stable / RC / beta) ship with ingress_port: 0, and Supervisor picks a free port at runtime so the addons can co-exist with Matter / Thread and other host-network services without manual port planning. The bridge reads the actual port back from /addons/self/info on startup.
web_port is read but not applied. The addon schema still accepts it for legacy parity, but the bridge currently does not open a parallel direct listener in addon mode. Leave it blank.
base_listen_port sets the default Sendspin player range for devices without an explicit listen_port. Per-channel defaults differ to keep multiple addon variants disjoint: stable 8928, RC 9028, beta 9128.
Device listen_port wins per player. Use it when one speaker needs a fixed port.
Device listen_host changes the advertised host/IP only. The player still binds on 0.0.0.0 internally.

Opening the web interface

Use Open Web UI on the addon page or the HA sidebar entry. Both routes go through HA Ingress on the Supervisor-assigned port — there is no separate direct URL to memorise.

Update channel semantics

The installed addon variant determines whether you are on stable, RC, or beta code.
The update_channel option only controls which releases the in-app updater checks for (stable, rc, or beta).
Changing update_channel does not switch the installed addon track.
To move from stable to RC/beta, install that addon variant explicitly from the Add-on Store.

Audio routing on HA OS

The addon requests audio: true, so Home Assistant injects the audio bridge automatically. No manual PulseAudio or PipeWire socket mount is required.

HA Supervised on Ubuntu

If you run HA Supervised on Ubuntu 24.04+, the host AppArmor may block Bluetooth access even though the addon has its own AppArmor profile. The addon profile (v2.52.0+) includes dbus, and network raw, rules to work around this.

If you are on an older addon version and cannot update yet, see the Troubleshooting page for a manual workaround.

Applying configuration changes

Changes to devices, adapters, web_port, base_listen_port, and Music Assistant connection settings take effect after a restart. Use Restart on the addon page or Save & Restart in the web UI.