bosesoundtouchapi.soundtouchwebsocket

@export
class SoundTouchWebSocket:

A wrapper class to use the notification system provided by SoundTouch devices.

In order to react to a message, there is a listener system. You can add functions as listener objects. The connection url is defined as follows: 'ws://{Host}:{Port}/'. Port 8080 is used by default.

This class can be used in two ways. First, the object can open a connection through the StartNotification method and secondly, the with-statement can be used to create an instance.

You must first check the device capabilities prior to using the support notifications functionality; if the device does not support it, then it's not going to work! To do this, fetch the device's capabilities and check for a IsWebSocketApiProxyCapable = True value. If true, then the device supports sending notifications; if false, it does not.

For more information and code samples refer to bosesoundtouchapi.soundtouchclient.GetCapabilities method.

Sample Code

# external package imports.
import time
from xml.etree.ElementTree import Element
from xml.etree import ElementTree

# our package imports.
from bosesoundtouchapi import *
from bosesoundtouchapi.models import Capabilities


class EventHandlerClass:

    def OnSoundTouchUpdateEvent(args:Element) -> None:
        if (args != None):
            ElementTree.indent(args)  # for pretty printing
            argsEncoded = ElementTree.tostring(args, encoding="unicode")
            print("\nStatus update args:\n%s" %  argsEncoded)


    def OnSoundTouchInfoEvent(args:Element) -> None:
        if (args != None):
            ElementTree.indent(args)  # for pretty printing
            argsEncoded = ElementTree.tostring(args, encoding="unicode")
            print("\nStatus info args:\n%s" % argsEncoded)

try:

    socket:SoundTouchWebSocket = None

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

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

    # get device capabilities - must have IsWebSocketApiProxyCapable=True 
    # in order to support notifications.
    capabilities:Capabilities = client.GetCapabilities()
    if capabilities.IsWebSocketApiProxyCapable:

        # create and start a websocket to receive notifications from the device.
        socket = SoundTouchWebSocket(client.Device)

        # add our listener(s) that will handle SoundTouch device status updates.
        #socket.AddListener(SoundTouchNotifyCategorys.ALL, EventHandlerClass.OnSoundTouchUpdateEvent)
        socket.AddListener(SoundTouchNotifyCategorys.connectionStateUpdated, EventHandlerClass.OnSoundTouchUpdateEvent)
        socket.AddListener(SoundTouchNotifyCategorys.criticalErrorUpdate, EventHandlerClass.OnSoundTouchUpdateEvent)
        socket.AddListener(SoundTouchNotifyCategorys.errorNotification, EventHandlerClass.OnSoundTouchUpdateEvent)
        socket.AddListener(SoundTouchNotifyCategorys.errorUpdate, EventHandlerClass.OnSoundTouchUpdateEvent)
        socket.AddListener(SoundTouchNotifyCategorys.groupUpdated, EventHandlerClass.OnSoundTouchUpdateEvent)
        socket.AddListener(SoundTouchNotifyCategorys.languageUpdated, EventHandlerClass.OnSoundTouchUpdateEvent)
        socket.AddListener(SoundTouchNotifyCategorys.LowPowerStandbyUpdate, EventHandlerClass.OnSoundTouchUpdateEvent)
        socket.AddListener(SoundTouchNotifyCategorys.nameUpdated, EventHandlerClass.OnSoundTouchUpdateEvent)
        socket.AddListener(SoundTouchNotifyCategorys.nowPlayingUpdated, EventHandlerClass.OnSoundTouchUpdateEvent)
        socket.AddListener(SoundTouchNotifyCategorys.nowSelectionUpdated, EventHandlerClass.OnSoundTouchUpdateEvent)
        socket.AddListener(SoundTouchNotifyCategorys.presetsUpdated, EventHandlerClass.OnSoundTouchUpdateEvent)
        socket.AddListener(SoundTouchNotifyCategorys.recentsUpdated, EventHandlerClass.OnSoundTouchUpdateEvent)
        socket.AddListener(SoundTouchNotifyCategorys.soundTouchConfigurationUpdated, EventHandlerClass.OnSoundTouchUpdateEvent)
        socket.AddListener(SoundTouchNotifyCategorys.sourcesUpdated, EventHandlerClass.OnSoundTouchUpdateEvent)
        socket.AddListener(SoundTouchNotifyCategorys.swUpdateStatusUpdated, EventHandlerClass.OnSoundTouchUpdateEvent)
        socket.AddListener(SoundTouchNotifyCategorys.volumeUpdated, EventHandlerClass.OnSoundTouchUpdateEvent)
        socket.AddListener(SoundTouchNotifyCategorys.zoneUpdated, EventHandlerClass.OnSoundTouchUpdateEvent)

        # add our listener(s) that will handle SoundTouch device informational events.
        socket.AddListener(SoundTouchNotifyCategorys.SoundTouchSdkInfo, EventHandlerClass.OnSoundTouchInfoEvent)
        socket.AddListener(SoundTouchNotifyCategorys.userActivityUpdate, EventHandlerClass.OnSoundTouchInfoEvent)

        # start receiving updates.
        socket.StartNotification()

        print("** Notification event loop has started.")
        print("** Try pressing some buttons on your SoundTouch remote or device ...")

        # for testing status notifications.
        maxcnt:int = 1200  # 1200=20 mins, 300=5 mins
        for i in range(maxcnt):

            # wait 1 second.
            time.sleep(1)

    else:

        print("SoundTouch device '%s' does not support Bose WebSocket API.")

except Exception as ex:

    print(str(ex))
    raise

finally:

    # stop listening for Bose SoundTouch status updates.
    if (socket != None):
        socket.StopNotification()

SoundTouchWebSocket( device: bosesoundtouchapi.soundtouchdevice.SoundTouchDevice, port: int = 8080)

Initializes a new instance of the class.

Arguments:
  • device (SoundTouchDevice): A SoundTouchDevice instance containing the host ip-address.
  • port (int): The port the Bose WebAPI socket is posting notifications on.
    Default is 8080.

A SoundTouchDevice instance containing the host ip-address.

def AddListener( self, category: bosesoundtouchapi.soundtouchnotifycategorys.SoundTouchNotifyCategorys, listener) -> bool:

Adds a listener provided here to the given category.

Since there are different types of events, the category-string can be used to add a listener to a specific notification category. The listener must take only one argument: xml.etree.ElementTree.Element.

Arguments:
  • category (SoundTouchNotifyCategorys): The category this listener should be added to.
    Use one of the pre-defined SoundTouchNotifyCategorys values to receive updates for that category (e.g. "volumeUpdated", "nowPlayingUpdated", etc). Use SoundTouchNotifyCategorys.Error to receive notifications for WebSocket errors.
    Use SoundTouchNotifyCategorys.ALL to receive notifications for any type of update event.
  • listener (object): A simple listener method which takes the XML-Element as a passed argument.
Returns:

True if the listener was added successfully; otherwise, False.

Please refer to the bosesoundtouchapi.soundtouchnotifycategories.SoundTouchNotifyCategorys class for more details on what events are raised and why / when they happen.

def GetListenerGroup(self, category: str) -> list:

Searches for a specific category in the registered ones.

This method is a convenient method to return all listeners that were added to a specific context.

Arguments:
  • category (str): The category, which has to be one of the SoundTouchNotifyCategorys values.
Returns:

A list containing all listeners linked to the given category.

def NotifyListeners(self, category: str, event: xml.etree.ElementTree.Element) -> None:

Notifies all listeners that were stored in the given context.

The name of each context is defined to be the tag element of the update XML-Element.

Arguments:
  • category (str): The category of which listeners should be notified from.
  • event (xmltree.Element): The event represents an XML-Element with event.tag == category.
def RemoveListener( self, category: bosesoundtouchapi.soundtouchnotifycategorys.SoundTouchNotifyCategorys, listener) -> bool:

Removes a listener from the given category.

Arguments:
  • category (str): The category this listener should be removed from.
    Use one of the pre-defined SoundTouchNotifyCategorys values to receive updates for that category (e.g. "volumeUpdated", "nowPlayingUpdated", etc).
  • listener (object): A simple listener method which takes the XML-Element as a passed argument.
Returns:

True if the listener was removed successfully; otherwise, False.

def StartNotification(self) -> None:

Creates and starts a web socket event loop thread that listens for notifications from the SoundTouch device.

Only one web socket event loop thread will be started for the device.

def StopNotification(self) -> None:

Stops the web socket event loop thread, if one was previously started using the StartNotification method.

This method does nothing if the event loop thread was not started.