spotifywebapiPython 1.0.150__py3-none-any.whl → 1.0.152__py3-none-any.whl

spotifywebapipython/spotifyclient.py

@@ -5,10 +5,16 @@ import json
 from io import BytesIO
 from oauthlib.oauth2 import BackendApplicationClient, WebApplicationClient
 import socket
+from soco import SoCo
+from soco.core import (
+    PLAY_MODE_BY_MEANING as SONOS_PLAY_MODE_BY_MEANING,
+    PLAY_MODES as SONOS_PLAY_MODES,
+)
 import time
 from typing import Tuple, Callable, Union
 from urllib3 import PoolManager, Timeout, HTTPResponse
 from urllib.parse import urlencode
+import urllib.parse
 from lxml.etree import fromstring, Element, tostring
 from lxml import etree
 from zeroconf import Zeroconf
@@ -18,7 +24,6 @@ from .oauthcli import AuthClient
 from .models import *
 from .models import UserProfile as UserProfileCurrentUser
 from .spotifyconnect import SpotifyConnectDirectoryTask
-from .sautils import export, GetUnixTimestampMSFromUtcNow, _xmlGetInnerText, validateDelay
 from .saappmessages import SAAppMessages
 from .spotifyapierror import SpotifyApiError
 from .spotifyapimessage import SpotifyApiMessage
@@ -28,6 +33,14 @@ from .spotifywebapiauthenticationerror import SpotifyWebApiAuthenticationError
 from .spotifywebapierror import SpotifyWebApiError
 from .zeroconfapi.zeroconfconnect import ZeroconfConnect, ZeroconfGetInfo, ZeroconfResponse, SpotifyZeroconfApiError
 from .zeroconfapi.zeroconfgetinfoalias import ZeroconfGetInfoAlias
+from .sautils import (
+    _xmlGetInnerText, 
+    export, 
+    GetUnixTimestampMSFromUtcNow, 
+    mediaPositionHMS_fromSeconds,
+    mediaPositionHMS_toSeconds,
+    validateDelay
+)
 from .const import (
     SPOTIFY_API_AUTHORIZE_URL,
     SPOTIFY_API_TOKEN_URL,
@@ -42,6 +55,7 @@ from .const import (
     TRACE_MSG_AUTHTOKEN_CREATE,
     TRACE_MSG_AUTOPAGING_NEXT,
     TRACE_MSG_DELAY_DEVICE,
+    TRACE_MSG_DELAY_DEVICE_SONOS,
     TRACE_MSG_USERPROFILE,
     TRACE_WARN_SPOTIFY_SEARCH_NO_MARKET,
     VERSION
@@ -733,19 +747,28 @@ class SpotifyClient:
 
     def _ResolveDeviceObject(
         self,
-        device:str | SpotifyConnectDevice
+        device:str | SpotifyConnectDevice,
+        activateDevice:bool=True,
         ) -> SpotifyConnectDevice:
         """
         Resolves a SpotifyConnectDevice object from a device identifier, name, or 
-        SpotifyConnectDevice object argument value.  An exception will be raised
-        if the `device` argument could not be resolved or activated.
+        SpotifyConnectDevice object argument value.  A null object will be returned
+        if the `device` argument could not be resolved.
 
         Args:
-            device (str|SpotifyConnectDevice):
-                A device identifier, name, or a SpotifyConnectDevice object.
+            device (str | SpotifyConnectDevice) | None):
+                The target player device identifier.
+                This could be an id, name, a default device indicator (e.g. "*"), a 
+                SpotifyConnectDevice object, or null to utilize the active player device.
+                A device is considered resolved if a SpotifyConnectDevice object is passed
+                for this argument.  
+                Examples are `0d1841b0976bae2a3a310dd74c0f3df354899bc8`, `Office`, `*`, None.  
+            activateDevice (bool):
+                True to activate the device if necessary; otherwise, False.  
+                Default is True.  
 
         Returns:
-            A SpotifyConnectDevice object for the specified device.
+            A SpotifyConnectDevice object for the specified device if found; otherwise, null.
 
         Raises:
             SpotifyApiError: 
@@ -766,13 +789,13 @@ class SpotifyClient:
 
         else:
 
-            # no - ensure the specified device id / name is active and available,
-            # and return the SpotifyConnectDevice object.
-            # an exception will be thrown if the device id could not be activated.
+            # no - ensure the specified device id / name is active (optional) and 
+            # available, and return the SpotifyConnectDevice object.
+            # a null object will be returned if the device id could not be found.
             scDevice = self.GetSpotifyConnectDevice(
                 device, 
                 refreshDeviceList=True, 
-                activateDevice=True)
+                activateDevice=activateDevice)
 
         return scDevice
 
@@ -1139,12 +1162,16 @@ class SpotifyClient:
                 Example: `spotify:track:6zd8T1PBe9JFHmuVnurdRp,spotify:track:1kWUud3vY5ij5r62zxpTRy`.  
                 An unlimited number of items can be added in one request, but the more items the longer it
                 will take.
-            deviceId (str):
-                The id or name of the device this command is targeting.  
-                If not supplied, the user's currently active device is the target.  
-                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`  
-                Example: `Web Player (Chrome)`  
+            deviceId (str | SpotifyConnectDevice) | None):
+                The target player device identifier.
+                This could be an id, name, a default device indicator (e.g. "*"), a 
+                SpotifyConnectDevice object, or null to utilize the active player device.
+                A device is considered resolved if a SpotifyConnectDevice object is passed
+                for this argument.  An exception will be raised if the argument value could 
+                not be resolved or activated.
+                Examples are `0d1841b0976bae2a3a310dd74c0f3df354899bc8`, `Office`, `*`, None.  
             verifyDeviceId (bool):
+                DEPRECATED - deviceId is automatically verified as of v1.0.149.
                 True to verify a device id is active; otherwise, false to assume that a
                 device id is already active.  
                 Default is True.  
@@ -1166,7 +1193,7 @@ class SpotifyClient:
         
         The Spotify Web API endpoint is called to add each item individually.  
         The Spotify Web API does not currently support adding more than 1 item to the queue at a time.
-        
+
         <details>
           <summary>Sample Code</summary>
         ```python
@@ -1183,14 +1210,12 @@ class SpotifyClient:
             apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
             apiMethodParms.AppendKeyValue("uris", uris)
             apiMethodParms.AppendKeyValue("deviceId", deviceId)
-            apiMethodParms.AppendKeyValue("verifyDeviceId", verifyDeviceId)
+            apiMethodParms.AppendKeyValue("verifyDeviceId (DEPRECATED)", verifyDeviceId)
             apiMethodParms.AppendKeyValue("delay", delay)
             _logsi.LogMethodParmList(SILevel.Verbose, "Add items to playback queue", apiMethodParms)
             
             # validations.
             delay = validateDelay(delay, 0.15, 10)
-            if (verifyDeviceId is None):
-                verifyDeviceId = True
 
             # build a list of all item uri's.
             # remove any leading / trailing spaces in case user put a space between the items.
@@ -1203,7 +1228,7 @@ class SpotifyClient:
                     arrUris[idx] = arrUris[idx].strip()
                 
             # resolve / activate the device object if needed.
-            scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId)
+            scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId, False)
                 
             # process all uri's.
             for idx in range(0, len(arrUris)):
@@ -1213,7 +1238,8 @@ class SpotifyClient:
                 {
                     'uri': arrUris[idx]
                 }
-                urlParms['device_id'] = scDevice.Id
+                if (scDevice is not None):
+                    urlParms['device_id'] = scDevice.Id
 
                 # execute spotify web api request.
                 msg:SpotifyApiMessage = SpotifyApiMessage(apiMethodName, '/me/player/queue')
@@ -1966,7 +1992,7 @@ class SpotifyClient:
                 A comma-separated list of Spotify User ID's to check.  
                 Maximum: 5 ID's.  
                 Example: `1kWUud3vY5ij5r62zxpTRy,2takcwOaAZWiXQijPHIx7B`  
-                Deprecated - A single item list containing current user's Spotify Username; Maximum of 1 id.
+                DEPRECATED - A single item list containing current user's Spotify Username; Maximum of 1 id.
                 
         Returns:
             Array of boolean, containing a single boolean status that indicates 
@@ -2000,7 +2026,7 @@ class SpotifyClient:
             # trace.
             apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
             apiMethodParms.AppendKeyValue("playlistId", playlistId)
-            apiMethodParms.AppendKeyValue("userIds", userIds)
+            apiMethodParms.AppendKeyValue("userIds (DEPRECATED)", userIds)
             _logsi.LogMethodParmList(SILevel.Verbose, "Check to see if users are following a playlist", apiMethodParms)
 
             # validations.
@@ -5457,7 +5483,8 @@ class SpotifyClient:
                 Example: `sv_SE`  
             refresh (bool):
                 True to return real-time information from the spotify web api and
-                update the cache; otherwise, False to just return the cached value.       
+                update the cache; otherwise, False to just return the cached value.  
+                Default is True.
                 
         Returns:
             A `list[Category]` object that contains the list category details.
@@ -6075,6 +6102,94 @@ class SpotifyClient:
             _logsi.LeaveMethod(SILevel.Debug, apiMethodName)
    
 
+    def GetDevicePlaybackState(
+        self, 
+        deviceId:str|SpotifyConnectDevice|None=None,
+        ) -> PlayerPlayState:
+        """
+        Get information about the current playback state of the device, including track or episode, 
+        and progress. For Sonos devices, this will return the playstate of the device instead of the
+        active Spotify Web API player playstate.
+
+        This method requires the `user-read-playback-state` scope.
+        
+        This is not part of the Spotify Web API specification.
+       
+        Args:
+            deviceId (str | SpotifyConnectDevice) | None):
+                The target player device identifier.
+                This could be an id, name, a default device indicator (e.g. "*"), a 
+                SpotifyConnectDevice object, or null to utilize the active player device.
+                A device is considered resolved if a SpotifyConnectDevice object is passed
+                for this argument.  An exception will be raised if the argument value could 
+                not be resolved.
+                Examples are `0d1841b0976bae2a3a310dd74c0f3df354899bc8`, `Office`, `*`, None.  
+                
+        Returns:
+            A `PlayerPlayState` object that contains player state details as well as
+            currently playing content.
+                
+        Raises:
+            SpotifyWebApiError: 
+                If the Spotify Web API request was for a non-authorization service 
+                and the response contains error information.
+            SpotifyApiError: 
+                If the method fails for any other reason.
+
+        <details>
+          <summary>Sample Code</summary>
+        ```python
+        .. include:: ../docs/include/samplecode/SpotifyClient/GetDevicePlaybackState.py
+        ```
+        </details>
+        """
+        apiMethodName:str = 'GetDevicePlaybackState'
+        apiMethodParms:SIMethodParmListContext = None
+        result:PlayerPlayState = None
+        
+        try:
+            
+            # trace.
+            apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
+            apiMethodParms.AppendKeyValue("deviceId", deviceId)
+            _logsi.LogMethodParmList(SILevel.Verbose, "Get the current playback state of the device", apiMethodParms)
+
+            # resolve the device object; no need to activate it for what we want here.
+            # this will also set the currently active device in the devices cache, as well as
+            # add the playstate to the configuration cache.
+            scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId, activateDevice=False)
+
+            # get cached Spotify Web API playerstate (_ResolveDeviceObject method just refreshed it).
+            result = self.GetPlayerPlaybackState(refresh=False)
+
+            # is this a Sonos device?
+            if (scDevice is not None) and (scDevice.IsSonos):
+
+                # get Sonos playback state via Sonos Controller instance.
+                playerStateSonos:PlayerPlayState = self.GetPlayerPlaybackStateSonos(scDevice)
+
+                # return the device playstate.
+                _logsi.LogVerbose("Sonos device %s playstate will be returned" % (scDevice.Title))
+                result = playerStateSonos
+
+            # trace.
+            _logsi.LogObject(SILevel.Verbose, TRACE_METHOD_RESULT_TYPE % (apiMethodName, type(result).__name__), result, excludeNonPublic=True)
+            return result
+
+        except SpotifyApiError: raise  # pass handled exceptions on thru
+        except SpotifyWebApiError: raise  # pass handled exceptions on thru
+        except SpotifyWebApiAuthenticationError: raise  # pass handled exceptions on thru
+        except Exception as ex:
+            
+            # format unhandled exception.
+            raise SpotifyApiError(SAAppMessages.UNHANDLED_EXCEPTION.format(apiMethodName, str(ex)), ex, logsi=_logsi)
+
+        finally:
+        
+            # trace.
+            _logsi.LeaveMethod(SILevel.Debug, apiMethodName)
+
+
     def GetEpisode(
         self, 
         episodeId:str=None, 
@@ -7477,7 +7592,8 @@ class SpotifyClient:
     def GetPlayerPlaybackState(
         self, 
         market:str=None, 
-        additionalTypes:str=None
+        additionalTypes:str=None,
+        refresh:bool=True,
         ) -> PlayerPlayState:
         """
         Get information about the user's current playback state, including track or episode, progress, 
@@ -7501,6 +7617,10 @@ class SpotifyClient:
                 Note: This parameter was introduced to allow existing clients to maintain their current behaviour 
                 and might be deprecated in the future. In addition to providing this parameter, make sure that your client 
                 properly handles cases of new types in the future by checking against the type field of each object.
+            refresh (bool):
+                True to return real-time information from the Spotify Web API and
+                update the cache; otherwise, False to just return the cached value.  
+                Default is True.
                 
         Returns:
             A `PlayerPlayState` object that contains player state details as well as
@@ -7529,8 +7649,25 @@ class SpotifyClient:
             # trace.
             apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
             apiMethodParms.AppendKeyValue("market", market)
+            apiMethodParms.AppendKeyValue("additionalTypes", additionalTypes)
+            apiMethodParms.AppendKeyValue("refresh", refresh)
             _logsi.LogMethodParmList(SILevel.Verbose, "Get the user's current playback state", apiMethodParms)
-                
+            
+            # validations.
+            if (refresh is None):
+                refresh = True
+
+            # are we getting the cached value? if so, then just return it.
+            if (not refresh):
+
+                result = self._ConfigurationCache.get(apiMethodName, None)
+                if (result is None):
+                    result = PlayerPlayState()
+
+                # trace.
+                _logsi.LogObject(SILevel.Verbose, TRACE_METHOD_RESULT_TYPE % (apiMethodName + " (cached)", type(result).__name__), result, excludeNonPublic=True)
+                return result
+
             # ensure market was either supplied or implied; default if neither.
             market = self._ValidateMarket(market)
 
@@ -7549,9 +7686,12 @@ class SpotifyClient:
 
             # process results.
             result = PlayerPlayState(root=msg.ResponseData)
-            
+
+            # update cache with result.
+            self._ConfigurationCache[apiMethodName] = result
+           
             # is this an episode?  if so, then determine the item type (e.g. podcast or audiobook).
-            if (result is not None):
+            if (not result.IsEmpty):
                 if (result.Item is not None):
                     result.ItemType = SpotifyClient.GetTypeFromUri(result.Item.Uri)
                     if (result.CurrentlyPlayingType == 'episode'):
@@ -7563,7 +7703,7 @@ class SpotifyClient:
         
             # check for a restricted device; if found, then grab the device id from the 
             # cached list of spotify connect devices (if present).
-            if result is not None:
+            if (not result.IsEmpty):
                 device:Device = result.Device
                 if (device is not None) and (device.Id is None or device.Id == ''):
                     cacheKey:str = 'GetSpotifyConnectDevices'
@@ -7573,6 +7713,11 @@ class SpotifyClient:
                         if scDevice is not None:
                             device.Id = scDevice.DeviceInfo.DeviceId
         
+            # update Spotify Connect Directory with active device details.
+            # IMPORTANT - make sure result contains an object, otherwise it's an endless loop!
+            if (result is not None):
+                self.SpotifyConnectDirectory.UpdateActiveDevice(result)
+
             # trace.
             _logsi.LogObject(SILevel.Verbose, TRACE_METHOD_RESULT_TYPE % (apiMethodName, type(result).__name__), result, excludeNonPublic=True)
             return result
@@ -7591,6 +7736,222 @@ class SpotifyClient:
             _logsi.LeaveMethod(SILevel.Debug, apiMethodName)
 
 
+    def GetPlayerPlaybackStateSonos(
+        self, 
+        scDevice:SpotifyConnectDevice,
+        ) -> PlayerPlayState:
+        """
+        Get information about the Sonos user's current playback state, including track or episode, progress, 
+        and active device.
+        
+        This is not part of the Spotify Web API specification; it is for Sonos devices only!
+
+        Args:
+            scDevice (SpotifyConnectDevice):
+                Spotify Connect device instance used to identify the Sonos player.
+                
+        Returns:
+            A `PlayerPlayState` object that contains Sonos player state details as well as
+            currently playing content.
+                
+        Raises:
+            SpotifyApiError: 
+                If the method fails for any other reason.
+        """
+        apiMethodName:str = 'GetPlayerPlaybackStateSonos'
+        apiMethodParms:SIMethodParmListContext = None
+        
+        try:
+            
+            # trace.
+            apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
+            apiMethodParms.AppendKeyValue("scDevice", scDevice)
+            _logsi.LogMethodParmList(SILevel.Verbose, "Get Sonos device current playback state", apiMethodParms)
+            
+            # create playstate object.
+            playerState = PlayerPlayState()
+
+            # get Sonos Controller instance for the device.
+            _logsi.LogVerbose("Getting Sonos device status via Sonos Controller instance for device: %s" % (scDevice.Title))
+            sonosPlayer:SoCo = self.SpotifyConnectDirectory.GetSonosPlayer(scDevice)
+
+            # build a spotify playback status instance with equivalent Sonos state values.
+            sonosTrackInfo:dict = sonosPlayer.get_current_track_info()
+            _logsi.LogDictionary(SILevel.Verbose, "Sonos device current_track_info results for device: %s" % (scDevice.Title), sonosTrackInfo, prettyPrint=True)
+            sonosTransportInfo:dict = sonosPlayer.get_current_transport_info()
+            _logsi.LogDictionary(SILevel.Verbose, "Sonos device get_current_transport_info results for device: %s" % (scDevice.Title), sonosTransportInfo, prettyPrint=True)
+
+            # indicate this is a device-specific playstate.
+            playerState.IsDeviceState = True
+            playerState.DeviceMusicSource = "" + str(sonosPlayer.music_source)
+
+            # update Spotify Web API player state with Sonos player state.
+            playerState._Device._Id = scDevice.Id
+            playerState._Device._Name = sonosPlayer.player_name
+            playerState._Device._VolumePercent = sonosPlayer.volume
+            playerState._Device._IsActive = True
+            playerState._Device._IsRestricted = True
+            playerState._Device._SupportsVolume = True
+            playerState._Device._Type = 'SPEAKER'
+                
+            # try to get the spotify uri from the "metadata" music library DIDL value, as
+            # the "uri" value (e.g. "x-sonos-vli:RINCON_38420B909DC801400:2,spotify:e934941535d7b182815bf688490ce8a8")
+            # is not a true spotify uri value (e.g. "spotify:track:6kYyS9g4WJeRzTYqsmcMmM")
+            spotifyUri:str = sonosTrackInfo.get('uri','')
+            didl:str = sonosTrackInfo.get('metadata',None)
+            if (didl):
+                METADATA_ID:str = 'x-sonos-spotify:'
+                idx:int = didl.find(METADATA_ID)
+                if (idx > -1):
+                    spotifyUri:str = didl[idx + len(METADATA_ID):]
+                    spotifyUri = urllib.parse.unquote(spotifyUri)
+                    idx = spotifyUri.find('?')
+                    if (idx > -1):
+                        spotifyUri = spotifyUri[:idx]
+            spotifyType = self.GetTypeFromUri(spotifyUri) or ''
+            spotifyId = self.GetIdFromUri(spotifyUri) or ''
+                
+            # set base item properties.
+            playerState.IsEmpty = False
+            playerState.ItemType = spotifyType
+            sTimeValue:str = sonosTrackInfo.get('position',None)
+            playerState._ProgressMS = mediaPositionHMS_toSeconds(sTimeValue) * 1000        # convert h:mm:ss to milliseconds
+                
+            # set some item properties based on the playing type (episode or non-episode).
+            if (spotifyType == 'episode'):
+
+                # get the episode data from spotify, as Sonos Soco data is incomplete.
+                playerState._CurrentlyPlayingType = 'episode'
+                episode:Episode = self.GetEpisode(spotifyId)
+                if (episode.Id is not None): 
+                    playerState._Item = episode
+                    if (playerState._Context is None):
+                        playerState._Context = Context()
+                        playerState._Context._Type = episode.Show.Type
+                        playerState._Context._Uri = episode.Show.Uri
+                        playerState._Context._Href = episode.Show.Href
+                        playerState._Context._ExternalUrls = episode.Show.ExternalUrls
+                else:
+                    # if data could not be obtained from spotify, then use what's 
+                    # available from Sonos Soco api metadata.
+                    playerState._Item = Episode()
+                    playerState._Item._Name = sonosTrackInfo.get('title','')
+                    playerState._Item._Uri = spotifyUri
+                    playerState._Item._Description = 'Sonos device does not provide a description'
+                    sTimeValue:str = sonosTrackInfo.get('duration',None)
+                    playerState._Item._DurationMS = mediaPositionHMS_toSeconds(sTimeValue) * 1000  # convert h:mm:ss to milliseconds
+                    playerState._Item._Explicit = False
+                    playerState._Item._Href = 'https://api.spotify.com/v1/episodes/' + spotifyId
+                    playerState._Item._HtmlDescription = playerState._Item._Description
+                    playerState._Item._Id = spotifyId
+                    playerState._Item.Images.append(ImageObject())
+                    playerState._Item.Images[0]._Url = sonosTrackInfo.get('album_art','')
+                    playerState._Item._TrackNumber = sonosTrackInfo.get('playlist_position','')
+                    playerState._Item._ReleaseDate = '0000'
+                    playerState._Item._ReleaseDatePrecision = 'year'
+                    playerState._Item._Type = 'episode'
+                    playerState._Item._Show = Show()
+                    playerState._Item._Show._Name = sonosTrackInfo.get('album','')  # TODO get this from metadata (<r:podcast>The Elfstones of Shannara</r:podcast>)
+                    playerState._Item._Show.Images.append(ImageObject())
+                    playerState._Item._Show.Images[0]._Url = sonosTrackInfo.get('album_art','')
+                    playerState._Item._Show._Publisher = sonosTrackInfo.get('artist','')
+
+                    # if show name not set then get it from metadata.
+                    if (playerState._Item._Show._Name == ''):
+                        if (didl):
+                            METADATA_ID:str = '<r:podcast>'
+                            METADATA_END:str = '</r:podcast>'
+                            idx:int = didl.find(METADATA_ID)
+                            if (idx > -1):
+                                metaValue:str = didl[idx + len(METADATA_ID):]
+                                idx = metaValue.find(METADATA_END)
+                                if (idx > -1):
+                                    metaValue = metaValue[:idx]
+                                    playerState._Item._Show._Name = metaValue
+                                    
+                # if episode is playing then resolve the underlying type (audiobook / podcast show).
+                if (self.IsChapterEpisode(spotifyId)):
+                    playerState.ItemType = 'audiobook'
+                else:
+                    playerState.ItemType = 'podcast'
+                        
+            elif (spotifyType == 'track'):
+                    
+                # get the track data from spotify, as Sonos Soco data is incomplete.
+                track:Track = self.GetTrack(spotifyId)
+                if (track.Id is not None): 
+                    playerState._Item = track
+                    if (playerState._Context is None):
+                        playerState._Context = Context()
+                        playerState._Context._Type = track.Album.Type
+                        playerState._Context._Uri = track.Album.Uri
+                        playerState._Context._Href = track.Album.Href
+                        playerState._Context._ExternalUrls = track.Album.ExternalUrls
+                else:
+                    # if data could not be obtained from spotify, then use what's 
+                    # available from Sonos Soco api metadata.
+                    playerState._CurrentlyPlayingType = 'track'
+                    playerState.ItemType = playerState._CurrentlyPlayingType
+                    playerState._Item = Track()
+                    playerState._Item._Name = sonosTrackInfo.get('title','')
+                    playerState._Item._Uri = spotifyUri
+                    playerState._Item._Description = 'Sonos device does not provide a description'
+                    sTimeValue:str = sonosTrackInfo.get('duration',None)
+                    playerState._Item._DurationMS = mediaPositionHMS_toSeconds(sTimeValue) * 1000  # convert h:mm:ss to milliseconds
+                    playerState._Item._Explicit = False
+                    playerState._Item._Href = 'https://api.spotify.com/v1/episodes/' + spotifyId
+                    playerState._Item._HtmlDescription = playerState._Item._Description
+                    playerState._Item._Id = spotifyId
+                    playerState._Item._TrackNumber = sonosTrackInfo.get('playlist_position','')
+                    playerState._Item._ReleaseDate = '0000'
+                    playerState._Item._ReleaseDatePrecision = 'year'
+                    playerState._Item._Type = 'track'
+                    playerState._Item._Album = Album()
+                    playerState._Item._Album._Name = sonosTrackInfo.get('album','')
+                    playerState._Item._Album.Images.append(ImageObject())
+                    playerState._Item._Album.Images[0]._Url = sonosTrackInfo.get('album_art','')
+                    playerState._Item.Artists.append(Artist())
+                    playerState._Item.Artists[0]._Name = sonosTrackInfo.get('artist','')
+                               
+            # set transport actions.
+            currentTransportState:str = sonosTransportInfo.get('current_transport_state','')
+            if currentTransportState == 'PLAYING':
+                playerState._IsPlaying = True
+            elif currentTransportState in ['PAUSED_PLAYBACK','STOPPED']:
+                playerState.Actions._Pausing = True
+                    
+            # only update the following PlayState attributes from SoCo if they are NOT set.
+            # these values are used to set the Sonos PlayMode value, which is the actual value that determines
+            # what the Repeat and Shuffle settings are (ya, it's weird!).  What is odd is that the Spotify
+            # Web API PlayerState values for Shuffle and Repeat can be different than what the Sonos Controller
+            # API (SoCo) report for the device!  This is why we use the Spotify Web API PlayerState values.
+            if playerState._ShuffleState is None:
+                playerState._ShuffleState = sonosPlayer.shuffle
+            if playerState._RepeatState is None:
+                sonosRepeat = sonosPlayer.repeat
+                if sonosRepeat == 'ONE':
+                    playerState._RepeatState = 'track'
+                elif sonosRepeat == False:
+                    playerState._RepeatState = 'off'
+                elif sonosRepeat == True:
+                    playerState._RepeatState = 'context'
+        
+            # trace.
+            _logsi.LogObject(SILevel.Verbose, "Current Spotify player PlayState (built from Sonos device current state) for device: %s" % (scDevice.Title), playerState, excludeNonPublic=True)
+            return playerState
+
+        except SpotifyApiError: raise  # pass handled exceptions on thru
+        except Exception as ex:
+            
+            # format unhandled exception.
+            raise SpotifyApiError(SAAppMessages.UNHANDLED_EXCEPTION.format(apiMethodName, str(ex)), ex, logsi=_logsi)
+
+        finally:
+        
+            # trace.
+            _logsi.LeaveMethod(SILevel.Debug, apiMethodName)
+
+
     def GetPlayerQueueInfo(self) -> PlayerQueueInfo:
         """
         Get the list of objects that make up the user's playback queue.
@@ -9161,7 +9522,7 @@ class SpotifyClient:
     def GetSpotifyConnectDevice(
         self, 
         deviceValue:str, 
-        verifyUserContext:bool=True,    # DEPRECATED
+        verifyUserContext:bool=True,
         verifyTimeout:float=5.0,
         refreshDeviceList:bool=False,
         activateDevice:bool=True,
@@ -9207,7 +9568,7 @@ class SpotifyClient:
         Returns:
             A `SpotifyConnectDevice` object for the deviceValue if one could be resolved.
             otherwise, a null value with the understanding that subsequent operations will probably 
-            fail since it's not in the Spotify Connect discovery list.  
+            fail since it's not in the Spotify Connect device list.  
                 
         Raises:
             SpotifyWebApiError: 
@@ -9244,13 +9605,14 @@ class SpotifyClient:
         apiMethodName:str = 'GetSpotifyConnectDevice'
         apiMethodParms:SIMethodParmListContext = None
         scDevice:SpotifyConnectDevice = None
+        sonosPlayer:SoCo = None
         
         try:
             
             # trace.
             apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
             apiMethodParms.AppendKeyValue("deviceValue", deviceValue)
-            apiMethodParms.AppendKeyValue("verifyUserContext", verifyUserContext)   # DEPRECATED
+            apiMethodParms.AppendKeyValue("verifyUserContext (DEPRECATED)", verifyUserContext)
             apiMethodParms.AppendKeyValue("verifyTimeout", verifyTimeout)
             apiMethodParms.AppendKeyValue("refreshDeviceList", refreshDeviceList)
             apiMethodParms.AppendKeyValue("activateDevice", activateDevice)
@@ -9266,8 +9628,15 @@ class SpotifyClient:
                 refreshDeviceList = False
 
             # resolve the device id from the specified device value.
-            # an exception will be raised if the device could not be resolved!
-            scDevice = self._SpotifyConnectDirectory.GetDevice(deviceValue, refreshDynamicDevices=True)
+            # returned value will be null if the device could not be resolved!
+            scDevice = self._SpotifyConnectDirectory.GetDevice(deviceValue, refreshDynamicDevices=True, raiseExceptionIfNotFound=False)
+
+            # if device could not be resolved, then go no further as it will result in a 
+            # "device not found" error from the Spotify Web API anyway!
+            if (scDevice is None):
+                _logsi.LogVerbose("Spotify Player device was not found, and there is no active Spotify player; no need to re-activate")
+                return None
+
             discovery:ZeroconfDiscoveryResult = scDevice.DiscoveryResult
             info:ZeroconfGetInfo = scDevice.DeviceInfo
             scDevice.WasReConnected = False
@@ -9277,32 +9646,17 @@ class SpotifyClient:
                 _logsi.LogVerbose("Spotify Connect device %s is already active; no need to re-activate" % (scDevice.Title))
                 return scDevice
 
-            # is the device in the player device list? if so, then it's already to be selected.  note that
-            # if another user is controlling the device, then it will not be in the active device list
-            # for the current user.
+            # is the device in the player device list? if so, then it's ready to be selected.
+            # note that if another user is controlling the device, then it will not be in the 
+            # active device list for the current user.
             if (scDevice.IsInDeviceList):
                 _logsi.LogVerbose("Spotify Connect device %s is already in the available device list; no need to re-activate" % (scDevice.Title))
                 return scDevice
 
-            # chromecast devices always require activation if they are not the active device.
-            # note that `transferPlayback=false`, as transfer should be done after we return to caller.
-            if (scDevice.IsChromeCast):
-
-                # activate the spotify cast application on the device.
-                _logsi.LogVerbose("Activating Chromecast Spotify Connect device: %s" % (scDevice.Title))
-                self._SpotifyConnectDirectory.ActivateCastAppSpotify(scDevice.Name, transferPlayback=False)
-
-                # re-fetch device instance, as it has updated Zeroconf Response data.
-                # do not need to refresh from Spotify Web API, as only zeroconf data was changed.
-                scDevice = self._SpotifyConnectDirectory.GetDevice(deviceValue, refreshDynamicDevices=False)
-
-                # return device to caller.
-                return scDevice
-
             # if this is a Sonos device and there is no Spotify Client Application token then don't bother.
             # in this case, we will exit and let the calling method switch to the Sonos device and play 
             # using the Sonos local queue.
-            if (info.IsBrandSonos):
+            if (scDevice.IsSonos):
                         
                 # check if the Spotify Desktop Application Client oauth2 token is defined.
                 hasToken:bool = AuthClient.HasTokenForKey(
@@ -9318,13 +9672,32 @@ class SpotifyClient:
                     _logsi.LogVerbose("Spotify Desktop Application Client oauth2 token was not found for Spotify LoginId: '%s'" % (self._SpotifyConnectLoginId))
                     return scDevice
 
-            # at this point, we will try to activate the device.
-                    
+                # get Sonos Controller instance for the device.
+                _logsi.LogVerbose("Target device is Sonos; getting Sonos Controller instance for device %s" % (scDevice.Title))
+                sonosPlayer = self.SpotifyConnectDirectory.GetSonosPlayer(scDevice)
+
             # was device activation requested?  if not, then we are done.
             if (not activateDevice):
                 _logsi.LogVerbose("Activation not requested for Spotify Connect device: %s" % (scDevice.Title))
                 return scDevice
             
+            # at this point, we will try to activate the device if needed.
+                    
+            # chromecast devices always require activation if they are not the active device.
+            # note that `transferPlayback=false`, as transfer should be done after we return to caller.
+            if (scDevice.IsChromeCast):
+
+                # activate the spotify cast application on the device.
+                _logsi.LogVerbose("Activating Chromecast Spotify Connect device: %s" % (scDevice.Title))
+                self._SpotifyConnectDirectory.ActivateCastAppSpotify(scDevice.Name, transferPlayback=False)
+
+                # re-fetch device instance, as it has updated Zeroconf Response data.
+                # do not need to refresh from Spotify Web API, as only zeroconf data was changed.
+                scDevice = self._SpotifyConnectDirectory.GetDevice(deviceValue, refreshDynamicDevices=False)
+
+                # return device to caller.
+                return scDevice
+
             zcfResult:ZeroconfResponse
 
             # store the currently active user of the device, in case we need to switch users later on.
@@ -9342,87 +9715,20 @@ class SpotifyClient:
                 tokenStorageDir=self.TokenStorageDir,
                 tokenStorageFile=self.TokenStorageFile)
             
-            # what if we DON'T disconnect the device?  
-            # will `Connect` switch the user context?
-
-            # # disconnect the device.
-            # # we will bypass disconnects for librespot devices (e.g. spotifyd, etc), as the
-            # # Spotify Connect Zeroconf `resetUsers` endpoint is not implemented and will
-            # # generate a 404 request response.
-            # if (info.BrandDisplayName != 'librespot'):                       
-
-            #     _logsi.LogVerbose("Issuing Disconnect to Spotify Connect device \"%s\" for current user context \"%s\" (ip=%s:%s)" % (scDevice.Title, oldActiveUser, zconn.HostIpAddress, zconn.HostIpPort))
-            #     zcfResult = zconn.Disconnect(delay)
-
-            #     # delay just a little to give the device time to process the disconnect.
-            #     # some devices only support a single connection on the spotify connect 
-            #     # zeroconf webserver, so we have to give it a little time to process the 
-            #     # disconnect command before we try to call the Connect method.
-            #     _logsi.LogVerbose(TRACE_MSG_DELAY_DEVICE % DELAY_DISCONNECT)
-            #     time.sleep(DELAY_DISCONNECT)
-
-            #     # some manufacturers will reset the device host ip port after a disconnect (e.g. "Denon", etc).
-            #     # due to this, the device will de-register itself via zeroconf and then re-register itself.
-            #     # we will now wait for the device to be re-discovered by zeroconf.
-            #     loopTotalDelay:float = 0
-            #     LOOP_DELAY:float = 0.25
-            #     while True:
-
-            #         # wait just a bit between available device list queries.
-            #         _logsi.LogVerbose(TRACE_MSG_DELAY_DEVICE % LOOP_DELAY)
-            #         time.sleep(LOOP_DELAY)
-            #         loopTotalDelay = loopTotalDelay + LOOP_DELAY
-
-            #         with self._SpotifyConnectDirectory._Zeroconf_Lock:
-
-            #         # check for the device in the available device list.
-            #         # if we find it, then we are done.
-
-            #         device:Device = self.GetPlayerDevice(deviceResultId, True)
-            #         if device is not None:
-            #             _logsi.LogVerbose("Spotify Connect device \"%s\" is now in the available device list; device found within %f seconds of Connect" % (scDevice.Title, loopTotalDelay))
-            #             break
-                        
+            # is this a Sonos device?
+            if (scDevice.IsSonos):
+                               
+                # trace.
+                sonosMusicSource:str = sonosPlayer.music_source
+                _logsi.LogVerbose("Sonos device %s music source before Connect: \"%s\"" % (scDevice.Title, sonosMusicSource))
+
+                # was the Sonos device music source set to SPOTIFY_CONNECT?
+                # if not, then issue a Disconnect to (hopefully) reset the music source. this should allow
+                # the subsequent Connect to re-establish a SPOTIFY_CONNECT music source on the Sonos device.
+                if sonosMusicSource != "SPOTIFY_CONNECT":
+                    _logsi.LogVerbose("Issuing Disconnect to Sonos Spotify Connect device %s" % (scDevice.Title))
+                    zcfResult = zconn.Disconnect(ignoreStatusResult=True)
 
-            #     # re-discover Spotify Connect devices on the network
-            #     _logsi.LogVerbose("Rediscovering Spotify Connect devices on the local network (due to previous disconnect)")
-            #     rediscovery:SpotifyDiscovery = SpotifyDiscovery(self._ZeroconfClient, printToConsole=False)
-            #     rediscovery.DiscoverDevices(timeout=self._SpotifyConnectDiscoveryTimeout)
-
-            #     # trace.
-            #     _logsi.LogDictionary(SILevel.Verbose, "Rediscovered Spotify Connect devices on the local network (due to previous disconnect)", rediscovery.DiscoveryResults, prettyPrint=True)
-
-            #     # process all rediscovered devices, and update selected device.
-            #     rediscovery:ZeroconfDiscoveryResult
-            #     for rediscovery in rediscovery.DiscoveryResults:
-
-            #         # add / update selected device discovery results by serviceinfo key value. 
-            #         if (rediscovery.Key == scDevice.DiscoveryResult.Key):
-
-            #             # save old discovery result id so we can log it later.
-            #             oldDiscoveryResultId:str = discovery.Id
-
-            #             # update selected device discovery result.
-            #             _logsi.LogObject(SILevel.Verbose, "Spotify Connect device \"%s\" DiscoveryResult instance rediscovered properties" % (rediscovery.Id), rediscovery, excludeNonPublic=True)
-            #             _logsi.LogVerbose("Updating Spotify Connect device \"%s\" DiscoveryResult instance with rediscovered properties" % (scDevice.Title))
-            #             scDevice.DiscoveryResult = rediscovery
-            #             discovery = rediscovery
-
-            #             # did the host ip address or port change?
-            #             # if so, then we need to recreate the ZeroconfConnect instance
-            #             # in order to access the updated ip address and port.
-            #             if (discovery.HostIpAddress != zconn.HostIpAddress) \
-            #             or (discovery.HostIpPort != zconn.HostIpPort):
-
-            #                 _logsi.LogVerbose("Spotify Connect device info changed to %s from %s after disconnect; recreating ZeroconfConnect instance" % (discovery.Id, oldDiscoveryResultId))
-            #                 zconn = ZeroconfConnect(discovery.HostIpAddress, 
-            #                                         discovery.HostIpPort, 
-            #                                         discovery.SpotifyConnectCPath,
-            #                                         useSSL=False,
-            #                                         tokenStorageDir=self.TokenStorageDir,
-            #                                         tokenStorageFile=self.TokenStorageFile)
-            #             break
-                    
             # connect the device to OUR Spotify Connect user context.
             # note that the result here only indicates that the connect was submitted - NOT that it was successful!
             _logsi.LogVerbose("Issuing Connect to Spotify Connect device %s for user context \"%s\" (ip=%s:%s)" % (scDevice.Title, self._SpotifyConnectLoginId, zconn.HostIpAddress, zconn.HostIpPort))
@@ -9434,6 +9740,26 @@ class SpotifyClient:
             # trace.
             _logsi.LogVerbose("User context switched from \"%s\" to \"%s\" for Spotify Connect device %s" % (oldActiveUser, self._SpotifyConnectLoginId, scDevice.Title))
 
+            # is this a Sonos device?
+            if (scDevice.IsSonos):
+                               
+                # trace.
+                sonosMusicSource:str = sonosPlayer.music_source
+                _logsi.LogVerbose("Sonos device %s music source after Connect: \"%s\"" % (scDevice.Title, sonosMusicSource))
+
+                # was the Sonos device music source set to Spotify Connect?
+                # if not, then it's a lost cause at this point since it's probably in an UNKNOWN state.
+                if sonosMusicSource != "SPOTIFY_CONNECT":
+                    _logsi.LogVerbose("Sonos device %s music source after Connect is not SPOTIFY_CONNECT; it will probably fail to play" % (scDevice.Title))
+
+                # at this point the Sonos music source should be set to SPOTIFY_CONNECT, and control
+                # transferred to the device.  note that the Sonos device will still NOT appear in the 
+                # player device list, but SHOULD be the active (restricted) device in player state.
+                
+            # wait for the device to enter the Spotify Web API player device list, or
+            # to become the active device.  
+            # Sonos devices are famous for not showing up in the device list, but DO 
+            # appear as the active (restricted) device!
             loopTotalDelay:float = 0
             LOOP_DELAY:float = 0.350
             while True:
@@ -9466,7 +9792,7 @@ class SpotifyClient:
                 # only check so many times before we give up;
                 # we will keep checking until we find the device, or we exceed the verifyTimeout value.
                 if (loopTotalDelay > verifyTimeout):
-                    _logsi.LogWarning("Verification timeout waiting for Spotify Connect device %s to be added to the player device list; device not found within %f seconds of Connect" % (scDevice.Title, verifyTimeout))
+                    _logsi.LogWarning("Verification timeout waiting for Spotify Connect device %s to be added to the player device list or become the active device; device not found within %f seconds of Connect" % (scDevice.Title, verifyTimeout))
                     break
 
             # return the device instance.
@@ -9544,7 +9870,7 @@ class SpotifyClient:
             # trace.
             apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
             apiMethodParms.AppendKeyValue("refresh", refresh)
-            apiMethodParms.AppendKeyValue("sortResult", sortResult) # DEPRECATED
+            apiMethodParms.AppendKeyValue("sortResult (DEPRECATED)", sortResult)
             _logsi.LogMethodParmList(SILevel.Verbose, "Get available Spotify Connect devices", apiMethodParms)
 
             # validations.
@@ -11171,11 +11497,14 @@ class SpotifyClient:
         This method requires the `user-modify-playback-state` scope.
 
         Args:
-            deviceId (str):
-                The id or name of the device this command is targeting.  
-                If not supplied, the user's currently active device is the target.  
-                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`  
-                Example: `Web Player (Chrome)`  
+            deviceId (str | SpotifyConnectDevice) | None):
+                The target player device identifier.
+                This could be an id, name, a default device indicator (e.g. "*"), a 
+                SpotifyConnectDevice object, or null to utilize the active player device.
+                A device is considered resolved if a SpotifyConnectDevice object is passed
+                for this argument.  An exception will be raised if the argument value could 
+                not be resolved or activated.
+                Examples are `0d1841b0976bae2a3a310dd74c0f3df354899bc8`, `Office`, `*`, None.  
             delay (float):
                 Time delay (in seconds) to wait AFTER issuing the command to the player.  
                 This delay will give the spotify web api time to process the change before 
@@ -11215,17 +11544,27 @@ class SpotifyClient:
             delay = validateDelay(delay, 0.50, 10)
 
             # resolve / activate the device object if needed.
-            scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId)
+            scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId, False)
 
-            # build spotify web api request parameters.
-            urlParms:dict = {}
-            urlParms['device_id'] = scDevice.Id
+            # is this an active Sonos device?
+            if (scDevice is not None) and (scDevice.IsSonos):
 
-            # execute spotify web api request.
-            msg:SpotifyApiMessage = SpotifyApiMessage(apiMethodName, '/me/player/pause')
-            msg.RequestHeaders[self.AuthToken.HeaderKey] = self.AuthToken.HeaderValue
-            msg.UrlParameters = urlParms
-            self.MakeRequest('PUT', msg)
+                _logsi.LogVerbose("Issuing command to Sonos device %s: PAUSE" % (scDevice.Title))
+                sonosPlayer:SoCo = self.SpotifyConnectDirectory.GetSonosPlayer(scDevice)
+                sonosPlayer.pause()
+
+            else:
+
+                # build spotify web api request parameters.
+                urlParms:dict = {}
+                if (scDevice is not None):
+                    urlParms['device_id'] = scDevice.Id
+
+                # execute spotify web api request.
+                msg:SpotifyApiMessage = SpotifyApiMessage(apiMethodName, '/me/player/pause')
+                msg.RequestHeaders[self.AuthToken.HeaderKey] = self.AuthToken.HeaderValue
+                msg.UrlParameters = urlParms
+                self.MakeRequest('PUT', msg)
             
             # give spotify web api time to process the change.
             if delay > 0:
@@ -11288,11 +11627,14 @@ class SpotifyClient:
                 player to start playing the next track.  
                 Default is `0`.  
                 Example: `25000`  
-            deviceId (str):
-                The id or name of the device this command is targeting.  
-                If not supplied, the user's currently active device is the target.  
-                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`  
-                Example: `Web Player (Chrome)`  
+            deviceId (str | SpotifyConnectDevice) | None):
+                The target player device identifier.
+                This could be an id, name, a default device indicator (e.g. "*"), a 
+                SpotifyConnectDevice object, or null to utilize the active player device.
+                A device is considered resolved if a SpotifyConnectDevice object is passed
+                for this argument.  An exception will be raised if the argument value could 
+                not be resolved or activated.
+                Examples are `0d1841b0976bae2a3a310dd74c0f3df354899bc8`, `Office`, `*`, None.  
             delay (float):
                 Time delay (in seconds) to wait AFTER issuing the command to the player.  
                 This delay will give the spotify web api time to process the change before 
@@ -11357,7 +11699,7 @@ class SpotifyClient:
             delay = validateDelay(delay, 0.50, 10)
 
             # resolve / activate the device object if needed.
-            scDevice = self._ResolveDeviceObject(deviceId)
+            scDevice = self._ResolveDeviceObject(deviceId, False)
 
             # build spotify web api request parameters.
             reqData:dict = \
@@ -11371,7 +11713,9 @@ class SpotifyClient:
                 reqData['offset'] = { 'position': offsetPosition }
 
             # formulate url parms; will manually add them since we are adding json body as well.
-            urlParms:str = '?device_id=%s' % scDevice.Id
+            urlParms:str = ''
+            if (scDevice is not None):
+                urlParms = '?device_id=%s' % scDevice.Id
 
             # execute spotify web api request.
             msg:SpotifyApiMessage = SpotifyApiMessage(apiMethodName, '/me/player/play{url_parms}'.format(url_parms=urlParms))
@@ -11415,11 +11759,14 @@ class SpotifyClient:
         and starts playing them.
         
         Args:
-            deviceId (str):
-                The id or name of the device this command is targeting.  
-                If not supplied, the user's currently active device is the target.  
-                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`  
-                Example: `Web Player (Chrome)`  
+            deviceId (str | SpotifyConnectDevice) | None):
+                The target player device identifier.
+                This could be an id, name, a default device indicator (e.g. "*"), a 
+                SpotifyConnectDevice object, or null to utilize the active player device.
+                A device is considered resolved if a SpotifyConnectDevice object is passed
+                for this argument.  An exception will be raised if the argument value could 
+                not be resolved or activated.
+                Examples are `0d1841b0976bae2a3a310dd74c0f3df354899bc8`, `Office`, `*`, None.  
             shuffle (bool):
                 True to set player shuffle mode to on; otherwise, False for no shuffle.
             delay (float):
@@ -11497,11 +11844,11 @@ class SpotifyClient:
                 arrUris.append(trackSaved.Track.Uri)
 
             # resolve / activate the device object if needed.
-            scDevice = self._ResolveDeviceObject(deviceId)
+            scDevice = self._ResolveDeviceObject(deviceId, False)
 
             # set desired shuffle mode.
             if (shuffle == True):
-                self.PlayerSetShuffleMode(shuffle, scDevice.Id, delay)
+                self.PlayerSetShuffleMode(shuffle, scDevice, delay)
 
             # play the tracks.
             # indicate device id has already been resolved.
@@ -11551,11 +11898,14 @@ class SpotifyClient:
                 player to start playing the next track.  
                 Default is `0`.  
                 Example: `25000`  
-            deviceId (str):
-                The id or name of the device this command is targeting.  
-                If not supplied, the user's currently active device is the target.  
-                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`  
-                Example: `Web Player (Chrome)`  
+            deviceId (str | SpotifyConnectDevice) | None):
+                The target player device identifier.
+                This could be an id, name, a default device indicator (e.g. "*"), a 
+                SpotifyConnectDevice object, or null to utilize the active player device.
+                A device is considered resolved if a SpotifyConnectDevice object is passed
+                for this argument.  An exception will be raised if the argument value could 
+                not be resolved or activated.
+                Examples are `0d1841b0976bae2a3a310dd74c0f3df354899bc8`, `Office`, `*`, None.  
             delay (float):
                 Time delay (in seconds) to wait AFTER issuing the command to the player.  
                 This delay will give the spotify web api time to process the change before 
@@ -11614,7 +11964,7 @@ class SpotifyClient:
                     arrUris[idx] = arrUris[idx].strip()
         
             # resolve / activate the device object if needed.
-            scDevice = self._ResolveDeviceObject(deviceId)
+            scDevice = self._ResolveDeviceObject(deviceId, False)
 
             # left this here in case we want to implement it in the future.
                     
@@ -11644,7 +11994,9 @@ class SpotifyClient:
                 reqData['uris'] = arrUris
 
             # formulate url parms; will manually add them since we are adding json body as well.
-            urlParms:str = '?device_id=%s' % scDevice.Id
+            urlParms:str = ''
+            if (scDevice is not None):
+                urlParms = '?device_id=%s' % scDevice.Id
 
             # execute spotify web api request.
             msg:SpotifyApiMessage = SpotifyApiMessage(apiMethodName, '/me/player/play{url_parms}'.format(url_parms=urlParms))
@@ -11686,11 +12038,14 @@ class SpotifyClient:
         This method requires the `user-modify-playback-state` scope.
 
         Args:
-            deviceId (str):
-                The id or name of the device this command is targeting.  
-                If not supplied, the user's currently active device is the target.  
-                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`  
-                Example: `Web Player (Chrome)`  
+            deviceId (str | SpotifyConnectDevice) | None):
+                The target player device identifier.
+                This could be an id, name, a default device indicator (e.g. "*"), a 
+                SpotifyConnectDevice object, or null to utilize the active player device.
+                A device is considered resolved if a SpotifyConnectDevice object is passed
+                for this argument.  An exception will be raised if the argument value could 
+                not be resolved or activated.
+                Examples are `0d1841b0976bae2a3a310dd74c0f3df354899bc8`, `Office`, `*`, None.  
             delay (float):
                 Time delay (in seconds) to wait AFTER issuing the command to the player.  
                 This delay will give the spotify web api time to process the change before 
@@ -11707,7 +12062,7 @@ class SpotifyClient:
         This API only works for users who have Spotify Premium. 
         
         The order of execution is not guaranteed when you use this API with other Player API endpoints.
-        
+               
         <details>
           <summary>Sample Code</summary>
         ```python
@@ -11730,17 +12085,27 @@ class SpotifyClient:
             delay = validateDelay(delay, 0.50, 10)
 
             # resolve / activate the device object if needed.
-            scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId)
+            scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId, False)
 
-            # build spotify web api request parameters.
-            urlParms:dict = {}
-            urlParms['device_id'] = scDevice.Id
+            # is this an active Sonos device?
+            if (scDevice is not None) and (scDevice.IsSonos):
 
-            # execute spotify web api request.
-            msg:SpotifyApiMessage = SpotifyApiMessage(apiMethodName, '/me/player/play')
-            msg.RequestHeaders[self.AuthToken.HeaderKey] = self.AuthToken.HeaderValue
-            msg.UrlParameters = urlParms
-            self.MakeRequest('PUT', msg)
+                _logsi.LogVerbose("Issuing command to Sonos device %s: PLAY (RESUME)" % (scDevice.Title))
+                sonosPlayer:SoCo = self.SpotifyConnectDirectory.GetSonosPlayer(scDevice)
+                sonosPlayer.play()
+
+            else:
+
+                # build spotify web api request parameters.
+                urlParms:dict = {}
+                if (scDevice is not None):
+                    urlParms['device_id'] = scDevice.Id
+
+                # execute spotify web api request.
+                msg:SpotifyApiMessage = SpotifyApiMessage(apiMethodName, '/me/player/play')
+                msg.RequestHeaders[self.AuthToken.HeaderKey] = self.AuthToken.HeaderValue
+                msg.UrlParameters = urlParms
+                self.MakeRequest('PUT', msg)
             
             # give spotify web api time to process the change.
             if delay > 0:
@@ -11785,11 +12150,14 @@ class SpotifyClient:
                 Passing in a position that is greater than the length of the track will cause the 
                 player to start playing the next song.  
                 Example = `25000` to start playing at the 25 second mark.  
-            deviceId (str):
-                The id or name of the device this command is targeting.  
-                If not supplied, the user's currently active device is the target.  
-                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`  
-                Example: `Web Player (Chrome)`  
+            deviceId (str | SpotifyConnectDevice) | None):
+                The target player device identifier.
+                This could be an id, name, a default device indicator (e.g. "*"), a 
+                SpotifyConnectDevice object, or null to utilize the active player device.
+                A device is considered resolved if a SpotifyConnectDevice object is passed
+                for this argument.  An exception will be raised if the argument value could 
+                not be resolved or activated.
+                Examples are `0d1841b0976bae2a3a310dd74c0f3df354899bc8`, `Office`, `*`, None.  
             delay (float):
                 Time delay (in seconds) to wait AFTER issuing the command to the player.  
                 This delay will give the spotify web api time to process the change before 
@@ -11855,13 +12223,13 @@ class SpotifyClient:
                 relativePositionMS = 0
 
             # resolve / activate the device object if needed.
-            scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId)
+            scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId, False)
            
             # was relative seeking specified?
-            if (relativePositionMS != 0) and ((positionMS is None) or (positionMS <= 0)):
+            if (scDevice is not None) and (relativePositionMS != 0) and ((positionMS is None) or (positionMS <= 0)):
                 
-                # get current track position.
-                playState:PlayerPlayState = self.GetPlayerPlaybackState()
+                # get current track position (from cache, since we called _ResolveDeviceObject method above).
+                playState:PlayerPlayState = self.GetDevicePlaybackState(scDevice)
                 newPositionMS:int = playState.ProgressMS
                 if (newPositionMS is not None) and (newPositionMS > 0):
                     
@@ -11871,18 +12239,29 @@ class SpotifyClient:
                         newPositionMS = 0
                     positionMS = newPositionMS
 
-            # build spotify web api request parameters.
-            urlParms:dict = \
-            {
-                'position_ms': positionMS
-            }
-            urlParms['device_id'] = scDevice.Id
+            # is this an active Sonos device?
+            if (scDevice is not None) and (scDevice.IsSonos):
 
-            # execute spotify web api request.
-            msg:SpotifyApiMessage = SpotifyApiMessage(apiMethodName, '/me/player/seek')
-            msg.RequestHeaders[self.AuthToken.HeaderKey] = self.AuthToken.HeaderValue
-            msg.UrlParameters = urlParms
-            self.MakeRequest('PUT', msg)
+                sonosPosition:str = mediaPositionHMS_fromSeconds(positionMS / 1000)    # convert from milliseconds to Sonos H:MM:SS format
+                _logsi.LogVerbose("Issuing command to Sonos device %s: SEEK (sonosPosition=%s)" % (scDevice.Title, sonosPosition))
+                sonosPlayer:SoCo = self.SpotifyConnectDirectory.GetSonosPlayer(scDevice)
+                sonosPlayer.seek(str(sonosPosition))
+
+            else:
+
+                # build spotify web api request parameters.
+                urlParms:dict = \
+                {
+                    'position_ms': positionMS
+                }
+                if (scDevice is not None):
+                    urlParms['device_id'] = scDevice.Id
+
+                # execute spotify web api request.
+                msg:SpotifyApiMessage = SpotifyApiMessage(apiMethodName, '/me/player/seek')
+                msg.RequestHeaders[self.AuthToken.HeaderKey] = self.AuthToken.HeaderValue
+                msg.UrlParameters = urlParms
+                self.MakeRequest('PUT', msg)
             
             # give spotify web api time to process the change.
             if delay > 0:
@@ -11918,11 +12297,14 @@ class SpotifyClient:
         This method requires the `user-modify-playback-state` scope.
 
         Args:
-            deviceId (str):
-                The id or name of the device this command is targeting.  
-                If not supplied, the user's currently active device is the target.  
-                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`  
-                Example: `Web Player (Chrome)`  
+            deviceId (str | SpotifyConnectDevice) | None):
+                The target player device identifier.
+                This could be an id, name, a default device indicator (e.g. "*"), a 
+                SpotifyConnectDevice object, or null to utilize the active player device.
+                A device is considered resolved if a SpotifyConnectDevice object is passed
+                for this argument.  An exception will be raised if the argument value could 
+                not be resolved or activated.
+                Examples are `0d1841b0976bae2a3a310dd74c0f3df354899bc8`, `Office`, `*`, None.  
             delay (float):
                 Time delay (in seconds) to wait AFTER issuing the command to the player.  
                 This delay will give the spotify web api time to process the change before 
@@ -11962,17 +12344,27 @@ class SpotifyClient:
             delay = validateDelay(delay, 0.50, 10)
 
             # resolve / activate the device object if needed.
-            scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId)
+            scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId, False)
 
-            # build spotify web api request parameters.
-            urlParms:dict = {}
-            urlParms['device_id'] = scDevice.Id
+            # is this an active Sonos device?
+            if (scDevice is not None) and (scDevice.IsSonos):
 
-            # execute spotify web api request.
-            msg:SpotifyApiMessage = SpotifyApiMessage(apiMethodName, '/me/player/next')
-            msg.RequestHeaders[self.AuthToken.HeaderKey] = self.AuthToken.HeaderValue
-            msg.UrlParameters = urlParms
-            self.MakeRequest('POST', msg)
+                _logsi.LogVerbose("Issuing command to Sonos device %s: NEXT" % (scDevice.Title))
+                sonosPlayer:SoCo = self.SpotifyConnectDirectory.GetSonosPlayer(scDevice)
+                sonosPlayer.next()
+
+            else:
+
+                # build spotify web api request parameters.
+                urlParms:dict = {}
+                if (scDevice is not None):
+                    urlParms['device_id'] = scDevice.Id
+
+                # execute spotify web api request.
+                msg:SpotifyApiMessage = SpotifyApiMessage(apiMethodName, '/me/player/next')
+                msg.RequestHeaders[self.AuthToken.HeaderKey] = self.AuthToken.HeaderValue
+                msg.UrlParameters = urlParms
+                self.MakeRequest('POST', msg)
             
             # give spotify web api time to process the change.
             if delay > 0:
@@ -12008,11 +12400,14 @@ class SpotifyClient:
         This method requires the `user-modify-playback-state` scope.
 
         Args:
-            deviceId (str):
-                The id or name of the device this command is targeting.  
-                If not supplied, the user's currently active device is the target.  
-                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`  
-                Example: `Web Player (Chrome)`  
+            deviceId (str | SpotifyConnectDevice) | None):
+                The target player device identifier.
+                This could be an id, name, a default device indicator (e.g. "*"), a 
+                SpotifyConnectDevice object, or null to utilize the active player device.
+                A device is considered resolved if a SpotifyConnectDevice object is passed
+                for this argument.  An exception will be raised if the argument value could 
+                not be resolved or activated.
+                Examples are `0d1841b0976bae2a3a310dd74c0f3df354899bc8`, `Office`, `*`, None.  
             delay (float):
                 Time delay (in seconds) to wait AFTER issuing the command to the player.  
                 This delay will give the spotify web api time to process the change before 
@@ -12052,17 +12447,27 @@ class SpotifyClient:
             delay = validateDelay(delay, 0.50, 10)
 
             # resolve / activate the device object if needed.
-            scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId)
+            scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId, False)
 
-            # build spotify web api request parameters.
-            urlParms:dict = {}
-            urlParms['device_id'] = scDevice.Id
+            # is this an active Sonos device?
+            if (scDevice is not None) and (scDevice.IsSonos):
 
-            # execute spotify web api request.
-            msg:SpotifyApiMessage = SpotifyApiMessage(apiMethodName, '/me/player/previous')
-            msg.RequestHeaders[self.AuthToken.HeaderKey] = self.AuthToken.HeaderValue
-            msg.UrlParameters = urlParms
-            self.MakeRequest('POST', msg)
+                _logsi.LogVerbose("Issuing command to Sonos device %s: PREVIOUS" % (scDevice.Title))
+                sonosPlayer:SoCo = self.SpotifyConnectDirectory.GetSonosPlayer(scDevice)
+                sonosPlayer.previous()
+
+            else:
+
+                # build spotify web api request parameters.
+                urlParms:dict = {}
+                if (scDevice is not None):
+                    urlParms['device_id'] = scDevice.Id
+
+                # execute spotify web api request.
+                msg:SpotifyApiMessage = SpotifyApiMessage(apiMethodName, '/me/player/previous')
+                msg.RequestHeaders[self.AuthToken.HeaderKey] = self.AuthToken.HeaderValue
+                msg.UrlParameters = urlParms
+                self.MakeRequest('POST', msg)
             
             # give spotify web api time to process the change.
             if delay > 0:
@@ -12105,11 +12510,14 @@ class SpotifyClient:
                 - `context` - will repeat the current context.
                 - `off`     - will turn repeat off.
                 Default: `off`  
-            deviceId (str):
-                The id or name of the device this command is targeting.  
-                If not supplied, the user's currently active device is the target.  
-                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`  
-                Example: `Web Player (Chrome)`  
+            deviceId (str | SpotifyConnectDevice) | None):
+                The target player device identifier.
+                This could be an id, name, a default device indicator (e.g. "*"), a 
+                SpotifyConnectDevice object, or null to utilize the active player device.
+                A device is considered resolved if a SpotifyConnectDevice object is passed
+                for this argument.  An exception will be raised if the argument value could 
+                not be resolved or activated.
+                Examples are `0d1841b0976bae2a3a310dd74c0f3df354899bc8`, `Office`, `*`, None.  
             delay (float):
                 Time delay (in seconds) to wait AFTER issuing the command to the player.  
                 This delay will give the spotify web api time to process the change before 
@@ -12150,20 +12558,47 @@ class SpotifyClient:
             delay = validateDelay(delay, 0.50, 10)
 
             # resolve / activate the device object if needed.
-            scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId)
+            scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId, False)
+
+            # is this an active Sonos device?
+            if (scDevice is not None) and (scDevice.IsSonos):
+
+                # get current Spotify Connect player state.
+                playerState = self.GetPlayerPlaybackStateSonos(scDevice)
+            
+                # set the Sonos PlayMode directly (instead of setting the Sonos repeat property)!
+                # The Spotify Web API PlayerState `ShuffleState` value can sometimes be different than what the
+                # Sonos device reports for its `shuffle` property value!
+                if state == 'track':
+                    sonos_repeat = 'ONE'
+                elif state == 'off':
+                    sonos_repeat = False
+                elif state == 'context':
+                    sonos_repeat = True
+                else:
+                    sonos_repeat = False
+                playMode:str = SONOS_PLAY_MODE_BY_MEANING[(playerState.ShuffleState, sonos_repeat)]
+                
+                # execute SoCo api request.
+                _logsi.LogVerbose("Issuing command to Sonos device %s: REPEAT (playmode=%s)" % (scDevice.Title, playMode))
+                sonosPlayer:SoCo = self.SpotifyConnectDirectory.GetSonosPlayer(scDevice)
+                sonosPlayer.play_mode = playMode
 
-            # build spotify web api request parameters.
-            urlParms:dict = \
-            {
-                'state': state
-            }
-            urlParms['device_id'] = scDevice.Id
+            else:
 
-            # execute spotify web api request.
-            msg:SpotifyApiMessage = SpotifyApiMessage(apiMethodName, '/me/player/repeat')
-            msg.RequestHeaders[self.AuthToken.HeaderKey] = self.AuthToken.HeaderValue
-            msg.UrlParameters = urlParms
-            self.MakeRequest('PUT', msg)
+                # build spotify web api request parameters.
+                urlParms:dict = \
+                {
+                    'state': state
+                }
+                if (scDevice is not None):
+                    urlParms['device_id'] = scDevice.Id
+
+                # execute spotify web api request.
+                msg:SpotifyApiMessage = SpotifyApiMessage(apiMethodName, '/me/player/repeat')
+                msg.RequestHeaders[self.AuthToken.HeaderKey] = self.AuthToken.HeaderValue
+                msg.UrlParameters = urlParms
+                self.MakeRequest('PUT', msg)
             
             # give spotify web api time to process the change.
             if delay > 0:
@@ -12205,11 +12640,14 @@ class SpotifyClient:
                 - `True`  - Shuffle user's playback.
                 - `False` - Do not shuffle user's playback.
                 Default is False
-            deviceId (str):
-                The id or name of the device this command is targeting.  
-                If not supplied, the user's currently active device is the target.  
-                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`  
-                Example: `Web Player (Chrome)`  
+            deviceId (str | SpotifyConnectDevice) | None):
+                The target player device identifier.
+                This could be an id, name, a default device indicator (e.g. "*"), a 
+                SpotifyConnectDevice object, or null to utilize the active player device.
+                A device is considered resolved if a SpotifyConnectDevice object is passed
+                for this argument.  An exception will be raised if the argument value could 
+                not be resolved or activated.
+                Examples are `0d1841b0976bae2a3a310dd74c0f3df354899bc8`, `Office`, `*`, None.  
             delay (float):
                 Time delay (in seconds) to wait AFTER issuing the command to the player.  
                 This delay will give the spotify web api time to process the change before 
@@ -12250,20 +12688,48 @@ class SpotifyClient:
             delay = validateDelay(delay, 0.50, 10)
 
             # resolve / activate the device object if needed.
-            scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId)
+            scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId, False)
+
+            # is this an active Sonos device?
+            if (scDevice is not None) and (scDevice.IsSonos):
+
+                # get current Spotify Connect player state.
+                playerState = self.GetPlayerPlaybackStateSonos(scDevice)
+            
+                # set the Sonos PlayMode directly (instead of setting the Sonos `shuffle` property)!
+                # the Spotify Web API PlayerState `RepeatState` value can sometimes be different than what the
+                # Sonos device reports for its `repeat` property value!
+                sonos_repeat:str
+                if playerState.RepeatState == 'track':
+                    sonos_repeat = 'ONE'
+                elif playerState.RepeatState == 'off':
+                    sonos_repeat = False
+                elif playerState.RepeatState == 'context':
+                    sonos_repeat = True
+                else:   # assume off if nothing else.
+                    sonos_repeat = False
+                playMode:str = SONOS_PLAY_MODE_BY_MEANING[(state, sonos_repeat)]
+                
+                # execute SoCo api request.
+                _logsi.LogVerbose("Issuing command to Sonos device %s: SHUFFLE (playmode=%s)" % (scDevice.Title, playMode))
+                sonosPlayer:SoCo = self.SpotifyConnectDirectory.GetSonosPlayer(scDevice)
+                sonosPlayer.play_mode = playMode
 
-            # build spotify web api request parameters.
-            urlParms:dict = \
-            {
-                'state': state
-            }
-            urlParms['device_id'] = scDevice.Id
+            else:
 
-            # execute spotify web api request.
-            msg:SpotifyApiMessage = SpotifyApiMessage(apiMethodName, '/me/player/shuffle')
-            msg.RequestHeaders[self.AuthToken.HeaderKey] = self.AuthToken.HeaderValue
-            msg.UrlParameters = urlParms
-            self.MakeRequest('PUT', msg)
+                # build spotify web api request parameters.
+                urlParms:dict = \
+                {
+                    'state': state
+                }
+                if (scDevice is not None):
+                    urlParms['device_id'] = scDevice.Id
+
+                # execute spotify web api request.
+                msg:SpotifyApiMessage = SpotifyApiMessage(apiMethodName, '/me/player/shuffle')
+                msg.RequestHeaders[self.AuthToken.HeaderKey] = self.AuthToken.HeaderValue
+                msg.UrlParameters = urlParms
+                self.MakeRequest('PUT', msg)
             
             # give spotify web api time to process the change.
             if delay > 0:
@@ -12304,11 +12770,14 @@ class SpotifyClient:
                 The volume to set.  
                 Must be a value from 0 to 100 inclusive.
                 Example: `50`
-            deviceId (str):
-                The id or name of the device this command is targeting.  
-                If not supplied, the user's currently active device is the target.  
-                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`  
-                Example: `Web Player (Chrome)`  
+            deviceId (str | SpotifyConnectDevice) | None):
+                The target player device identifier.
+                This could be an id, name, a default device indicator (e.g. "*"), a 
+                SpotifyConnectDevice object, or null to utilize the active player device.
+                A device is considered resolved if a SpotifyConnectDevice object is passed
+                for this argument.  An exception will be raised if the argument value could 
+                not be resolved or activated.
+                Examples are `0d1841b0976bae2a3a310dd74c0f3df354899bc8`, `Office`, `*`, None.  
             delay (float):
                 Time delay (in seconds) to wait AFTER issuing the command to the player.  
                 This delay will give the spotify web api time to process the change before 
@@ -12349,20 +12818,30 @@ class SpotifyClient:
             delay = validateDelay(delay, 0.50, 10)
 
             # resolve / activate the device object if needed.
-            scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId)
+            scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId, False)
 
-            # build spotify web api request parameters.
-            urlParms:dict = \
-            {
-                'volume_percent': volumePercent
-            }
-            urlParms['device_id'] = scDevice.Id
+            # is this an active Sonos device?
+            if (scDevice is not None) and (scDevice.IsSonos):
 
-            # execute spotify web api request.
-            msg:SpotifyApiMessage = SpotifyApiMessage(apiMethodName, '/me/player/volume')
-            msg.RequestHeaders[self.AuthToken.HeaderKey] = self.AuthToken.HeaderValue
-            msg.UrlParameters = urlParms
-            self.MakeRequest('PUT', msg)
+                _logsi.LogVerbose("Issuing command to Sonos device %s: VOLUME = %s" % (scDevice.Title, volumePercent))
+                sonosPlayer:SoCo = self.SpotifyConnectDirectory.GetSonosPlayer(scDevice)
+                sonosPlayer.volume = volumePercent
+
+            else:
+
+                # build spotify web api request parameters.
+                urlParms:dict = \
+                {
+                    'volume_percent': volumePercent
+                }
+                if (scDevice is not None):
+                    urlParms['device_id'] = scDevice.Id
+
+                # execute spotify web api request.
+                msg:SpotifyApiMessage = SpotifyApiMessage(apiMethodName, '/me/player/volume')
+                msg.RequestHeaders[self.AuthToken.HeaderKey] = self.AuthToken.HeaderValue
+                msg.UrlParameters = urlParms
+                self.MakeRequest('PUT', msg)
             
             # give spotify web api time to process the change.
             if delay > 0:
@@ -12394,6 +12873,7 @@ class SpotifyClient:
         delay:float=0.50,
         refreshDeviceList:bool=True,
         forceActivateDevice:bool=True,
+        deviceIdFrom:str=None,
         ) -> None:
         """
         Transfer playback to a new Spotify Connect device and optionally begin playback.
@@ -12401,10 +12881,14 @@ class SpotifyClient:
         This method requires the `user-modify-playback-state` scope.
 
         Args:
-            deviceId (str):
-                The id or name of the device on which playback should be started/transferred.
-                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`  
-                Example: `Web Player (Chrome)`  
+            deviceId (str | SpotifyConnectDevice) | None):
+                The target player device identifier.
+                This could be an id, name, a default device indicator (e.g. "*"), a 
+                SpotifyConnectDevice object, or null to utilize the active player device.
+                A device is considered resolved if a SpotifyConnectDevice object is passed
+                for this argument.  An exception will be raised if the argument value could 
+                not be resolved or activated.
+                Examples are `0d1841b0976bae2a3a310dd74c0f3df354899bc8`, `Office`, `*`, None.  
             play (bool):
                 The transfer method:  
                 - `True`  - ensure playback happens on new device.   
@@ -12424,6 +12908,13 @@ class SpotifyClient:
                 force the device to reconnect to Spotify Connect; otherwise, False to not
                 disconnect.
                 Default is True.  
+            deviceIdFrom (str | SpotifyConnectDevice) | None):
+                The player device identifier where play is being transferred from.
+                This could be an id, name, a default device indicator (e.g. "*"), a 
+                SpotifyConnectDevice object, or null.
+                A device is considered resolved if a SpotifyConnectDevice object is passed
+                for this argument.  
+                Examples are `0d1841b0976bae2a3a310dd74c0f3df354899bc8`, `Office`, `*`, None.  
                 
         Raises:
             SpotifyWebApiError: 
@@ -12435,6 +12926,11 @@ class SpotifyClient:
         This API only works for users who have Spotify Premium. 
         
         The order of execution is not guaranteed when you use this API with other Player API endpoints.
+
+        The `deviceIdFrom` argument is not part of the Spotify Web API specification.  If a value
+        was supplied, then we will attempt to stop play on the device if it's needed.  This is required 
+        if transferring playback from a Sonos device that is playing content on its local queue; if you 
+        don't stop playback on it, then it and the target device will both be playing!
         
         <details>
           <summary>Sample Code</summary>
@@ -12456,6 +12952,7 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("delay", delay)
             apiMethodParms.AppendKeyValue("refreshDeviceList", refreshDeviceList)
             apiMethodParms.AppendKeyValue("forceActivateDevice", forceActivateDevice)
+            apiMethodParms.AppendKeyValue("deviceIdFrom", deviceIdFrom)
             _logsi.LogMethodParmList(SILevel.Verbose, "Transfer playback to a new Spotify Connect device", apiMethodParms)
             
             # validations.
@@ -12467,15 +12964,69 @@ class SpotifyClient:
             if (forceActivateDevice is None):
                 forceActivateDevice = True
 
+            # was a from deviceId specified? if so, then we will attempt to stop play on the device
+            # if it's needed.  this is required if transferring playback from a Sonos device that is
+            # playing content on its local queue; if you don't stop playback on it, then it and the
+            # target device will both be playing!
+            if (deviceIdFrom is not None):
+
+                # trace.
+                _logsi.LogVerbose("FROM deviceId supplied; checking to see if we need to pause play on device \"%s\" prior to transferring playback to device \"%s\"" % (deviceIdFrom, deviceId))
+
+                # resolve from device object; no need to activate it for what we want here.
+                scDeviceFrom:SpotifyConnectDevice = self._ResolveDeviceObject(deviceIdFrom, activateDevice=False)
+
+                # if it's a Sonos, then pause the player.
+                # note that for other brands, the Spotify Web API transfer playback takes care of
+                # pausing the player since everything is under the Spotify players control.
+                if (scDeviceFrom is not None) and (scDeviceFrom.IsSonos):
+                    self.PlayerMediaPause(scDeviceFrom)
+
             # resolve / activate the device object if needed.
-            scDevice = self._ResolveDeviceObject(deviceId)
+            # for transfer playback, we will always activate the device.
+            scDevice = self._ResolveDeviceObject(deviceId, True)
+
+            # if device could not be resolved, then go no further as it will result in a 
+            # "device not found" error from the Spotify Web API anyway!
+            if (scDevice is None):
+                raise SpotifyConnectDeviceNotFound("Spotify Player device was not found, and there is no active Spotify player", logsi=_logsi)
 
             # is this a Sonos device? 
             # if so, then control was automatically transferred by activating the device.
-            # note that we also cannot stop nor start play on the device either, as it's
-            # considered a restricted device and the Spotify Web API cannot control it!
-            if scDevice.DeviceInfo.IsBrandSonos:
-                _logsi.LogVerbose('Sonos device detected; bypassing call to Spotify Web API Transfer Playback endpoint')
+            # note that the Spotify Web API cannot stop nor start play on the device either, 
+            # as it's considered a restricted device and the Spotify Web API cannot control it!
+            # all requests to control the device will be made via the Sonos Controller API.
+            if (scDevice.IsSonos):
+
+                # get Sonos Controller instance for the device.
+                sonosPlayer:SoCo = self.SpotifyConnectDirectory.GetSonosPlayer(scDevice)
+
+                # get current Sonos transport status.
+                sonosTransportInfo:dict = sonosPlayer.get_current_transport_info()
+                currentTransportState:str = sonosTransportInfo.get('current_transport_state', None)
+                currentTransportStatus:str = sonosTransportInfo.get('current_transport_status', None)
+                _logsi.LogVerbose("Sonos device %s current transport state after activation: \"%s\" (Status=%s)" % (scDevice.Title, currentTransportState, currentTransportStatus))
+
+                # stop / start play as requested.
+                wasCmdIssued:bool = False
+                if currentTransportState == 'PLAYING':
+                    if play == False:
+                        _logsi.LogVerbose("Issuing command to Sonos device %s: PAUSE" % (scDevice.Title))
+                        sonosPlayer.pause()
+                        wasCmdIssued = True
+                elif currentTransportState in ['PAUSED_PLAYBACK','STOPPED','TRANSITIONING']:
+                    if play == True:
+                        _logsi.LogVerbose("Issuing command to Sonos device %s: PLAY" % (scDevice.Title))
+                        sonosPlayer.play()
+                        wasCmdIssued = True
+                                        
+                # give SoCo api time to process the change.
+                if (wasCmdIssued) and (delay > 0):
+                    _logsi.LogVerbose(TRACE_MSG_DELAY_DEVICE_SONOS % delay)
+                    time.sleep(delay)
+
+                # trace.
+                _logsi.LogVerbose("Sonos device detected (IsRestricted); bypassing call to Spotify Web API Transfer Playback endpoint")
                 return
 
             # before transferring playback to the device, we first need to check to see if anything