Skip to content
BranchesTags

Latest commit

 

History

87 Commits

Folders and files

NameName
Last commit message
Last commit date
.github/workflows
.github/workflows
 
 
custom_components/soundtouch_direct
custom_components/soundtouch_direct
 
 
README.md
README.md
 
 
hacs.json
hacs.json
 
 

Repository files navigation

Bose SoundTouch Direct

hacs_badge HA Version License: MIT

A full-featured Home Assistant custom integration for Bose SoundTouch speakers, communicating directly with the local SoundTouch Web API — no cloud, no third-party libraries, no polling lag.

Why not use the built-in soundtouch integration?
The built-in integration hasn't been meaningfully updated in years. This integration adds real-time WebSocket push updates, TTS support, media browsing, multi-room zone management, bass control, track feedback, and a proper UI config flow with auto-discovery.

Features

Feature Details
🎵 Full media player Play, pause, stop, next/prev track, volume, mute
📻 Source selection Switch between physical inputs (TV, HDMI) and network sources (Spotify, TuneIn, etc.) directly from HA
🔢 Presets Trigger any of the 6 hardware presets from automations
⚡ Real-time updates WebSocket push notifications — state changes appear instantly
🔊 Multi-room zones Create, expand, and dissolve speaker groups
🎚️ Bass control Adjust bass level per speaker (-9 to +9)
👍 Track feedback Thumbs up/down (Pandora), add/remove favourites
🗣️ TTS support Works as a target in the HA Media browser and tts.speak service — plays via UPnP AVTransport without switching the device's active source
🔔 TTS chime A soft chime precedes announcements on active sources to absorb the firmware's fade-in effect
💤 TTS from standby Wakes the device, plays the announcement, then correctly returns it to standby afterwards
🔍 Auto-discovery Finds devices automatically via Zeroconf/mDNS
🔄 Reconfigure Update IP address without losing entity history
📋 Device registry Shows firmware version, model, and manufacturer

⚠️ Bose cloud notice: Bose is shutting down their cloud services in May 2026. This integration is designed to work entirely locally and is not affected.

Requirements

  • Home Assistant 2024.1 or later
  • Bose SoundTouch speaker on the same local network as Home Assistant
  • Ports 8090 (HTTP API) and 8080 (WebSocket) reachable from HA

Installation

Via HACS (recommended)

  1. Open HACS → Integrations → ⋮ → Custom Repositories
  2. Add this repository URL, set category to Integration, click Add
  3. Search for Bose SoundTouch Direct and click Download
  4. Restart Home Assistant

Manual

  1. Download the latest release zip and extract it
  2. Copy the soundtouch_direct folder into config/custom_components/
  3. Restart Home Assistant

Setup

Auto-discovery

If your SoundTouch speaker is on the same network, Home Assistant will detect it automatically via mDNS and show a notification. Click Configure to add it in one step.

Manual

  1. Go to Settings → Devices & Services → Add Integration
  2. Search for Bose SoundTouch Direct
  3. Enter the IP address of your speaker (e.g. 192.168.1.50)
  4. Click Submit — the device and entity are created immediately

Tip: Assign your speaker a static IP (or a DHCP reservation) so the address never changes. If it does change, use Settings → Devices & Services → Bose SoundTouch Direct → Reconfigure to update it without losing your entity.

Text-to-Speech

The integration registers as a full media browser target, so your SoundTouch speaker will appear in:

  • The Media panel TTS target picker
  • The tts.speak service entity dropdown
  • Any automation action targeting a media player

TTS is played via an internal stream proxy using the LOCAL_INTERNET_RADIO source, which works entirely locally without requiring Bose cloud services.

How TTS playback works:

TTS audio is pushed to the device via UPnP AVTransport (SetAVTransportURI + Play on port 8091), not by switching the device's source through the Web API. This has two nice side effects:

  • No source switching, no restore needed. Whatever was playing (TV, radio, Spotify, etc.) keeps reporting as the active source the whole time — announcements simply play on top and the original source is never actually left.
  • Active source (e.g. TV): The SoundTouch firmware still applies its own audio fade-in when new audio starts playing. A soft chime is automatically prepended to the announcement to absorb this fade-in so the spoken message isn't clipped.
  • Standby: The device wakes to play the announcement. Afterwards, the integration checks whether the device is genuinely awake before sending the power-off command — avoiding accidentally turning the device back on if it never left standby state in the Web API.

Why UPnP? Bose shut down their cloud services on May 6, 2026, which broke the LOCAL_INTERNET_RADIO source entirely (even for purely local URLs). UPnP AVTransport on port 8091 is unaffected and fully local.

Example automation using TTS:

action:
  - service: tts.speak
    target:
      entity_id: tts.piper  # or whichever TTS engine you use
    data:
      media_player_entity_id: media_player.living_room
      message: "Dinner is ready!"

Custom Services

All services target media_player entities from this integration.

soundtouch_direct.play_preset

Play one of the 6 presets stored on the device (configured via the SoundTouch app).

service: soundtouch_direct.play_preset
target:
  entity_id: media_player.living_room
data:
  preset_id: 2   # 1–6

soundtouch_direct.set_bass

Adjust the bass level.

service: soundtouch_direct.set_bass
target:
  entity_id: media_player.living_room
data:
  bass_level: 4   # -9 to +9, 0 is default

soundtouch_direct.play_everywhere

Set this speaker as the zone master and group every other SoundTouch device on your network into it.

service: soundtouch_direct.play_everywhere
target:
  entity_id: media_player.living_room

soundtouch_direct.create_zone

Create a multi-room zone with specific speakers. Use device IDs (found in the device registry or the device_id config entry attribute).

service: soundtouch_direct.create_zone
target:
  entity_id: media_player.living_room
data:
  master: "A1B2C3D4E5F6"
  slaves:
    - "F6E5D4C3B2A1"
    - "B2C3D4E5F6A1"

soundtouch_direct.add_zone_slave / remove_zone_slave

Add or remove a speaker from an existing zone without dissolving it.

service: soundtouch_direct.add_zone_slave
target:
  entity_id: media_player.living_room
data:
  slaves:
    - "F6E5D4C3B2A1"

soundtouch_direct.thumbs_up / thumbs_down

Send track feedback on services that support it (Pandora, etc.).

service: soundtouch_direct.thumbs_up
target:
  entity_id: media_player.living_room

soundtouch_direct.add_favorite / remove_favorite

Bookmark or remove the currently playing track.

service: soundtouch_direct.add_favorite
target:
  entity_id: media_player.living_room

Source Selection

The integration exposes all READY sources from the device as a source list with friendly names (e.g. TV, HDMI_1, ALEXA, TUNEIN). The current source is also shown with its friendly name.

The default HA media player card does not prominently expose the source selector. For the best experience, add a media-control card to your dashboard:

type: media-control
entity: media_player.your_soundtouch_entity

You can also switch source via a service call:

service: media_player.select_source
target:
  entity_id: media_player.living_room
data:
  source: TV

Extra State Attributes

The entity exposes these additional attributes beyond the standard media player ones:

Attribute Description
station_name Internet radio station name
station_location Station location or description
source_account Account used for the current source (e.g. Spotify username)
presets List of all 6 presets with their name and source

Example Automations

Morning playlist — play preset 1 at 7am

automation:
  alias: Morning music
  trigger:
    platform: time
    at: "07:00:00"
  action:
    service: soundtouch_direct.play_preset
    target:
      entity_id: media_player.bedroom
    data:
      preset_id: 1

Pause everything when you leave home

automation:
  alias: Pause on leaving
  trigger:
    platform: state
    entity_id: person.you
    to: not_home
  action:
    service: media_player.media_pause
    target:
      entity_id: all

Announce doorbell on all speakers

automation:
  alias: Doorbell announcement
  trigger:
    platform: state
    entity_id: binary_sensor.doorbell
    to: "on"
  action:
    service: tts.speak
    target:
      entity_id: tts.piper
    data:
      media_player_entity_id: media_player.living_room
      message: "Someone is at the front door."

Party mode on button press

automation:
  alias: Party mode
  trigger:
    platform: state
    entity_id: input_button.party_mode
  action:
    service: soundtouch_direct.play_everywhere
    target:
      entity_id: media_player.living_room

Troubleshooting

Device not found by auto-discovery
Ensure mDNS traffic is not blocked between your speaker's VLAN and Home Assistant. As a fallback, add the device manually using its IP address.

Cannot connect

  • Verify the SoundTouch app can reach the speaker from the same network
  • Confirm port 8090 is not firewalled between HA and the speaker
  • Assign the speaker a static IP or DHCP reservation to prevent address changes

WebSocket not connecting / state updates are slow
The WebSocket listener uses port 8080. If this port is blocked, the integration automatically falls back to polling every 10 seconds — the entity will still work, just with slightly delayed state updates. Check Settings → System → Logs and filter by soundtouch_direct for details.

Speaker not appearing as a TTS target
Make sure you are on the latest version of this integration. After updating the files, do a full HA restart (not just a reload).

IP address changed
Go to Settings → Devices & Services → Bose SoundTouch Direct → ⋮ → Reconfigure and enter the new IP. Your entity history is preserved.

How It Works

The integration communicates entirely on your local network:

Channel Port Purpose
HTTP REST 8090 All API commands (play, volume, source, etc.)
WebSocket 8080 Real-time push notifications from the device
HA HTTP 8123 Internal stream proxy for TTS and live radio (served via LOCAL_INTERNET_RADIO)

On startup, HA connects to the WebSocket and listens for notifications from the speaker (now playing changed, volume changed, etc.). When a notification arrives the coordinator immediately refreshes state — no polling required. If the WebSocket drops, the listener reconnects automatically with exponential backoff, and polling kicks in as a fallback in the meantime.

API Reference

Built against the Bose SoundTouch Web API.
Full spec: SoundTouch-Web-API.pdf

Endpoint Method Description
/info GET Device info, firmware version, capabilities
/now_playing GET Current playback state, track, art
/volume GET / POST Get or set volume level
/key POST Send key press (play, pause, presets, etc.)
/select POST Select a source or play a URL
/presets GET All 6 stored presets
/sources GET Available and ready sources
/bass GET / POST Bass level get/set
/bassCapabilities GET Min/max bass for this device
/getZone GET Current multi-room zone config
/setZone POST Create a zone
/addZoneSlave POST Add a slave to a zone
/removeZoneSlave POST Remove a slave from a zone
/recent GET Recently played items
WebSocket :8080 WS Push notifications for all state changes

License

MIT License — see LICENSE for details.
Not affiliated with or endorsed by Bose Corporation.

About

Home Assitant support for the Bose Sound Touch with direct connection

Topics

bosebose-soundtouchhome-assistanthome-assistant-componenthome-assistant-integrationsoundtouch

Resources

Readme
Activity

Stars

3 stars

Watchers

1 watching

Forks

1 fork
Report repository

Releases

Contributors

Languages