PrivateLyricsService

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

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 authentication-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 authentication 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.

set_sp_dc(sp_dc: str = None, *, save: bool = True) → None

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.

set_access_token(access_token: str = None, expiry: datetime | str = None) → None

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.

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

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>
}