bosesoundtouchapi.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>]
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.
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.
Sets the request PoolManager object to use for http requests to the device.
Returns:
The `_Manager' property value.
A dictionary of configuration objects that are used by the Snapshot processing methods.
This property is read-only.
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))
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 typeZoneMember
.
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))
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.
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))
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 theToXmlRequestBody
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))
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))
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))
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))
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))
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 typeZoneMember
.
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))
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))