spotifywebapiPython 1.0.242__py3-none-any.whl

spotifywebapipython/spotifyconnect/spotifyconnectzeroconfcastlistener.py

@@ -0,0 +1,359 @@
+# external package imports.
+from pychromecast import CastInfo, HostServiceInfo
+from pychromecast.discovery import AbstractCastListener
+import threading
+from uuid import UUID
+
+# our package imports.
+from spotifywebapipython.models import ZeroconfProperty, ZeroconfDiscoveryResult
+# note - cannot reference `SpotifyConnectDirectoryTask` due to circular import!
+# from .spotifyconnectdirectorytask import SpotifyConnectDirectoryTask
+
+# get smartinspect logger reference; create a new session for this module name.
+from smartinspectpython.siauto import SIAuto, SILevel, SISession, SIMethodParmListContext, SIColors
+import logging
+
+_logsi:SISession = SIAuto.Si.GetSession(__name__)
+if (_logsi == None):
+    _logsi = SIAuto.Si.AddSession(__name__, True)
+_logsi.SystemLogger = logging.getLogger(__name__)
+
+ZEROCONF_SERVICETYPE_GOOGLECAST:str = "_googlecast._tcp.local."
+"""
+Googlecast Zeroconf service type identifier (e.g. "_googlecast._tcp.local.").
+"""
+
+# chromecast types supported.
+CAST_TYPE_CHROMECAST = "cast"
+""" Regular chromecast, supports video/audio """
+CAST_TYPE_AUDIO = "audio"
+""" Cast Audio device, supports only audio """
+CAST_TYPE_GROUP = "group" 
+""" Cast Audio group device, supports only audio """
+CAST_TYPE_NONE = None
+""" cast_type not set; assume it supports audio """
+
+
+class SpotifyConnectZeroconfCastListener(AbstractCastListener):
+    """
+    Google Chromecast Zeroconf Listener class.
+    
+    Listens for Chromecast device connection updates for devices that
+    support Spotify Connect.
+    """
+
+    def __init__(
+        self, 
+        parentDirectory,
+        zeroconf_RLock:threading.RLock,
+        ) -> None:
+        """
+        Initializes a new instance of the class.
+
+        Args:
+            parentDirectory (SpotifyConnectDirectoryTask):
+                Parent SpotifyConnectDirectoryTask instance.
+            zeroconf_RLock (threading.RLock):
+                Lock object used to enforce thread-safe updates.
+        """
+        # invoke base class method.
+        super().__init__()
+
+        # initialize storage.
+        self._ParentDirectory = parentDirectory
+        self._Zeroconf_RLock:threading.RLock = zeroconf_RLock
+
+
+    def _GetZeroconfDiscoveryResult(
+        self,
+        uuid:UUID, 
+        serviceName:str,
+        castInfo_removed:CastInfo = None
+        ) -> ZeroconfDiscoveryResult:
+        """
+        Builds a `ZeroconfDiscoveryResult` instance from Zeroconf CastInfo data
+        when an add or update service state change takes place.
+
+        Args:
+            uuid (UUID):
+                The cast's uuid, which is the dictionary key to find the chromecast 
+                metadata in CastBrowser.devices collection.
+            serviceName (str):
+                First known MDNS service name or host:port.
+            castInfo_removed (CastInfo):
+                CastInfo for the service to aid cleanup; only supplied for removal
+                requests since the CastBrowser.services collection no longer contains
+                a CastInfo object for the specified uuid.
+        """
+        result:ZeroconfDiscoveryResult = None
+        castInfoHost:str = None
+        castInfoPort:int = 0
+
+        try:
+
+            # is this an MDNSServiceInfo service record?  we only want discovery results
+            # that contain MDNSServiceInfo service information.
+            if (serviceName.find(ZEROCONF_SERVICETYPE_GOOGLECAST) == -1):
+                _logsi.LogDebug("Chromecast Zeroconf discovery service notification: \"%s\" (%s)" % (serviceName, "ignored; not MDNSInfo"))
+                return None
+
+            # get chromecast info.
+            castInfo:CastInfo = castInfo_removed
+            if (castInfo is None):
+
+                # map the CastInfo object.
+                castInfo:CastInfo = self._ParentDirectory._CastBrowser.services[uuid]
+                castInfoHost = castInfo.host
+                castInfoPort = castInfo.port
+
+                # 20250628 commented out the ipv6 address resolution code.
+                # the `get_multizone_status` (in directorytask) could possibly return ipv6 info, with no ipv4 data!
+
+                # # find ipv4 host and port number.
+                # # if the base CastInfo object is ipv6, then find the ipv4 HostServiceInfo
+                # # service record and get it from there.
+                # if ((castInfoHost + "").find(":") != -1):
+
+                #     # cast info host information is ipv6!
+                #     # find the ipv4 host service info object.
+                #     _logsi.LogDebug("Chromecast Zeroconf discovery service notification contained IPV6 HostServiceInfo data: \"%s\" (%s)" % (serviceName, "searching for IPV4 info"), colorValue=SIColors.Coral)
+                #     castHostIpv4:HostServiceInfo = None
+                #     for castSvc in castInfo.services:
+                #         if (isinstance(castSvc, HostServiceInfo)):
+                #             if ((castSvc.host + "").find(":") == -1):
+                #                 castInfoHost = castSvc.host
+                #                 castInfoPort = castSvc.port
+                #                 castHostIpv4 = castSvc
+                #                 break
+
+                #     # if ipv4 host service info not found then we are done, as Spotify Connect 
+                #     # zeroconf requires an IPV4 address structure.
+                #     if (castHostIpv4 is None):
+                #         _logsi.LogDebug("Chromecast Zeroconf discovery service notification did not contain IPV4 HostServiceInfo service entry: \"%s\" (%s)" % (serviceName, "IPV6 HostServiceInfo may fail"), colorValue=SIColors.Coral)
+
+            else:
+
+                # set host and port number for remove request.
+                castInfoHost = castInfo.host
+                castInfoPort = castInfo.port
+
+            # trace.
+            _logsi.LogObject(SILevel.Debug, "Chromecast Zeroconf service details: \"%s\" (%s) (CastInfo object)" % (castInfo.friendly_name, serviceName), castInfo) 
+
+            # only certain cast_type values support Spotify Connect.
+            castType:str = castInfo.cast_type
+            if (not (castType in [CAST_TYPE_AUDIO, CAST_TYPE_GROUP, CAST_TYPE_CHROMECAST, CAST_TYPE_NONE])):
+                _logsi.LogDebug("Chromecast device cast_type of \"%s\" is not supported; ignoring: \"%s\" (%s)" % (castType, castInfo.friendly_name, serviceName), colorValue=SIColors.Coral)
+                return None
+            
+            # create new discovery result instance.
+            result:ZeroconfDiscoveryResult = ZeroconfDiscoveryResult()
+            result.DeviceName = castInfo.friendly_name
+            result.Domain = ".local"
+            result.HostIpAddresses = [castInfoHost]
+            result.HostIpPort = castInfoPort
+            result.HostTTL = 120
+            result.IsChromeCast = True
+            result.Key = str(uuid)
+            result.Name = serviceName
+            result.Priority = 0
+            result.OtherTTL = 4500
+            result.Server = serviceName
+            result.ServerKey = serviceName
+            result.ServiceType = ZEROCONF_SERVICETYPE_GOOGLECAST
+            result.Weight = 0
+            result.Properties.append(ZeroconfProperty("CPath", "/na"))
+            result.Properties.append(ZeroconfProperty("VERSION", "1.0"))
+            result.Properties.append(ZeroconfProperty("cast_type", castType))
+            result.SpotifyConnectCPath = "/na"
+            result.SpotifyConnectVersion = "1.0"
+            result.Id = "\"%s\" (%s:%s)" % (result.DeviceName, result.HostIpAddress, result.HostIpPort)
+
+            # trace.
+            _logsi.LogObject(SILevel.Debug, "Chromecast Zeroconf Discovery Result: %s (object)" % (result.Id), result, excludeNonPublic=True)                        
+
+            # return discovery result.
+            return result
+
+        except Exception as ex:
+            
+            # trace.
+            _logsi.LogException("Could not load ZeroconfDiscoveryResult instance from Chromecast Zeroconf service details", ex, logToSystemLogger=False)
+            
+            # ignore exception
+            return None
+            
+
+    def add_cast(
+        self, 
+        uuid:UUID, 
+        serviceName:str
+        ) -> None:
+        """
+        Called when a new cast has been discovered.
+
+        Args:
+            uuid (UUID):
+                The cast's uuid, which is the dictionary key to find the chromecast 
+                metadata in CastBrowser.devices collection.
+            serviceName (str):
+                First known MDNS service name or host:port.
+        """
+        # use lock, as multiple threads could be calling this method simultaneously.
+        with self._Zeroconf_RLock:
+
+            # copy passed parameters to thread-safe storage.
+            argsUuid:UUID = uuid
+            argsServiceName:str = serviceName
+                
+            apiMethodName:str = "add_cast"
+            apiMethodParms:SIMethodParmListContext = None
+
+            try:
+
+                # trace.
+                apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
+                apiMethodParms.AppendKeyValue("uuid", argsUuid)
+                apiMethodParms.AppendKeyValue("serviceName", argsServiceName)
+                _logsi.LogMethodParmList(SILevel.Debug, "Chromecast Zeroconf discovery service notification: \"%s\" (%s)" % (argsServiceName, apiMethodName), apiMethodParms)
+
+                # build discovery result instance from service state information.
+                # if nothing returned, then don't bother!
+                result:ZeroconfDiscoveryResult = self._GetZeroconfDiscoveryResult(argsUuid, argsServiceName, None)
+                if (result is None):
+                    return
+
+                # let the parent handle the event.
+                self._ParentDirectory.OnServiceInfoAddedUpdatedChromecast(result, argsUuid, argsServiceName, apiMethodName)
+
+            except Exception as ex:
+            
+                # trace.
+                _logsi.LogException("Unhandled exception occured while processing Chromecast Zeroconf service browser ServiceStateChange notification (%s)" % (apiMethodName), ex, logToSystemLogger=False)
+            
+                # ignore exception, as nothing can be done about it.
+
+            finally:
+
+                # trace.
+                _logsi.LeaveMethod(SILevel.Debug, apiMethodName)
+
+
+    def remove_cast(
+        self, 
+        uuid:UUID, 
+        serviceName:str, 
+        castInfo:CastInfo
+        ) -> None:
+        """
+        Called when a cast has been lost (MDNS info expired or host down).
+
+        Args:
+            uuid (UUID):
+                The cast's uuid, which is the dictionary key to find the chromecast 
+                metadata in CastBrowser.devices collection.
+            serviceName (str):
+                Last valid MDNS service name or host:port.
+            castInfo (CastInfo):
+                CastInfo for the service to aid cleanup.
+        """
+        # use lock, as multiple threads could be calling this method simultaneously.
+        with self._Zeroconf_RLock:
+                
+            # copy passed parameters to thread-safe storage.
+            argsUuid:UUID = uuid
+            argsServiceName:str = serviceName
+            argsCastInfo:CastInfo = castInfo
+                
+            apiMethodName:str = "remove_cast"
+            apiMethodParms:SIMethodParmListContext = None
+
+            try:
+
+                # trace.
+                apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
+                apiMethodParms.AppendKeyValue("uuid", argsUuid)
+                apiMethodParms.AppendKeyValue("serviceName", argsServiceName)
+                _logsi.LogMethodParmList(SILevel.Debug, "Chromecast Zeroconf discovery service notification: \"%s\" (%s)" % (argsServiceName, apiMethodName), apiMethodParms)
+
+                # for service removal notifications, there will be no zeroconf service info.
+                # build discovery result instance from service state information.
+                # if nothing returned, then it's ok - build a minimal discovery instance that
+                # will contain the necessary details to remove the device entry.
+                result:ZeroconfDiscoveryResult = self._GetZeroconfDiscoveryResult(argsUuid, argsServiceName, argsCastInfo)
+                if (result is None):
+                    result = ZeroconfDiscoveryResult()
+                    result.DeviceName = castInfo.friendly_name
+                    result.Key = str(uuid)
+                    result.Name = serviceName
+                    result.ServiceType = ZEROCONF_SERVICETYPE_GOOGLECAST
+
+                # let the parent handle the event.
+                self._ParentDirectory.OnServiceInfoRemovedChromecast(result, argsUuid, argsServiceName, argsCastInfo)
+
+            except Exception as ex:
+            
+                # trace.
+                _logsi.LogException("Unhandled exception occured while processing Chromecast Zeroconf service browser ServiceStateChange notification (%s)" % (apiMethodName), ex, logToSystemLogger=False)
+            
+                # ignore exception, as nothing can be done about it.
+
+            finally:
+
+                # trace.
+                _logsi.LeaveMethod(SILevel.Debug, apiMethodName)
+
+
+    def update_cast(
+        self, 
+        uuid:UUID, 
+        serviceName:str
+        ) -> None:
+        """
+        Called when a cast has been updated (MDNS info renewed or changed).
+
+        Args:
+            uuid (UUID):
+                The cast's uuid, which is the dictionary key to find the chromecast 
+                metadata in CastBrowser.devices collection.
+            serviceName (str):
+                MDNS service name or host:port.
+        """
+        # use lock, as multiple threads could be calling this method simultaneously.
+        with self._Zeroconf_RLock:
+                
+            # copy passed parameters to thread-safe storage.
+            argsUuid:UUID = uuid
+            argsServiceName:str = serviceName
+                
+            apiMethodName:str = "update_cast"
+            apiMethodParms:SIMethodParmListContext = None
+
+            try:
+
+                # trace.
+                apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
+                apiMethodParms.AppendKeyValue("uuid", argsUuid)
+                apiMethodParms.AppendKeyValue("serviceName", argsServiceName)
+                _logsi.LogMethodParmList(SILevel.Debug, "Chromecast Zeroconf discovery service notification: \"%s\" (%s)" % (serviceName, apiMethodName), apiMethodParms)
+
+                # build discovery result instance from service state information.
+                # if nothing returned, then don't bother!
+                result:ZeroconfDiscoveryResult = self._GetZeroconfDiscoveryResult(argsUuid, argsServiceName, None)
+                if (result is None):
+                    return
+
+                # let the parent handle the event.
+                self._ParentDirectory.OnServiceInfoAddedUpdatedChromecast(result, argsUuid, argsServiceName, apiMethodName)
+
+            except Exception as ex:
+            
+                # trace.
+                _logsi.LogException("Unhandled exception occured while processing Chromecast Zeroconf service browser ServiceStateChange notification (%s)" % (apiMethodName), ex, logToSystemLogger=False)
+            
+                # ignore exception, as nothing can be done about it.
+
+            finally:
+
+                # trace.
+                _logsi.LeaveMethod(SILevel.Debug, apiMethodName)

spotifywebapipython/spotifyconnect/spotifyconnectzeroconfcastmultizonelistener.py

@@ -0,0 +1,212 @@
+# external package imports.
+from pychromecast.controllers.multizone import MultizoneController, MultiZoneControllerListener
+from pychromecast.dial import MultizoneStatus, get_multizone_status
+from pychromecast import Chromecast
+import pychromecast
+import threading
+from uuid import UUID
+from zeroconf import Zeroconf
+
+# our package imports.
+from spotifywebapipython.models import SpotifyConnectDevice, ZeroconfDiscoveryResult
+# note - cannot reference `SpotifyConnectDirectoryTask` due to circular import!
+# from .spotifyconnectdirectorytask import SpotifyConnectDirectoryTask
+
+# get smartinspect logger reference; create a new session for this module name.
+from smartinspectpython.siauto import SIAuto, SILevel, SISession, SIMethodParmListContext, SIColors
+import logging
+
+_logsi:SISession = SIAuto.Si.GetSession(__name__)
+if (_logsi == None):
+    _logsi = SIAuto.Si.AddSession(__name__, True)
+_logsi.SystemLogger = logging.getLogger(__name__)
+
+
+class SpotifyConnectZeroconfCastMultiZoneListener(MultiZoneControllerListener):
+    """
+    Google Chromecast Zeroconf MultiZone Listener class.
+    
+    Listens for Chromecast device multi-zone status updates for devices that
+    support multi-zone / group functionality.
+    """
+
+    def __init__(
+        self, 
+        parentDirectory,
+        zeroconfInstance:Zeroconf,
+        zeroconf_RLock:threading.RLock,
+        castMultizoneController:MultizoneController,
+        castDevice:Chromecast,
+        ) -> None:
+        """
+        Initializes a new instance of the class.
+
+        Args:
+            parentDirectory (SpotifyConnectDirectoryTask):
+                Parent SpotifyConnectDirectoryTask instance.
+            zeroconfInstance (Zeroconf):
+                Zeroconf instance used to query zeroconf.
+            zeroconf_RLock (threading.RLock):
+                Lock object used to enforce thread-safe updates.
+            castMultizoneController (MultizoneController)
+                MultizoneController parent instance.
+            castDevice (Chromecast):
+                Chromecast device object.
+        """
+        # invoke base class method.
+        super().__init__()
+
+        # initialize storage.
+        self._CastMultizoneController:MultizoneController = castMultizoneController
+        self._CastDevice = castDevice
+        self._ParentDirectory = parentDirectory
+        self._ZeroconfInstance:Zeroconf = zeroconfInstance
+        self._Zeroconf_RLock:threading.RLock = zeroconf_RLock
+
+
+    def multizone_member_added(
+        self, 
+        group_uuid:str, 
+        ) -> None:
+        """
+        Called when cast has been added to group identified by group_uuid.
+        """
+        # use lock, as multiple threads could be calling this method simultaneously.
+        with self._Zeroconf_RLock:
+
+            # copy passed parameters to thread-safe storage.
+            argsGroupUuid:UUID = group_uuid
+                
+            apiMethodName:str = "multizone_member_added"
+            apiMethodParms:SIMethodParmListContext = None
+
+            try:
+
+                # trace.
+                apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
+                apiMethodParms.AppendKeyValue("group_uuid", argsGroupUuid)
+                _logsi.LogMethodParmList(SILevel.Debug, "Chromecast multizone group notification was received for group \"%s\"" % (argsGroupUuid), apiMethodParms, colorValue=SIColors.Lavender)
+
+                # get device instance.
+                scDevice:SpotifyConnectDevice = self._ParentDirectory._SpotifyConnectDevices.GetDeviceByDiscoveryKey(str(argsGroupUuid))
+                if (scDevice is None):
+
+                    # trace.
+                    _logsi.LogVerbose("Could not find SpotifyConnectDevices instance for Cast Group discovery key: \"%s\"" % (str(argsGroupUuid)), colorValue=SIColors.Lavender)
+
+                else:
+
+                    # trace.
+                    _logsi.LogVerbose("Chromecast member device %s was added to multizone group \"%s\"" % (scDevice.Title, self._CastDevice.cast_info.friendly_name), colorValue=SIColors.Lavender)
+
+                    # dump the multizone status for the newly added member.
+                    castMultiZoneStatus:MultizoneStatus = get_multizone_status(scDevice.DiscoveryResult.HostIpAddress, self._CastDevice.cast_info.services, self._ZeroconfInstance, 5)
+                    _logsi.LogObject(SILevel.Verbose, "Chromecast member device multizone status: %s [%s] (get_multizone_status)" % (scDevice.Title, scDevice.DiscoveryResult.HostIpTitle), castMultiZoneStatus, colorValue=SIColors.Lavender)
+
+            except Exception as ex:
+            
+                # trace.
+                _logsi.LogException("Unhandled exception occured while processing Chromecast MultiZoneController notification (%s)" % (apiMethodName), ex, logToSystemLogger=False)
+            
+                # ignore exception, as nothing can be done about it.
+
+            finally:
+
+                # trace.
+                _logsi.LeaveMethod(SILevel.Debug, apiMethodName)
+
+
+    def multizone_member_removed(
+        self, 
+        group_uuid, 
+        ) -> None:
+        """
+        Called when cast has been removed from group identified by group_uuid.
+        """
+        # use lock, as multiple threads could be calling this method simultaneously.
+        with self._Zeroconf_RLock:
+
+            # copy passed parameters to thread-safe storage.
+            argsGroupUuid:UUID = group_uuid
+                
+            apiMethodName:str = "multizone_member_removed"
+            apiMethodParms:SIMethodParmListContext = None
+
+            try:
+
+                # trace.
+                apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
+                apiMethodParms.AppendKeyValue("group_uuid", argsGroupUuid)
+                _logsi.LogMethodParmList(SILevel.Debug, "Chromecast multizone group notification was received for group \"%s\"" % (argsGroupUuid), apiMethodParms, colorValue=SIColors.Lavender)
+
+                # get device instance.
+                scDevice:SpotifyConnectDevice = self._ParentDirectory._SpotifyConnectDevices.GetDeviceByDiscoveryKey(str(argsGroupUuid))
+                if (scDevice is None):
+
+                    # trace.
+                    _logsi.LogVerbose("Could not find SpotifyConnectDevices instance for Cast Group discovery key: \"%s\"" % (str(argsGroupUuid)), colorValue=SIColors.Lavender)
+
+                else:
+
+                    # trace.
+                    _logsi.LogVerbose("Chromecast member device %s was removed from multizone group \"%s\"" % (scDevice.Title, self._CastDevice.cast_info.friendly_name), colorValue=SIColors.Lavender)
+
+            except Exception as ex:
+            
+                # trace.
+                _logsi.LogException("Unhandled exception occured while processing Chromecast MultiZoneController notification (%s)" % (apiMethodName), ex, logToSystemLogger=False)
+            
+                # ignore exception, as nothing can be done about it.
+
+            finally:
+
+                # trace.
+                _logsi.LeaveMethod(SILevel.Debug, apiMethodName)
+
+
+    def multizone_status_received(
+        self, 
+        ) -> None:
+        """
+        Called when Multizone status has been updated.
+        """
+        # use lock, as multiple threads could be calling this method simultaneously.
+        with self._Zeroconf_RLock:
+
+            # copy passed parameters to thread-safe storage.
+            # n/a
+                
+            apiMethodName:str = "multizone_status_received"
+            apiMethodParms:SIMethodParmListContext = None
+
+            try:
+
+                # trace.
+                apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
+                _logsi.LogMethodParmList(SILevel.Debug, "Chromecast multizone group status has been updated", apiMethodParms, colorValue=SIColors.Lavender)
+
+                # trace.
+                if (_logsi.IsOn(SILevel.Verbose)):
+
+                    # build member list with friendly names.
+                    result:list[str] = []
+                    member:str = None
+                    for member in self._CastMultizoneController.members:
+                        scDevice:SpotifyConnectDevice = self._ParentDirectory._SpotifyConnectDevices.GetDeviceByDiscoveryKey(member)
+                        if (scDevice is None):
+                            result.append(member)
+                        else:
+                            result.append(scDevice.Title)
+                    _logsi.LogArray(SILevel.Verbose, "Chromecast multizone group \"%s\" members (count=%d)" % (self._CastDevice.cast_info.friendly_name, len(result)), result, colorValue=SIColors.Lavender)
+
+            except Exception as ex:
+            
+                # trace.
+                _logsi.LogException("Unhandled exception occured while processing Chromecast MultiZoneController notification (%s)" % (apiMethodName), ex, logToSystemLogger=False)
+            
+                # ignore exception, as nothing can be done about it.
+
+            finally:
+
+                # trace.
+                _logsi.LeaveMethod(SILevel.Debug, apiMethodName)

spotifywebapipython/spotifyconnect/spotifyconnectzeroconfexceptions.py

@@ -0,0 +1,20 @@
+# our package imports.
+from spotifywebapipython import SpotifyApiError
+
+
+class SpotifyConnectZeroconfLaunchError(Exception):
+    """
+    Exception raised when a cast app fails to launch.
+    """
+
+
+class SpotifyConnectZeroconfPlaybackTransferError(Exception):
+    """
+    Exception raised when a cast app fails to receive transfer of playback control.
+    """
+
+
+class SpotifyConnectDeviceNotFound(SpotifyApiError):
+    """
+    Exception raised when a Spotify Connect device could not be resolved.
+    """