PrivateLyricsService#

class minim.spotify.PrivateLyricsService(*, sp_dc: str = None, access_token: str = None, expiry: datetime | str = None, save: bool = True)[source]#

Bases: object

Spotify Lyrics service client.

The Spotify Lyrics service, which is powered by Musixmatch (or PetitLyrics in Japan), provides line- or word-synced lyrics for Spotify tracks when available. The Spotify Lyrics interface is not publicly documented, so its endpoints have been determined by watching HTTP network traffic.

Attention

As the Spotify Lyrics service is not designed to be publicly accessible, this class can be disabled or removed at any time to ensure compliance with the Spotify Developer Terms of Service.

Requests to the Spotify Lyrics endpoints must be accompanied by a valid access token in the header. An access token can be obtained using the Spotify Web Player sp_dc cookie, which must either be provided to this class’s constructor as a keyword argument or be stored as SPOTIFY_SP_DC in the operating system’s environment variables.

Hint

The sp_dc cookie can be extracted from the local storage of your web browser after you log into Spotify.

If an existing access token is available, it and its expiry time can be provided to this class’s constructor as keyword arguments to bypass the access token exchange process. It is recommended that all other authorization-related keyword arguments be specified so that a new access token can be obtained when the existing one expires.

Tip

The sp_dc cookie and access token can be changed or updated at any time using set_sp_dc() and set_access_token(), respectively.

Minim also stores and manages access tokens and their properties. When an access token is acquired, it is automatically saved to the Minim configuration file to be loaded on the next instantiation of this class. This behavior can be disabled if there are any security concerns, like if the computer being used is a shared device.

Parameters:

sp_dcstr, optional: Spotify Web Player sp_dc cookie. If it is not stored as SPOTIFY_SP_DC in the operating system’s environment variables or found in the Minim configuration file, it must be provided here.
access_tokenstr, keyword-only, optional: Access token. If provided here or found in the Minim configuration file, the authorization process is bypassed. In the former case, all other relevant keyword arguments should be specified to automatically refresh the access token when it expires.
expirydatetime.datetime or str, keyword-only, optional: Expiry time of access_token in the ISO 8601 format %Y-%m-%dT%H:%M:%SZ. If provided, the user will be reauthenticated when access_token expires.
savebool, keyword-only, default: True: Determines whether newly obtained access tokens and their associated properties are stored to the Minim configuration file.

Attributes:

LYRICS_URLstr: Base URL for the Spotify Lyrics service.
TOKEN_URLstr: URL for the Spotify Web Player access token endpoint.
sessionrequests.Session: Session used to send requests to the Spotify Lyrics service.

Methods

`get_lyrics`	Get lyrics for a Spotify track.
`set_access_token`	Set the Spotify Lyrics service access token.
`set_sp_dc`	Set the Spotify Web Player `sp_dc` cookie.

get_lyrics(track_id: str) → dict[str, Any][source]#

Get lyrics for a Spotify track.

Parameters:

track_idstr

The Spotify ID for the track.

Example: "0VjIjW4GlUZAMYd2vXMi3b".

Returns:

lyricsdict

Formatted or time-synced lyrics.

Sample response

{
  "lyrics": {
    "syncType": <str>,
    "lines": [
      {
        "startTimeMs": <str>,
        "words": <str>,
        "syllables": [],
        "endTimeMs": <str>
      }
    ],
    "provider": <str>,
    "providerLyricsId": <str>,
    "providerDisplayName": <str>,
    "syncLyricsUri": <str>,
    "isDenseTypeface": <bool>,
    "alternatives": [],
    "language": <str>,
    "isRtlLanguage": <bool>,
    "fullscreenAction": <str>,
    "showUpsell": <bool>
  },
  "colors": {
    "background": <int>,
    "text": <int>,
    "highlightText": <int>
  },
  "hasVocalRemoval": <bool>
}

set_access_token(access_token: str = None, expiry: datetime | str = None) → None[source]#

Set the Spotify Lyrics service access token.

Parameters:

access_tokenstr, optional: Access token. If not provided, an access token is obtained from the Spotify Web Player using the sp_dc cookie.
expirystr or datetime.datetime, keyword-only, optional: Access token expiry timestamp in the ISO 8601 format %Y-%m-%dT%H:%M:%SZ. If provided, the user will be reauthenticated (if sp_dc is found or provided) when the access_token expires.

set_sp_dc(sp_dc: str = None, *, save: bool = True) → None[source]#

Set the Spotify Web Player sp_dc cookie.

Parameters:

sp_dcstr, optional: Spotify Web Player sp_dc cookie.
savebool, keyword-only, default: True: Determines whether to save the newly obtained access tokens and their associated properties to the Minim configuration file.