spotifywebapiPython 1.0.155__py3-none-any.whl → 1.0.157__py3-none-any.whl

spotifywebapipython/spotifyclient.py

@@ -24,7 +24,7 @@ from zeroconf import Zeroconf
 from .oauthcli import AuthClient
 from .models import *
 from .models import UserProfile as UserProfileCurrentUser
-from .spotifyconnect import SpotifyConnectDirectoryTask
+from .spotifyconnect import SpotifyConnectDirectoryTask, SpotifyConnectDeviceNotFound
 from .saappmessages import SAAppMessages
 from .spotifyapierror import SpotifyApiError
 from .spotifyapimessage import SpotifyApiMessage
@@ -473,6 +473,25 @@ class SpotifyClient:
         return self._ZeroconfClient
     
 
+    def _CheckForDeviceNotFound(
+        self,
+        scDevice:SpotifyConnectDevice,
+        deviceId:str,
+        ) -> None:
+        """
+        Called to raise a SpotifyConnectDeviceNotFound exception when a Spotify Connect 
+        device could not be found and there is no active player.
+        """
+        # was a device resolved?
+        if (scDevice is None):
+
+            # if deviceId could not be resolved, then it's an error.
+            if (deviceId is None) or (deviceId == "*"):
+                raise SpotifyConnectDeviceNotFound("There is no active Spotify player, and a default player device was not configured; select a player device and try again.")
+            else:
+                raise SpotifyConnectDeviceNotFound("Spotify Player device \"%s\" was not found, and there is no active Spotify player; verify the device is active and available on the local network, and try again." % (deviceId))
+
+
     def _CheckForNextPageWithOffset(
         self, 
         pageObj:PageObject,
@@ -1231,10 +1250,11 @@ class SpotifyClient:
                 for idx in range(0, len(arrUris)):
                     arrUris[idx] = arrUris[idx].strip()
                 
-            # resolve / activate the device object if needed.
+            # resolve the device object from the device id.
             scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId, False)
 
-            # is this a Sonos device?
+            # is this an active Sonos device?
+            # Sonos device can still be active, even if there is no active device in Spotify playstate.
             if (scDevice is not None) and (scDevice.IsSonos):
 
                 # trace.
@@ -1257,6 +1277,10 @@ class SpotifyClient:
                 # trace.
                 _logsi.LogVerbose("Items will be added to playback queue for device: %s" % (scDevice.Title))
                 
+                # was the deviceId resolved? 
+                # if not, then raise an exception as the Spotify Web API request will fail anyway.
+                self._CheckForDeviceNotFound(scDevice, deviceId)
+
                 # process all uri's.
                 for idx in range(0, len(arrUris)):
                 
@@ -11569,10 +11593,11 @@ class SpotifyClient:
             # validations.
             delay = validateDelay(delay, 0.50, 10)
 
-            # resolve / activate the device object if needed.
+            # resolve the device object from the device id.
             scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId, False)
 
             # is this an active Sonos device?
+            # Sonos device can still be active, even if there is no active device in Spotify playstate.
             if (scDevice is not None) and (scDevice.IsSonos):
 
                 _logsi.LogVerbose("Issuing command to Sonos device %s: PAUSE" % (scDevice.Title))
@@ -11581,6 +11606,10 @@ class SpotifyClient:
 
             else:
 
+                # was the deviceId resolved? 
+                # if not, then raise an exception as the Spotify Web API request will fail anyway.
+                self._CheckForDeviceNotFound(scDevice, deviceId)
+
                 # build spotify web api request parameters.
                 urlParms:dict = {}
                 if (scDevice is not None):
@@ -11728,10 +11757,11 @@ class SpotifyClient:
             if (offsetPosition is None) or (offsetPosition < 0):
                 offsetPosition = 0
 
-            # resolve / activate the device object if needed.
-            scDevice = self._ResolveDeviceObject(deviceId, False)
+            # resolve the device object from the device idl activate if it's dormant.
+            scDevice = self._ResolveDeviceObject(deviceId, True)
 
-            # is this a Sonos device?
+            # is this an active Sonos device?
+            # Sonos device can still be active, even if there is no active device in Spotify playstate.
             if (scDevice is not None) and (scDevice.IsSonos):
 
                 # trace.
@@ -11808,6 +11838,10 @@ class SpotifyClient:
                 # trace.
                 _logsi.LogVerbose("Context will be played on the Spotify Connect device via Spotify Web API")
 
+                # was the deviceId resolved? 
+                # if not, then raise an exception as the Spotify Web API request will fail anyway.
+                self._CheckForDeviceNotFound(scDevice, deviceId)
+
                 # build spotify web api request parameters.
                 reqData:dict = \
                 {
@@ -11950,7 +11984,7 @@ class SpotifyClient:
             for trackSaved in tracks.Items:
                 arrUris.append(trackSaved.Track.Uri)
 
-            # resolve / activate the device object if needed.
+            # resolve the device object from the device id.
             scDevice = self._ResolveDeviceObject(deviceId, False)
 
             # set desired shuffle mode.
@@ -12073,10 +12107,11 @@ class SpotifyClient:
                 for idx in range(0, len(arrUris)):
                     arrUris[idx] = arrUris[idx].strip()
         
-            # resolve / activate the device object if needed.
+            # resolve the device object from the device id; activate if it's dormant.
             scDevice = self._ResolveDeviceObject(deviceId, True)
 
-            # is this a Sonos device?
+            # is this an active Sonos device?
+            # Sonos device can still be active, even if there is no active device in Spotify playstate.
             if (scDevice is not None) and (scDevice.IsSonos):
 
                 # trace.
@@ -12129,6 +12164,10 @@ class SpotifyClient:
                 # trace.
                 _logsi.LogVerbose("Track list will be played on the Spotify Connect device via Spotify Web API")
 
+                # was the deviceId resolved? 
+                # if not, then raise an exception as the Spotify Web API request will fail anyway.
+                self._CheckForDeviceNotFound(scDevice, deviceId)
+
                 # build spotify web api request parameters.
                 reqData:dict = \
                 {
@@ -12228,10 +12267,12 @@ class SpotifyClient:
             # validations.
             delay = validateDelay(delay, 0.50, 10)
 
-            # resolve / activate the device object if needed.
-            scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId, False)
+            # resolve the device object from the device id; activate if it's dormant.
+            # we activate the device here, as it may have been paused for a long time.
+            scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId, True)
 
             # is this an active Sonos device?
+            # Sonos device can still be active, even if there is no active device in Spotify playstate.
             if (scDevice is not None) and (scDevice.IsSonos):
 
                 _logsi.LogVerbose("Issuing command to Sonos device %s: PLAY (RESUME)" % (scDevice.Title))
@@ -12240,6 +12281,10 @@ class SpotifyClient:
 
             else:
 
+                # was the deviceId resolved? 
+                # if not, then raise an exception as the Spotify Web API request will fail anyway.
+                self._CheckForDeviceNotFound(scDevice, deviceId)
+
                 # build spotify web api request parameters.
                 urlParms:dict = {}
                 if (scDevice is not None):
@@ -12366,7 +12411,7 @@ class SpotifyClient:
             if (relativePositionMS is None):
                 relativePositionMS = 0
 
-            # resolve / activate the device object if needed.
+            # resolve the device object from the device id.
             scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId, False)
            
             # was relative seeking specified?
@@ -12384,6 +12429,7 @@ class SpotifyClient:
                     positionMS = newPositionMS
 
             # is this an active Sonos device?
+            # Sonos device can still be active, even if there is no active device in Spotify playstate.
             if (scDevice is not None) and (scDevice.IsSonos):
 
                 sonosPosition:str = mediaPositionHMS_fromSeconds(positionMS / 1000)    # convert from milliseconds to Sonos H:MM:SS format
@@ -12393,6 +12439,10 @@ class SpotifyClient:
 
             else:
 
+                # was the deviceId resolved? 
+                # if not, then raise an exception as the Spotify Web API request will fail anyway.
+                self._CheckForDeviceNotFound(scDevice, deviceId)
+
                 # build spotify web api request parameters.
                 urlParms:dict = \
                 {
@@ -12487,10 +12537,11 @@ class SpotifyClient:
             # validations.
             delay = validateDelay(delay, 0.50, 10)
 
-            # resolve / activate the device object if needed.
+            # resolve the device object from the device id.
             scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId, False)
 
             # is this an active Sonos device?
+            # Sonos device can still be active, even if there is no active device in Spotify playstate.
             if (scDevice is not None) and (scDevice.IsSonos):
 
                 _logsi.LogVerbose("Issuing command to Sonos device %s: NEXT" % (scDevice.Title))
@@ -12499,6 +12550,10 @@ class SpotifyClient:
 
             else:
 
+                # was the deviceId resolved? 
+                # if not, then raise an exception as the Spotify Web API request will fail anyway.
+                self._CheckForDeviceNotFound(scDevice, deviceId)
+
                 # build spotify web api request parameters.
                 urlParms:dict = {}
                 if (scDevice is not None):
@@ -12590,10 +12645,11 @@ class SpotifyClient:
             # validations.
             delay = validateDelay(delay, 0.50, 10)
 
-            # resolve / activate the device object if needed.
+            # resolve the device object from the device id.
             scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId, False)
 
             # is this an active Sonos device?
+            # Sonos device can still be active, even if there is no active device in Spotify playstate.
             if (scDevice is not None) and (scDevice.IsSonos):
 
                 _logsi.LogVerbose("Issuing command to Sonos device %s: PREVIOUS" % (scDevice.Title))
@@ -12602,6 +12658,10 @@ class SpotifyClient:
 
             else:
 
+                # was the deviceId resolved? 
+                # if not, then raise an exception as the Spotify Web API request will fail anyway.
+                self._CheckForDeviceNotFound(scDevice, deviceId)
+
                 # build spotify web api request parameters.
                 urlParms:dict = {}
                 if (scDevice is not None):
@@ -12701,10 +12761,11 @@ class SpotifyClient:
             # validations.
             delay = validateDelay(delay, 0.50, 10)
 
-            # resolve / activate the device object if needed.
+            # resolve the device object from the device id.
             scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId, False)
 
             # is this an active Sonos device?
+            # Sonos device can still be active, even if there is no active device in Spotify playstate.
             if (scDevice is not None) and (scDevice.IsSonos):
 
                 # get current Spotify Connect player state.
@@ -12730,6 +12791,10 @@ class SpotifyClient:
 
             else:
 
+                # was the deviceId resolved? 
+                # if not, then raise an exception as the Spotify Web API request will fail anyway.
+                self._CheckForDeviceNotFound(scDevice, deviceId)
+
                 # build spotify web api request parameters.
                 urlParms:dict = \
                 {
@@ -12831,10 +12896,11 @@ class SpotifyClient:
             # validations.
             delay = validateDelay(delay, 0.50, 10)
 
-            # resolve / activate the device object if needed.
+            # resolve the device object from the device id.
             scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId, False)
 
             # is this an active Sonos device?
+            # Sonos device can still be active, even if there is no active device in Spotify playstate.
             if (scDevice is not None) and (scDevice.IsSonos):
 
                 # get current Spotify Connect player state.
@@ -12861,6 +12927,10 @@ class SpotifyClient:
 
             else:
 
+                # was the deviceId resolved? 
+                # if not, then raise an exception as the Spotify Web API request will fail anyway.
+                self._CheckForDeviceNotFound(scDevice, deviceId)
+
                 # build spotify web api request parameters.
                 urlParms:dict = \
                 {
@@ -12961,10 +13031,11 @@ class SpotifyClient:
             # validations.
             delay = validateDelay(delay, 0.50, 10)
 
-            # resolve / activate the device object if needed.
+            # resolve the device object from the device id.
             scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId, False)
 
             # is this an active Sonos device?
+            # Sonos device can still be active, even if there is no active device in Spotify playstate.
             if (scDevice is not None) and (scDevice.IsSonos):
 
                 _logsi.LogVerbose("Issuing command to Sonos device %s: VOLUME = %s" % (scDevice.Title, volumePercent))
@@ -12973,6 +13044,10 @@ class SpotifyClient:
 
             else:
 
+                # was the deviceId resolved? 
+                # if not, then raise an exception as the Spotify Web API request will fail anyway.
+                self._CheckForDeviceNotFound(scDevice, deviceId)
+
                 # build spotify web api request parameters.
                 urlParms:dict = \
                 {
@@ -13129,7 +13204,7 @@ class SpotifyClient:
                 if (scDeviceFrom is not None) and (scDeviceFrom.IsSonos):
                     self.PlayerMediaPause(scDeviceFrom)
 
-            # resolve / activate the device object if needed.
+            # resolve the device object from the device id; activate if it's dormant.
             # for transfer playback, we will always activate the device.
             scDevice = self._ResolveDeviceObject(deviceId, True)
 

spotifywebapipython/spotifyconnect/__init__.py

@@ -4,7 +4,7 @@ from .spotifyconnectdirectorytask import SpotifyConnectDirectoryTask
 from .spotifyconnectzeroconfcastapptask import SpotifyConnectZeroconfCastAppTask
 from .spotifyconnectzeroconfcastcontroller import SpotifyConnectZeroconfCastController
 from .spotifyconnectzeroconfcastlistener import SpotifyConnectZeroconfCastListener
-from .spotifyconnectzeroconfexceptions import SpotifyConnectZeroconfLaunchError, SpotifyConnectZeroconfPlaybackTransferError
+from .spotifyconnectzeroconfexceptions import SpotifyConnectZeroconfLaunchError, SpotifyConnectZeroconfPlaybackTransferError, SpotifyConnectDeviceNotFound
 from .spotifyconnectzeroconflistener import SpotifyConnectZeroconfListener
 
 # all classes to import when "import *" is specified.
@@ -15,5 +15,5 @@ __all__ = [
     'SpotifyConnectZeroconfCastListener',
     'SpotifyConnectDirectoryTask', 
     'SpotifyConnectZeroconfListener',
-    'SpotifyConnectZeroconfLaunchError', 'SpotifyConnectZeroconfPlaybackTransferError',
+    'SpotifyConnectZeroconfLaunchError', 'SpotifyConnectZeroconfPlaybackTransferError', 'SpotifyConnectDeviceNotFound',
 ]

spotifywebapipython/spotifyconnect/spotifyconnectdirectorytask.py

@@ -22,8 +22,9 @@ from .spotifyconnectzeroconfcastcontroller import (
     TYPE_ADD_USER_RESPONSE,
     TYPE_ADD_USER_ERROR,
     TYPE_GET_INFO_ERROR,
-    TYPE_TRANSFER_ERROR_RESPONSE,
-    TYPE_TRANSFER_SUCCESS_RESPONSE
+    TYPE_LAUNCH_ERROR,
+    TYPE_TRANSFER_ERROR,
+    TYPE_TRANSFER_SUCCESS
     )
 # note - cannot reference `SpotifyClient` due to circular import!
 # from spotifywebapipython import SpotifyClient
@@ -523,7 +524,7 @@ class SpotifyConnectDirectoryTask(threading.Thread):
 
             # wait for the launched spotify app to activate the user (or fail).
             # this occurs when we receive any of the following zeroconf response 
-            # messages: `addUserResponse`, `addUserError`, `getInfoError`.
+            # messages: `addUserResponse`, `addUserError`, `getInfoError`, `launchError`.
 
             counter = 0
             while counter < (timeoutActivation + 1):
@@ -533,8 +534,9 @@ class SpotifyConnectDirectoryTask(threading.Thread):
                         scDevice:SpotifyConnectDevice = self._SpotifyConnectDevices.GetDeviceByDiscoveryKey(str(castDevice.uuid))
                     if (scDevice is not None):
                         response = scDevice.ZeroconfResponseInfo
-                        if (response.ResponseSource == TYPE_ADD_USER_RESPONSE):
-                            # indicate device was reconnected.
+                        if (response.ResponseSource == TYPE_LAUNCH_ERROR):
+                            raise SpotifyApiError("Spotify Cast Application could not be activated on Chromecast device \"%s\": %s" % (deviceName, response.StatusString), logsi=_logsi)
+                        elif (response.ResponseSource == TYPE_ADD_USER_RESPONSE):
                             scDevice.WasReConnected = True
                             break
                         raise SpotifyApiError("Spotify Cast App could not be activated on Chromecast device \"%s\": %s" % (deviceName, response.ToString(False)), logsi=_logsi)
@@ -567,7 +569,7 @@ class SpotifyConnectDirectoryTask(threading.Thread):
                             scDevice:SpotifyConnectDevice = self._SpotifyConnectDevices.GetDeviceByDiscoveryKey(str(castDevice.uuid))
                         if (scDevice is not None):
                             response = scDevice.ZeroconfResponseInfo
-                            if (response.ResponseSource == TYPE_TRANSFER_SUCCESS_RESPONSE):
+                            if (response.ResponseSource == TYPE_TRANSFER_SUCCESS):
                                 break
                             raise SpotifyApiError("Spotify Cast App failed to receive playback transfer on Chromecast device \"%s\": %s" % (deviceName, response.ToString(False)), logsi=_logsi)
                         raise SpotifyApiError("Spotify Cast App failed to receive playback transfer on Chromecast device: unknown error", logsi=_logsi)
@@ -1661,10 +1663,13 @@ class SpotifyConnectDirectoryTask(threading.Thread):
                 _logsi.LogObject(SILevel.Debug, "SpotifyConnectDevice info: \"%s\" (ZeroconfResponseInfo)" % (scDevice.Name), scDevice.ZeroconfResponseInfo, excludeNonPublic=True)
 
                 # indicate zeroconf response data was received.
-                if (response.ResponseSource == TYPE_ADD_USER_RESPONSE) or (response.ResponseSource == TYPE_ADD_USER_ERROR) or (response.ResponseSource == TYPE_GET_INFO_ERROR):
+                if (response.ResponseSource == TYPE_ADD_USER_RESPONSE) or (response.ResponseSource == TYPE_ADD_USER_ERROR) \
+                or (response.ResponseSource == TYPE_GET_INFO_ERROR):
                     self.WaitForActivationComplete.set()
-                elif (response.ResponseSource == TYPE_TRANSFER_SUCCESS_RESPONSE) or (response.ResponseSource == TYPE_TRANSFER_ERROR_RESPONSE):
+                elif (response.ResponseSource == TYPE_TRANSFER_SUCCESS) or (response.ResponseSource == TYPE_TRANSFER_ERROR):
                     self.WaitForTransferComplete.set()
+                elif (response.ResponseSource == TYPE_LAUNCH_ERROR):
+                    self.WaitForActivationComplete.set()
 
 
     def OnServiceInfoAddedUpdatedSpotifyConnect(

spotifywebapipython/spotifyconnect/spotifyconnectzeroconfcastapptask.py

@@ -4,11 +4,9 @@ import threading
 import time
 
 # our package imports.
-from .spotifyconnectzeroconfcastcontroller import SpotifyConnectZeroconfCastController
-from .spotifyconnectzeroconfexceptions import SpotifyConnectZeroconfPlaybackTransferError
-#from spotifywebapipython import SpotifyClient
-from spotifywebapipython.zeroconfapi import ZeroconfGetInfo, ZeroconfResponse
+from .spotifyconnectzeroconfcastcontroller import SpotifyConnectZeroconfCastController, TYPE_LAUNCH_ERROR
 from spotifywebapipython.spotifywebplayertoken import SpotifyWebPlayerToken
+from spotifywebapipython.zeroconfapi import ZeroconfGetInfo, ZeroconfResponse
 
 # get smartinspect logger reference; create a new session for this module name.
 from smartinspectpython.siauto import SIAuto, SILevel, SISession
@@ -118,42 +116,27 @@ class SpotifyConnectZeroconfCastAppTask(threading.Thread):
         return self._TransferPlayback
 
 
-    @property
-    def ZeroconfInfo(self) -> ZeroconfGetInfo:
-        """ 
-        Returns the Chromecast Spotify Connect getinfo response, if the Spotify
-        application is running on the Chromecast devive; otherwise, None.
-        """
-        if (self._SpotifyConnectZeroconfCastController is None):
-            return None
-        return self._SpotifyConnectZeroconfCastController.zeroconfGetInfo
-
-
-    @property
-    def ZeroconfResponseObject(self) -> ZeroconfResponse:
-        """ 
-        Returns the Chromecast Spotify Connect zeroconf response, if the Spotify
-        application returned one; otherwise, None.
+    def _CallGetInfoResponseReceivedCallback(
+        self,
+        zcResponse:ZeroconfGetInfo=None,
+        ) -> None:
         """
-        if (self._SpotifyConnectZeroconfCastController is None):
-            return None
-        return self._SpotifyConnectZeroconfCastController.zeroconfResponse
+        Executes the callback to process the zeroconf getInfo response from the cast app task.
 
-
-    def _CallGetInfoResponseReceivedCallback(self) -> None:
-        """
-        If defined, call the callback to process the zeroconf getInfo response from the cast app task.
+        Args:
+            zcResponse (ZeroconfGetInfo):
+                Zeroconf getInfo response object.
         """
-        # was a GetInfoResponse callback defined?
+        # was the callback defined?
         if (self._GetInfoResponseReceivedCallback):
 
             try:
 
                 # trace.
-                _logsi.LogVerbose("%s - Zeroconf getInfoResponse received; Spotify Connect info: \"%s\" (%s)" % (self.name, self.ZeroconfInfo.RemoteName, self.ZeroconfInfo.DeviceId))
+                _logsi.LogVerbose("%s - Zeroconf getInfoResponse received; Spotify Connect info: \"%s\" (%s)" % (self.name, zcResponse.RemoteName, zcResponse.DeviceId))
 
                 # invoke callback to process the GetInfoResponse data.
-                self._GetInfoResponseReceivedCallback(self._CastDevice.uuid, self.ZeroconfInfo)
+                self._GetInfoResponseReceivedCallback(self._CastDevice.uuid, zcResponse)
 
             except Exception as ex:
 
@@ -162,21 +145,27 @@ class SpotifyConnectZeroconfCastAppTask(threading.Thread):
                 #ignore exceptions, as there is nothing we can do about them!
 
 
-
-    def _CallZeroconfResponseReceivedCallback(self) -> None:
+    def _CallZeroconfResponseReceivedCallback(
+        self,
+        zcResponse:ZeroconfResponse=None,
+        ) -> None:
         """
-        If defined, call the callback to process the various zeroconf responses from the cast app task.
+        Executes the callback to process the various zeroconf responses from the cast app task.
+
+        Args:
+            zcResponse (ZeroconfResponse):
+                Zeroconf response object.
         """
-        # was a ZeroconfResponse callback defined?
+        # was the callback defined?
         if (self._ZeroconfResponseReceivedCallback):
 
             try:
 
                 # trace.
-                _logsi.LogVerbose("%s - Zeroconf \"%s\" received; Spotify Connect response: \"%s\" (%s)" % (self.name, self.ZeroconfResponseObject.ResponseSource, self.ZeroconfResponseObject.StatusString, self.ZeroconfResponseObject.Status))
+                _logsi.LogVerbose("%s - Zeroconf \"%s\" received; Spotify Connect response: \"%s\" (%s)" % (self.name, zcResponse.ResponseSource, zcResponse.StatusString, zcResponse.Status))
 
                 # invoke callback to process the ZeroconfResponse data.
-                self._ZeroconfResponseReceivedCallback(self._CastDevice.uuid, self.ZeroconfResponseObject)
+                self._ZeroconfResponseReceivedCallback(self._CastDevice.uuid, zcResponse)
 
             except Exception as ex:
 
@@ -188,6 +177,9 @@ class SpotifyConnectZeroconfCastAppTask(threading.Thread):
     def run(self):
         """
         The task to perform on a seperate thread.
+
+        Note that any exceptions must be processed via a call to _PostLaunchErrorEvent, if you 
+        want the exception to be see by the user; just raising an exception will only log it!
         """
         try:
 
@@ -220,32 +212,24 @@ class SpotifyConnectZeroconfCastAppTask(threading.Thread):
             # at this point the cast app should be either fully launched, or an error
             # occured while trying to launch.
 
-            # was a ZeroconfResponse callback defined?
-            if (self._ZeroconfResponseReceivedCallback):
-
-                try:
+            # did an error occur?
+            if (not self._SpotifyConnectZeroconfCastController.isLaunched):
 
-                    # at this point, the Spotify Connect `addUser` has been made and the results populated.
-                    _logsi.LogVerbose("%s - Zeroconf ZeroconfResponse received; Spotify Connect response: \"%s\" (%s)" % (self.name, self.ZeroconfResponseObject.StatusString, self.ZeroconfResponseObject.ResponseSource))
+                # was it a launchError or getInfoError?
+                if (not self._SpotifyConnectZeroconfCastController.isAddUserError):
+                    self._CallZeroconfResponseReceivedCallback(self._SpotifyConnectZeroconfCastController.zeroconfResponse)
+                    _logsi.LogException("%s - Failed to launch spotify controller due to timeout" % (self.name), None, logToSystemLogger=False)
+                    return
 
-                    # invoke callback to process the ZeroconfResponse data.
-                    self._ZeroconfResponseReceivedCallback(self._CastDevice.uuid, self.ZeroconfResponseObject)
+                # if getInfoResponse was received, then execute callback to process the getInfoResponse.
+                if (not self._SpotifyConnectZeroconfCastController.isGetInfoError) and (self._SpotifyConnectZeroconfCastController.zeroconfGetInfo is not None):
+                    self._CallGetInfoResponseReceivedCallback(self._SpotifyConnectZeroconfCastController.zeroconfGetInfo)
 
-                except Exception as ex:
-
-                    # trace.
-                    _logsi.LogException("An unhandled exception occured in ZeroconfResponseReceivedCallback: %s" % (str(ex)), ex, logToSystemLogger=False)
-                    #ignore exceptions, as there is nothing we can do about them!
-
-            # check for launch or getInfoError errors.
-            if (not self._SpotifyConnectZeroconfCastController.isLaunched) and (not self._SpotifyConnectZeroconfCastController.isAddUserError):
-                self._CallZeroconfResponseReceivedCallback()
-                raise ValueError("%s - Failed to launch spotify controller due to timeout" % (self.name))
-
-            # check for addUserError errors.
-            if (not self._SpotifyConnectZeroconfCastController.isLaunched) and (self._SpotifyConnectZeroconfCastController.isAddUserError):
-                self._CallZeroconfResponseReceivedCallback()
-                raise ValueError("%s - Failed to launch spotify controller due to credentials error" % (self.name))
+                # was it a addUserError? if so, then sp_dc / sp_key credentials are probably bad.
+                if (self._SpotifyConnectZeroconfCastController.isAddUserError):
+                    self._CallZeroconfResponseReceivedCallback(self._SpotifyConnectZeroconfCastController.zeroconfResponse)
+                    _logsi.LogException("%s - Failed to launch spotify controller due to credentials error" % (self.name), None, logToSystemLogger=False)
+                    return
 
             # at this point the cast app launch was successful; the following steps were performed:
             # - issues a Spotify Connect Zeroconf `getInfo` request to retrieve info about the device.
@@ -258,10 +242,10 @@ class SpotifyConnectZeroconfCastAppTask(threading.Thread):
             # as well as AFTER the call to `addUser` (no need to call `getInfo` again AFTER addUser).
 
             # call the callback to process the getInfoResponse.
-            self._CallGetInfoResponseReceivedCallback()
+            self._CallGetInfoResponseReceivedCallback(self._SpotifyConnectZeroconfCastController.zeroconfGetInfo)
 
             # call the callback to process the addUserResponse.
-            self._CallZeroconfResponseReceivedCallback()
+            self._CallZeroconfResponseReceivedCallback(self._SpotifyConnectZeroconfCastController.zeroconfResponse)
 
             # trace.
             _logsi.LogVerbose("%s - User is logged in to Spotify Cast App; waiting for transfer playback ..." % (self.name))
@@ -271,7 +255,8 @@ class SpotifyConnectZeroconfCastAppTask(threading.Thread):
 
                 # transfer playback to the Chromecast device.
                 _logsi.LogVerbose("%s - Transferring playback for loginId \"%s\"" % (self.name, self.SpotifyClientInstance.SpotifyConnectLoginId))
-                self.SpotifyClientInstance.PlayerTransferPlayback(self.ZeroconfInfo.DeviceId, play=True, refreshDeviceList=False)
+                deviceId:str = self._SpotifyConnectZeroconfCastController.zeroconfGetInfo.DeviceId
+                self.SpotifyClientInstance.PlayerTransferPlayback(deviceId, play=True, refreshDeviceList=False)
 
                 # the cast device will receive a Chromecast message of payload type `transferSuccess`
                 # on successful transfer of playback; this will set the `isPlaybackTransferred` flag to True.
@@ -284,17 +269,19 @@ class SpotifyConnectZeroconfCastAppTask(threading.Thread):
             while counter < (timeout + 1):
                 if (self._SpotifyConnectZeroconfCastController.waitPlaybackTransfer.wait(1)):
                     if (self._SpotifyConnectZeroconfCastController.isPlaybackTransferError):
-                        raise SpotifyConnectZeroconfPlaybackTransferError("%s - playback transfer error: %s" % (self.name, str(self.ZeroconfResponseObject)))
+                        self._PostLaunchErrorEvent(1001, "Playback transfer error: %s" % (self._SpotifyConnectZeroconfCastController.zeroconfResponse.StatusString))
+                        return
                     break
                 if (counter >= timeout):
-                    raise SpotifyConnectZeroconfPlaybackTransferError("%s - Timed out waiting for playback transfer to device" % (self.name))
+                    self._PostLaunchErrorEvent(1002, "Playback transfer error - Timed out waiting for playback transfer to device")
+                    return
                 counter += 1
 
             # update task status.
             _logsi.LogVerbose("%s - Transfer Playback complete for loginId \"%s\"" % (self.name, self.SpotifyClientInstance.SpotifyConnectLoginId))
 
             # call the callback to process the transferSuccess or transferError.
-            self._CallZeroconfResponseReceivedCallback()
+            self._CallZeroconfResponseReceivedCallback(self._SpotifyConnectZeroconfCastController.zeroconfResponse)
 
             # event loop; we have to keep this thread active in order to keep the 
             # Spotify App on the Chromecast device active and available.
@@ -309,20 +296,16 @@ class SpotifyConnectZeroconfCastAppTask(threading.Thread):
             # trace.
             _logsi.LogVerbose("%s - Thread task was stopped" % (self.name))
         
-        except SpotifyConnectZeroconfPlaybackTransferError as ex:
-
-            # trace.
-            _logsi.LogError(str(ex))
-            _logsi.LogVerbose("%s - Thread task is ending due to error" % (self.name))
-            
         except Exception as ex:
 
+            # post launchError event with exception details.
+            # this will also log a trace message.
+            self._PostLaunchErrorEvent(1000, str(ex))
+
             # trace.
-            _logsi.LogException("%s - Exception: %s" % (self.name, str(ex)), ex, logToSystemLogger=False)
             _logsi.LogVerbose("%s - Thread task is ending due to exception" % (self.name))
-            
-            # raise unhandled exception.
-            raise
+
+            #ignore exceptions, as there is nothing we can do about them!
 
         finally:
 
@@ -334,3 +317,29 @@ class SpotifyConnectZeroconfCastAppTask(threading.Thread):
                     self._SpotifyConnectZeroconfCastController.tear_down()
             except:
                 pass
+
+
+    def _PostLaunchErrorEvent(
+        self,
+        returnCode:int,
+        message:str
+        ) -> None:
+        """
+        Formats a `launchError` Zeroconf Response, and executes the callback.
+        """
+        try:
+
+            # trace.
+            _logsi.LogError("%s - LaunchError event; (%s) %s" % (self.name, returnCode, message), logToSystemLogger=False)
+
+            # post launchError event with error details.
+            response:ZeroconfResponse = ZeroconfResponse()
+            response.ResponseSource = TYPE_LAUNCH_ERROR
+            response.Status = returnCode
+            response.StatusString = message
+            self._CallZeroconfResponseReceivedCallback(response)
+
+        except:
+
+            # ignore exceptions, as there is nothing we can do about them.
+            pass