The following custom services are provided by this integration.

• Adjust Audio Tone Levels
• Clear Source NowPlayingStatus
• Get Audio DSP Controls
• Get Audio Product Tone Controls
• Get Balance
• Get Bass Capabilities
• Get Bass Level
• Get Device Information
• Get Music Station List
• Get Preset List
• Get Recent List
• Get Recent List Cache
• Get Supported URLs
• Play Content Item
• Play Handoff
• Play TTS Message
• Play URL DLNA
• Play URL Notification
• Reboot Device
• Remote Keypress
• Set Audio DSP Controls
• Set Audio Product Tone Controls
• Set Balance Level
• Set Bass Level
• Snapshot Restore
• Snapshot Store
• Update Source NowPlayingStatus
• Zone Member Toggle

Adjusts the Bass and Treble values for SoundTouch devices that support the /audioproducttonecontrols feature. This allows both the bass and treble values to be adjusted.

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SoundTouchPlus device that will process the request.
• bass_level - The bass level to set; range is -100 to +100.
• treble_level - The treble level to set; range is -100 to +100.

service: soundtouchplus.audio_tone_levels
data:
  entity_id: media_player.soundtouch_livingroom
  bass_level: 50
  treble_level: 50

Clears the NowPlayingStatus object for a given source and sourceAccount.

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SoundTouchPlus device that will process the request.
• source - Source input this content item is played with (case-sensitive).
• source_account - Source account this content item is played with (case-sensitive).

service: soundtouchplus.clear_source_nowplayingstatus
data:
  entity_id: media_player.soundtouch_livingroom
  source: PRODUCT
  source_account: TV

Gets the current audio dsp controls configuration for SoundTouch devices that support the /audiodspcontrols feature.

Note that some SoundTouch devices do not support this functionality. For example, the ST-300 will support this, but the ST-10 will not.

This service will return service response data.

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SoundTouchPlus device that will process the request.
• refresh - True to query the device for realtime information and refresh the cache; otherwise, False to just return the cached information.

action: soundtouchplus.get_audio_dsp_controls
data:
  entity_id: media_player.soundtouch_livingroom
  refresh: true

audio_mode: AUDIO_MODE_DIRECT
supported_audio_modes: AUDIO_MODE_NORMAL|AUDIO_MODE_DIALOG
video_sync_audio_delay: 0

Gets the current audio product tone controls configuration for SoundTouch devices that support the /audioproducttonecontrols feature.

Note that some SoundTouch devices do not support this functionality. For example, the ST-300 will support this, but the ST-10 will not.

This service will return service response data.

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SoundTouchPlus device that will process the request.
• refresh - True to query the device for realtime information and refresh the cache; otherwise, False to just return the cached information.

action: soundtouchplus.get_audio_product_tone_controls
data:
  entity_id: media_player.soundtouch_livingroom
  refresh: true

bass:
  control_type: bass
  min_value: -100
  max_value: 100
  step: 25
  value: 75
treble:
  control_type: treble
  min_value: -100
  max_value: 100
  step: 25
  value: 75

Gets the current balance configuration of the device.

Note that some SoundTouch devices do not support this functionality. For example, the ST-10 will support this if configured as a stereo pair, but the ST-300 will not.

This service will return service response data.

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SoundTouchPlus device that will process the request.
• refresh - True to query the device for realtime information and refresh the cache; otherwise, False to just return the cached information.

action: soundtouchplus.get_balance
data:
  entity_id: media_player.bose_st10_1
  refresh: false

device_id: 9030618C7D4C
actual: 0
default: 0
is_available: false
maximum: 7
minimum: -7
target: 0

Gets the current bass capability configuration of the device.

Note that some SoundTouch devices do not support this functionality. For example, the ST-10 will support this, but the ST-300 will not.

This service will return service response data.

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SoundTouchPlus device that will process the request.
• refresh - True to query the device for realtime information and refresh the cache; otherwise, False to just return the cached information.

action: soundtouchplus.get_bass_capabilities
data:
  entity_id: media_player.bose_st10_1
  refresh: false

device_id: 5072249B7B1D
default: 0
is_available: true
maximum: 0
minimum: -9

Gets the current bass configuration of the device.

Note that some SoundTouch devices do not support this functionality. For example, the ST-10 will support this, but the ST-300 will not.

This service will return service response data.

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SoundTouchPlus device that will process the request.
• refresh - True to query the device for realtime information and refresh the cache; otherwise, False to just return the cached information.

action: soundtouchplus.get_bass_level
data:
  entity_id: media_player.bose_st10_1
  refresh: true

device_id: 9030618C7D4C
actual: 0
target: 0

Gets information about the device.

This service will return service response data.

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SoundTouchPlus device that will process the request.

action: soundtouchplus.get_device_info
data:
  entity_id: media_player.bose_st10_1
  refresh: true

device_id: A8EB31B0B723
device_name: Bose-ST300
device_type: SoundTouch 300
country_code: US
connect_timeout: 30
host: 192.168.1.80
ip_port: 8090
log_read_url: http://192.168.1.80/logread.dat
mac_address: A8EB31B0B723
module_type: sm2
pts_url: http://192.168.1.80/pts.dat
region_code: US
streaming_account_uuid: "1234567"
streaming_url: https://streaming.bose.com
upnp_url: http://192.168.1.80:8091/XD/BO5EBO5E-F00D-F00D-FEED-A8EB31B0B723.xml
variant: ginger
variant_mode: noap
components:
  - component_category: SCM
    software_version: 27.0.6.46330.5043500 epdbuild.trunk.hepdswbld04.2022-08-04T11:20:29
    serial_number: A8EB31B0B723
  - component_category: PackagedProduct
    software_version: 1.16.7.5043495
    serial_number: 073992P72221440AE
  - component_category: F0
    software_version: 1.8.1.12410
    serial_number: n/a
  - component_category: BLOB
    software_version: 1.16.7.5043495
    serial_number: n/a
  - component_category: LPM
    software_version: "1.16.7.12619: 2021-06-15T12:16:01 (Release)"
    serial_number: n/a
  - component_category: LPMBL
    software_version: 1.0.0.7617
    serial_number: n/a
  - component_category: LLW
    software_version: "25"
    serial_number: n/a
  - component_category: DSP
    software_version: 1.9.12.12429
    serial_number: n/a
  - component_category: HDMI
    software_version: 1.00.21.20
    serial_number: n/a
  - component_category: BASS
    software_version: 01.09.15
    serial_number: n/a
network_info:
  - mac_address: A8EB31B0B723
    ip_address: 192.168.1.80
    type_value: SCM
  - mac_address: A43739210527
    ip_address: 192.168.1.80
    type_value: SMSC
supported_uris:
  - addGroup
  - addStation
  - addWirelessProfile
  - addZoneSlave
  - audiodspcontrols
  - audioproductlevelcontrols
  - audioproducttonecontrols
  - audiospeakerattributeandsetting
  - balance
  - bass
  - bassCapabilities
  - bluetoothInfo
  - bookmark
  - cancelPairLightswitch
  - capabilities
  - clearBluetoothPaired
  - clearPairedList
  - clockDisplay
  - clockTime
  - criticalError
  - DSPMonoStereo
  - enterBluetoothPairing
  - enterPairingMode
  - factoryDefault
  - genreStations
  - getActiveWirelessProfile
  - getBCOReset
  - getGroup
  - getZone
  - info
  - introspect
  - key
  - language
  - listMediaServers
  - lowPowerStandby
  - marge
  - masterMsg
  - name
  - nameSource
  - navigate
  - netStats
  - networkInfo
  - notification
  - nowPlaying
  - nowSelection
  - pairLightswitch
  - pdo
  - performWirelessSiteSurvey
  - playbackRequest
  - playNotification
  - powerManagement
  - powersaving
  - presets
  - productcechdmicontrol
  - producthdmiassignmentcontrols
  - pushCustomerSupportInfoToMarge
  - rebroadcastlatencymode
  - recents
  - removeGroup
  - removeMusicServiceAccount
  - removePreset
  - removeStation
  - removeZoneSlave
  - requestToken
  - search
  - searchStation
  - select
  - selectLastSoundTouchSource
  - selectLastSource
  - selectLastWiFiSource
  - selectLocalSource
  - selectPreset
  - serviceAvailability
  - setBCOReset
  - setComponentSoftwareVersion
  - setMargeAccount
  - setMusicServiceAccount
  - setMusicServiceOAuthAccount
  - setPairedStatus
  - setPairingStatus
  - setProductSerialNumber
  - setProductSoftwareVersion
  - setup
  - setWiFiRadio
  - setZone
  - slaveMsg
  - soundTouchConfigurationStatus
  - sourceDiscoveryStatus
  - sources
  - speaker
  - standby
  - stationInfo
  - storePreset
  - supportedURLs
  - swUpdateAbort
  - swUpdateCheck
  - swUpdateQuery
  - swUpdateStart
  - systemtimeout
  - systemtimeoutcontrol
  - test
  - trackInfo
  - updateGroup
  - userActivity
  - userPlayControl
  - userRating
  - userTrackControl
  - volume
unknown_url_names:
  - now_playing
unsupported_url_names:
  - AbortSoftwareUpdate
  - addStereoPair
  - art
  - removeStereoPair
  - services
  - setPower
  - SoftwareUpdateExit
  - StartSoftwareUpdate

Retrieves a list of your stored stations from the specified music service (e.g. PANDORA, etc).

The returned list is sorted by stationName ascending by default. You can also sort by dateCreated.

For PANDORA source, the first station returned is always the Shuffle station entry.

This service will return service response data.

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SoundTouchPlus device that will process the request.
• source - Music service source to navigate (e.g. 'PANDORA', etc); the value is case-sensitive, and should normally be UPPER case.
• source_account - Music service source account (e.g. the music service user-id). Default is none.
• sort_type - Sort type used by the Music Service to sort the returned items by ('dateCreated', 'stationName'); the value is case-sensitive.

service: soundtouchplus.musicservice_station_list
data:
  entity_id: media_player.bose_st10_1
  source: PANDORA
  source_account: youruseridvalue
  sort_type: stationName

items:
  "@totalItems": "18"
  "@itemCount": "18"
  "@SourceTitle": Pandora (youruseridvalue)
  item:
    - name: Shuffle
      type: station
      logo: https://www.pandora.com/img/shuffle_art_500W_500H.png
      token: "78324812463748620"
      ContentItem:
        "@source": PANDORA
        "@location": "78324812463748620"
        "@sourceAccount": youruseridvalue
        "@isPresetable": "true"
        itemName: Shuffle
        containerArt: https://www.pandora.com/img/shuffle_art_500W_500H.png
    - name: Big Daddy Weave Radio
      type: station
      logo: >-
        https://content-images.p-cdn.com/images/fa/2b/4f/a2/c1fa4f2c99b15e3f0cd1531c/_500W_500H.jpg
      token: "132210777829423505"
      ContentItem:
        "@source": PANDORA
        "@location": "132210777829423505"
        "@sourceAccount": youruseridvalue
        "@isPresetable": "true"
        itemName: Big Daddy Weave Radio
        containerArt: >-
          https://content-images.p-cdn.com/images/fa/2b/4f/a2/c1fa4f2c99b15e3f0cd1531c/_500W_500H.jpg
    - name: Chris Tomlin Radio
      type: station
      logo: >-
        https://content-images.p-cdn.com/images/1b/c4/8c/ad/fc73402e84ab420c547570d7/_500W_500H.jpg
      token: "134448283991947609"
      ContentItem:
        "@source": PANDORA
        "@location": "134448283991947609"
        "@sourceAccount": youruseridvalue
        "@isPresetable": "true"
        itemName: Chris Tomlin Radio
        containerArt: >-
          https://content-images.p-cdn.com/images/1b/c4/8c/ad/fc73402e84ab420c547570d7/_500W_500H.jpg
...          

Retrieves the list of presets defined to the device. The SoundTouch App limits preset storage to 6 items.

The returned list is sorted by @id ascending.

This service will return service response data.

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SoundTouchPlus device that will process the request.
• include_empty_slots - True (default) to include ALL preset slots (both empty and set); otherwise, False to only include preset slots that have been set.

service: soundtouchplus.preset_list
data:
  entity_id: media_player.soundtouch_livingroom
  include_empty_slots: true

presets:
  preset:
    - "@id": "1"
      "@SourceTitle": Tunein
      ContentItem:
        "@source": TUNEIN
        "@type": stationurl
        "@location": /v1/playback/station/s33828
        "@isPresetable": "true"
        itemName: K-LOVE Radio
        containerArt: >-
          http://cdn-profiles.tunein.com/s33828/images/logog.png?t=637986894890000000
    - "@id": "2"
      ContentItem:
        itemName: empty preset
    - "@id": "3"
    ...      

Retrieves the list of recently played items defined to the device.

The returned list is sorted by @createdOn date descending.

This service will return service response data.

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SoundTouchPlus device that will process the request.

service: soundtouchplus.recent_list
data:
  entity_id: media_player.soundtouch_livingroom

recents:
  recent:
    - "@id": "2482521126"
      "@createdOn": "1700942079"
      "@SourceTitle": Tunein
      ContentItem:
        "@source": TUNEIN
        "@type": stationurl
        "@location": /v1/playback/station/s309605
        "@isPresetable": "true"
        itemName: My Copy K-Love 90s
        containerArt: >-
          http://cdn-profiles.tunein.com/s309605/images/logog.png?t=637986891960000000
    - "@id": "2482862902"
      "@createdOn": "1700941687"
      "@SourceTitle": Tunein
      ContentItem:
        "@source": TUNEIN
        "@type": stationurl
        "@location": /v1/playback/station/s33828
        "@isPresetable": "true"
        itemName: K-LOVE Radio
        containerArt: >-
          http://cdn-profiles.tunein.com/s33828/images/logog.png?t=637986894890000000
...          

Retrieves the cached list of recently played items that are stored on the file system.

This feature overcomes the issue with the device recent list processing where the cover art url's are removed from the list. Note that the cached recent list could be different than the device recent list, as the cache is a function of the underlying BoseSoundTouchApi and NOT the physical SoundTouch device; e.g. items played on the device outside of this API will not be stored in the cache.

The cache is stored to the local file system each time an item is added to the cache. The file is located in the Home Assistant configuration directory structure, specifically in the /config/www/soundtouchplus/recently_played_cache_<DEVICE_ID>.xml location, where DEVICE_ID is the SoundTouch device identifier (e.g. recently_played_cache_9030618C7D4C.xml).

The maximum number of items to keep in the cache is configured in the SoundTouchPlus device configuration options. Older items are automatically removed from the cache once the maximum number of items has been reached.

The returned list is sorted by @createdOn date descending.

This service will return service response data.

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SoundTouchPlus device that will process the request.

service: soundtouchplus.recent_list_cache
data:
  entity_id: media_player.soundtouch_livingroom

recents:
  recent:
    - "@id": "2482521126"
      "@createdOn": "1700942079"
      "@SourceTitle": Tunein
      ContentItem:
        "@source": TUNEIN
        "@type": stationurl
        "@location": /v1/playback/station/s309605
        "@isPresetable": "true"
        itemName: My Copy K-Love 90s
        containerArt: >-
          http://cdn-profiles.tunein.com/s309605/images/logog.png?t=637986891960000000
    - "@id": "2482862902"
      "@createdOn": "1700941687"
      "@SourceTitle": Tunein
      ContentItem:
        "@source": TUNEIN
        "@type": stationurl
        "@location": /v1/playback/station/s33828
        "@isPresetable": "true"
        itemName: K-LOVE Radio
        containerArt: >-
          http://cdn-profiles.tunein.com/s33828/images/logog.png?t=637986894890000000
...          

Gets the supported urls configuration of the device.

This service will return service response data.

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SoundTouchPlus device that will process the request.
• refresh - True to query the device for realtime information and refresh the cache; otherwise, False to just return the cached information.

action: soundtouchplus.get_supported_urls
data:
  entity_id: media_player.bose_st10_1
  refresh: false

device_id: 9030618C7D4C
urls:
  - location: /addGroup
  - location: /addStation
  - location: /addWirelessProfile
  - location: /addZoneSlave
  - location: /balance
  - location: /bass
  - location: /bassCapabilities
  - location: /bluetoothInfo
  - location: /bookmark
  - location: /cancelPairLightswitch
  - location: /capabilities
  - location: /clearBluetoothPaired
...

Play media content from a content item source (e.g. TUNEIN station, etc) on a SoundTouch device.

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SoundTouchPlus device that will process the request.
• name - Name of the content item.
• source - Source to select to play the content; the value is case-sensitive, and should normally be UPPER case.
• source_account - (optional )Source account this content item is played with. Default is none.
• item_type - Type of content item to play; the value is case-sensitive, and should normally be lower case.
• location - A direct link to the media content that will be played. This value should be enclosed in single quotes, as Home Assistant sometimes will try to interpret it as an integer if it's all numeric.
• container_art - A direct link to the container art (if present).
• is_presetable - true if this item can be saved as a Preset; otherwise, false.

# play dlna local music content.
service: soundtouchplus.play_contentitem
data:
  entity_id: media_player.soundtouch_10
  name: Welcome to the New
  source: LOCAL_MUSIC
  source_account: 3f205110-4a57-4e91-810a-ad949d25abb2
  item_type: album
  location: 'album:983'
  container_art: http://192.168.1.1:8085/v1/albums/983/image?_=1&w=62
  is_presetable: true

# play music library on NAS content.
service: soundtouchplus.play_contentitem
data:
  entity_id: media_player.soundtouch_10
  name: Welcome to the New
  source: STORED_MUSIC
  source_account: 'd09708a1-5953-44bc-a413-123456789012/0'
  location: '7_11412345'
  container_art: http://192.168.1.1:10243/WMPNSSv4/2050238549/0_N18xMTRlOGRlOS00MDE5.jpg?albumArt=true
  is_presetable: true

# play Pandora music service content.
service: soundtouchplus.play_contentitem
data:
  entity_id: media_player.soundtouch_10
  name: Zach Williams
  source: PANDORA
  source_account: yourPandoraUserId
  location: '126740707481236361'
  container_art: https://content-images.p-cdn.com/images/8b/a1/c6/4f/b1984bf7881e1e207790968b/_500W_500H.jpg
  is_presetable: true

Note that a Premium-level membership is required in order to play Spotify content.

I prefer playing Spotify content using the uri item type, as the location values appear to match what you see in the Spotify.com web-site url when playing content. For example, take a link from spotify.com such as https://open.spotify.com/album/6vc9OTcyd3hyzabCmsdnwE - the uri value to play the same content would be spotify:album:6vc9OTcyd3hyzabCmsdnwE. It seems to apply for all of the different content types (e.g. album, artist, track, playlist, episode, show, etc).

With that said, you can also play Spotify content using the tracklisturl item type, and specifying the container url (e.g. "/playback/container/c3BvdGlmeTphcnRpc3Q6NkFQbThFanhPSFNZTTVCNGkzdlQzcQ==") in the location value. The tracklisturl item type is what shows in the \nowPlaying service status under the ContentItem parameters.

# play Spotify music service content - artist.
service: soundtouchplus.play_contentitem
data:
  entity_id: media_player.bose_st10_1
  name: MercyMe
  source: SPOTIFY
  source_account: yourSpotifyUserId
  location: 'spotify:artist:6APm8EjxOHSYM5B4i3vT3q'
  item_type: uri
  container_art: https://i.scdn.co/image/ab67616d0000b27316c019c87a927829804caf0b
  is_presetable: true

# play Spotify music service content - artist (by tracklisturl type).
service: soundtouchplus.play_contentitem
data:
  entity_id: media_player.bose_st10_1
  name: MercyMe
  source: SPOTIFY
  source_account: yourSpotifyUserId
  location: '/playback/container/c3BvdGlmeTphcnRpc3Q6NkFQbThFanhPSFNZTTVCNGkzdlQzcQ=='
  item_type: tracklisturl
  container_art: https://i.scdn.co/image/ab67616d0000b27316c019c87a927829804caf0b
  is_presetable: true

# play Spotify music service content - album.
service: soundtouchplus.play_contentitem
data:
  entity_id: media_player.bose_st10_1
  name: Welcome to the New
  source: SPOTIFY
  source_account: yourSpotifyUserId
  location: 'spotify:album:6vc9OTcyd3hyzabCmsdnwE'
  item_type: uri
  container_art: https://i.scdn.co/image/ab67616d0000b27316c019c87a927829804caf0b
  is_presetable: true

# play Spotify music service content - track.
service: soundtouchplus.play_contentitem
data:
  entity_id: media_player.bose_st10_1
  name: Flawless
  source: SPOTIFY
  source_account: yourSpotifyUserId
  location: 'spotify:track:1kWUud3vY5ij5r62zxpTRy'
  item_type: uri
  container_art: https://i.scdn.co/image/ab67616d0000b2734e3dd900c3352f0ad34fbdd7
  is_presetable: true

# play Spotify music service content - playlist.
service: soundtouchplus.play_contentitem
data:
  entity_id: media_player.bose_st10_1
  name: Worship Playlist
  source: SPOTIFY
  source_account: yourSpotifyUserId
  location: 'spotify:playlist:5v5ETK9WFXAnGQ3MRubKuE'
  item_type: uri
  container_art: https://i.scdn.co/image/ab67706c0000da84820d2514932c9e2ea40f6473
  is_presetable: true

# play Spotify music service content - episode.
service: soundtouchplus.play_contentitem
data:
  entity_id: media_player.bose_st10_1
  name: We Can Do Hard Things
  source: SPOTIFY
  source_account: yourSpotifyUserId
  location: 'spotify:episode:3tWDribcG7X5Q6KBx8xupp'
  item_type: uri
  container_art: https://i.scdn.co/image/ab6765630000ba8a31936fcc7887c8a10ba9af9d
  is_presetable: true

# play Spotify music service content - podcast, audiobook.
service: soundtouchplus.play_contentitem
data:
  entity_id: media_player.bose_st10_1
  name: K-Love On The Mic
  source: SPOTIFY
  source_account: yourSpotifyUserId
  location: 'spotify:show:39EidgdUzHLZ1Wab01NiGk'
  item_type: uri
  container_art: https://i.scdn.co/image/206f1a5d5e27e9516a5c0cdb06ee3ae079a78ac9
  is_presetable: true

# play tunein radio station content.
service: soundtouchplus.play_contentitem
data:
  entity_id: media_player.soundtouch_10
  name: K-LOVE Radio
  source: TUNEIN
  item_type: stationurl
  location: '/v1/playback/station/s33828'
  container_art: http://cdn-profiles.tunein.com/s33828/images/logog.png?t=637986894890000000
  is_presetable: false

Handoff playing source from one SoundTouch device to another.

All parameters are required unless otherwise noted.

• entity_id_from - Entity ID of the SoundTouch device that is currently playing.
• entity_id_to - Entity ID of the SoundTouch device that needs to play what the 'from' device is currently playing.
• restore_volume - True to handoff the FROM device volume level to the TO device; False (default) to leave the TO device volume level as-is.
• snapshot_only - True to only handoff the snapshot and not trigger the restore and power off; False (default) to handoff the snapshot, restore it, and power off the FROM device.

service: soundtouchplus.play_handoff
data:
  entity_id_from: media_player.soundtouch_livingroom
  entity_id_to: media_player.soundtouch_bedroom
  restore_volume: true
  snapshot_only: true

Play Text-To-Speech notification on a SoundTouch device. Note that this is limited to ST-10,20,30 devices, as Bose ST-300 does not support notifications (AFAIK).

The default service to use is Google Translate, with an american translation language.

There are models of Bose SoundTouch speakers that do not support notifications. Only the Bose SoundTouch 10, 20, and 30 in the III series support notifications, as far as I know. I could not get this to work on my SoundTouch 300, but it did work on my ST 10.

The notification message is played at the level specified by the volume_level argument. Specify a volume_level of zero to play the notification at the current volume level. The volume level is restored to the level it was before the notification message was played after the notification is complete; e.g. if you made changes to the volume while the notification is playing then they are changed back to the volume level that was in effect prior to playing the notification. The SoundTouch device automatically takes care of the volume level switching; there are no calls in the method to change the volume or currently playing content status. The SoundTouch device also limits the volume range between 10 (min) and 70 (max); this is a Bose limitation, and is not imposed by this API.

The currently playing content (if any) is paused while the notification message content is played, and then resumed once the notification ends.

If the device is the master controller of a zone, then the notification message will be played on all devices that are members of the zone.

A small delay can be inserted at the start of the message by prefixing the message argument value with "a.". Example: "a.This is a test message". It's not a perfect solution, but works for me since my SoundTouch speaker takes a second or two to switch into active mode, and the first second of the played message is lost.

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SoundTouchPlus device that will process the request.
• message - The message that will be converted from text to speech and played on the device.
• artist - (optional) The message text that will appear in the NowPlaying Artist node; if omitted, default is "TTS Notification".
• album - (optional) The message text that will appear in the NowPlaying Album node; if omitted, default is "Google TTS".
• track - (optional) The message text that will appear in the NowPlaying Track node; if omitted, default is the message value.
• tts_url - (optional) The Text-To-Speech url used to translate the message. The value should contain a "{saytext}" format parameter, that will be used to insert the encoded message text.
  default: http://translate.google.com/translate_tts?ie=UTF-8&tl=EN&client=tw-ob&q={saytext}
• volume_level - (optional) The temporary volume level that will be used when the message is played. Specify a value of zero to play at the current volume. Default is zero, range is 0 to 100.
• app_key - (optional) Bose Developer API application key; if omitted, defaults to a pre-defined App Developer Key.

# play message using default english voice.
service: soundtouchplus.play_tts
data:
  entity_id: media_player.soundtouch_livingroom
  message: Hello World, How are you today?
  volume_level: 50

# play message using dutch voice.
service: soundtouchplus.play_tts
data:
  entity_id: media_player.soundtouch_livingroom
  message: Hello World, How are you today?
  tts_url: >-
    http://translate.google.com/translate_tts?ie=UTF-8&tl=DE&client=tw-ob&q={saytext}
  volume_level: 50

# play message using custom status messages.
service: soundtouchplus.play_tts
data:
  entity_id: media_player.soundtouch_livingroom
  message: There is someone at the front door.
  artist: Camera Alert
  album: Motion Detected
  track: Front Door
  volume_level: 75

Play media content from a URL on a SoundTouch device via the SoundTouch DLNA service. Note that HTTPS URL's are NOT supported by this service due to DLNA restrictions.

The given url content is played using the DLNA server on the SoundTouch device. This service calls the SetAVTransportURI DLNA command to play the media.

If the updateNowPlayingStatus argument is True, then a call is made to the underlying UpdateNowPlayingStatusForSource method to update source-specific nowPlaying details (artist, album, track, and art) for the specified source / source account. It does this as a convenience method, since the Bose nowPlaying service will not return any media-specific information for UPNP context.

If the device is the master controller of a zone, then the given url content will be played on all devices that are members of the zone.

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SoundTouchPlus device that will process the request.
• url - The url to play; value must start with http.
• artist - (optional) The message text that will appear in the NowPlaying Artist node; if omitted, default is "Unknown Artist".
• album - (optional) The message text that will appear in the NowPlaying Album node; if omitted, default is "Unknown Album".
• track - (optional) The message text that will appear in the NowPlaying Track node; if omitted, default is "Unknown Track".
• art_url - (optional) A url link to the cover art image that represents the url (if present).
• update_now_playing_status - (optional) True (default) to update the source-specific nowPlaying information; False to not update the source-specific nowPlaying information.
• delay - (optional) Time delay (in seconds) to wait AFTER sending the play next track request if the currently playing media is a notification source. This delay will give the device time to process the change before another command is accepted. Default is 1; value range is 0 - 10.

# play the given url via the SoundTouch DLNA web server.
service: soundtouchplus.play_url_dlna
data:
  entity_id: media_player.soundtouch_livingroom
  url: http://edge-bauerall-01-gos2.sharp-stream.com/ghr70s.aac
  artist: Greatest Hits Radio
  album: "70's Classic Hits"
  track: ghr70s.aac
  art_url: https://image-cdn-ak.spotifycdn.com/image/ab67706c0000da849d37dd221d8aa1b35c545057

Plays media from the given URL as a notification message, interrupting the currently playing media to play the specified url. The currently playing will then resume playing once play of the specified URL is complete.

This service should only be used to play URL streams that are short in nature, as they will be played as notification messages on the device. The currently playing content (if any) is paused while the given url content is played, and then resumed once the given url content ends. If the currently playing content is a url (or other "notification" source type), then the MediaNextTrack method will be called to stop the current play and the new source will be played.

The given url content is played at the level specified by the volumeLevel argument. Specify a volumeLevel of zero to play the given url content at the current volume level. The volume level is restored to the level it was before the given url content was played after play is complete; e.g. if you made changes to the volume while the given url content is playing then they are changed back to the volume level that was in effect prior to playing the given url content. The SoundTouch device automatically takes care of the volume level switching; there are no calls in the method to change the volume or currently playing content status.

If the device is the master controller of a zone, then the given url content will be played on all devices that are members of the zone.

This method calls the play_info SoundTouch API service for the notification. There are models of SoundTouch speakers that do not support notifications. Per the SoundTouch WebServices API reference: audio Notifications are only available for SoundTouch 10, SoundTouch 20 Series III, and SoundTouch 30 Series III. Attempting to send an Audio Notification to an incompatible device will return a 403 Forbidden error.

play_info supports the following file formats and bit rates:

• MP3: 8 kbit/s ~ 320 kbit/s
• AAC: 24 kbit/s ~ 128 kbit/s
• HE-AAC: 48 kbit/s ~ 64 kbit/s
• WMA: 8 kbit/s ~ 329 kbit/s
• Vorbis: 32 kbit/S ~ 500 kbit/s
• FLAC: VBR: 0bit/s ~ 1.4 Mbit/s, up to CD quality (2 channels / 48 kHz / 16 bit)
• ALAC: 300 kbit/s ~ 5 Mbit/s, HD (2 channels / 96 kHz / 32 bit)

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SoundTouchPlus device that will process the request.
• url - The url to play; value must start with http or https.
• artist - (optional) The message text that will appear in the NowPlaying Artist node; if omitted, default is "Unknown Artist".
• album - (optional) The message text that will appear in the NowPlaying Album node; if omitted, default is "Unknown Album".
• track - (optional) The message text that will appear in the NowPlaying Track node; if omitted, default is "Unknown Track".
• volume_level - (optional) The temporary volume level that will be used when the media is played. Specify a value of zero to play at the current volume. Default is zero, range is 0 - 100.
• app_key - (optional) Bose Developer API application key; if omitted, defaults to a pre-defined App Developer Key.
• get_metadata_from_url_file - (optional) If True, the artist, album, and song title metadata details will be retrieved from the ID3 header of the url content (if available); otherwise, False to use the artist, album, and song title arguments specified.

# play the given https url at the current volume level.
service: soundtouchplus.play_url
data:
  entity_id: media_player.soundtouch_livingroom
  url: >-
    https://freetestdata.com/wp-content/uploads/2021/09/Free_Test_Data_1MB_MP3.mp3
  artist: FreeTestData.com
  album: MP3 Test Data
  track: Free_Test_Data_1MB_MP3
  volume_level: 0

# play the given http url at the current volume level.
service: soundtouchplus.play_url
data:
  entity_id: media_player.soundtouch_livingroom
  url: >-
    http://www.hyperion-records.co.uk/audiotest/14%20Clementi%20Piano%20Sonata%20in%20D%20major,%20Op%2025%20No%206%20-%20Movement%202%20Un%20poco%20andante.MP3
  artist: Clementi
  album: Movements Album
  track: Piano Sonata in D major
  volume_level: 0

# play the given url, retrieving metadata (artist,album,track) from the url content.
service: soundtouchplus.play_url
data:
  entity_id: media_player.soundtouch_livingroom
  url: >-
    http://homeassistant.local:8123/media/local/06%20Flawless.mp3?authSig=xxxx
  volume_level: 0
  get_metadata_from_url_file: true

Reboots the operating system of the SoundTouch device.

This service will open a telnet connection to the SoundTouch SSH server running on the device (port 17000). It will then issue a sys reboot command to reboot the device. The telnet session will fail if any other process has a telnet session open to the device; this is a SoundTouch device limitation, as only one SSH session is allowed per device.

If successful, all communication with the device will be lost while the device is rebooting. SoundTouch web-services API connectivity should be restored within 45 - 60 seconds if the reboot is successful.

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SoundTouchPlus device that will process the request.
• port - SSH port to connect to; default is 17000.

# reboot the speaker.
service: soundtouchplus.reboot_device
data:
  entity_id: media_player.soundtouch_10

Simulates the press and release of a key on the SoundTouch device remote control.

Note that some keys on the SoundTouch remote control are not sent to the SoundTouch device, and therefore are not supported by this service.

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SoundTouchPlus device that will process the request.
• key_id - SoundTouch remote control key identifier.
• key_state - SoundTouch remote control key state. Most key identifiers will use 'both' for state; the 'PRESET_n' key identifiers use 'press' to store a preset, and 'release' to select (or play) a preset.

# press the mute button.
service: soundtouchplus.remote_keypress
data:
  entity_id: media_player.soundtouch_10
  key_id: MUTE
  key_state: press

# press and release the power button.
service: soundtouchplus.remote_keypress
data:
  entity_id: media_player.soundtouch_10
  key_id: POWER
  key_state: both

# press preset 2 button to store the currently playing content as preset slot 2.
service: soundtouchplus.remote_keypress
data:
  entity_id: media_player.soundtouch_10
  key_id: PRESET_2
  key_state: press

# release preset 2 button to play stored preset slot 2 content.
service: soundtouchplus.remote_keypress
data:
  entity_id: media_player.soundtouch_10
  key_id: PRESET_2
  key_state: release

Sets the current audio dsp controls configuration for SoundTouch devices that support the /audiodspcontrols feature.

Note that some SoundTouch devices do not support this functionality. For example, the ST-300 will support this, but the ST-10 will not.

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SoundTouchPlus device that will process the request.
• audio_mode - Audio mode value (e.g. "AUDIO_MODE_NORMAL", "AUDIO_MODE_DIALOG", etc).
• video_sync_audio_delay - Video syncronization audio delay value (in milliseconds). Suggested range is 0 - 250ms, in increments of 10.

service: soundtouchplus.set_audio_dsp_controls
data:
  entity_id: media_player.soundtouch_livingroom
  audio_mode: AUDIO_MODE_NORMAL
  video_sync_audio_delay: 0

Sets the current audio product tone controls configuration for SoundTouch devices that support the /audioproducttonecontrols feature.

Note that some SoundTouch devices do not support this functionality. For example, the ST-300 will support this, but the ST-10 will not.

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SoundTouchPlus device that will process the request.
• bass_level - The bass level to set; range is -100 to +100.
• treble_level - The treble level to set; range is -100 to +100.

service: soundtouchplus.set_audio_product_tone_controls
data:
  entity_id: media_player.soundtouch_livingroom
  bass_level: 50
  treble_level: 50

Sets the device balance level to the given level for SoundTouch devices that support the /balance feature.

This service only works if the device is configured as part of a stereo pair.

The argument level range can vary by device; use the Get Balance service to determine if the device has the capability to adjust the balance, as well as the allowable range (minimum, maximum, default) levels.

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SoundTouchPlus device that will process the request.
• level - Balance level to set, usually in the range of -7 (left) to 7 (right).

action: soundtouchplus.set_balance_level
data:
  entity_id: media_player.soundtouch_10
  level: 0

Sets the device bass level to the given level for SoundTouch devices that support the /bass feature.

The argument level range can vary by device; use the Get Bass Capabilities method to retrieve the allowable range for a device.

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SoundTouchPlus device that will process the request.
• level - Bass level to set, usually in the range of -9 (no bass) to 0 (full bass).

action: soundtouchplus.set_bass_level
data:
  entity_id: media_player.soundtouch_10
  level: -5

Restore SoundTouch device settings from a snapshot.

Restores selected portions of the configuration from a snapshot that was previously taken with the Snapshot Store service.

The following settings will be restored from the snapshot:

• nowPlaying - playing content.
• volume - volume level and mute status.

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SoundTouchPlus device that will process the request.
• restore_volume - Indicates if the volume also needs to be restored (True, default) or not (False).

# restore snapshot data, including volume level.
service: soundtouchplus.snapshot_restore
data:
  entity_id: media_player.soundtouch_livingroom
  restore_volume: true

# restore snapshot data; do not restore volume level.
service: soundtouchplus.snapshot_restore
data:
  entity_id: media_player.soundtouch_livingroom
  restore_volume: false

Store SoundTouch device settings to a snapshot.

Stores selected portions of the configuration so that they can be easily restored with the Restore Snapshot service.

The following settings will be stored in the snapshot:

• nowPlaying - playing content.
• volume - volume level and mute status.

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SoundTouchPlus device that will process the request.

# store snapshot data.
service: soundtouchplus.snapshot_store
data:
  entity_id: media_player.soundtouch_livingroom

Updates the NowPlayingStatus object for a given source and sourceAccount.

Use this service to update a NowPlayingStatus for a specific source, which can be used by external entities that want to keep track of sources that are currently playing on the SoundTouch device. For example, you could have a Home Assistant media player playing TV content from Kodi media center on the SoundTouch and it could keep track of what is currently playing for a source that the SoundTouch API does not track (e.g. PRODUCT:TV).

All parameters are required unless otherwise noted.

• entity_id - Entity ID of the SoundTouchPlus device that will process the request.
• source - Source input this content item is played with (case-sensitive).
• source_account - Source account this content item is played with (case-sensitive).
• album - (optional) The album of the playing track (if present).
• artist - (optional) The creator of the track (if present).
• artist_id - (optional) Unique identifier of the artist, as provided by the source music service (if present).
• art_url - (optional) A url link to the art image of the station (if present).
• description - (optional) A brief description that was added to the track (if present).
• duration - (optional) The track's duration (if present).
• genre - (optional) The genre of the track (if present).
• play_status - (optional) Indicates whether the device is currently playing the embedded track.
• position - (optional) The current position of the playing media (if present).
• session_id - (optional) Unique identifier of the session, as provided by the source music service (if present).
• station_location - (optional) The station's location.
• station_name - (optional) The station's name (if present).
• track - (optional) The current media track name (if present).
• track_id - (optional) Unique identifier of the track, as provided by the source music service (if present).

service: soundtouchplus.update_source_nowplayingstatus
data:
  entity_id: media_player.soundtouch_livingroom
  source: PRODUCT
  source_account: TV
  art_url: "{{ state_attr('media_player.kodi_hearthroom', 'entity_picture') }}"
  artist: "{{ state_attr('media_player.kodi_hearthroom', 'media_artist') }}"
  album: "{{ state_attr('media_player.kodi_hearthroom', 'media_album_name') }}"
  track: "{{ state_attr('media_player.kodi_hearthroom', 'media_title') }}"
  station_location: Kodi Hearthroom

The following automation will update the SoundTouchPlus media player information from Kodi media center attributes for Movie content.

alias: Kodi Hearthroom Media Player Image Assign Movie
description: >-
  Calls the SoundTouchPlus UpdateNowPlayingStatus service to update the media
  player information from Kodi media center attributes for Movie content.
trigger:
  - platform: state
    entity_id:
      - media_player.kodi_hearthroom
    attribute: media_title
condition:
  - condition: state
    entity_id: media_player.kodi_hearthroom
    attribute: media_content_type
    state: movie
  - condition: state
    entity_id: media_player.bose_hearthroom
    attribute: source
    state: "Product (TV)"
action:
  - service: soundtouchplus.update_source_nowplayingstatus
    data:
      entity_id: media_player.bose_hearthroom
      source_title: "Product (TV)"
      art_url: "{{ state_attr('media_player.kodi_hearthroom', 'entity_picture') }}"
      station_name: "{{ state_attr('media_player.kodi_hearthroom', 'media_title') }}"
      station_location: Kodi Hearthroom
mode: single

Toggles the given zone member to or from the master device's zone. A new zone will be created automatically if needed.

All parameters are required unless otherwise noted.

• entity_id_master - Entity ID of the SoundTouch device master zone.
• entity_id_member - Entity ID of the SoundTouch device that will be toggled to or from the master zone.

service: soundtouchplus.zone_toggle_member
data:
  entity_id_master: media_player.bose_st10_1
  entity_id_member: media_player.bose_st10_2