bosesoundtouchapi.soundtouchclient

@export
class SoundTouchClient:

The SoundTouchClient uses the underlying Bose Web Socket api to communicate with a specified Bose SoundTouch device.

This client communicates with a Bose device on port 8090 by default (the standard WebAPI port), but the port number can be changed.

The client uses an urllib3.PoolManager instance to delegate the HTTP-requests. Set a custom manager with the manage_traffic() method.

Like the BoseWebSocket, this client can be used in two ways: 1. create a client manually or 2. use the client within a _with_ statement. Additionally, this class implements a dict-like functionality. So, the loaded configuration can be accessed by typing: config = client[<config_name>]

SoundTouchClient( device: bosesoundtouchapi.soundtouchdevice.SoundTouchDevice, raiseErrors: bool = True, manager: urllib3.poolmanager.PoolManager = None)

Initializes a new instance of the class.

Arguments:
  • device (SoundTouchDevice): The device to interace with. Some configuration data stored here will be updated if specific methods were called in this client.
  • raiseErrors (bool): Specifies if the client should raise exceptions returned by the SoundTouch device. Use ignore to ignore the errors (they will be given as the response object in a SoundTouchMessage). Default = 'raise'.
  • manager (urllib3.PoolManager): The manager for HTTP requests to the device.
ConfigurationCache: dict

A dictionary of cached configuration objects that have been obtained from the SoundTouch device. Use the objects in this cache whenever it is too expensive or time consuming to make a real-time request from the device.

The configuration cache is updated for any "Get...()" methods that return device information. All of the "Get...()" methods have a refresh:bool argument that controls where information is obtained from; if refresh=True, then the device is queried for real-time configuration information. If refresh=False, then the configuration information is pulled from the configuration cache dictionary; if the cache does not contain the object, then the device is queried for real-time configuration information.

It is obviously MUCH faster to retrieve device configuration objects from the cache than from real-time device queries. This works very well for configuration objects that do not change very often (e.g. Capabilities, Language, SourceList, etc). You will still want to make real-time queries for configuration objects that change frequently (e.g. Volume, NowPlayingStatus, Presets, etc).

This property is read-only, and is set when the class is instantiated. The dictionary entries can be changed, but not the dictionary itself.

Returns:

The _ConfigurationCache property value.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *
from bosesoundtouchapi.uri import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get cached configuration objects, refreshing from device if needed.
    # since the refresh argument is false to all of these, they will request
    # real-time information from the device the first time, and then the
    # ConfigurationCache will be updated with the results.
    sourceList:SourceList = client.GetSourceList(False)

    print("\nCached configuration:\n%s" % sourceList.ToString(True))

    # get cached configuration directly from the configuration manager dictionary.
    if SoundTouchNodes.sources.Path in client.ConfigurationCache:
        sourceList:SourceList = client.ConfigurationCache[SoundTouchNodes.sources.Path]
        print("\nCached configuration, direct:\n%s" % sourceList.ToString(True))

except Exception as ex:

    print("** Exception: %s" % str(ex))

The SoundTouchDevice object used to connect to the SoundTouch device.

This property is read-only, and is set when the class is instantiated.

Manager: urllib3.poolmanager.PoolManager

Sets the request PoolManager object to use for http requests to the device.

Returns:

The `_Manager' property value.

SnapshotSettings: dict

A dictionary of configuration objects that are used by the Snapshot processing methods.

This property is read-only.

def Action(self, keyName: bosesoundtouchapi.soundtouchkeys.SoundTouchKeys) -> None:

Tries to imitate a pressed key.

Arguments:
  • keyName (SoundTouchKeys): The specified key to press. A string is also accepted for this argument.

This method can be used to invoke different actions by using the different keys defined in bosesoundtouchapi.soundtouchkeys.SoundTouchKeys.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *
import time

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # send a POWER action to toggle power state.
    client.Action(SoundTouchKeys.POWER)
    print("\nPOWER key was pressed")

except Exception as ex:

    print("** Exception: %s" % str(ex))

def AddFavorite(self) -> None:

Adds the currently playing media to the device favorites.

This will first make a call to GetNowPlayingStatus() method to ensure favorites are enabled for the now playing media. If not enabled, then the request is ignored and no exception is raised.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *
import time

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("\nCurrent Now Playing Status:\n%s" % nowPlaying.ToString())

    # does nowPlaying item support favorites?
    if nowPlaying.IsFavoriteEnabled:

        # add the currently playing media to the device favorites.
        client.AddFavorite()

        # give the device time to process the change.
        time.sleep(1)

        # get current nowPlaying status.
        nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
        print("\nUpdated Now Playing Status:\n%s" % nowPlaying.ToString())

    else:

        print("\nFavorites not enabled for currently playing media")

except Exception as ex:

    print("** Exception: %s" % str(ex))

Adds the given zone members to the device's zone.

Arguments:
  • members (list): A list of ZoneMember objects to add to the master zone.
  • delay (int): Time delay (in seconds) to wait AFTER adding zone members. This delay will give the device time to process the change before another command is accepted.
    Default is 3; value range is 0 - 10.
Raises:
  • SoundTouchError: Master zone status could not be retrieved.
    Master zone does not exist; zone members cannot be added.
    Members argument was not supplied, or has no members.
    Members argument contained a list item that is not of type ZoneMember.

The SoundTouch master device cannot find zone members without their device id.

The SoundTouch device does not return errors if a zone member device id does not exist; it simply ignores the invalid member entry and moves on to the next.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # build list of zone members to add.
    zoneMembers:list = []
    zoneMembers.append(ZoneMember("192.168.1.130", "E8EB11B9B723"))
    zoneMembers.append(ZoneMember("192.168.1.132", "F9BC35A6D825"))
    zoneMembers.append(ZoneMember("192.168.1.133", "B8BD47C7F452"))

    # get current zone configuration status.
    zoneBefore:Zone = client.GetZoneStatus()
    print("\nCurrent Zone Status:\n%s" % zoneBefore.ToString(True))

    # if zone not active, then create one so that we have something to add.
    if len(zoneBefore.Members) == 0:

        print("Creating a new master zone so we have a master zone to add to ...")

        # initialize the new master zone configuration.
        masterZone:Zone = Zone(client.Device.DeviceId, client.Device.Host,True) # <- master
        member:ZoneMember
        for member in zoneMembers:
            masterZone.AddMember(member)                                        # <- member
            break   # only add 1 zone member, so it actually adds something below

        # create a new master zone configuration on the device.
        client.CreateZone(masterZone)

        # get current zone configuration status.
        zoneBefore:Zone = client.GetZoneStatus()
        print("\nZone Status Before:\n%s" % zoneBefore.ToString(True))

    # add zone members to the master zone configuration.
    client.AddZoneMembers(zoneMembers)

    # get current zone configuration status.
    zoneAfter:Zone = client.GetZoneStatus()
    print("\nZone Status After:\n%s" % zoneAfter.ToString(True))

except Exception as ex:

    print("** Exception: %s" % str(ex))

Creates a multiroom zone from a Zone object.

Arguments:
  • zone (Zone): Multiroom configuration (zone) object that will control the zone (e.g. the master). This object also contains a list of all zone members that will be under its control (e.g. Members property).
  • delay (int): Time delay (in seconds) to wait AFTER creating the zone. This delay will give the device time to process the change before another command is accepted.
    Default is 3; value range is 0 - 10.
Raises:
  • SoundTouchError: Zone argument was not supplied.
    Zone argument is not of type Zone.
    Zone argument did not contain any members. The zone must have at least one zone member in order to create a zone.

The master SoundTouch device cannot find zone members without their device id.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current zone configuration status.
    zoneBefore:Zone = client.GetZoneStatus()
    print("\nZone Status Before:\n%s" % zoneBefore.ToString(True))

    # initialize the new master zone configuration.
    masterZone:Zone = Zone(client.Device.DeviceId, client.Device.Host, True) # <- master
    masterZone.AddMember(ZoneMember("192.168.1.130", "E8EB11B9B723"))        # <- member

    # create a new master zone configuration on the device.
    client.CreateZone(masterZone)

    # get current zone configuration status.
    zoneAfter:Zone = client.GetZoneStatus()
    print("\nZone Status After:\n%s" % zoneAfter.ToString(True))

except Exception as ex:

    print("** Exception: %s" % str(ex))

def CreateZoneFromDevices( self, master: bosesoundtouchapi.soundtouchdevice.SoundTouchDevice, members: list) -> bosesoundtouchapi.models.zone.Zone:

Creates a new multiroom zone with the given member devices.

Arguments:
  • master (SoundTouchDevice): The device object that will control the zone (e.g. the master).
  • members (list): A list of SoundTouchDevice objects that will be controlled by the master zone (e.g. the zone members).
Raises:
  • SoundTouchError: Master argument was not supplied.
    Master argument is not of type SoundTouchDevice.
    Members argument is not of type list.
    Members argument was not supplied, or has no members.
    Members argument contained a list item that is not of type SoundTouchDevice.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current zone configuration status.
    zoneBefore:Zone = client.GetZoneStatus()
    print("\nZone Status Before:\n%s" % zoneBefore.ToString(True))

    # create new device instances for all zone members.
    device_master:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # master
    device_member:SoundTouchDevice = SoundTouchDevice("192.168.1.130") # member

    # create a new master zone configuration on the device.
    masterZone:Zone = client.CreateZoneFromDevices(device_master, [device_member])
    print("\nMaster Zone created:\n%s" % (masterZone.ToString(True)))

    # get current zone configuration status.
    zoneAfter:Zone = client.GetZoneStatus()
    print("\nZone Status After:\n%s" % zoneAfter.ToString(True))

except Exception as ex:

    print("** Exception: %s" % str(ex))

Makes a GET request to retrieve a stored value.

Use this method when querying for specific nodes. All standard nodes are implemented by this class.

Arguments:
  • uri (SoundTouchUri): The node where the requested value is stored. DANGER: This request can also have a massive effect on your Bose device, for instance when calling client.get(SoundTouchNodes.resetDefaults), it will wipe all data on the device and perform a factory reset.
Returns:

An object storing the request uri, optional a payload that has been sent and the response as an xml.etree.ElementTree.Element.

Raises:
  • SoundTouchError: When errors should not be ignored on this client, they will raise a SoundTouchError exception with all information related to that error.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.uri import *
from xml.etree.ElementTree import Element
from xml.etree import ElementTree

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get configuration for specified node.
    msg:SoundTouchMessage = client.Get(SoundTouchNodes.volume)

    if msg != None:
        ElementTree.indent(msg.Response)  # for pretty printing
        responseEncoded = ElementTree.tostring(msg.Response, encoding="unicode")
        print("Get Response Message:\n%s" %  responseEncoded)

except Exception as ex:

    print("** Exception: %s" % str(ex))

def GetBalance(self, refresh=True) -> bosesoundtouchapi.models.balance.Balance:

Gets the current balance configuration of the device.

Arguments:
  • refresh (bool): True to query the device for realtime information and refresh the cache; otherwise, False to just return the cached information.
Returns:

A Balance object that contains balance configuration of the device.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *
from bosesoundtouchapi.uri import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get real-time configuration from the device.
    balance:Balance = client.GetBalance()
    print(balance.ToString())
    print("Balance Level = %d" % balance.Actual)

    # get cached configuration, refreshing from device if needed.
    balance:Balance = client.GetBalance(False)
    print("\nCached configuration:\n%s" % balance.ToString())
    print("Balance Level = %d" % balance.Actual)

    # get cached configuration directly from the configuration manager dictionary.
    if SoundTouchNodes.balance.Path in client.ConfigurationCache:
        balance:Balance = client.ConfigurationCache[SoundTouchNodes.balance.Path]
        print("\nCached configuration, direct:\n%s" % balance.ToString())
        print("Balance Level = %d" % balance.Actual)

except Exception as ex:

    print("** Exception: %s" % str(ex))

def GetBass(self, refresh=True) -> bosesoundtouchapi.models.bass.Bass:

Gets the current bass configuration of the device.

Arguments:
  • refresh (bool): True to query the device for realtime information and refresh the cache; otherwise, False to just return the cached information.
Returns:

A Bass object that contains bass configuration of the device.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *
from bosesoundtouchapi.uri import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get real-time configuration from the device.
    bass:Bass = client.GetBass()
    print(bass.ToString())
    print("Bass Level = %d" % bass.Actual)

    # get cached configuration, refreshing from device if needed.
    bass:Bass = client.GetBass(False)
    print("\nCached configuration:\n%s" % bass.ToString())
    print("Bass Level = %d" % bass.Actual)

    # get cached configuration directly from the configuration manager dictionary.
    if SoundTouchNodes.bass.Path in client.ConfigurationCache:
        bass:Bass = client.ConfigurationCache[SoundTouchNodes.bass.Path]
        print("\nCached configuration, direct:\n%s" % bass.ToString())
        print("Bass Level = %d" % bass.Actual)

except Exception as ex:

    print("** Exception: %s" % str(ex))

def GetBassCapabilities( self, refresh=True) -> bosesoundtouchapi.models.basscapabilities.BassCapabilities:

Gets the current bass capability configuration of the device.

Arguments:
  • refresh (bool): True to query the device for realtime information and refresh the cache; otherwise, False to just return the cached information.
Returns:

A BassCapabilities object that contains bass capabilities configuration of the device.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *
from bosesoundtouchapi.uri import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get real-time configuration from the device.
    bassCapabilities:BassCapabilities = client.GetBassCapabilities()
    print(bassCapabilities.ToString())

    # get cached configuration, refreshing from device if needed.
    bassCapabilities:BassCapabilities = client.GetBassCapabilities(False)
    print("\nCached configuration:\n%s" % bassCapabilities.ToString())

    # get cached configuration directly from the configuration manager dictionary.
    if SoundTouchNodes.bassCapabilities.Path in client.ConfigurationCache:
        bassCapabilities:BassCapabilities = client.ConfigurationCache[SoundTouchNodes.bassCapabilities.Path]
        print("\nCached configuration, direct:\n%s" % bassCapabilities.ToString())

except Exception as ex:

    print("** Exception: %s" % str(ex))

def GetCapabilities(self, refresh=True) -> bosesoundtouchapi.models.capabilities.Capabilities:

Gets the current bass capability configuration of the device.

Arguments:
  • refresh (bool): True to query the device for realtime information and refresh the cache; otherwise, False to just return the cached information.
Returns:

A Capabilities object that contains capabilities configuration of the device.

The returned object has a dict-like implementation; individual capabilities can be accessed by typing: GetCapabilities_results['capability_name'].

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *
from bosesoundtouchapi.uri import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get real-time configuration from the device.
    capabilities:Capabilities = client.GetCapabilities()
    print(capabilities.ToString())

    # get cached configuration, refreshing from device if needed.
    capabilities:Capabilities = client.GetCapabilities(False)
    print("\nCached configuration:\n%s" % capabilities.ToString())

    # get cached configuration directly from the configuration manager dictionary.
    if SoundTouchNodes.capabilities.Path in client.ConfigurationCache:
        capabilities:Capabilities = client.ConfigurationCache[SoundTouchNodes.capabilities.Path]
        print("\nCached configuration, direct:\n%s" % capabilities.ToString())

except Exception as ex:

    print("** Exception: %s" % str(ex))

def GetClockConfig(self, refresh=True) -> bosesoundtouchapi.models.clockconfig.ClockConfig:

Gets the current clock configuration of the device.

Arguments:
  • refresh (bool): True to query the device for realtime information and refresh the cache; otherwise, False to just return the cached information.
Returns:

A ClockConfig object that contains clock configuration of the device.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *
from bosesoundtouchapi.uri import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get real-time configuration from the device.
    clockConfig:ClockConfig = client.GetClockConfig()
    print(clockConfig.ToString())

    # get cached configuration, refreshing from device if needed.
    clockConfig:ClockConfig = client.GetClockConfig(False)
    print("\nCached configuration:\n%s" % clockConfig.ToString())

    # get cached configuration directly from the configuration manager dictionary.
    if SoundTouchNodes.clockDisplay.Path in client.ConfigurationCache:
        clockConfig:ClockConfig = client.ConfigurationCache[SoundTouchNodes.clockDisplay.Path]
        print("\nCached configuration, direct:\n%s" % clockConfig.ToString())

except Exception as ex:

    print("** Exception: %s" % str(ex))

def GetClockTime(self, refresh=True) -> bosesoundtouchapi.models.clocktime.ClockTime:

Gets the current clock time configuration of the device.

Arguments:
  • refresh (bool): True to query the device for realtime information and refresh the cache; otherwise, False to just return the cached information.
Returns:

A ClockTime object that contains clock time configuration of the device.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *
from bosesoundtouchapi.uri import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get real-time configuration from the device.
    clockTime:ClockTime = client.GetClockTime()
    print(clockTime.ToString())

    # get cached configuration, refreshing from device if needed.
    clockTime:ClockTime = client.GetClockTime(False)
    print("\nCached configuration:\n%s" % clockTime.ToString())

    # get cached configuration directly from the configuration manager dictionary.
    if SoundTouchNodes.clockDisplay.Path in client.ConfigurationCache:
        clockTime:ClockTime = client.ConfigurationCache[SoundTouchNodes.clockDisplay.Path]
        print("\nCached configuration, direct:\n%s" % clockTime.ToString())

except Exception as ex:

    print("** Exception: %s" % str(ex))

def GetDspMono( self, refresh=True) -> bosesoundtouchapi.models.dspmonostereoitem.DSPMonoStereoItem:

Gets the current digital signal processor configuration of the device.

Arguments:
  • refresh (bool): True to query the device for realtime information and refresh the cache; otherwise, False to just return the cached information.
Returns:

A DSPMonoStereoItem object that contains DSP configuration of the device.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *
from bosesoundtouchapi.uri import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get real-time configuration from the device.
    dspMonoStereoItem:DSPMonoStereoItem = client.GetDspMono()
    print(dspMonoStereoItem.ToString())

    # get cached configuration, refreshing from device if needed.
    dspMonoStereoItem:DSPMonoStereoItem = client.GetDspMono(False)
    print("\nCached configuration:\n%s" % dspMonoStereoItem.ToString())

    # get cached configuration directly from the configuration manager dictionary.
    if SoundTouchNodes.DSPMonoStereo.Path in client.ConfigurationCache:
        dspMonoStereoItem:DSPMonoStereoItem = client.ConfigurationCache[SoundTouchNodes.DSPMonoStereo.Path]
        print("\nCached configuration, direct:\n%s" % dspMonoStereoItem.ToString())

except Exception as ex:

    print("** Exception: %s" % str(ex))

def GetLanguage(self, refresh=True) -> bosesoundtouchapi.models.simpleconfig.SimpleConfig:

Gets the current language configuration of the device.

Arguments:
  • refresh (bool): True to query the device for realtime information and refresh the cache; otherwise, False to just return the cached information.
Returns:

A SimpleConfig object that contains language configuration of the device.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *
from bosesoundtouchapi.uri import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get real-time configuration from the device.
    language:SimpleConfig = client.GetLanguage()
    print(language.ToString())
    print("\nDevice Language = '%s'" % language.Value)

    # get cached configuration, refreshing from device if needed.
    language:SimpleConfig = client.GetLanguage(False)
    print("\nCached configuration:\n%s" % language.ToString())

    # get cached configuration directly from the configuration manager dictionary.
    if SoundTouchNodes.language.Path in client.ConfigurationCache:
        language:SimpleConfig = client.ConfigurationCache[SoundTouchNodes.language.Path]
        print("\nCached configuration, direct:\n%s" % language.ToString())

except Exception as ex:

    print("** Exception: %s" % str(ex))

def GetMediaServerList( self, refresh=True) -> bosesoundtouchapi.models.mediaserverlist.MediaServerList:

Gets the list of UPnP Media servers found by the device.

Arguments:
  • refresh (bool): True to query the device for realtime information and refresh the cache; otherwise, False to just return the cached information.
Returns:

A MediaServerList object that contains media server configuration of the device.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *
from bosesoundtouchapi.uri import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get real-time configuration from the device.
    mediaServerList:MediaServerList = client.GetMediaServerList()
    print(mediaServerList.ToString(True))

    # get cached configuration, refreshing from device if needed.
    mediaServerList:MediaServerList = client.GetMediaServerList(False)
    print("\nCached configuration:\n%s" % mediaServerList.ToString(True))

    # get cached configuration directly from the configuration manager dictionary.
    if SoundTouchNodes.listMediaServers.Path in client.ConfigurationCache:
        mediaServerList:MediaServerList = client.ConfigurationCache[SoundTouchNodes.listMediaServers.Path]
        print("\nCached configuration, direct:\n%s" % mediaServerList.ToString(True))

except Exception as ex:

    print("** Exception: %s" % str(ex))

def GetName(self, refresh=True) -> bosesoundtouchapi.models.simpleconfig.SimpleConfig:

Gets the current name configuration of the device, and updates the SoundTouchDevice class device name if possible.

Arguments:
  • refresh (bool): True to query the device for realtime information and refresh the cache; otherwise, False to just return the cached information.
Returns:

A SimpleConfig object that contains name configuration of the device.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *
from bosesoundtouchapi.uri import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get real-time configuration from the device.
    name:SimpleConfig = client.GetName()
    print(name.ToString())
    print("\nDevice Name = '%s'" % name.Value)

    # get cached configuration, refreshing from device if needed.
    name:SimpleConfig = client.GetName(False)
    print("\nCached configuration:\n%s" % name.ToString())
    print("\nDevice Name = '%s'" % name.Value)

    # get cached configuration directly from the configuration manager dictionary.
    if SoundTouchNodes.name.Path in client.ConfigurationCache:
        name:SimpleConfig = client.ConfigurationCache[SoundTouchNodes.name.Path]
        print("\nCached configuration, direct:\n%s" % name.ToString())
        print("\nDevice Name = '%s'" % name.Value)

except Exception as ex:

    print("** Exception: %s" % str(ex))

def GetNetworkInfo(self, refresh=True) -> bosesoundtouchapi.models.networkinfo.NetworkInfo:

Gets the current network information configuration of the device.

Arguments:
  • refresh (bool): True to query the device for realtime information and refresh the cache; otherwise, False to just return the cached information.
Returns:

A NetworkInfo object that contains network information configuration of the device.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *
from bosesoundtouchapi.uri import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get real-time configuration from the device.
    networkInfo:NetworkInfo = client.GetNetworkInfo()
    print(networkInfo.ToString(True))

    # get cached configuration, refreshing from device if needed.
    networkInfo:NetworkInfo = client.GetNetworkInfo(False)
    print("\nCached configuration:\n%s" % networkInfo.ToString(True))

    # get cached configuration directly from the configuration manager dictionary.
    if SoundTouchNodes.networkInfo.Path in client.ConfigurationCache:
        networkInfo:NetworkInfo = client.ConfigurationCache[SoundTouchNodes.networkInfo.Path]
        print("\nCached configuration, direct:\n%s" % networkInfo.ToString(True))

except Exception as ex:

    print("** Exception: %s" % str(ex))

def GetNetworkStatus( self, refresh=True) -> bosesoundtouchapi.models.networkstatus.NetworkStatus:

Gets the current network status configuration of the device.

Arguments:
  • refresh (bool): True to query the device for realtime information and refresh the cache; otherwise, False to just return the cached information.
Returns:

A NetworkStatus object that contains network status configuration of the device.

This method can be used to retrieve the network status of the device for each network interface that has established a connection. This includes details like the interface name (e.g. 'eth0'), the network SSID, MAC Address, and more.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *
from bosesoundtouchapi.uri import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get real-time configuration from the device.
    networkStatus:NetworkStatus = client.GetNetworkStatus()
    print(networkStatus.ToString(True))

    # get cached configuration, refreshing from device if needed.
    networkStatus:NetworkStatus = client.GetNetworkStatus(False)
    print("\nCached configuration:\n%s" % networkStatus.ToString(True))

    # get cached configuration directly from the configuration manager dictionary.
    if SoundTouchNodes.netStats.Path in client.ConfigurationCache:
        networkStatus:NetworkStatus = client.ConfigurationCache[SoundTouchNodes.netStats.Path]
        print("\nCached configuration, direct:\n%s" % networkStatus.ToString(True))

except Exception as ex:

    print("** Exception: %s" % str(ex))

def GetNowPlayingStatus( self, refresh=True) -> bosesoundtouchapi.models.nowplayingstatus.NowPlayingStatus:

Gets the now playing status configuration of the device.

Arguments:
  • refresh (bool): True to query the device for realtime information and refresh the cache; otherwise, False to just return the cached information.
Returns:

A NowPlayingStatus object that contains now playing status configuration of the device.

This method can be used to retrieve the status of media that is currently playing on the device. This includes the media source, ContentItem, track, artist, album, preview image, duration, position, play status, shuffle and repeat setting, stream type, track ID, station description and the location of the station.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *
from bosesoundtouchapi.uri import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get real-time configuration from the device.
    nowPlayingStatus:NowPlayingStatus = client.GetNowPlayingStatus()
    print(nowPlayingStatus.ToString())

    # get cached configuration, refreshing from device if needed.
    nowPlayingStatus:NowPlayingStatus = client.GetNowPlayingStatus(False)
    print("\nCached configuration:\n%s" % nowPlayingStatus.ToString())

    # get cached configuration directly from the configuration manager dictionary.
    if SoundTouchNodes.nowPlaying.Path in client.ConfigurationCache:
        nowPlayingStatus:NowPlayingStatus = client.ConfigurationCache[SoundTouchNodes.nowPlaying.Path]
        print("\nCached configuration, direct:\n%s" % nowPlayingStatus.ToString())

except Exception as ex:

    print("** Exception: %s" % str(ex))

def GetOptions(self, uri: bosesoundtouchapi.uri.soundtouchuri.SoundTouchUri) -> list:

Makes an OPTIONS request and returns the list of available HTTP-Methods.

Use this method when testing whether a node can be accessed.

Arguments:
  • uri (SoundTouchUri): The node where the requested value is stored.
Returns:

A list of strings storing all available HTTP-Methods.

Raises:
  • SoundTouchError: When errors should not be ignored on this client, they will raise a SoundTouchError exception with all information related to that error.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *
from bosesoundtouchapi.uri import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # list available HTTP-Methods for a specific node.
    node:SoundTouchUri = SoundTouchNodes.volume
    methods:list = client.GetOptions(node)
    print("Options for '%s' node: %s" % (node.Path, str(methods)))

    # list available HTTP-Methods for ALL nodes supported by the device.
    node:SoundTouchUri
    for node in device.SupportedUris:
        methods:list = client.GetOptions(node)
        print("Options for '%s' node: %s" % (node.Path, str(methods)))

except Exception as ex:

    print("** Exception: %s" % str(ex))

def GetPowerManagement( self, refresh=True) -> bosesoundtouchapi.models.powermanagement.PowerManagement:

Gets the current power management status configuration of the device.

Arguments:
  • refresh (bool): True to query the device for realtime information and refresh the cache; otherwise, False to just return the cached information.
Returns:

A PowerManagement object that contains power management configuration of the device.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *
from bosesoundtouchapi.uri import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get real-time configuration from the device.
    powerManagement:PowerManagement = client.GetPowerManagement()
    print(powerManagement.ToString())

    # get cached configuration, refreshing from device if needed.
    powerManagement:PowerManagement = client.GetPowerManagement(False)
    print("\nCached configuration:\n%s" % powerManagement.ToString())

    # get cached configuration directly from the configuration manager dictionary.
    if SoundTouchNodes.powerManagement.Path in client.ConfigurationCache:
        powerManagement:PowerManagement = client.ConfigurationCache[SoundTouchNodes.powerManagement.Path]
        print("\nCached configuration, direct:\n%s" % powerManagement.ToString())

except Exception as ex:

    print("** Exception: %s" % str(ex))

def GetPresetList(self, refresh=True) -> bosesoundtouchapi.models.presetlist.PresetList:

Gets the current preset list configuration of the device.

Arguments:
  • refresh (bool): True to query the device for realtime information and refresh the cache; otherwise, False to just return the cached information.
Returns:

A PresetList object that contains preset list configuration of the device.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *
from bosesoundtouchapi.uri import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get real-time configuration from the device.
    presetList:PresetList = client.GetPresetList()
    print(presetList.ToString(True))

    # get cached configuration, refreshing from device if needed.
    presetList:PresetList = client.GetPresetList(False)
    print("\nCached configuration:\n%s" % presetList.ToString(True))

    # get cached configuration directly from the configuration manager dictionary.
    if SoundTouchNodes.presets.Path in client.ConfigurationCache:
        presetList:PresetList = client.ConfigurationCache[SoundTouchNodes.presets.Path]
        print("\nCached configuration, direct:\n%s" % presetList.ToString(True))

except Exception as ex:

    print("** Exception: %s" % str(ex))

def GetProperty( self, uri: bosesoundtouchapi.uri.soundtouchuri.SoundTouchUri, classType, refresh=True):

Returns a cached property mapped to the given URI.

Arguments:
  • uri (SoundTouchUri): The property key (e.g. 'balance', 'volume', etc).
  • classType (type): The configuration class type (e.g. Balance, Volume, etc).
  • refresh (bool): True to refresh the property with real-time information from the device; otherwise, False to just return the cached value.
Returns:

A configuration instance of the provided classType argument.

This method will refresh the property from the device if the property does not exist in the cache, regardless of the refresh argument value.

def GetRecentList(self, refresh=True) -> bosesoundtouchapi.models.recentlist.RecentList:

Gets the current recent list configuration of the device.

Arguments:
  • refresh (bool): True to query the device for realtime information and refresh the cache; otherwise, False to just return the cached information.
Returns:

A RecentList object that contains recent list configuration of the device.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *
from bosesoundtouchapi.uri import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get real-time configuration from the device.
    recentList:RecentList = client.GetRecentList()
    print(recentList.ToString(True))

    # get cached configuration, refreshing from device if needed.
    recentList:RecentList = client.GetRecentList(False)
    print("\nCached configuration:\n%s" % recentList.ToString(True))

    # get cached configuration directly from the configuration manager dictionary.
    if SoundTouchNodes.recents.Path in client.ConfigurationCache:
        recentList:RecentList = client.ConfigurationCache[SoundTouchNodes.recents.Path]
        print("\nCached configuration, direct:\n%s" % recentList.ToString(True))

except Exception as ex:

    print("** Exception: %s" % str(ex))

def GetRequestToken(self, refresh=True) -> bosesoundtouchapi.models.simpleconfig.SimpleConfig:

Gets a new request token generated by the device.

Arguments:
  • refresh (bool): True to query the device for realtime information and refresh the cache; otherwise, False to just return the cached information.
Returns:

A SimpleConfig object that contains the request token in the Attribute property.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *
from bosesoundtouchapi.uri import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get real-time configuration from the device.
    requestToken:SimpleConfig = client.GetRequestToken()
    print(requestToken.ToString())
    print("\nToken = '%s'" % requestToken.Attribute['value'])

    # get cached configuration, refreshing from device if needed.
    requestToken:SimpleConfig = client.GetRequestToken(False)
    print("\nCached configuration:\n%s" % requestToken.ToString())
    print("\nToken = '%s'" % requestToken.Attribute['value'])

    # get cached configuration directly from the configuration manager dictionary.
    if SoundTouchNodes.requestToken.Path in client.ConfigurationCache:
        requestToken:SimpleConfig = client.ConfigurationCache[SoundTouchNodes.requestToken.Path]
        print("\nCached configuration, direct:\n%s" % requestToken.ToString())
        print("\nToken = '%s'" % requestToken.Attribute['value'])

except Exception as ex:

    print("** Exception: %s" % str(ex))

def GetSourceList(self, refresh=True) -> bosesoundtouchapi.models.sourcelist.SourceList:

Gets the current source list configuration of the device.

Arguments:
  • refresh (bool): True to query the device for realtime information and refresh the cache; otherwise, False to just return the cached information.
Returns:

A SourceList object that contains source list configuration of the device.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *
from bosesoundtouchapi.uri import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get real-time configuration from the device.
    sourceList:SourceList = client.GetSourceList()
    print(sourceList.ToString(True))

    # get specific sourceitem with the source name.
    sourceItem = sourceList['TUNEIN']
    print("(by name 'TUNEIN')  %s" % (sourceItem.ToString()))

    # get specific sourceitem at the index position.
    sourceItem = sourceList[0]
    print("(by index 0)        %s" % (sourceItem.ToString()))

    # get cached configuration, refreshing from device if needed.
    sourceList:SourceList = client.GetSourceList(False)
    print("\nCached configuration:\n%s" % sourceList.ToString(True))

    # get cached configuration directly from the configuration manager dictionary.
    if SoundTouchNodes.sources.Path in client.ConfigurationCache:
        sourceList:SourceList = client.ConfigurationCache[SoundTouchNodes.sources.Path]
        print("\nCached configuration, direct:\n%s" % sourceList.ToString(True))


except Exception as ex:

    print("** Exception: %s" % str(ex))

def GetSystemTimeout( self, refresh=True) -> bosesoundtouchapi.models.systemtimeout.SystemTimeout:

Gets the current system timeout configuration of the device.

Arguments:
  • refresh (bool): True to query the device for realtime information and refresh the cache; otherwise, False to just return the cached information.
Returns:

A SystemTimeout object that contains system timeout configuration of the device.

Use this method to determine whether power saving is enabled or not.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *
from bosesoundtouchapi.uri import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get real-time configuration from the device.
    systemTimeout:SystemTimeout = client.GetSystemTimeout()
    print(systemTimeout.ToString())

    # get cached configuration, refreshing from device if needed.
    systemTimeout:SystemTimeout = client.GetSystemTimeout(False)
    print("\nCached configuration:\n%s" % systemTimeout.ToString())

    # get cached configuration directly from the configuration manager dictionary.
    if SoundTouchNodes.systemtimeout.Path in client.ConfigurationCache:
        systemTimeout:SystemTimeout = client.ConfigurationCache[SoundTouchNodes.systemtimeout.Path]
        print("\nCached configuration, direct:\n%s" % systemTimeout.ToString())

except Exception as ex:

    print("** Exception: %s" % str(ex))

def GetVolume(self, refresh=True) -> bosesoundtouchapi.models.volume.Volume:

Gets the current volume configuration of the device.

Arguments:
  • refresh (bool): True to query the device for realtime information and refresh the cache; otherwise, False to just return the cached information.
Returns:

A Volume object that contains volume configuration of the device.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *
from bosesoundtouchapi.uri import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get real-time configuration from the device.
    volume:Volume = client.GetVolume()
    print(volume.ToString())
    print("Volume Level = %d" % volume.Actual)

    # get cached configuration, refreshing from device if needed.
    volume:Volume = client.GetVolume(False)
    print("\nCached configuration:\n%s" % volume.ToString())
    print("Volume Level = %d" % volume.Actual)

    # get cached configuration directly from the configuration manager dictionary.
    if SoundTouchNodes.volume.Path in client.ConfigurationCache:
        volume:Volume = client.ConfigurationCache[SoundTouchNodes.volume.Path]
        print("\nCached configuration, direct:\n%s" % volume.ToString())
        print("Volume Level = %d" % volume.Actual)

except Exception as ex:

    print("** Exception: %s" % str(ex))

def GetWirelessProfile( self, refresh=True) -> bosesoundtouchapi.models.wirelessprofile.WirelessProfile:

Gets the current wireless profile configuration of the device.

Arguments:
  • refresh (bool): True to query the device for realtime information and refresh the cache; otherwise, False to just return the cached information.
Returns:

A WirelessProfile object that contains wireless profile configuration of the device.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *
from bosesoundtouchapi.uri import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get real-time configuration from the device.
    wirelessProfile:WirelessProfile = client.GetWirelessProfile()
    print(wirelessProfile.ToString())

    # get cached configuration, refreshing from device if needed.
    wirelessProfile:WirelessProfile = client.GetWirelessProfile(False)
    print("\nCached configuration:\n%s" % wirelessProfile.ToString())

    # get cached configuration directly from the configuration manager dictionary.
    if SoundTouchNodes.getActiveWirelessProfile.Path in client.ConfigurationCache:
        wirelessProfile:WirelessProfile = client.ConfigurationCache[SoundTouchNodes.getActiveWirelessProfile.Path]
        print("\nCached configuration, direct:\n%s" % wirelessProfile.ToString())

except Exception as ex:

    print("** Exception: %s" % str(ex))

def GetZoneStatus(self, refresh=True) -> bosesoundtouchapi.models.zone.Zone:

Gets the current wireless zone status configuration of the device.

Arguments:
  • refresh (bool): True to query the device for realtime information and refresh the cache; otherwise, False to just return the cached information.
Returns:

A Zone object that contains zone configuration of the device.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *
from bosesoundtouchapi.uri import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get real-time configuration from the device.
    zone:Zone = client.GetZoneStatus()
    print(zone.ToString(True))

    # get cached configuration, refreshing from device if needed.
    zone:Zone = client.GetZoneStatus(False)
    print("\nCached configuration:\n%s" % zone.ToString(True))

    # get cached configuration directly from the configuration manager dictionary.
    if SoundTouchNodes.getZone.Path in client.ConfigurationCache:
        zone:Zone = client.ConfigurationCache[SoundTouchNodes.getZone.Path]
        print("\nCached configuration, direct:\n%s" % zone.ToString(True))


except Exception as ex:

    print("** Exception: %s" % str(ex))

def MakeRequest( self, method: str, msg: bosesoundtouchapi.soundtouchmessage.SoundTouchMessage) -> int:

Performs a generic request by converting the response into the message object.

Arguments:
  • method (str): The preferred HTTP method (e.g. "GET", "POST", etc).
  • msg (SoundTouchMessage): The altered message object.
Returns:

The status code (integer) or allowed methods (list).

Raises:
  • InterruptedError: If an error occurs while requesting content.

A 400 status code is immediately returned for the following scenarios:

  • The method argument is not supplied.
  • The msg argument is not supplied.
  • The msg.Uri is not in the device list of supported URI's.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *
from bosesoundtouchapi.uri import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # manually make a request to the volume status node.
    volume:Volume = Volume(25)
    print("\nVolume object:\n%s" % volume.ToString())
    reqBody:str = volume.ToXmlRequestBody()
    message = SoundTouchMessage(SoundTouchNodes.volume, reqBody)
    client.MakeRequest('POST', message)
    print("\nMakeRequest Response:\n%s" % message.XmlMessage)

except Exception as ex:

    print("** Exception: %s" % str(ex))

def MediaNextTrack(self) -> None:

Move to the next track in the current media playlist.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("(before): '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))

    # move to the next track in the current media playlist.
    client.MediaNextTrack()

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("(after):  '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))

except Exception as ex:

    print("** Exception: %s" % str(ex))

def MediaPause(self) -> None:

Pause the current media playing.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("(before): '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))

    # pause currently playing media.
    client.MediaPause()

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("(after):  '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))

except Exception as ex:

    print("** Exception: %s" % str(ex))

def MediaPlay(self) -> None:

Play the currently paused media.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("(before): '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))

    # play currently paused media.
    client.MediaPlay()

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("(after):  '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))

except Exception as ex:

    print("** Exception: %s" % str(ex))

def MediaPlayPause(self) -> None:

Toggle the Play / Pause state of the current media playing.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("(before): '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))

    # toggle the play / pause state of the current media playing.
    client.MediaPlayPause()

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("(after):  '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))

except Exception as ex:

    print("** Exception: %s" % str(ex))

def MediaPreviousTrack(self) -> None:

Move to the previous track in the current media playlist.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("(before): '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))

    # move to the previous track in the current media playlist.
    client.MediaPreviousTrack()

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("(after):  '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))

except Exception as ex:

    print("** Exception: %s" % str(ex))

def MediaRepeatAll(self) -> None:

Enables repeat all processing for the current media playlist.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("(before): '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))

    # enable repeat all processing for the current media playlist.
    client.MediaRepeatAll()

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("(after):  '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))

except Exception as ex:

    print("** Exception: %s" % str(ex))

def MediaRepeatOff(self) -> None:

Turns off repeat (all / one) processing for the current media playlist.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("(before): '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))

    # disable repeat (all / one) processing for the current media playlist.
    client.MediaRepeatOff()

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("(after):  '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))

except Exception as ex:

    print("** Exception: %s" % str(ex))

def MediaRepeatOne(self) -> None:

Enables repeat single track processing for the current media playlist.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("(before): '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))

    # enable repeat one processing for the current media playlist.
    client.MediaRepeatOne()

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("(after):  '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))

except Exception as ex:

    print("** Exception: %s" % str(ex))

def MediaResume(self) -> None:

Resume the current media playing.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("(before): '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))

    # resume currently playing media.
    client.MediaResume()

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("(after):  '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))

except Exception as ex:

    print("** Exception: %s" % str(ex))

def MediaShuffleOff(self) -> None:

Disables shuffling of the current media playlist.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("(before): '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))

    # disable shuffling of the current media playlist. 
    client.MediaShuffleOff()

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("(after):  '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))

except Exception as ex:

    print("** Exception: %s" % str(ex))

def MediaShuffleOn(self) -> None:

Enables shuffling of the current media playlist.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("(before): '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))

    # enable shuffling of the current media playlist. 
    client.MediaShuffleOn()

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("(after):  '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))

except Exception as ex:

    print("** Exception: %s" % str(ex))

def MediaStop(self) -> None:

Stop the current media playing.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("(before): '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))

    # stop currently playing media.
    client.MediaStop()

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("(after):  '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))

except Exception as ex:

    print("** Exception: %s" % str(ex))

def Mute(self) -> None:

Toggle mute / unmute.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get real-time configuration from the device.
    volume:Volume = client.GetVolume()
    print("(before) %s" % volume.ToString())

    # toggle mute / unmute of the device.
    client.Mute()

    # get real-time configuration from the device.
    volume:Volume = client.GetVolume()
    print("(after)  %s" % volume.ToString())

except Exception as ex:

    print("** Exception: %s" % str(ex))

def MuteOff(self, refresh: bool = True) -> None:

Unmutes the device, if the device is currently muted.

Arguments:
  • refresh (bool): True to check the real-time status of the device; otherwise, False to check the cached status of the device.
    Default = True.

This will first issue a GetVolume() method call to query the current volume of the device. If the refresh argument is True, then the volume status is refreshed with real-time data; otherwise the cached volume status is used.

If the volume IsMuted property is true, then the MUTE key will be sent to unmute the device.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get real-time configuration from the device.
    volume:Volume = client.GetVolume()
    print("(before) %s" % volume.ToString())

    # unmute device.
    client.MuteOff()

    # get real-time configuration from the device.
    volume:Volume = client.GetVolume()
    print("(after)  %s" % volume.ToString())

except Exception as ex:

    print("** Exception: %s" % str(ex))

def MuteOn(self, refresh: bool = True) -> None:

Mutes the device, if the device is currently not muted.

Arguments:
  • refresh (bool): True to check the real-time status of the device; otherwise, False to check the cached status of the device.
    Default = True.

This will first issue a GetVolume() method call to query the current volume of the device. If the refresh argument is True, then the volume status is refreshed with real-time data; otherwise the cached volume status is used.

If the volume IsMuted property is false, then the MUTE key will be sent to mute the device.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get real-time configuration from the device.
    volume:Volume = client.GetVolume()
    print("(before) %s" % volume.ToString())

    # mute device.
    client.MuteOn()

    # get real-time configuration from the device.
    volume:Volume = client.GetVolume()
    print("(after)  %s" % volume.ToString())

except Exception as ex:

    print("** Exception: %s" % str(ex))

Plays the given ContentItem.

Arguments:
  • item (ContentItem): content item to play.
  • delay (int): Time delay (in seconds) to wait AFTER selecting the content item.
    This delay will give the device time to process the change before another command is accepted.
    Default is 5; value range is 0 - 10.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("(before): %s" % (nowPlaying.ToString()))

    # play the specified media content.
    content_item_radio:ContentItem = ContentItem("TUNEIN","stationurl","/v1/playback/station/s309605","",True,"K-LOVE 90s")
    client.PlayContentItem(content_item_radio)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("(after):  %s" % (nowPlaying.ToString()))

except Exception as ex:

    print("** Exception: %s" % str(ex))

def PlayNotificationTTS( self, sayText: str, ttsUrl: str = None, artist: str = None, album: str = None, track: str = None, volumeLevel: int = 0, appKey: str = None) -> bosesoundtouchapi.soundtouchmessage.SoundTouchMessage:

Plays a notification message via Google TTS (Text-To-Speech) processing.

Arguments:
  • sayText (str): The message that will be converted from text to speech and played on the device.
  • ttsUrl (str): 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 sayText value. Default value is:
    "http://translate.google.com/translate_tts?ie=UTF-8&tl=EN&client=tw-ob&q={saytext}"
  • artist (str): The message text that will appear in the NowPlaying Artist node.
    Default is "TTS Notification"
  • album (str): The message text that will appear in the NowPlaying Album node.
    Default is "Google TTS"
  • track (str): The message text that will appear in the NowPlaying Track node.
    Default is the sayText argument value.
  • volumeLevel (int): The temporary volume level that will be used when the message is played.
    Specify a value of zero to play at the current volume.
    Per Bose limitations, max level cannot be more than 70. Default is zero.
  • appKey (str): Bose Developer API application key.
Raises:
  • SoundTouchError: ttsUrl argument value does not start with 'http://'. ttsUrl argument was not a string; ignoring PlayNotificationTTS request.

Note that SoundTouch devices do not support playing content from HTTPS (secure socket layer) url's. A SoundTouchException will be raised if a non http:// url is supplied for the ttsUrl argument.

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 volumeLevel argument. Specify a volumeLevel 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.

Sample Code

import time
from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # use google text to speech to say a message.
    print("\nSaying message via Google TTS (language=EN) ...")
    client.PlayNotificationTTS("There is activity at the front door.")

    # if playing messages back to back, then give the message time to play
    # before playing the next one; otherwise the next message is lost.
    time.sleep(6)

    # use google text to speech to say a message.
    print("\nSaying message via Google TTS (language=DE) ...")
    client.PlayNotificationTTS("There is activity at the front door.", 
                               "http://translate.google.com/translate_tts?ie=UTF-8&tl=DE&client=tw-ob&q={saytext}",
                               volumeLevel=30)

    # if playing messages back to back, then give the message time to play
    # before playing the next one; otherwise the next message is lost.
    time.sleep(6)

    # use google text to speech to say a message.
    print("\nSaying message via Google TTS (language=EN) ...")
    client.PlayNotificationTTS("There is activity at the front door.", 
                               "http://translate.google.com/translate_tts?ie=UTF-8&tl=EN&client=tw-ob&q={saytext}",
                               "Activity Detected", # <- appears in nowPlaying.Artist
                               "Front Door",        # <- appears in nowPlaying.Album
                               "Motion Sensor",     # <- appears in nowPlaying.Track
                               volumeLevel=20)

    # if playing messages back to back, then give the message time to play
    # before playing the next one; otherwise the next message is lost.
    time.sleep(6)

    # use google text to speech to say a message using a custom Bose developer appKey.
    print("\nSaying message via Google TTS (language=EN) ...")
    client.PlayNotificationTTS("There is activity at the front door.", 
                               appKey="YourBoseAppKey")

except Exception as ex:

    print("** Exception: %s" % str(ex))

def PlayUrl( self, url: str, artist: str = None, album: str = None, track: str = None, volumeLevel: int = 0, appKey: str = None, getMetaDataFromUrlFile: bool = False) -> bosesoundtouchapi.soundtouchmessage.SoundTouchMessage:

Plays media from the given URL.

Arguments:
  • url (str): The url to play.
  • artist (str): The message text that will appear in the NowPlaying Artist node.
    Default is "Unknown Artist"
  • album (str): The message text that will appear in the NowPlaying Album node.
    Default is "Unknown Album"
  • track (str): The message text that will appear in the NowPlaying Track node.
    Default is "Unknown Track"
  • volumeLevel (int): 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.
  • appKey (str): Bose Developer API application key.
  • getMetaDataFromUrlFile (bool): 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.

Returns:
A SoundTouchMessage object storing the request uri, a payload that has been sent (optional), and the response as an xml.etree.ElementTree.Element.

Raises:
  • SoundTouchError: Url argument value does not start with 'http://' or 'https://'.
    If the SoundTouch device encounters an error while trying to play the url media content.

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.

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.

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.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("\n(before): %s" % (nowPlaying.ToString()))

    # play the given https url at the current volume level.
    print("\nPlaying HTTPS URL content from the web ...")
    client.PlayUrl("https://freetestdata.com/wp-content/uploads/2021/09/Free_Test_Data_1MB_MP3.mp3",
                   "FreeTestData.com",
                   "MP3 Test Data",
                   "Free_Test_Data_1MB_MP3",
                   volumeLevel=0)

    # play the given http url at the current volume level.
    print("\nPlaying HTTP URL content from the web ...")
    client.PlayUrl("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",
                   "Clementi",
                   "Movements Album",
                   "Piano Sonata in D major",
                   volumeLevel=0)

    # play the given url, retrieving metadata (artist,album,track) from the url content.
    print("\nPlaying HTTP URL content from Home Assistant ...")
    client.PlayUrl("http://homeassistant.local:8123/media/local/06%20Flawless.mp3?authSig=xxxx",
                   getMetaDataFromUrlFile=True,
                   volumeLevel=0)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("\n(after):  %s" % (nowPlaying.ToString()))

except Exception as ex:

    print("** Exception: %s" % str(ex))

def Power(self) -> None:

Toggle power on / off.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("(before): '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))

    # toggle power on / off of the device.
    client.Power()

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("(after):  '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))

except Exception as ex:

    print("** Exception: %s" % str(ex))

def PowerOff(self, refresh: bool = True) -> None:

Set power off, if the device is currently powered on and not in standby mode.

Arguments:
  • refresh (bool): True to check the real-time status of the device; otherwise, False to check the cached status of the device.
    Default = True.

This will first issue a GetNowPlayingStatus() method call to query the current status of the device. If the refresh argument is True, then the status is refreshed with real-time data; otherwise the cached status is used.

If the nowPlaying source is not "STANDBY", then the POWER key will be sent to power off the device.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("(before): '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))

    # power off (standby) the device.
    client.PowerOff()

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("(after):  '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))

except Exception as ex:

    print("** Exception: %s" % str(ex))

def PowerOn(self, refresh: bool = True) -> None:

Set power on, if the device is currently in standby mode.

Arguments:
  • refresh (bool): True to check the real-time status of the device; otherwise, False to check the cached status of the device.
    Default = True.

This will first issue a GetNowPlayingStatus() method call to query the current status of the device. If the refresh argument is True, then the status is refreshed with real-time data; otherwise the cached status is used.

If the nowPlaying source is "STANDBY", then the POWER key will be sent to power on the device.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("(before): '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))

    # power on the device.
    client.PowerOn()

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("(after):  '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))

except Exception as ex:

    print("** Exception: %s" % str(ex))

def PowerStandby(self) -> None:

Set power to standby, if the device is currently powered on.

This method does not update a configuration, as there is no object to configure - it simply places the device in STANDBY mode.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("(before): '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))

    # power standby (off) the device.
    client.PowerStandby()

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("(after):  '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))

except Exception as ex:

    print("** Exception: %s" % str(ex))

Makes a POST request to apply a new value for the given node.

Use this method when setting some configuration related data. All standard operations where a POST request is necessary are implemented by this class.

Arguments:
  • uri (SoundTouchUri): The node where the requested value is stored.
  • body (str | SoundTouchModelRequest): The request body xml, or a class that inherits from SoundTouchModelRequest that implements the ToXmlRequestBody method.

Returns: A SoundTouchMessage object storing the request uri, a payload that has been sent (optional), and the response as an xml.etree.ElementTree.Element.

Raises:
  • SoundTouchError: When errors should not be ignored on this client, they will raise a SoundTouchError exception with all information related to that error.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *
from bosesoundtouchapi.uri import *
from xml.etree.ElementTree import Element
from xml.etree import ElementTree

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # update configuration for specified node.
    msg:SoundTouchMessage = client.Put(SoundTouchNodes.volume, '<volume>10</volume>')

    if msg != None:
        ElementTree.indent(msg.Response)  # for pretty printing
        responseEncoded = ElementTree.tostring(msg.Response, encoding="unicode")
        print("Put Response Message:\n%s" %  responseEncoded)

except Exception as ex:

    print("** Exception: %s" % str(ex))

def RefreshConfiguration( self, uri: bosesoundtouchapi.uri.soundtouchuri.SoundTouchUri, classType) -> object:

Refreshes the cached configuration for the given URI.

Arguments:
  • uri (SoundTouchUri): The configuration uri key.
  • classType (type): The configuration class type (e.g. Balance, Volume, etc).
  • refresh (bool): True to refresh the property with real-time information from the device; otherwise, False to just return the cached value.
Returns:

A configuration instance of the provided classType argument.

This method will call the Get() method to refresh the configuration with real-time information from the device, and store the results in the cache.

Removes all presets from the device's list of presets.

Returns:

A message object that may contain more information about the result.

Raises:
  • Exception: If the command fails for any reason.

A GetPresetList() method call is made to retrieve the current list of presets. The returned list of presets are deleted one by one.
The message returned is the message returned from the final preset removal.
If there were no presets to remove, then the returned result is None.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # remove all presets.
    client.RemoveAllPresets()

    # get list of defined presets.
    presetList:PresetList = client.GetPresetList()
    print(presetList.ToString(True))

except Exception as ex:

    print("** Exception: %s" % str(ex))

def RemovePreset( self, presetId: int) -> bosesoundtouchapi.soundtouchmessage.SoundTouchMessage:

Removes the specified Preset id from the device's list of presets.

Arguments:
  • presetId (int): The preset id to remove; valid values are 1 thru 6.
Returns:

A message object that may contain more information about the result.

Raises:
  • Exception: If the command fails for any reason.

The preset with the specified id is removed.
No exception is raised if the preset id does not exist.

Presets and favorites in the SoundTouch app are not reordered once the preset is removed; it simply creates an open / empty slot in the list.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # remove preset #4.
    client.RemovePreset(4)

    # get list of defined presets.
    presetList:PresetList = client.GetPresetList()
    print(presetList.ToString(True))

except Exception as ex:

    print("** Exception: %s" % str(ex))

def RemoveFavorite(self) -> None:

Removes the currently playing media from the device favorites.

This will first make a call to GetNowPlayingStatus() method to ensure favorites are enabled for the now playing media. If not enabled, then the request is ignored and no exception is raised.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *
import time 

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("\nCurrent Now Playing Status:\n%s" % nowPlaying.ToString())

    # does nowPlaying item support favorites?
    if nowPlaying.IsFavoriteEnabled:

        # remove the currently playing media from the device favorites.
        client.RemoveFavorite()

        # give the device time to process the change.
        time.sleep(1)

        # get current nowPlaying status.
        nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
        print("\nUpdated Now Playing Status:\n%s" % nowPlaying.ToString())

    else:

        print("\nFavorites not enabled for currently playing media")

except Exception as ex:

    print("** Exception: %s" % str(ex))

def RemoveZone( self, delay: int = 1) -> bosesoundtouchapi.soundtouchmessage.SoundTouchMessage:

Removes the given zone.

Arguments:
  • delay (int): Time delay (in seconds) to wait AFTER removing zone members. This delay will give the device time to process the change before another command is accepted.
    Default is 1; value range is 0 - 10.
Raises:
  • SoundTouchError: Master zone status could not be retrieved.
    Master zone does not exist; zone members cannot be removed.

This method retrieves the current master zone status, and issues a call to RemoveZoneMembers to remove all members from the zone.

Note that the master zone itself is also removed; you will need to reissue a call to the CreateZone() method to re-create the master zone.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current zone configuration status.
    zoneBefore:Zone = client.GetZoneStatus()
    print("\nCurrent Zone Status:\n%s" % zoneBefore.ToString(True))

    # if zone not active, then create one so that we have something to remove.
    if len(zoneBefore.Members) == 0:

        print("Creating a new master zone so we have a zone to remove ...")

        # build list of zone members to remove.
        zoneMembers:list = []
        zoneMembers.append(ZoneMember("192.168.1.130", "E8EB11B9B723"))

        # initialize the new master zone configuration.
        masterZone:Zone = Zone(client.Device.DeviceId, client.Device.Host, True) # <- master
        member:ZoneMember
        for member in zoneMembers:
            masterZone.AddMember(member)                                         # <- member

        # create a new master zone configuration on the device.
        client.CreateZone(masterZone)

        # get current zone configuration status.
        zoneBefore:Zone = client.GetZoneStatus()
        print("\nZone Status Before:\n%s" % zoneBefore.ToString(True))

    # remove the master zone configuration from the device.
    client.RemoveZone()

    # get current zone configuration status.
    zoneAfter:Zone = client.GetZoneStatus()
    print("\nZone Status After:\n%s" % zoneAfter.ToString(True))

except Exception as ex:

    print("** Exception: %s" % str(ex))

def RemoveZoneMembers( self, members: list, delay: int = 3) -> bosesoundtouchapi.soundtouchmessage.SoundTouchMessage:

Removes the given zone members from the device's zone.

Arguments:
  • members (list): A list of ZoneMember objects to remove from the master zone.
  • delay (int): Time delay (in seconds) to wait AFTER removing zone members. This delay will give the device time to process the change before another command is accepted.
    Default is 3; value range is 0 - 10.
Raises:
  • SoundTouchError: Master zone status could not be retrieved.
    Master zone does not exist; zone members cannot be removed.
    Members argument was not supplied, or has no members.
    Members argument contained a list item that is not of type ZoneMember.

Note that the master zone itself is also removed if there are no zone members left after the remove request is complete. In this case, you will need to reissue a call to the CreateZone() method to re-create the master zone.

The SoundTouch device does not return errors if a zone member device id does not exist; it simply ignores the invalid member entry and moves on to the next.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # build list of zone members to remove.
    zoneMembers:list = []
    zoneMembers.append(ZoneMember("192.168.1.130", "E8EB11B9B723"))

    # get current zone configuration status.
    zoneBefore:Zone = client.GetZoneStatus()
    print("\nCurrent Zone Status:\n%s" % zoneBefore.ToString(True))

    # if zone not active, then create one so that we have something to remove.
    if len(zoneBefore.Members) == 0:

        print("Creating a new master zone so we have a zone member to remove ...")

        # initialize the new master zone configuration.
        masterZone:Zone = Zone(client.Device.DeviceId, client.Device.Host, True) # <- master
        member:ZoneMember
        for member in zoneMembers:
            masterZone.AddMember(member)                                         # <- member

        # create a new master zone configuration on the device.
        client.CreateZone(masterZone)

        # get current zone configuration status.
        zoneBefore:Zone = client.GetZoneStatus()
        print("\nZone Status Before:\n%s" % zoneBefore.ToString(True))

    # remove zone members from the master zone configuration on the device.
    client.RemoveZoneMembers(zoneMembers)

    # get current zone configuration status.
    zoneAfter:Zone = client.GetZoneStatus()
    print("\nZone Status After:\n%s" % zoneAfter.ToString(True))

except Exception as ex:

    print("** Exception: %s" % str(ex))

def RestoreSnapshot(self, delay: int = 5) -> None:

Restores selected portions of the configuration from a snapshot that was previously taken with the StoreSnapshot method.

Arguments:
  • delay (int): Time delay (in seconds) to wait for the playing content to change.
    Default is 5 seconds.

The following settings will be restored from the snapshot dictionary by default:

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

No restore actions will be taken if snapshot settings do not exist.

You can restore your own custom settings from the snapshot dictionary; note that these custom settings are NOT restored by default.

You may remove default items from the snapshot dictionary prior to calling the RestoreSnapshot method. Let's say you did not want to restore the volume level - simply remove the volume item from the snapshot dictionary. See the sample code below for an example.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current settings that will be restored by the snapshot.
    print("** Settings before StoreSnapshot ... **")
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("Now Playing: '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))
    volume:Volume = client.GetVolume(True)
    print("Volume     : %s" % (volume.ToString()))

    # store current settings to snapshot.
    print("\n** Storing Snapshot ... **")
    client.StoreSnapshot()
    print("\n** Snapshot stored **\n")

    # select a different source.
    print("Changing Source ...")
    client.SelectSource(SoundTouchSources.BLUETOOTH)

    # change the volume level.
    print("Changing Volume to 30 ...")
    client.SetVolumeLevel(30)

    # mute the device.
    print("Changing Mute to On ...")
    client.mute_on()

    # get current settings before the snapshot restore.
    print("\n** Settings before RestoreSnapshot ... **")
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("Now Playing: '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))
    volume:Volume = client.GetVolume(True)
    print("Volume     : %s" % (volume.ToString()))

    # if you don't want to restore a configuration, then simply delete 
    # it from the snapshot dictionary, like so:
    # if SoundTouchNodes.volume.Path in client.SnapshotSettings:
    #     client.SnapshotSettings.pop(SoundTouchNodes.volume.Path)

    # restore settings from snapshot.
    print("\n** Restoring Snapshot ... **")
    client.RestoreSnapshot()

    # get current settings after the snapshot restore.
    print("\n** Settings after RestoreSnapshot (should match settings before StoreSnapshot) ... **")
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("Now Playing: '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))
    volume:Volume = client.GetVolume(True)
    print("Volume     : %s" % (volume.ToString()))

except Exception as ex:

    print("** Exception: %s" % str(ex))

Selects the given ContentItem.

Arguments:
  • item (ContentItem): Content item to select.
  • delay (int): Time delay (in seconds) to wait AFTER selecting the content item.
    This delay will give the device time to process the change before another command is accepted.
    Default is 5; value range is 0 - 10.

Note that playing of "https://" content is not supported by SoundTouch devices.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current nowPlaying status.
    nowPlayingBefore:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("\n** Current Now Playing Status:\n%s" % nowPlayingBefore.ToString())

    # create various content items to play.
    contentRadio01:ContentItem = ContentItem("TUNEIN","stationurl","/v1/playback/station/s249983","",True,"Christian Hits")
    contentRadio02:ContentItem = ContentItem("TUNEIN","stationurl","/v1/playback/station/s309605","",True,"K-LOVE 90s")

    # ensure the now playing changes.
    selection:ContentItem = contentRadio01
    if nowPlayingBefore.ContentItem != None:
        if nowPlayingBefore.ContentItem.Location == contentRadio01.Location:
            selection = contentRadio02

    # selects the specified content item.
    print("\n** Playing content item: %s - %s ..." % (selection.Name, selection.Location))
    client.SelectContentItem(selection)

    # create various content items to play.
    selections:list = []
    selections.append(ContentItem("TUNEIN","stationurl","/v1/playback/station/s249983",None,True,"Christian Hits"))
    selections.append(ContentItem("UPNP",None,"http://192.168.1.186:8123/api/tts_proxy/c96b99f3a949febd2a1f680e3b6dc4f01eb67e68_en_-_google_translate.mp3","UPnPUserName",True))
    selections.append(ContentItem("LOCAL_INTERNET_RADIO","stationurl","https://content.api.bose.io/core02/svc-bmx-adapter-orion/prod/orion/station?data=eyJuYW1lIjoiSm1uIDgwOTYiLCJpbWFnZVVybCI6IiIsInN0cmVhbVVybCI6Imh0dHA6Ly9qbThuLi5jb20vODA5Ni9zdHJlYW0ifQ%3D%3D",None,True,"Jmn 8096"))
    selections.append(ContentItem("TUNEIN","stationurl","/v1/playback/station/s309605",None,True,"K-LOVE 90s"))

    # play them all
    selection:ContentItem
    for selection in selections:
        print("\n** Playing content item: %s - %s ..." % (selection.Name, selection.Location))
        client.SelectContentItem(selection, 10)

    print("\n** Restoring original source ...")

    # play original source (if one was selected).
    if nowPlayingBefore.ContentItem.Source != "STANDBY":
        client.SelectContentItem(nowPlayingBefore.ContentItem)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("\n** Updated Now Playing Status:\n%s" % nowPlaying.ToString())

except Exception as ex:

    print("** Exception: %s" % str(ex))

Selects the given preset.

Arguments:
  • item (Preset): Preset item to select.
  • delay (int): Time delay (in seconds) to wait AFTER selecting the preset. This delay will give the device time to process the change before another command is accepted.
    Default is 5; value range is 0 - 10.
Raises:
  • SoundTouchError: Preset argument was not supplied.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    print("Getting list of presets ...")

    # get list of defined presets.
    presetList:PresetList = client.GetPresetList()
    print(presetList.ToString(True))

    preset:Preset
    for preset in presetList:

        print("\nSelecting Preset: '%s' - %s" % (preset.Name, preset.Location))

        # select a preset, and delay 10 seconds after for the device to process the change.
        client.SelectPreset(preset, 10)

        # get current nowPlaying status.
        nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
        print("\nNow Playing: '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))

except Exception as ex:

    print("** Exception: %s" % str(ex))

def SelectPreset1(self, delay: int = 3) -> None:

Mirrors the press and release of the PRESET1 key on the SoundTouch remote.

Arguments:
  • delay (int): Time delay (in seconds) to wait AFTER selecting the preset. This delay will give the device time to process the change before another command is accepted.
    Default is 3; value range is 0 - 10.

This method does nothing if there is no preset at the specified preset index.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("\nCurrent Now Playing Status:\n%s" % nowPlaying.ToString())

    # select the preset, and delay 3 seconds after for the device to process the change.
    client.SelectPreset1(3)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("\nUpdated Now Playing Status:\n%s" % nowPlaying.ToString())

except Exception as ex:

    print("** Exception: %s" % str(ex))

def SelectPreset2(self, delay: int = 3) -> None:

Mirrors the press and release of the PRESET2 key on the SoundTouch remote.

Arguments:
  • delay (int): Time delay (in seconds) to wait AFTER selecting the preset. This delay will give the device time to process the change before another command is accepted.
    Default is 3; value range is 0 - 10.

This method does nothing if there is no preset at the specified preset index.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("\nCurrent Now Playing Status:\n%s" % nowPlaying.ToString())

    # select the preset, and delay 3 seconds after for the device to process the change.
    client.SelectPreset2(3)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("\nUpdated Now Playing Status:\n%s" % nowPlaying.ToString())

except Exception as ex:

    print("** Exception: %s" % str(ex))

def SelectPreset3(self, delay: int = 3) -> None:

Mirrors the press and release of the PRESET3 key on the SoundTouch remote.

Arguments:
  • delay (int): Time delay (in seconds) to wait AFTER selecting the preset. This delay will give the device time to process the change before another command is accepted.
    Default is 3; value range is 0 - 10.

This method does nothing if there is no preset at the specified preset index.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("\nCurrent Now Playing Status:\n%s" % nowPlaying.ToString())

    # select the preset, and delay 3 seconds after for the device to process the change.
    client.SelectPreset3(3)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("\nUpdated Now Playing Status:\n%s" % nowPlaying.ToString())

except Exception as ex:

    print("** Exception: %s" % str(ex))

def SelectPreset4(self, delay: int = 3) -> None:

Mirrors the press and release of the PRESET4 key on the SoundTouch remote.

Arguments:
  • delay (int): Time delay (in seconds) to wait AFTER selecting the preset. This delay will give the device time to process the change before another command is accepted.
    Default is 3; value range is 0 - 10.

This method does nothing if there is no preset at the specified preset index.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("\nCurrent Now Playing Status:\n%s" % nowPlaying.ToString())

    # select the preset, and delay 3 seconds after for the device to process the change.
    client.SelectPreset4(3)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("\nUpdated Now Playing Status:\n%s" % nowPlaying.ToString())

except Exception as ex:

    print("** Exception: %s" % str(ex))

def SelectPreset5(self, delay: int = 3) -> None:

Mirrors the press and release of the PRESET5 key on the SoundTouch remote.

Arguments:
  • delay (int): Time delay (in seconds) to wait AFTER selecting the preset. This delay will give the device time to process the change before another command is accepted.
    Default is 3; value range is 0 - 10.

This method does nothing if there is no preset at the specified preset index.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("\nCurrent Now Playing Status:\n%s" % nowPlaying.ToString())

    # select the preset, and delay 3 seconds after for the device to process the change.
    client.SelectPreset5(3)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("\nUpdated Now Playing Status:\n%s" % nowPlaying.ToString())

except Exception as ex:

    print("** Exception: %s" % str(ex))

def SelectPreset6(self, delay: int = 3) -> None:

Mirrors the press and release of the PRESET6 key on the SoundTouch remote.

Arguments:
  • delay (int): Time delay (in seconds) to wait AFTER selecting the preset. This delay will give the device time to process the change before another command is accepted.
    Default is 3; value range is 0 - 10.

This method does nothing if there is no preset at the specified preset index.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("\nCurrent Now Playing Status:\n%s" % nowPlaying.ToString())

    # select the preset, and delay 3 seconds after for the device to process the change.
    client.SelectPreset6(3)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("\nUpdated Now Playing Status:\n%s" % nowPlaying.ToString())

except Exception as ex:

    print("** Exception: %s" % str(ex))

Selects the given recent.

Arguments:
  • item (Recent): Recent item to select.
  • delay (int): Time delay (in seconds) to wait AFTER selecting the recent. This delay will give the device time to process the change before another command is accepted.
    Default is 5; value range is 0 - 10.
Raises:
  • SoundTouchError: Recent argument was not supplied.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    print("Getting list of recents ...")

    # get list of defined recents.
    recents:RecentList = client.GetRecentList()
    print(recents.ToString(True))

    # process list.
    recent:Recent = None
    for i, recent in list(enumerate(recents)):

        print("\nSelecting Recent: '%s' - %s" % (recent.Name, recent.Location))

        # select a recent, and delay 10 seconds after for the device to process the change.
        client.SelectRecent(recent, 10)

        # get current nowPlaying status.
        nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
        print("\nNow Playing: '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))

        # only process a few of the recent entries, as there could be a lot.
        if i >= 2:
            break

except Exception as ex:

    print("** Exception: %s" % str(ex))

def SelectSource( self, source: bosesoundtouchapi.soundtouchsources.SoundTouchSources, sourceAccount: str = None, delay: int = 3) -> bosesoundtouchapi.soundtouchmessage.SoundTouchMessage:

Selects a new input source.

Arguments:
  • source (SoundTouchSources | str): Input source value; this can either be a SoundTouchSources enum value or a string. If specifying a string value, then it should be in upper-case.
  • sourceAccount (str): Source account value; some sources require one when changing the input source (e.g. "AUX").
  • delay (int): time delay (in seconds) to wait AFTER selecting the source. This delay will give the SoundTouch device time to process the change before another command is accepted. default is 3 seconds, and value range is 0 - 10.
Returns:

A SoundTouchMessage response that indicates success or failure of the command.

Raises:
  • SoundTouchError: Source argument was not supplied.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current nowPlaying status.
    nowPlayingBefore:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("\n** Current Now Playing Status:\n%s" % nowPlayingBefore.ToString())

    # get list of source items.
    sources:SourceList = client.GetSourceList()

    print("\n** Sources supported by the device:\n%s" % sources.ToString(True))
    print("\n** Selecting Sources one-by-one ...")

    # select each source.
    sourceItem:SourceItem
    for sourceItem in sources:

        # trace.
        print("- Source='%s', SourceAccount='%s' ..." % (sourceItem.Source, sourceItem.SourceAccount))

        # select an input source.
        msg:SoundTouchMessage = client.SelectSource(sourceItem.Source, sourceItem.SourceAccount)

    print("\n** Restoring original source ...")

    # play original source (if one was selected).
    if nowPlayingBefore.ContentItem.Source != "STANDBY":
        client.SelectContentItem(nowPlayingBefore.ContentItem)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("\n** Updated Now Playing Status:\n%s" % nowPlaying.ToString())

except Exception as ex:

    print("** Exception: %s" % str(ex))

def SetBassLevel( self, level: int) -> bosesoundtouchapi.soundtouchmessage.SoundTouchMessage:

Sets the device bass level to the given level.

Arguments:
  • level (int): Bass level to set, in the range of -9 (no bass) to 0 (full bass). The range can vary by device; use GetBassCapabilities() method to retrieve the allowable range for your device.

Sets a new device name.

Sample Code

from bosesoundtouchapi import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    print("Name Before: '%s'" % client.Device.DeviceName)

    # set the device name.
    client.SetName('My SoundTouch 10')

    print("Name After:  '%s'" % client.Device.DeviceName)

except Exception as ex:

    print("** Exception: %s" % str(ex))

def SetVolumeLevel( self, level: int) -> bosesoundtouchapi.soundtouchmessage.SoundTouchMessage:

Sets the device volume level to the given level.

Arguments:
  • level (int): Volume level to set, in the range of 0 (mute) to 100 (full volume).

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current volume level.
    volumeBefore:Volume = client.GetVolume(True)
    print("\nCurrent Volume Levels: %s" % (volumeBefore.ToString()))

    # for testing purposes, use a volume of 30.  if the volume is currently at 30,
    # then we will use a volume of 25.
    newLevel:int = 30
    if volumeBefore.Actual == newLevel:
        newLevel = 25
    print("\nSetting Volume level to %d (from %s) ..." % (newLevel, volumeBefore.Actual))

    # set volume to specific level.
    client.SetVolumeLevel(newLevel)

    # get current volume level.
    volumeAfter:Volume = client.GetVolume(True)
    print("\nChanged Volume Levels: %s" % (volumeAfter.ToString()))

except Exception as ex:

    print("** Exception: %s" % str(ex))

Stores the given Preset to the device's list of presets.

Arguments:
  • item (Preset): The Preset object to store.
Returns:

A message object that may contain more information about the result.

Raises:
  • Exception: If the command fails for any reason.

Most SoundTouch devices can only store 6 presets in their internal memory. The Preset.preset_id property controls what slot the stored preset gets placed in. If a preset already exists in a slot, then it is over-written with the newly stored preset. If a preset with the same details exists in another slot, then the duplicate preset is removed and its slot is emptied.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *
import time

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # create a new preset - radio station.
    new_preset_radio:Preset = Preset(
        4,
        time.time(),
        None,
        "TUNEIN",
        "stationurl",
        "/v1/playback/station/s309605",
        "",
        True,
        "My New Preset",
        "http://cdn-profiles.tunein.com/s309605/images/logog.png?t=637986891960000000"
        )

    print("Storing Preset: '%s' - %s" % (new_preset_radio.Name, new_preset_radio.Location))

    # store preset.
    client.StorePreset(new_preset_radio)

    # get list of defined presets.
    presetList:PresetList = client.GetPresetList()
    print(presetList.ToString(True))

except Exception as ex:

    print("** Exception: %s" % str(ex))

def StoreSnapshot(self) -> None:

Stores selected portions of the configuration so that they can be easily restored with the RestoreSnapshot method.

The following settings will be stored to the snapshot dictionary by default:

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

The SnapshotSettings dictionary is cleared prior to storing any settings.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current settings that will be restored by the snapshot.
    print("** Settings before StoreSnapshot ... **")
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("Now Playing: '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))
    volume:Volume = client.GetVolume(True)
    print("Volume     : %s" % (volume.ToString()))

    # store current settings to snapshot.
    print("\n** Storing Snapshot ... **")
    client.StoreSnapshot()
    print("\n** Snapshot stored **\n")

    # select a different source.
    print("Changing Source ...")
    client.SelectSource(SoundTouchSources.BLUETOOTH)

    # change the volume level.
    print("Changing Volume to 30 ...")
    client.SetVolumeLevel(30)

    # mute the device.
    print("Changing Mute to On ...")
    client.mute_on()

    # get current settings before the snapshot restore.
    print("\n** Settings before RestoreSnapshot ... **")
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("Now Playing: '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))
    volume:Volume = client.GetVolume(True)
    print("Volume     : %s" % (volume.ToString()))

    # if you don't want to restore a configuration, then simply delete 
    # it from the snapshot dictionary, like so:
    # if SoundTouchNodes.volume.Path in client.SnapshotSettings:
    #     client.SnapshotSettings.pop(SoundTouchNodes.volume.Path)

    # restore settings from snapshot.
    print("\n** Restoring Snapshot ... **")
    client.RestoreSnapshot()

    # get current settings after the snapshot restore.
    print("\n** Settings after RestoreSnapshot (should match settings before StoreSnapshot) ... **")
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("Now Playing: '%s' - '%s'" % (nowPlaying.ContentItem.Name, nowPlaying.ContentItem.Location))
    volume:Volume = client.GetVolume(True)
    print("Volume     : %s" % (volume.ToString()))

except Exception as ex:

    print("** Exception: %s" % str(ex))

def ThumbsDown(self) -> None:

Removes the currently playing media from the device favorites.

This will first make a call to GetNowPlayingStatus() method to ensure favorites are enabled for the now playing media. If not enabled, then the request is ignored and no exception is raised.

The THUMBS_DOWN key appears to do the same thing as the REMOVE_FAVORITE key, but it's included here for completeness.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("\nCurrent Now Playing Status:\n%s" % nowPlaying.ToString())

    # does nowPlaying item support favorites?
    if nowPlaying.IsFavoriteEnabled:

        # remove the currently playing media from the device favorites.
        client.ThumbsDown()

        # give the device time to process the change.
        time.sleep(1)

        # get current nowPlaying status.
        nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
        print("\nUpdated Now Playing Status:\n%s" % nowPlaying.ToString())

    else:

        print("\nFavorites not enabled for currently playing media")

except Exception as ex:

    print("** Exception: %s" % str(ex))

def ThumbsUp(self) -> None:

Adds the currently playing media to the device favorites.

This will first make a call to GetNowPlayingStatus() method to ensure favorites are enabled for the now playing media. If not enabled, then the request is ignored and no exception is raised.

The THUMBS_UP key appears to do the same thing as the ADD_FAVORITE key, but it's included here for completeness.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get current nowPlaying status.
    nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
    print("\nCurrent Now Playing Status:\n%s" % nowPlaying.ToString())

    # does nowPlaying item support favorites?
    if nowPlaying.IsFavoriteEnabled:

        # add the currently playing media to the device favorites.
        client.ThumbsUp()

        # give the device time to process the change.
        time.sleep(1)

        # get current nowPlaying status.
        nowPlaying:NowPlayingStatus = client.GetNowPlayingStatus(True)
        print("\nUpdated Now Playing Status:\n%s" % nowPlaying.ToString())

    else:

        print("\nFavorites not enabled for currently playing media")

except Exception as ex:

    print("** Exception: %s" % str(ex))

def ToString(self) -> str:

Returns a displayable string representation of the class.

def VolumeDown(self) -> None:

Decrease the volume of the device by one.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get real-time configuration from the device.
    volume:Volume = client.GetVolume()
    print("(before) %s" % volume.ToString())

    # tick volume down one notch.
    client.VolumeDown()

    # get real-time configuration from the device.
    volume:Volume = client.GetVolume()
    print("(after)  %s" % volume.ToString())

except Exception as ex:

    print("** Exception: %s" % str(ex))

def VolumeUp(self) -> None:

Increase the volume of the device by one.

Sample Code

from bosesoundtouchapi import *
from bosesoundtouchapi.models import *

try:

    # create SoundTouch device instance.
    device:SoundTouchDevice = SoundTouchDevice("192.168.1.131") # Bose SoundTouch 10

    # create SoundTouch client instance from device.
    client:SoundTouchClient = SoundTouchClient(device)

    # get real-time configuration from the device.
    volume:Volume = client.GetVolume()
    print("(before) %s" % volume.ToString())

    # tick volume up one notch.
    client.VolumeUp()

    # get real-time configuration from the device.
    volume:Volume = client.GetVolume()
    print("(after)  %s" % volume.ToString())

except Exception as ex:

    print("** Exception: %s" % str(ex))