spotifywebapiPython 1.0.99__py3-none-any.whl → 1.0.101__py3-none-any.whl

spotifywebapipython/spotifyclient.py

@@ -745,6 +745,7 @@ class SpotifyClient:
                 
             # trace.
             if (msg.HasRequestHeaders):
+                # "User-Agent: Spotify/8.9.76 iOS/18.1 (iPhone17,1)"
                 _logsi.LogCollection(SILevel.Verbose, "SpotifyClient http request: '%s' (headers)" % (url), msg.RequestHeaders.items())
 
             # *** IMPORTANT ***
@@ -1022,7 +1023,7 @@ class SpotifyClient:
                 Example: `5AC9ZXA7nJ7oGWO911FuDG`
             uris (str):  
                 A comma-separated list of Spotify URIs to add; can be track or episode URIs.  
-                Example: `spotify:track:4iV5W9uYEdYUVa79Axb7Rh,spotify:episode:512ojhOuo1ktJprKbVcKyQ`.  
+                Example: `spotify:track:4iV5W9uYEdYUVa79Axb7Rh,spotify:episode:26c0zVyOv1lzfYpBXdh1zC`.  
                 A maximum of 100 items can be specified in one request.
                 If null, the currently playing context uri value is used.
             position (int):  
@@ -5420,7 +5421,7 @@ class SpotifyClient:
         Args:
             episodeId (str):  
                 The Spotify ID for the episode.
-                Example: `512ojhOuo1ktJprKbVcKyQ`
+                Example: `26c0zVyOv1lzfYpBXdh1zC`
                 If null, the currently playing episode uri id value is used; a Spotify Free or Premium account 
                 is required to correctly read the currently playing context.
             market (str):
@@ -6436,10 +6437,12 @@ class SpotifyClient:
                                                                 tokenStorageDir=self.TokenStorageDir,
                                                                 tokenStorageFile=self.TokenStorageFile)
                     
-                        # if a different user context has control of the device then we need to disconnect 
-                        # the current user context before connecting a different user.
-                        if (info.HasActiveUser):
-                            _logsi.LogVerbose("Issuing Disconnect to Spotify Connect device '%s' for user context '%s'" % (scDevice.Title, deviceActiveUser))
+                        # 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'" % (scDevice.Title, deviceActiveUser))
                             zcfResult = zconn.Disconnect(delay)
                             status = status + 'disconnected from user context "%s";' % deviceActiveUser
 
@@ -8650,7 +8653,8 @@ class SpotifyClient:
                 True to refresh the Spotify Connect device list; otherwise, False to use the 
                 Spotify Connect device list cache.
             activateDevice (bool):
-                True to activate the device if necessary; otherwise, False.
+                True to activate the device if necessary; otherwise, False.  
+                Default is True.  
             delay (float):
                 Time delay (in seconds) to wait AFTER issuing any command to the device.  
                 This delay will give the spotify zeroconf api time to process the change before 
@@ -8679,14 +8683,12 @@ class SpotifyClient:
         
         The `SpotifyConnectDevice` object is returned if a match is found; otherwise, a null value is 
         returned.
-        
-        A user context switch will also be performed if a device id is resolved AND the active user of the 
-        device does not match the `SpotifyConnectUsername` argument specified on the class constructor.
-        The user context switch is bypassed if the `verifyUserContext` argument is False, or if the 
-        `SpotifyConnectUsername` was not supplied on the class constructor.  If the user context is to be
-        switched, then a Disconnect will be issued if a user context is active on the device followed by
-        a Connect to the user context specified on the class constructor.
 
+        A Spotify Connect Zeroconf Disconnect (e.g. `resetUsers`) will be issued if the `activateDevice`
+        argument is True, AND the device is not a dynamic device.  This will temporarily remove the device
+        from the Spotify Connect device list, but the device will be re-added when the Connect
+        call is issued.
+        
         <details>
           <summary>Sample Code</summary>
         ```python
@@ -8779,7 +8781,8 @@ class SpotifyClient:
                 # did we resolve the device id?
                 if deviceResult is not None:
                     
-                    # at this point, we will try to activate the device if it requires it.
+                    # at this point, we will try to activate the device if it requires it
+                    # of if the caller forces us to do so (e.g. `activateDevice=True`).
                     
                     # reset device reconnected flag.
                     scDevice.WasReConnected = False
@@ -8824,34 +8827,31 @@ class SpotifyClient:
                     # store the currently active user of the device, in case we need to switch users later on.
                     deviceActiveUser = info.ActiveUser.lower()
 
-                    # was device activation requested?  if not, then we are done.
-                    if activateDevice == False:
-                        _logsi.LogVerbose("Activation not requested for Spotify Connect device: '%s'" % (deviceResult.Title))
-                        break
-                    
                     # is this a dynamic device?  if so, then there is no need to activate it as it's already active.
                     if (discoverResult.IsDynamicDevice):
                         _logsi.LogVerbose("Activation not required for dynamic Spotify Connect device: '%s'" % (deviceResult.Title))
                         break
                     
-                    # did caller request user context switch bypass?
-                    # if so, then just return the device.
-                    if (not verifyUserContext):
-                        _logsi.LogVerbose("User context '%s' will be used for Spotify Connect device '%s', as user chose to bypass user context switch" % (deviceActiveUser, deviceResult.Title))
+                    # was device activation requested?  if not, then we are done.
+                    if (not activateDevice):
+                        _logsi.LogVerbose("Activation not requested for Spotify Connect device: '%s'" % (deviceResult.Title))
                         break
 
+                    zcfResult:ZeroconfResponse
+                                          
                     # was a Spotify Connect user account specified on the class constructor?
-                    # if not, then do not switch the user context.
+                    # if not, then we cannot re-activate the device!
                     if (self._SpotifyConnectUsername is None):
-                        _logsi.LogVerbose("User context '%s' will be used for Spotify Connect device '%s', as a SpotifyConnectUsername parameter was not supplied" % (deviceActiveUser, deviceResult.Title))
+                        raise SpotifyApiError("A SpotifyConnectUsername parameter was not supplied; could not reactivate Spotify Connect device '%s'" % (deviceResult.Title), logsi=_logsi)
+                        #_logsi.LogVerbose("A SpotifyConnectUsername parameter was not supplied; could not reactivate Spotify Connect device '%s'" % (deviceResult.Title))
                         break
-                    
-                    zcfResult:ZeroconfResponse
-                    
-                    # if a different user context has control of the device then we need to disconnect 
-                    # the current user context before connecting a different user.
-                    if (info.HasActiveUser):
-                        _logsi.LogVerbose("Issuing Disconnect to Spotify Connect device '%s' for user context '%s'" % (deviceResult.Title, deviceActiveUser))
+                                       
+                    # 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'" % (deviceResult.Title, deviceActiveUser))
                         zcfResult = zconn.Disconnect(delay)
                     
                     # connect the device to OUR Spotify Connect user context.
@@ -10896,13 +10896,12 @@ class SpotifyClient:
             # has the device id been resolved?
             if (resolveDeviceId):
                 
-                # ensure the specified device id / name is active and available, and
+                # no - ensure the specified device id / name is active and available, and
                 # the user context is set correctly.
                 scDevice = self.GetSpotifyConnectDevice(
                     deviceId, 
                     refreshDeviceList=False, 
-                    activateDevice=True,
-                    verifyUserContext=True)
+                    activateDevice=True)
 
                 # did we find the device?
                 # if so, then use the found device id in case a device name was specified.
@@ -11038,13 +11037,12 @@ class SpotifyClient:
             # has the device id been resolved?
             if (resolveDeviceId):
                 
-                # ensure the specified device id / name is active and available, and
+                # no - ensure the specified device id / name is active and available, and
                 # the user context is set correctly.
                 scDevice = self.GetSpotifyConnectDevice(
                     deviceId, 
                     refreshDeviceList=False, 
-                    activateDevice=True,
-                    verifyUserContext=True)
+                    activateDevice=True)
 
                 # did we find the device?
                 # if so, then use the found device id in case a device name was specified.
@@ -11166,13 +11164,12 @@ class SpotifyClient:
             # has the device id been resolved?
             if (resolveDeviceId):
                 
-                # ensure the specified device id / name is active and available, and
+                # no - ensure the specified device id / name is active and available, and
                 # the user context is set correctly.
                 scDevice = self.GetSpotifyConnectDevice(
                     deviceId, 
                     refreshDeviceList=False, 
-                    activateDevice=True,
-                    verifyUserContext=True)
+                    activateDevice=True)
 
                 # did we find the device?
                 # if so, then use the found device id in case a device name was specified.
@@ -11696,7 +11693,6 @@ class SpotifyClient:
             # call newer method to resolve the device id.
             scDevice:SpotifyConnectDevice = self.GetSpotifyConnectDevice(
                 deviceValue=deviceValue, 
-                verifyUserContext=verifyUserContext, 
                 verifyTimeout=verifyTimeout, 
                 refreshDeviceList=True, 
                 activateDevice=True, 
@@ -12040,6 +12036,7 @@ class SpotifyClient:
             play:bool=True,
             delay:float=0.50,
             refreshDeviceList:bool=True,
+            forceActivateDevice:bool=True,
             ) -> None:
         """
         Transfer playback to a new Spotify Connect device and optionally begin playback.
@@ -12065,6 +12062,11 @@ class SpotifyClient:
                 True to refresh the Spotify Connect device list; otherwise, False to use the 
                 Spotify Connect device list cache.  
                 Default is True.  
+            forceActivateDevice (bool):
+                True to issue a Spotify Connect Disconnect call prior to transfer, which will
+                force the device to reconnect to Spotify Connect; otherwise, False to not
+                disconnect.
+                Default is True.  
                 
         Raises:
             SpotifyWebApiError: 
@@ -12096,6 +12098,7 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("play", play)
             apiMethodParms.AppendKeyValue("delay", delay)
             apiMethodParms.AppendKeyValue("refreshDeviceList", refreshDeviceList)
+            apiMethodParms.AppendKeyValue("forceActivateDevice", forceActivateDevice)
             _logsi.LogMethodParmList(SILevel.Verbose, "Transfer playback to a new Spotify Connect device", apiMethodParms)
             
             # validations.
@@ -12105,9 +12108,8 @@ class SpotifyClient:
             # the user context is set correctly.
             scDevice = self.GetSpotifyConnectDevice(
                 deviceId, 
-                verifyUserContext=True, 
                 refreshDeviceList=refreshDeviceList, 
-                activateDevice=True)
+                activateDevice=forceActivateDevice)
 
             # did we find the device?
             # if so, then use the found device id in case a device name was specified.
@@ -12117,7 +12119,8 @@ class SpotifyClient:
                     
                 # is this a Sonos device? 
                 # if so, then control was automatically transferred by activating the device.
-                # it's a restricted device, so the Spotify Web API cannot control it!
+                # 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')
                     return
@@ -12608,7 +12611,7 @@ class SpotifyClient:
                 Example: `5AC9ZXA7nJ7oGWO911FuDG`
             uris (str):  
                 A comma-separated list of Spotify URIs to remove; can be track or episode URIs.  
-                Example: `spotify:track:4iV5W9uYEdYUVa79Axb7Rh,spotify:episode:512ojhOuo1ktJprKbVcKyQ`.  
+                Example: `spotify:track:4iV5W9uYEdYUVa79Axb7Rh,spotify:episode:26c0zVyOv1lzfYpBXdh1zC`.  
                 A maximum of 100 items can be specified in one request.
                 If null, the currently playing context uri value is used.
             snapshotId (str):  
@@ -13015,7 +13018,7 @@ class SpotifyClient:
                 Example: `5AC9ZXA7nJ7oGWO911FuDG`
             uris (str):  
                 A comma-separated list of Spotify URIs to replace; can be track or episode URIs.  
-                Example: `spotify:track:4iV5W9uYEdYUVa79Axb7Rh,spotify:episode:512ojhOuo1ktJprKbVcKyQ`.  
+                Example: `spotify:track:4iV5W9uYEdYUVa79Axb7Rh,spotify:episode:26c0zVyOv1lzfYpBXdh1zC`.  
                 A maximum of 100 items can be specified in one request.
                 
         Returns:

spotifywebapipython/zeroconfapi/credentials.py

@@ -29,6 +29,9 @@ class Credentials:
         
         # initialize storage.
         self.username: bytes = bytes(username, 'ascii')
-        self.password: bytes = bytes(password, 'ascii')
+        if (isinstance(password, bytes)):
+            self.password: bytes = password
+        else:
+            self.password: bytes = bytes(password, 'ascii')
         self.auth_type: AuthenticationTypes = authenticationType
         

spotifywebapipython/zeroconfapi/helpers.py

@@ -43,6 +43,13 @@ def b64_to_int(value: str):
     return int.from_bytes(b64decode(value), 'big')
 
 
+def b64str_to_bytes(value: str):
+    """
+    Decodes a base64-encoded string to a byte array.
+    """
+    return b64decode(value)
+
+
 def string_to_int(value):
     """
     Converts a string to a big integer.

spotifywebapipython/zeroconfapi/zeroconfconnect.py

@@ -1,5 +1,6 @@
 # external package imports.
 import json
+import os.path
 import requests
 from requests.models import Response
 import time
@@ -7,7 +8,7 @@ import time
 # our package imports.
 from .blobbuilder import BlobBuilder
 from .credentials import Credentials, AuthenticationTypes
-from .helpers import int_to_b64str
+from .helpers import int_to_b64str, b64str_to_bytes
 from .spotifyzeroconfapierror import SpotifyZeroconfApiError
 from .zeroconfresponse import ZeroconfResponse
 from .zeroconfgetinfo import ZeroconfGetInfo
@@ -379,6 +380,12 @@ class ZeroconfConnect:
         .. include:: ../../docs/include/samplecode/ZeroconfConnect/Connect.py
         ```
         </details>
+        <details>
+          <summary>Sample Code - spotifyD</summary>
+        ```python
+        .. include:: ../../docs/include/samplecode/ZeroconfConnect/Connect_SPOTIFYD.py
+        ```
+        </details>
         """
         apiMethodName:str = 'Connect'
         apiMethodParms:SIMethodParmListContext = None
@@ -559,8 +566,37 @@ class ZeroconfConnect:
             if (info.PublicKey == 'SU5WQUxJRA==') and (info.Availability == 'NOT-LOADED'):
                 includeOriginDeviceInfo = True
 
+            # special processing for librespot, spotifyd.
+            if info.ModelDisplayName == 'librespot':
+
+                # we will use credentials from a librespot credentials.json file.
+                # this requires that the user copy the "credentials.json" file from the 
+                # librespot cache location (e.g. "/home/user/.cache/spotifyd/credentials.json", etc)
+                # and place it in the same folder as the token storage file with a new name
+                # of "SpotifyWebApiPython_librespot_credentials.json".
+                
+                # get credentials from librespot credentials file.
+                credentials:dict = self._LoadLibrespotCredentials(loginId)
+                
+                # create credentials and builder objects.
+                librespot_username = credentials.get('username','')
+                librespot_password = b64str_to_bytes(credentials.get('auth_data',''))
+                credentials:Credentials = Credentials(librespot_username, librespot_password, AuthenticationTypes.STORED_SPOTIFY_CREDENTIALS)
+                builder = BlobBuilder(credentials, info.DeviceId, info.PublicKey)
+
+                # set defaults used by this token type:
+                # - clientKey should be the getInfo response PublicKey (base64 encoded).
+                # - include origin device information in the addUser request.
+                # - tokenType should be set to '' (not used by librespot).
+                clientKey:str = builder.dh_keys.PublicKeyBase64String
+                includeOriginDeviceInfo = True
+                tokenType = ''
+            
+                # formulate the blob.
+                blob = builder.build()
+            
             # special processing for tokenType "authorization_code":
-            if info.TokenType == 'authorization_code':
+            elif info.TokenType == 'authorization_code':
 
                 # trace.
                 _logsi.LogVerbose("Spotify Connect token type is '%s' - using Spotify Desktop Client OAuth2 token to connect: '%s' (ip=%s)" % (info.TokenType, info.RemoteName, self._HostIpAddress))
@@ -819,6 +855,90 @@ class ZeroconfConnect:
             _logsi.LeaveMethod(SILevel.Debug, apiMethodName)
 
 
+    def _LoadLibrespotCredentials(self, loginId:str) -> dict:
+        """
+        Loads spotify user credentials from a librespot credentials.json file.
+        
+        Args:
+            loginId (str):
+                Spotify canonical login id of the authenticating user.  
+                Example = `3758dfdsfjk435hjk6k79lm0n3c4`
+        
+        Returns:
+            A credentials dictionary, if one was found in the credentials storage file; 
+            otherwise, null.
+        """
+        apiMethodName:str = '_LoadLibrespotCredentials'
+        apiMethodParms:SIMethodParmListContext = None
+        
+        try:
+
+            # trace.
+            apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
+            _logsi.LogMethodParmList(SILevel.Verbose, "Loading librespot credentials from storage", apiMethodParms)
+               
+            # librespot credntials.json file format as of 2024/09/28
+            # {
+            #   "username": "31l77xxxxxxxxxxxxxxxxxxxxxxx",
+            #   "auth_type": 1,
+            #   "auth_data": "QVFET2h6 ... aFp3OHg="
+            # }
+
+            # formulate the credentials file path.
+            filePath:str = os.path.join(self._TokenStorageDir, "SpotifyWebApiPython_librespot_credentials.json")
+            
+            # does the file exist?  if not, then it's an error as we are trying to authenticate!
+            if (not os.path.exists(filePath)):
+                raise SpotifyApiError("Could not find librespot authorization credentials file (%s).  This file is required in order to authenticate to a device or service that utilizes the librespot application." % (filePath), logsi=_logsi)
+
+            # open the credentials file, and load its contents.
+            _logsi.LogVerbose('Opening librespot credentials file: "%s"' % (filePath))
+            with open(filePath, 'r') as f:
+                credentials:dict = json.load(f)
+                _logsi.LogDictionary(SILevel.Verbose, 'librespot credentials were loaded successfully', credentials, prettyPrint=True)
+    
+            # prepare for comparison.
+            loginId = loginId.lower()
+            credential:dict = None
+
+            # check for multiple credential format.
+            if (isinstance(credentials, list)):
+                
+                # file contents are an array of librespot credentials.
+                for credential in credentials:
+                    if (credential.get('username','').lower() == loginId):
+                        break
+                    
+            else:
+                
+                # file contents are a single librespot credential.
+                credential = credentials
+
+            # does the found credential match the requested login?  if not, then reset the credential.
+            if (credential is not None):
+                if (credential.get('username','').lower() != loginId):
+                    credential = None
+                
+            # if no credentials then it's an error.
+            if (credential is None):
+                raise SpotifyApiError("librespot authorization credentials file (%s) did not contain credentials for canonical loginid (%s)." % (filePath, loginId), logsi=_logsi)
+                
+            # return credentials to caller.
+            return credential
+
+        except SpotifyApiError: raise  # pass handled exceptions on thru
+        except Exception as ex:
+            
+            # trace.
+            _logsi.LogException('Could not load librespot authorization credentials file (%s).' % (filePath), ex)
+            raise
+
+        finally:
+        
+            # trace.
+            _logsi.LeaveMethod(SILevel.Debug, apiMethodName)
+
+
     def Disconnect(
             self,
             delay:float=0.50,
@@ -848,6 +968,10 @@ class ZeroconfConnect:
 
         The currently logged in user (if any) will be logged out of Spotify Connect, and the 
         device id removed from the active Spotify Connect device list.  
+        
+        This method should not be attempted for devices or services that utilize `librespot`,
+        such as `spotifyd`.  The `librespot` library does not implement the `resetUsers`
+        Spotify Connect Zeroconf endpoint, and will fail with a 404 error.
 
         <details>
           <summary>Sample Code</summary>