PrivateAPI

class minim.tidal.PrivateAPI(*, client_id: str = None, client_secret: str = None, flow: str = None, browser: bool = False, scopes: str | list[str] = 'r_usr', user_agent: str = None, access_token: str = None, refresh_token: str = None, expiry: datetime = None, overwrite: bool = False, save: bool = True)

Bases: object

Private TIDAL API client.

The private TIDAL API allows media (tracks, videos), collections (albums, playlists), and performers to be queried, and information about them to be retrieved. As there is no available official documentation for the private TIDAL API, its endpoints have been determined by watching HTTP network traffic.

Attention

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

While authentication is not necessary to search for and retrieve data from public content, it is required to access personal content and stream media (with an active TIDAL subscription). In the latter case, requests to the private TIDAL API endpoints must be accompanied by a valid user access token in the header.

Minim can obtain user access tokens via the authorization code with proof key for code exchange (PKCE) and device code flows. These OAuth 2.0 authorization flows require valid client credentials (client ID and client secret) to either be provided to this class’s constructor as keyword arguments or be stored as TIDAL_PRIVATE_CLIENT_ID and TIDAL_PRIVATE_CLIENT_SECRET in the operating system’s environment variables.

Hint

Client credentials can be extracted from the software you use to access TIDAL, including but not limited to the TIDAL Web Player and the Android, iOS, macOS, and Windows applications. Only the TIDAL Web Player and desktop application client credentials can be used without authorization.

If an existing access token is available, it and its accompanying information (refresh token and expiry time) can be provided to this class’s constructor as keyword arguments to bypass the access token retrieval 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 authorization flow and access token can be changed or updated at any time using set_flow() 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:

client_idstr, keyword-only, optional

Client ID. If it is not stored as TIDAL_PRIVATE_CLIENT_ID in the operating system’s environment variables or found in the Minim configuration file, it must be provided here.

client_secretstr, keyword-only, optional

Client secret. Required for the authorization code and device code flows. If it is not stored as TIDAL_PRIVATE_CLIENT_SECRET in the operating system’s environment variables or found in the Minim configuration file, it must be provided here.

flowstr, keyword-only, optional

Authorization flow. If not specified, no user authorization will be performed.

Valid values:

• "pkce" for the authorization code with proof key for code exchange (PKCE) flow.

• "device_code" for the device code flow.

browserbool, keyword-only, default: False

Determines whether a web browser is automatically opened for the authorization code with PKCE or device code flows. If False, users will have to manually open the authorization URL, and for the authorization code flow, provide the full callback URI via the terminal. For the authorization code with PKCE flow, the Playwright framework by Microsoft is used.

scopesstr or list, keyword-only, default: "r_usr"

Authorization scopes to request user access for in the OAuth 2.0 flows.

Valid values: "r_usr", "w_usr", and "w_sub" (device code flow only).

user_agentstr, keyword-only, optional

User agent information to send in the header of HTTP requests.

Note

If not specified, TIDAL may temporarily block your IP address if you are making requests too quickly.

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.

refresh_tokenstr, keyword-only, optional

Refresh token accompanying access_token. If not provided, the user will be reauthenticated using the specified authorization flow when access_token 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 using refresh_token (if available) or the specified authorization flow (if possible) when access_token expires.

overwritebool, keyword-only, default: False

Determines whether to overwrite an existing access token in the Minim configuration file.

savebool, keyword-only, default: True

Determines whether newly obtained access tokens and their associated properties are stored to the Minim configuration file.

Attributes:

API_URLstr

Base URL for the private TIDAL API.

AUTH_URLstr

URL for device code requests.

LOGIN_URLstr

URL for authorization code requests.

REDIRECT_URLstr

URL for authorization code callbacks.

RESOURCES_URLstr

URL for cover art and image requests.

TOKEN_URLstr

URL for access token requests.

WEB_URLstr

URL for the TIDAL Web Player.

sessionrequests.Session

Session used to send requests to the private TIDAL API.

Methods

add_playlist_items	Add items to a playlist owned by the current user.
block_artist	Block an artist from appearing in mixes and the radio.
block_user	Block a user.
create_playlist	Create a user playlist.
create_playlist_folder	Create a user playlist folder.
delete_playlist	Delete a playlist owned by the current user.
delete_playlist_folder	Delete a playlist folder owned by the current user.
delete_playlist_item	Delete an item from a playlist owned by the current user.
favorite_albums	Add albums to the current user's collection.
favorite_artists	Add artists to the current user's collection.
favorite_mixes	Add mixes to the current user's collection.
favorite_playlists	Add playlists to the current user's collection.
favorite_tracks	Add tracks to the current user's collection.
favorite_videos	Add videos to the current user's collection.
follow_user	Follow a user.
get_album	Get TIDAL catalog information for an album.
get_album_credits	Get credits for an album.
get_album_items	Get TIDAL catalog information for items (tracks and videos) in an album.
get_album_page	Get the TIDAL page for an album.
get_album_review	Get a review of or a synopsis for an album.
get_artist	Get TIDAL catalog information for an artist.
get_artist_albums	Get TIDAL catalog information for albums by an artist.
get_artist_biography	Get an artist's biographical information.
get_artist_links	Get links to websites associated with an artist.
get_artist_mix_id	Get the ID of a curated mix of tracks based on an artist's works.
get_artist_page	Get the TIDAL page for an artist.
get_artist_radio	Get TIDAL catalog information for tracks inspired by an artist's works.
get_artist_top_tracks	Get TIDAL catalog information for an artist's top tracks.
get_artist_videos	Get TIDAL catalog information for an artist's videos.
get_blocked_artists	Get TIDAL catalog information for the current user's blocked artists.
get_blocked_users	Get users blocked by the current user.
get_collection_streams	Get audio and video stream data for items (tracks and videos) in an album, mix, or playlist.
get_country_code	Get the country code based on the current IP address.
get_favorite_albums	Get TIDAL catalog information for albums in the current user's collection.
get_favorite_artists	Get TIDAL catalog information for artists in the current user's collection.
get_favorite_ids	Get TIDAL IDs or UUIDs of the albums, artists, playlists, tracks, and videos in the current user's collection.
get_favorite_mixes	Get TIDAL catalog information for or IDs of mixes in the current user's collection.
get_favorite_tracks	Get TIDAL catalog information for tracks in the current user's collection.
get_favorite_videos	Get TIDAL catalog information for videos in the current user's collection.
get_image	Get (animated) cover art or image for a TIDAL item.
get_mix_items	Get TIDAL catalog information for items (tracks and videos) in a mix.
get_mix_page	Get the TIDAL page for a mix.
get_personal_playlist_folders	Get TIDAL catalog information for a playlist folder (and optionally, playlists and other playlist folders in it) created by the current user.
get_personal_playlists	Get TIDAL catalog information for playlists created by the current user.
get_playlist	Get TIDAL catalog information for a playlist.
get_playlist_etag	Get the entity tag (ETag) for a playlist.
get_playlist_items	Get TIDAL catalog information for items (tracks and videos) in a playlist.
get_playlist_recommendations	Get TIDAL catalog information for recommended tracks based on a playlist's items.
get_profile	Get the current user's profile information.
get_session	Get information about the current private TIDAL API session.
get_similar_albums	Get TIDAL catalog information for albums similar to the specified album.
get_similar_artists	Get TIDAL catalog information for artists similar to a specified artist.
get_track	Get TIDAL catalog information for a track.
get_track_composers	Get the composers, lyricists, and/or songwriters of a track.
get_track_contributors	Get the contributors to a track and their roles.
get_track_credits	Get credits for a track.
get_track_lyrics	Get lyrics for a track.
get_track_mix_id	Get the curated mix of tracks based on a track.
get_track_playback_info	Get playback information for a track.
get_track_recommendations	Get TIDAL catalog information for a track's recommended tracks and videos.
get_track_stream	Get the audio stream data for a track.
get_user_followers	Get a TIDAL user's followers.
get_user_following	Get the people (artists, users, etc.) a TIDAL user follows.
get_user_playlist	Get TIDAL catalog information for a user playlist.
get_user_playlists	Get TIDAL catalog information for playlists created by a TIDAL user.
get_user_profile	Get a TIDAL user's profile information.
get_video	Get TIDAL catalog information for a video.
get_video_page	Get the TIDAL page for a video.
get_video_playback_info	Get playback information for a video.
get_video_stream	Get the video stream data for a music video.
move_playlist	Move a playlist in the current user's collection.
move_playlist_item	Move an item in a playlist owned by the current user.
search	Search for albums, artists, tracks, and videos.
set_access_token	Set the private TIDAL API access token.
set_flow	Set the authorization flow.
set_playlist_privacy	Set the privacy of a playlist owned by the current user.
unblock_artist	Unblock an artist from appearing in mixes and the radio.
unblock_user	Unblock a user.
unfavorite_albums	Remove albums from the current user's collection.
unfavorite_artists	Remove artists from the current user's collection.
unfavorite_mixes	Remove mixes from the current user's collection.
unfavorite_playlist	Remove a playlist from the current user's collection.
unfavorite_tracks	Remove tracks from the current user's collection.
unfavorite_videos	Remove videos from the current user's collection.
unfollow_user	Unfollow a user.
update_playlist	Update the title or description of a playlist owned by the current user.

add_playlist_items(playlist_uuid: str, items: int | str | list[int | str] = None, *, from_playlist_uuid: str = None, on_duplicate: str = 'FAIL', on_artifact_not_found: str = 'FAIL') → None

Add items to a playlist owned by the current user.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

playlist_uuidstr

TIDAL playlist UUID.

Example: "e09ab9ce-2e87-41b8-b404-3cd712bf706e".

itemsint, str, or list, optional

Items to add to the playlist. If not specified, from_playlist_uuid must be provided.

Note

If both items and from_playlist_uuid are specified, only the items in items will be added to the playlist.

from_playlist_uuidstr, keyword-only, optional

TIDAL playlist from which to copy items.

on_duplicatestr, keyword-only, default: "FAIL"

Behavior when the item to be added is already in the playlist.

Valid values: "ADD", "SKIP", and "FAIL".

on_artifact_not_foundstr, keyword-only, default: "FAIL"

Behavior when the item to be added does not exist.

Valid values: "FAIL".

block_artist(artist_id: int | str) → None

Block an artist from appearing in mixes and the radio.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

artist_idint or str

TIDAL artist ID.

Example: 1566.

block_user(user_id: int | str) → None

Block a user.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

user_idint or str

TIDAL user ID.

Example: 172311284.

create_playlist(name: str, *, description: str = None, folder_uuid: str = 'root', public: bool = None) → dict[str, Any]

Create a user playlist.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

namestr

Playlist name.

descriptionstr, keyword-only, optional

Brief playlist description.

folder_uuidstr, keyword-only, default: "root"

UUID of the folder the new playlist will be placed in. To place a playlist directly under “My Playlists”, use folder_id="root".

publicbool, keyword-only, optional

Determines whether the playlist is public (True) or private (False).

Returns:

playlistdict

TIDAL catalog information for the newly created playlist.

Sample response

{
  "trn": <str>,
  "itemType": "PLAYLIST",
  "addedAt": <str>,
  "lastModifiedAt": <str>,
  "name": <str>,
  "parent": <str>,
  "data": {
    "uuid": <str>,
    "type": "USER",
    "creator": {
      "id": <int>,
      "name": <str>,
      "picture": <str>,
      "type": "USER"
    },
    "contentBehavior": <str>,
    "sharingLevel": <str>,
    "status": "READY",
    "source": <str>,
    "title": <str>,
    "description": <str>,
    "image": <str>,
    "squareImage": <str>,
    "url": <str>,
    "created": <str>,
    "lastUpdated": <str>,
    "lastItemAddedAt": <str>,
    "duration": <int>,
    "numberOfTracks": <int>,
    "numberOfVideos": <int>,
    "promotedArtists": <list>,
    "trn": <str>,
    "itemType": "PLAYLIST"
  }
}

create_playlist_folder(name: str, *, folder_uuid: str = 'root') → None

Create a user playlist folder.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

namestr

Playlist folder name.

folder_uuidstr, keyword-only, default: "root"

UUID of the folder in which the new playlist folder should be created in. To create a folder directly under “My Playlists”, use folder_id="root".

delete_playlist(playlist_uuid: str) → None

Delete a playlist owned by the current user.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

playlist_uuidstr

TIDAL playlist UUID.

Example: "e09ab9ce-2e87-41b8-b404-3cd712bf706e".

delete_playlist_folder(folder_uuid: str) → None

Delete a playlist folder owned by the current user.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

folder_uuidstr

TIDAL playlist folder UUID.

Example: "92b3c1ea-245a-4e5a-a5a4-c215f7a65b9f".

delete_playlist_item(playlist_uuid: str, index: int | str) → None

Delete an item from a playlist owned by the current user.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

playlist_uuidstr

TIDAL playlist UUID.

Example: "e09ab9ce-2e87-41b8-b404-3cd712bf706e".

indexint or str

Item index.

favorite_albums(album_ids: int | str | list[int | str], country_code: str = None, *, on_artifact_not_found: str = 'FAIL') → None

Add albums to the current user’s collection.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

album_idsint, str, or list

TIDAL album ID(s).

Examples: "251380836,275646830" or [251380836, 275646830].

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

on_artifact_not_foundstr, keyword-only, default: "FAIL"

Behavior when the item to be added does not exist.

Valid values: "FAIL" or "SKIP".

favorite_artists(artist_ids: int | str | list[int | str], country_code: str = None, *, on_artifact_not_found: str = 'FAIL') → None

Add artists to the current user’s collection.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

artist_idsint, str, or list

TIDAL artist ID(s).

Examples: "1566,7804" or [1566, 7804].

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

on_artifact_not_foundstr, keyword-only, default: "FAIL"

Behavior when the item to be added does not exist.

Valid values: "FAIL" or "SKIP".

favorite_mixes(mix_ids: str | list[str], *, on_artifact_not_found: str = 'FAIL') → None

Add mixes to the current user’s collection.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

mix_idsstr or list

TIDAL mix ID(s).

Examples: "000ec0b01da1ddd752ec5dee553d48,            000dd748ceabd5508947c6a5d3880a" or ["000ec0b01da1ddd752ec5dee553d48", "000dd748ceabd5508947c6a5d3880a"]

on_artifact_not_foundstr, keyword-only, default: "FAIL"

Behavior when the item to be added does not exist.

Valid values: "FAIL" or "SKIP".

favorite_playlists(playlist_uuids: str | list[str], *, folder_id: str = 'root') → None

Add playlists to the current user’s collection.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

playlist_uuidsstr or list

TIDAL playlist UUID(s).

Example: ["36ea71a8-445e-41a4-82ab-6628c581535d", "4261748a-4287-4758-aaab-6d5be3e99e52"].

folder_idstr, keyword-only, default: "root"

ID of the folder to move the playlist into. To place a playlist directly under “My Playlists”, use folder_id="root".

favorite_tracks(track_ids: int | str | list[int | str], country_code: str = None, *, on_artifact_not_found: str = 'FAIL') → None

Add tracks to the current user’s collection.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

track_idsint, str, or list

TIDAL track ID(s).

Examples: "251380837,251380838" or [251380837, 251380838].

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

on_artifact_not_foundstr, keyword-only, default: "FAIL"

Behavior when the item to be added does not exist.

Valid values: "FAIL" or "SKIP".

favorite_videos(video_ids: int | str | list[int | str], country_code: str = None, *, on_artifact_not_found: str = 'FAIL') → None

Add videos to the current user’s collection.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

video_idsint, str, or list

TIDAL video ID(s).

Examples: "59727844,75623239" or [59727844, 75623239].

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

on_artifact_not_foundstr, keyword-only, default: "FAIL"

Behavior when the item to be added does not exist.

Valid values: "FAIL" or "SKIP".

follow_user(user_id: int | str) → None

Follow a user.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

user_idint or str

TIDAL user ID.

Example: 172311284.

get_album(album_id: int | str, country_code: str = None) → dict[str, Any]

Get TIDAL catalog information for an album.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

album_idint or str

TIDAL album ID.

Example: 251380836.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

Returns:

albumdict

TIDAL catalog information for an album.

Sample response

{
  "id": <int>,
  "title": <str>,
  "duration": <int>,
  "streamReady": <bool>,
  "adSupportedStreamReady": <bool>,
  "djReady": <bool>,
  "stemReady": <bool>,
  "streamStartDate": <str>,
  "allowStreaming": <bool>,
  "premiumStreamingOnly": <bool>,
  "numberOfTracks": <int>,
  "numberOfVideos": <int>,
  "numberOfVolumes": <int>,
  "releaseDate": <str>,
  "copyright": <str>,
  "type": "ALBUM",
  "version": <str>,
  "url": <str>,
  "cover": <str>,
  "vibrantColor": <str>,
  "videoCover": <str>,
  "explicit": <bool>,
  "upc": <str>,
  "popularity": <int>,
  "audioQuality": <str>,
  "audioModes": [<str>],
  "mediaMetadata": {
    "tags": [<str>]
  },
  "artist": {
    "id": <int>,
    "name": <str>,
    "type": <str>,
    "picture": <str>
  },
  "artists": [
    {
      "id": <int>,
      "name": <str>,
      "type": <str>,
      "picture": <str>
    }
  ]
}

get_album_credits(album_id: int | str, country_code: str = None) → dict[str, Any]

Get credits for an album.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

album_idint or str

TIDAL album ID.

Example: 251380836.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

Returns:

creditsdict

A dictionary containing TIDAL catalog information for the album contributors.

Sample response

[
  {
    "type": <str>,
    "contributors": [
      {
        "name": <str>
      }
    ]
  }
]

get_album_items(album_id: int | str, country_code: str = None, *, limit: int = 100, offset: int = None, credits: bool = False) → dict[str, Any]

Get TIDAL catalog information for items (tracks and videos) in an album.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

album_idint or str

TIDAL album ID.

Examples: 251380836.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

limitint, keyword-only, default: 100

Page size.

Example: 10.

offsetint, keyword-only, optional

Pagination offset (in number of items).

Example: 0.

creditsbool, keyword-only, default: False

Determines whether credits for each item is returned.

Returns:

itemsdict

A dictionary containing TIDAL catalog information for tracks and videos in the specified album and metadata for the returned results.

Sample response

{
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>,
  "items": [
    {
      "item": {
        "id": <int>,
        "title": <str>,
        "duration": <int>,
        "replayGain": <float>,
        "peak": <float>,
        "allowStreaming": <bool>,
        "streamReady": <bool>,
        "adSupportedStreamReady": <bool>,
        "djReady": <bool>,
        "stemReady": <bool>,
        "streamStartDate": <str>,
        "premiumStreamingOnly": <bool>,
        "trackNumber": <int>,
        "volumeNumber": >int>,
        "version": <str>,
        "popularity": <int>,
        "copyright": <str>,
        "url": <str>,
        "isrc": <str>,
        "editable": <bool>,
        "explicit": <bool>,
        "audioQuality": <str>,
        "audioModes": [<str>],
        "mediaMetadata": {
          "tags": [<str>]
        },
        "artist": {
          "id": <int>,
          "name": <str>,
          "type": <str>,
          "picture": <str>
        },
        "artists": [
          {
            "id": <int>,
            "name": <str>,
            "type": <str>,
            "picture": <str>
          }
        ],
        "album": {
          "id": <int>,
          "title": <str>,
          "cover": <str>,
          "vibrantColor": <str>,
          "videoCover": <str>
        },
        "mixes": {
          "TRACK_MIX": <str>
        }
      },
      "type": "track"
    }
  ]
}

get_album_page(album_id: int | str, country_code: str = None, *, device_type: str = 'BROWSER') → dict[str, Any]

Get the TIDAL page for an album.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

album_idint or str

TIDAL album ID.

Example: 251380836.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

device_typestr, keyword-only, default: "BROWSER"

Device type.

Valid values:

• "BROWSER" for a web browser.

• "DESKTOP" for the desktop TIDAL application.

• "PHONE" for the mobile TIDAL application.

• "TV" for the smart TV TIDAL application.

Returns:

pagedict

A dictionary containing the page ID, title, and submodules.

get_album_review(album_id: int | str, country_code: str = None) → dict[str, str]

Get a review of or a synopsis for an album.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

album_idint or str

TIDAL album ID.

Example: 251380836.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

Returns:

reviewdict

A dictionary containing a review of or a synopsis for an album and its source.

Sample response

{
  "source": <str>,
  "lastUpdated": <str>,
  "text": <str>,
  "summary": <str>
}

get_artist(artist_id: int | str, country_code: str = None) → dict[str, Any]

Get TIDAL catalog information for an artist.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

artist_idint or str

TIDAL artist ID.

Example: 1566.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

Returns:

artistdict

TIDAL catalog information for an artist.

Sample response

{
  "id": <int>,
  "name": <str>,
  "artistTypes": [<str>],
  "url": <str>,
  "picture": <str>,
  "popularity": <int>,
  "artistRoles": [
    {
      "categoryId": <int>,
      "category": <str>
    }
  ],
  "mixes": {
    "ARTIST_MIX": <str>
  }
}

get_artist_albums(artist_id: int | str, country_code: str = None, *, filter: str = None, limit: int = 100, offset: int = None) → dict[str, Any]

Get TIDAL catalog information for albums by an artist.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

artist_idint or str

TIDAL artist ID.

Example: 1566.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

filterstr, keyword-only, optional

Subset of albums to retrieve.

Valid values: "EPSANDSINGLES" and "COMPILATIONS".

limitint, keyword-only, default: 100

Page size.

Example: 10.

offsetint, keyword-only, optional

Pagination offset (in number of items).

Example: 0.

Returns:

albumsdict

A dictionary containing TIDAL catalog information for albums by the specified artist and metadata for the returned results.

Sample response

{
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>,
  "items": [
    {
      "id": <int>,
      "title": <str>,
      "duration": <int>,
      "streamReady": <bool>,
      "adSupportedStreamReady": <bool>,
      "djReady": <bool>,
      "stemReady": <bool>,
      "streamStartDate": <str>,
      "allowStreaming": <bool>,
      "premiumStreamingOnly": <bool>,
      "numberOfTracks": <int>,
      "numberOfVideos": <int>,
      "numberOfVolumes": <int>,
      "releaseDate": <str>,
      "copyright": <str>,
      "type": "ALBUM",
      "version": <str>,
      "url": <str>,
      "cover": <str>,
      "vibrantColor": <str>,
      "videoCover": <str>,
      "explicit": <bool>,
      "upc": <str>,
      "popularity": <int>,
      "audioQuality": <str>,
      "audioModes": [<str>],
      "mediaMetadata": {
        "tags": [<str>]
      },
      "artist": {
        "id": <int>,
        "name": <str>,
        "type": <str>,
        "picture": <str>
      },
      "artists": [
        {
          "id": <int>,
          "name": <str>,
          "type": <str>,
          "picture": <str>
        }
      ]
    }
  ]
}

get_artist_biography(artist_id: int | str, country_code: str = None) → dict[str, str]

Get an artist’s biographical information.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

artist_idint or str

TIDAL artist ID.

Example: 1566.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

Returns:

biographydict

A dictionary containing an artist’s biographical information and its source.

Sample response

{
  "source": <str>,
  "lastUpdated": <str>,
  "text": <str>,
  "summary": <str>
}

get_artist_links(artist_id: int | str, country_code: str = None, *, limit: int = None, offset: int = None) → dict[str, Any]

Get links to websites associated with an artist.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

artist_idint or str

TIDAL artist ID.

Example: 1566.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

limitint, keyword-only, optional

Page size.

Example: 10.

offsetint, keyword-only, optional

Pagination offset (in number of items).

Example: 0.

Returns:

linksdict

A dictionary containing the artist’s links and metadata for the returned results.

Sample response

{
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>,
  "items": [
    {
      "url": <str>,
      "siteName": <str>
    }
  ],
  "source": <str>
}

get_artist_mix_id(artist_id: int | str, country_code: str = None) → str

Get the ID of a curated mix of tracks based on an artist’s works.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

artist_idint or str

TIDAL artist ID.

Example: 1566.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

Returns:

mix_idstr

TIDAL mix ID.

Example: "000ec0b01da1ddd752ec5dee553d48".

get_artist_page(artist_id: int | str, country_code: str = None, *, device_type: str = 'BROWSER') → dict[str, Any]

Get the TIDAL page for an artist.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

artist_idint or str

TIDAL artist ID.

Example: 1566.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

device_typestr, keyword-only, default: "BROWSER"

Device type.

Valid values:

• "BROWSER" for a web browser.

• "DESKTOP" for the desktop TIDAL application.

• "PHONE" for the mobile TIDAL application.

• "TV" for the smart TV TIDAL application.

Returns:

pagedict

A dictionary containing the page ID, title, and submodules.

get_artist_radio(artist_id: int | str, country_code: str = None, *, limit: int = None, offset: int = None) → dict[str, Any]

Get TIDAL catalog information for tracks inspired by an artist’s works.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Note

This method is functionally identical to first getting the artist mix ID using get_artist_mix_id() and then retrieving TIDAL catalog information for the items in the mix using get_mix_items().

Parameters:

artist_idint or str

TIDAL artist ID.

Example: 1566.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

limitint, keyword-only, optional

Page size.

Default: 100.

offsetint, keyword-only, optional

Pagination offset (in number of items).

Example: 0.

Returns:

tracksdict

A dictionary containing TIDAL catalog information for tracks inspired by an artist’s works and metadata for the returned results.

Sample response

{
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>,
  "items": [
    {
      "id": <int>,
      "title": <str>,
      "duration": <int>,
      "replayGain": <float>,
      "peak": <float>,
      "allowStreaming": <bool>,
      "streamReady": <bool>,
      "adSupportedStreamReady": <bool>,
      "djReady": <bool>,
      "stemReady": <bool>,
      "streamStartDate": <str>,
      "premiumStreamingOnly": <bool>,
      "trackNumber": <int>,
      "volumeNumber": <int>,
      "version": <str>,
      "popularity": <int>,
      "copyright": <str>,
      "url": <str>,
      "isrc": <str>,
      "editable": <bool>,
      "explicit": <bool>,
      "audioQuality": <str>,
      "audioModes": [<str>],
      "mediaMetadata": {
        "tags": [<str>]
      },
      "artist": {
        "id": <int>,
        "name": <str>,
        "type": <str>,
        "picture": <str>
      },
      "artists": [
        {
          "id": <int>,
          "name": <str>,
          "type": <str>,
          "picture": <str>
        }
      ],
      "album": {
        "id": <int>,
        "title": <str>,
        "cover": <str>,
        "vibrantColor": <str>,
        "videoCover": <str>
      },
      "mixes": {
        "TRACK_MIX": <str>
      }
    }
  ]
}

get_artist_top_tracks(artist_id: int | str, country_code: str = None, *, limit: int = 100, offset: int = None) → dict[str, Any]

Get TIDAL catalog information for an artist’s top tracks.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

artist_idint or str

TIDAL artist ID.

Example: 1566.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

limitint, keyword-only, default: 100

Page size.

Example: 10.

offsetint, keyword-only, optional

Pagination offset (in number of items).

Example: 0.

Returns:

tracksdict

A dictionary containing TIDAL catalog information for the artist’s top tracks and metadata for the returned results.

Sample response

{
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>,
  "items": [
    {
      "id": <int>,
      "title": <str>,
      "duration": <int>,
      "replayGain": <float>,
      "peak": <float>,
      "allowStreaming": <bool>,
      "streamReady": <bool>,
      "adSupportedStreamReady": <bool>,
      "djReady": <bool>,
      "stemReady": <bool>,
      "streamStartDate": <str>,
      "premiumStreamingOnly": <bool>,
      "trackNumber": <int>,
      "volumeNumber": <int>,
      "version": <str>,
      "popularity": <int>,
      "copyright": <str>,
      "url": <str>,
      "isrc": <str>,
      "editable": <bool>,
      "explicit": <bool>,
      "audioQuality": <str>,
      "audioModes": [<str>],
      "mediaMetadata": {
        "tags": [<str>]
      },
      "artist": {
        "id": <int>,
        "name": <str>,
        "type": <str>,
        "picture": <str>
      },
      "artists": [
        {
          "id": <int>,
          "name": <str>,
          "type": <str>,
          "picture": <str>
        }
      ],
      "album": {
        "id": <int>,
        "title": <str>,
        "cover": <str>,
        "vibrantColor": <str>,
        "videoCover": <str>
      },
      "mixes": {
        "TRACK_MIX": <str>
      }
    }
  ]
}

get_artist_videos(artist_id: int | str, country_code: str = None, *, limit: int = 100, offset: int = None) → dict[str, Any]

Get TIDAL catalog information for an artist’s videos.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

artist_idint or str

TIDAL artist ID.

Example: 1566.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

limitint, keyword-only, default: 100

Page size.

Example: 10.

offsetint, keyword-only, optional

Pagination offset (in number of items).

Example: 0.

Returns:

videosdict

A dictionary containing TIDAL catalog information for the artist’s videos and metadata for the returned results.

Sample response

{
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>,
  "items": [
    {
      "id": <int>,
      "title": <str>,
      "volumeNumber": <int>,
      "trackNumber": <int>,
      "releaseDate": <str>,
      "imagePath": <str>,
      "imageId": <str>,
      "vibrantColor": <str>,
      "duration": <int>,
      "quality": <str>,
      "streamReady": <bool>,
      "adSupportedStreamReady": <bool>,
      "djReady": <bool>,
      "stemReady": <bool>,
      "streamStartDate": <str>,
      "allowStreaming": <bool>,
      "explicit": <bool>,
      "popularity": <int>,
      "type": "Music Video",
      "adsUrl": <str>,
      "adsPrePaywallOnly": <bool>,
      "artist": {
        "id": <int>,
        "name": <str>,
        "type": <str>,
        "picture": <str>
      },
      "artists": [
        {
          "id": <int>,
          "name": <str>,
          "type": <str>,
          "picture": <str>
        }
      ],
      "album": <dict>
    }
  ]
}

get_blocked_artists(*, limit: int = 50, offset: int = None) → dict[str, Any]

Get TIDAL catalog information for the current user’s blocked artists.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

limitint, keyword-only, default: 50

Page size.

Example: 10.

offsetint, keyword-only, optional

Pagination offset (in number of items).

Example: 0.

Returns:

artistsdict

A dictionary containing TIDAL catalog information for the the current user’s blocked artists and metadata for the returned results.

Sample response

{
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>,
  "items": [
    {
      "item": {
        "id": <int>,
        "name": <str>,
        "type": <str>,
        "artistTypes": [<str>],
        "url": <str>,
        "picture": <str>,
        "popularity": <int>,
        "banner": <str>,
        "artistRoles": [
          {
            "categoryId": <int>,
            "category": <str>
          }
        ],
        "mixes": {
          "ARTIST_MIX": <str>
        }
      },
      "created": <str>,
      "type": "ARTIST"
    }
  ]
}

get_blocked_users(*, limit: int = None, offset: int = None) → dict[str, Any]

Get users blocked by the current user.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

limitint, keyword-only, optional

Page size.

Example: 10.

offsetint, keyword-only, optional

Pagination offset (in number of items).

Example: 0.

Returns:

usersdict

A dictionary containing the users blocked by the current user and the number of results.

get_collection_streams(collection_id: int | str, type: str, *, audio_quality: str = 'HI_RES', video_quality: str = 'HIGH', max_resolution: int = 2160, playback_mode: str = 'STREAM', asset_presentation: str = 'FULL', streaming_session_id: str = None) → list[tuple[bytes, str]]

Get audio and video stream data for items (tracks and videos) in an album, mix, or playlist.

User authentication, authorization scope, and subscription

Requires the r_usr authorization scope if the device code flow was used.

Full track and video playback information and lossless audio is only available with user authentication and an active TIDAL subscription.

High-resolution and immersive audio is only available with the HiFi Plus plan and when the current client credentials are from a supported device.

See also

For more information on audio quality availability, see the Download TIDAL, TIDAL Pricing, and Dolby Atmos web pages.

Note

This method is provided for convenience and is not a private TIDAL API endpoint.

Parameters:

collection_idint or str

TIDAL collection ID or UUID.

typestr

Collection type.

Valid values: "album", "mix", and "playlist".

audio_qualitystr, keyword-only, default: "HI-RES"

Audio quality.

Valid values:

• "LOW" for 64 kbps (22.05 kHz) MP3 without user authentication or 96 kbps AAC with user authentication.

• "HIGH" for 320 kbps AAC.

• "LOSSLESS" for 1411 kbps (16-bit, 44.1 kHz) ALAC or FLAC.

• "HI_RES" for up to 9216 kbps (24-bit, 96 kHz) MQA-encoded FLAC.

video_qualitystr, keyword-only, default: "HIGH"

Video quality.

Valid values: "AUDIO_ONLY", "LOW", "MEDIUM", and "HIGH".

max_resolutionint, keyword-only, default: 2160

Maximum video resolution (number of vertical pixels).

playback_modestr, keyword-only, default: "STREAM"

Playback mode.

Valid values: "STREAM" and "OFFLINE".

asset_presentationstr, keyword-only, default: "FULL"

Asset presentation.

Valid values:

• "FULL": Full track or video.

• "PREVIEW": 30-second preview of the track or video.

streaming_session_idstr, keyword-only, optional

Streaming session ID.

Returns:

streamslist

Audio and video stream data and their MIME types.

get_country_code() → str

Get the country code based on the current IP address.

Returns:

countrystr, keyword-only, optional

ISO 3166-1 alpha-2 country code.

Example: "US".

get_favorite_albums(country_code: str = None, *, limit: int = 50, offset: int = None, order: str = 'DATE', order_direction: str = 'DESC') → None

Get TIDAL catalog information for albums in the current user’s collection.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

limitint, keyword-only, default: 50

Page size.

Example: 10.

offsetint, keyword-only, optional

Pagination offset (in number of items).

Example: 0.

orderstr, keyword-only, default: "DATE"

Sorting order.

Valid values: "DATE" and "NAME".

order_directionstr, keyword-only, default: "DESC"

Sorting order direction.

Valid values: "DESC" and "ASC".

Returns:

albumsdict

A dictionary containing TIDAL catalog information for albums in the current user’s collection and metadata for the returned results.

Sample response

{
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>,
  "items": [
    {
      "created": <str>,
      "item": {
        "id": <int>,
        "title": <str>,
        "duration": <int>,
        "streamReady": <bool>,
        "adSupportedStreamReady": <bool>,
        "djReady": <bool>,
        "stemReady": <bool>,
        "streamStartDate": <str>,
        "allowStreaming": <bool>,
        "premiumStreamingOnly": <bool>,
        "numberOfTracks": <int>,
        "numberOfVideos": <int>,
        "numberOfVolumes": <int>,
        "releaseDate": <str>,
        "copyright": <str>,
        "type": "ALBUM",
        "version": <str>,
        "url": <str>,
        "cover": <str>,
        "vibrantColor": <str>,
        "videoCover": <str>,
        "explicit": <bool>,
        "upc": <str>,
        "popularity": <int>,
        "audioQuality": <str>,
        "audioModes": [<str>],
        "mediaMetadata": {
          "tags": [<str>]
        },
        "artist": {
          "id": <int>,
          "name": <str>,
          "type": <str>,
          "picture": <str>
        },
        "artists": [
          {
            "id": <int>,
            "name": <str>,
            "type": <str>,
            "picture": <str>
          }
        ]
      }
    }
  ]
}

get_favorite_artists(country_code: str = None, *, limit: int = 50, offset: int = None, order: str = 'DATE', order_direction: str = 'DESC') → None

Get TIDAL catalog information for artists in the current user’s collection.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

limitint, keyword-only, default: 50

Page size.

Example: 10.

offsetint, keyword-only, optional

Pagination offset (in number of items).

Example: 0.

orderstr, keyword-only, default: "DATE"

Sorting order.

Valid values: "DATE" and "NAME".

order_directionstr, keyword-only, default: "DESC"

Sorting order direction.

Valid values: "DESC" and "ASC".

Returns:

artistsdict

A dictionary containing TIDAL catalog information for artists in the current user’s collection and metadata for the returned results.

Sample response

{
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>,
  "items": [
    {
      "created": <str>,
      "item": {
        "id": <int>,
        "name": <str>,
        "artistTypes": [<str>],
        "url": <str>,
        "picture": <str>,
        "popularity": <int>,
        "artistRoles": [
          {
            "categoryId": <int>,
            "category": <str>
          }
        ],
        "mixes": {
          "ARTIST_MIX": <str>
        }
      }
    }
  ]
}

get_favorite_ids() → dict[str, list[str]]

Get TIDAL IDs or UUIDs of the albums, artists, playlists, tracks, and videos in the current user’s collection.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Returns:

idsdict

A dictionary containing the IDs or UUIDs of the items in the current user’s collection.

Sample response

{
  "ARTIST": [<str>],
  "ALBUM": [<str>],
  "VIDEO": [<str>],
  "PLAYLIST": [<str>],
  "TRACK": [<str>]
}

get_favorite_mixes(*, ids: bool = False, limit: int = 50, cursor: str = None) → dict[str, Any]

Get TIDAL catalog information for or IDs of mixes in the current user’s collection.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

idsbool, keyword-only, default: False

Determine whether TIDAL catalog information about the mixes (False) or the mix IDs (True) are returned.

limitint, keyword-only, default: 50

Page size.

Example: 10.

cursorstr, keyword-only, optional

Cursor position of the last item in previous search results. Use with limit to get the next page of search results.

Returns:

mixesdict

A dictionary containing the TIDAL catalog information for or IDs of the mixes in the current user’s collection and the cursor position.

Sample response

{
  "items": [
    {
      "dateAdded": <str>,
      "title": <str>,
      "id": <str>,
      "mixType": <str>,
      "updated": <str>,
      "subTitleTextInfo": {
        "text": <str>,
        "color": <str>
      },
      "images": {
        "SMALL": {
          "width": <int>,
          "height": <int>,
          "url": <str>
        },
        "MEDIUM": {
          "width": <int>,
          "height": <int>,
          "url": <str>
        },
        "LARGE": {
          "width": <int>,
          "height": <int>,
          "url": <str>
        },
      },
      "detailImages": {
        "SMALL": {
          "width": <int>,
          "height": <int>,
          "url": <str>
        },
        "MEDIUM": {
          "width": <int>,
          "height": <int>,
          "url": <str>
        },
        "LARGE": {
          "width": <int>,
          "height": <int>,
          "url": <str>
        }
      },
      "master": <bool>,
      "subTitle": <str>,
      "titleTextInfo": {
        "text": <str>,
        "color": <str>
      }
    }
  ],
  "cursor": <str>,
  "lastModifiedAt": <str>
}

get_favorite_tracks(country_code: str = None, *, limit: int = 50, offset: int = None, order: str = 'DATE', order_direction: str = 'DESC')

Get TIDAL catalog information for tracks in the current user’s collection.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

limitint, keyword-only, default: 50

Page size.

Example: 10.

offsetint, keyword-only, optional

Pagination offset (in number of items).

Example: 0.

orderstr, keyword-only, default: "DATE"

Sorting order.

Valid values: "DATE" and "NAME".

order_directionstr, keyword-only, default: "DESC"

Sorting order direction.

Valid values: "DESC" and "ASC".

Returns:

tracksdict

A dictionary containing TIDAL catalog information for tracks in the current user’s collection and metadata for the returned results.

Sample response

{
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>,
  "items": [
    {
      "created": <str>,
      "item": {
        "id": <int>,
        "title": <str>,
        "duration": <int>,
        "replayGain": <float>,
        "peak": <float>,
        "allowStreaming": <bool>,
        "streamReady": <bool>,
        "adSupportedStreamReady": <bool>,
        "djReady": <bool>,
        "stemReady": <bool>,
        "streamStartDate": <str>,
        "premiumStreamingOnly": <bool>,
        "trackNumber": <int>,
        "volumeNumber": <int>,
        "version": <str>,
        "popularity": <int>,
        "copyright": <str>,
        "url": <str>,
        "isrc": <str>,
        "editable": <bool>,
        "explicit": <bool>,
        "audioQuality": <str>,
        "audioModes": [<str>],
        "mediaMetadata": {
          "tags": [<str>]
        },
        "artist": {
          "id": <int>,
          "name": <str>,
          "type": <str>,
          "picture": <str>
        },
        "artists": [
          {
            "id": <int>,
            "name": <str>,
            "type": <str>,
            "picture": <str>
          }
        ],
        "album": {
          "id": <int>,
          "title": <str>,
          "cover": <str>,
          "vibrantColor": <str>,
          "videoCover": <str>
        },
        "mixes": {
          "TRACK_MIX": <str>
        }
      }
    }
  ]
}

get_favorite_videos(country_code: str = None, *, limit: int = 50, offset: int = None, order: str = 'DATE', order_direction: str = 'DESC')

Get TIDAL catalog information for videos in the current user’s collection.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

limitint, keyword-only, default: 50

Page size.

Example: 10.

offsetint, keyword-only, optional

Pagination offset (in number of items).

Example: 0.

orderstr, keyword-only, default: "DATE"

Sorting order.

Valid values: "DATE" and "NAME".

order_directionstr, keyword-only, default: "DESC"

Sorting order direction.

Valid values: "DESC" and "ASC".

Returns:

videosdict

A dictionary containing TIDAL catalog information for videos in the current user’s collection and metadata for the returned results.

Sample response

{
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>,
  "items": [
    {
      "created": <str>,
      "item": {
        "id": <int>,
        "title": <str>,
        "volumeNumber": <int>,
        "trackNumber": <int>,
        "releaseDate": <str>,
        "imagePath": <str>,
        "imageId": <str>,
        "vibrantColor": <str>,
        "duration": <int>,
        "quality": <str>,
        "streamReady": <bool>,
        "adSupportedStreamReady": <bool>,
        "djReady": <bool>,
        "stemReady": <bool>,
        "streamStartDate": <str>,
        "allowStreaming": <bool>,
        "explicit": <bool>,
        "popularity": <int>,
        "type": <str>,
        "adsUrl": <str>,
        "adsPrePaywallOnly": <bool>,
        "artist": {
          "id": <int>,
          "name": <str>,
          "type": <str>,
          "picture": <str>
        },
        "artists": [
          {
            "id": <int>,
            "name": "<str>,
            "type": <str>,
            "picture": <str>
          }
        ],
        "album": <dict>
      }
    }
  ]
}

get_image(uuid: str, type: str = None, animated: bool = False, *, width: int = None, height: int = None, filename: str | Path = None) → bytes

Get (animated) cover art or image for a TIDAL item.

Note

This method is provided for convenience and is not a private TIDAL API endpoint.

Parameters:

uuidstr

Image UUID.

Example: "d3c4372b-a652-40e0-bdb1-fc8d032708f6".

typestr

Item type.

Valid values: "artist", "album", "playlist", "track", "userProfile", and "video".

animatedbool, default: False

Specifies whether the image is animated.

widthint, keyword-only, optional

Valid image width for the item type. If not specified, the default size for the item type is used.

heightint, keyword-only, optional

Valid image height for the item type. If not specified, the default size for the item type is used.

filenamestr or pathlib.Path, keyword-only, optional

Filename with the .jpg or .mp4 extension. If specified, the image is saved to a file instead.

Returns:

imagebytes

Image data. If save=True, the stream data is saved to an image or video file and its filename is returned instead.

get_mix_items(mix_id: str, country_code: str = None) → dict[str, Any]

Get TIDAL catalog information for items (tracks and videos) in a mix.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

mix_idstr

TIDAL mix ID.

Example: "000ec0b01da1ddd752ec5dee553d48".

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

Returns:

itemsdict

A dictionary containing TIDAL catalog information for tracks and videos in the specified mix and metadata for the returned results.

Sample response

{
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>,
  "items": [
    {
      "item": {
        "id": <int>,
        "title": <str>,
        "duration": <int>,
        "replayGain": <float>,
        "peak": <float>,
        "allowStreaming": <bool>,
        "streamReady": <bool>,
        "adSupportedStreamReady": <bool>,
        "djReady": <bool>,
        "stemReady": <bool>,
        "streamStartDate": <str>,
        "premiumStreamingOnly": <bool>,
        "trackNumber": <int>,
        "volumeNumber": >int>,
        "version": <str>,
        "popularity": <int>,
        "copyright": <str>,
        "url": <str>,
        "isrc": <str>,
        "editable": <bool>,
        "explicit": <bool>,
        "audioQuality": <str>,
        "audioModes": [<str>],
        "mediaMetadata": {
          "tags": [<str>]
        },
        "artist": {
          "id": <int>,
          "name": <str>,
          "type": <str>,
          "picture": <str>
        },
        "artists": [
          {
            "id": <int>,
            "name": <str>,
            "type": <str>,
            "picture": <str>
          }
        ],
        "album": {
          "id": <int>,
          "title": <str>,
          "cover": <str>,
          "vibrantColor": <str>,
          "videoCover": <str>
        },
        "mixes": {
          "TRACK_MIX": <str>
        }
      },
      "type": "track"
    }
  ]
}

get_mix_page(mix_id: str, country_code: str = None, *, device_type: str = 'BROWSER') → dict[str, Any]

Get the TIDAL page for a mix.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

mix_idstr

TIDAL mix ID.

Example: "000ec0b01da1ddd752ec5dee553d48".

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

device_typestr, keyword-only, default: "BROWSER"

Device type.

Valid values:

• "BROWSER" for a web browser.

• "DESKTOP" for the desktop TIDAL application.

• "PHONE" for the mobile TIDAL application.

• "TV" for the smart TV TIDAL application.

Returns:

pagedict

A dictionary containing the page ID, title, and submodules.

get_personal_playlist_folders(folder_uuid: str = None, *, flattened: bool = False, include_only: str = None, limit: int = 50, order: str = 'DATE', order_direction: str = 'DESC') → dict[str, Any]

Get TIDAL catalog information for a playlist folder (and optionally, playlists and other playlist folders in it) created by the current user.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

folder_uuidstr, optional

UUID of the folder in which to look for playlists and other folders. If not specified, all folders and playlists in “My Playlists” are returned.

flattenedbool, keyword-only, default: False

Determines whether the results are flattened into a list.

include_onlystr, keyword-only, optional

Type of playlist-related item to return.

Valid values: "FAVORITE_PLAYLIST", "FOLDER", and "PLAYLIST".

limitint, keyword-only, default: 50

Page size.

Example: 10.

orderstr, keyword-only, default: "DATE"

Sorting order.

Valid values: "DATE", "DATE_UPDATED", and "NAME".

order_directionstr, keyword-only, default: "DESC"

Sorting order direction.

Valid values: "DESC" and "ASC".

Returns:

itemsdict

A dictionary containing playlist-related items and the total number of items available.

Sample response

{
  "lastModifiedAt": <str>,
  "items": [
    {
      "trn": <str>,
      "itemType": "FOLDER",
      "addedAt": <str>,
      "lastModifiedAt": <str>,
      "name": <str>,
      "parent": <str>,
      "data": {
        "trn": <str>,
        "name": <str>,
        "createdAt": <str>,
        "lastModifiedAt": <str>,
        "totalNumberOfItems": <int>,
        "id": <str>,
        "itemType": "FOLDER"
      }
    }
  ],
  "totalNumberOfItems": <int>,
  "cursor": <str>
}

get_personal_playlists(country_code: str = None, *, limit: int = 50, offset: int = None) → dict[str, Any]

Get TIDAL catalog information for playlists created by the current user.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

limitint, keyword-only, default: 50

Page size.

Example: 10.

offsetint, keyword-only, optional

Pagination offset (in number of items).

Example: 0.

Returns:

playlistsdict

TIDAL catalog information for a user playlists created by the current user and metadata for the returned results.

Sample response

{
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>,
  "items": [
    {
      "uuid": <str>",
      "title": <str>,
      "numberOfTracks": <int>,
      "numberOfVideos": <int>,
      "creator": {
        "id": <int>
      },
      "description": <str>,
      "duration": <int>,
      "lastUpdated": <str>,
      "created": <str>,
      "type": "USER",
      "publicPlaylist": <bool>,
      "url": <str>,
      "image": <str>,
      "popularity": <int>,
      "squareImage": <str>,
      "promotedArtists": [],
      "lastItemAddedAt": <str>
    }
  ]
}

get_playlist(playlist_uuid: str, country_code: str = None) → dict[str, Any]

Get TIDAL catalog information for a playlist.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

playlist_uuidstr

TIDAL playlist UUID.

Example: "36ea71a8-445e-41a4-82ab-6628c581535d".

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

Returns:

playlistdict

TIDAL catalog information for a playlist.

Sample response

{
  "uuid": <str>,
  "title": <str>,
  "numberOfTracks": <int>,
  "numberOfVideos": <int>,
  "creator": {
    "id": <int>
  },
  "description": <str>,
  "duration": <int>,
  "lastUpdated": <str>,
  "created": <str>,
  "type": <str>,
  "publicPlaylist": <bool>,
  "url": <str>,
  "image": <str>,
  "popularity": <int>,
  "squareImage": <str>,
  "promotedArtists": [
    {
      "id": <int>,
      "name": <str>,
      "type": <str>,
      "picture": <str>,
    }
  ],
  "lastItemAddedAt": <str>
}

get_playlist_etag(playlist_uuid: str, country_code: str = None) → str

Get the entity tag (ETag) for a playlist.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Note

This method is provided for convenience and is not a private TIDAL API endpoint.

Parameters:

playlist_uuidstr

TIDAL playlist UUID.

Example: "36ea71a8-445e-41a4-82ab-6628c581535d".

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

Returns:

etagstr

ETag for a playlist.

Example: "1698984074453".

get_playlist_items(playlist_uuid: str, country_code: str = None, *, limit: int = 100, offset: int = None) → dict[str, Any]

Get TIDAL catalog information for items (tracks and videos) in a playlist.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

playlist_uuidstr

TIDAL playlist UUID.

Example: "36ea71a8-445e-41a4-82ab-6628c581535d".

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

limitint, keyword-only, default: 100

Page size.

Example: 10.

offsetint, keyword-only, optional

Pagination offset (in number of items).

Example: 0.

Returns:

itemsdict

A dictionary containing TIDAL catalog information for tracks and videos in the specified playlist and metadata for the returned results.

Sample response

{
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>,
  "items": [
    {
      "item": {
        "id": <int>,
        "title": <str>,
        "duration": <int>,
        "replayGain": <float>,
        "peak": <float>,
        "allowStreaming": <bool>,
        "streamReady": <bool>,
        "adSupportedStreamReady": <bool>,
        "djReady": <bool>,
        "stemReady": <bool>,
        "streamStartDate": <str>,
        "premiumStreamingOnly": <bool>,
        "trackNumber": <int>,
        "volumeNumber": >int>,
        "version": <str>,
        "popularity": <int>,
        "copyright": <str>,
        "url": <str>,
        "isrc": <str>,
        "editable": <bool>,
        "explicit": <bool>,
        "audioQuality": <str>,
        "audioModes": [<str>],
        "mediaMetadata": {
          "tags": [<str>]
        },
        "artist": {
          "id": <int>,
          "name": <str>,
          "type": <str>,
          "picture": <str>
        },
        "artists": [
          {
            "id": <int>,
            "name": <str>,
            "type": <str>,
            "picture": <str>
          }
        ],
        "album": {
          "id": <int>,
          "title": <str>,
          "cover": <str>,
          "vibrantColor": <str>,
          "videoCover": <str>
        },
        "mixes": {
          "TRACK_MIX": <str>
        }
      },
      "type": "track"
    }
  ]
}

get_playlist_recommendations(playlist_uuid: str, country_code: str = None, *, limit: int = None, offset: int = None) → dict[str, Any]

Get TIDAL catalog information for recommended tracks based on a playlist’s items.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

playlist_uuidstr

TIDAL playlist UUID.

Example: "36ea71a8-445e-41a4-82ab-6628c581535d".

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

limitint, keyword-only, optional

Page size.

Example: 10.

offsetint, keyword-only, optional

Pagination offset (in number of items).

Example: 0.

Returns:

itemsdict

A dictionary containing TIDAL catalog information for recommended tracks and videos and metadata for the returned results.

Sample response

{
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>,
  "items": [
    {
      "item": {
        "id": <int>,
        "title": <str>,
        "duration": <int>,
        "replayGain": <float>,
        "peak": <float>,
        "allowStreaming": <bool>,
        "streamReady": <bool>,
        "adSupportedStreamReady": <bool>,
        "djReady": <bool>,
        "stemReady": <bool>,
        "streamStartDate": <str>,
        "premiumStreamingOnly": <bool>,
        "trackNumber": <int>,
        "volumeNumber": >int>,
        "version": <str>,
        "popularity": <int>,
        "copyright": <str>,
        "url": <str>,
        "isrc": <str>,
        "editable": <bool>,
        "explicit": <bool>,
        "audioQuality": <str>,
        "audioModes": [<str>],
        "mediaMetadata": {
          "tags": [<str>]
        },
        "artist": {
          "id": <int>,
          "name": <str>,
          "type": <str>,
          "picture": <str>
        },
        "artists": [
          {
            "id": <int>,
            "name": <str>,
            "type": <str>,
            "picture": <str>
          }
        ],
        "album": {
          "id": <int>,
          "title": <str>,
          "cover": <str>,
          "vibrantColor": <str>,
          "videoCover": <str>
        },
        "mixes": {
          "TRACK_MIX": <str>
        }
      },
      "type": "track"
    }
  ]
}

get_profile() → dict[str, Any]

Get the current user’s profile information.

User authentication

Requires user authentication via an OAuth 2.0 authorization flow.

Returns:

profiledict

A dictionary containing the current user’s profile information.

Sample response

{
  "userId": <int>,
  "email": <str>,
  "countryCode": <str>,
  "fullName": <str>,
  "firstName": <str>,
  "lastName": <str>,
  "nickname": <str>,
  "username": <str>,
  "address": <str>,
  "city": <str>,
  "postalcode": <str>,
  "usState": <str>,
  "phoneNumber": <int>,
  "birthday": <int>,
  "channelId": <int>,
  "parentId": <int>,
  "acceptedEULA": <bool>,
  "created": <int>,
  "updated": <int>,
  "facebookUid": <int>,
  "appleUid": <int>,
  "googleUid": <int>,
  "accountLinkCreated": <bool>,
  "emailVerified": <bool>,
  "newUser": <bool>
}

get_session() → dict[str, Any]

Get information about the current private TIDAL API session.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Returns:

sessiondict

Information about the current private TIDAL API session.

Sample response

{
  "sessionId": <str>,
  "userId": <int>,
  "countryCode": <str>,
  "channelId": <int>,
  "partnerId": <int>,
  "client": {
    "id": <int>,
    "name": <str>,
    "authorizedForOffline": <bool>,
    "authorizedForOfflineDate": <str>
  }
}

get_similar_albums(album_id: int | str, country_code: str = None) → dict[str, Any]

Get TIDAL catalog information for albums similar to the specified album.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

album_idint or str

TIDAL album ID.

Example: 251380836.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

Returns:

albumdict

TIDAL catalog information for an album.

Sample response

{
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>,
  "items": [
    {
      "id": <int>,
      "title": <str>,
      "duration": <int>,
      "streamReady": <bool>,
      "adSupportedStreamReady": <bool>,
      "djReady": <bool>,
      "stemReady": <bool>,
      "streamStartDate": <str>,
      "allowStreaming": <bool>,
      "premiumStreamingOnly": <bool>,
      "numberOfTracks": <int>,
      "numberOfVideos": <int>,
      "numberOfVolumes": <int>,
      "releaseDate": <str>,
      "copyright": <str>,
      "type": "ALBUM",
      "version": <str>,
      "url": <str>,
      "cover": <str>,
      "vibrantColor": <str>,
      "videoCover": <str>,
      "explicit": <bool>,
      "upc": <str>,
      "popularity": <int>,
      "audioQuality": <str>,
      "audioModes": [<str>],
      "mediaMetadata": {
        "tags": [<str>]
      },
      "artist": {
        "id": <int>,
        "name": <str>,
        "type": <str>,
        "picture": <str>
      },
      "artists": [
        {
          "id": <int>,
          "name": <str>,
          "type": <str>,
          "picture": <str>
        }
      ]
    }
  ],
  "source": <str>
}

get_similar_artists(artist_id: str, country_code: str = None, *, limit: int = None, offset: int = None) → dict[str, Any]

Get TIDAL catalog information for artists similar to a specified artist.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

artist_idint or str

TIDAL artist ID.

Example: 1566.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

limitint, keyword-only, default: 100

Page size.

Example: 10.

offsetint, keyword-only, optional

Pagination offset (in number of items).

Example: 0.

Returns:

artistsdict

A dictionary containing TIDAL catalog information for artists similar to the specified artist and metadata for the returned results.

Sample response

{
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>,
  "items": [
    {
      "id": <int>,
      "name": <str>,
      "type": None,
      "artistTypes": [<str>],
      "url": <str>,
      "picture": <str>,
      "popularity": <int>,
      "banner": <str>,
      "artistRoles": <list>,
      "mixes": <dict>,
      "relationType": "SIMILAR_ARTIST"
    }
  ],
  "source": "TIDAL"
}

get_track(track_id: int | str, country_code: str = None) → dict[str, Any]

Get TIDAL catalog information for a track.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

track_idint or str

TIDAL track ID.

Example: 251380837.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

Returns:

trackdict

TIDAL catalog information for a track.

Sample response

{
  "id": <int>,
  "title": <str>,
  "duration": <int>,
  "replayGain": <float>,
  "peak": <float>,
  "allowStreaming": <bool>,
  "streamReady": <bool>,
  "adSupportedStreamReady": <bool>,
  "djReady": <bool>,
  "stemReady": <bool>,
  "streamStartDate": <str>,
  "premiumStreamingOnly": <bool>,
  "trackNumber": <int>,
  "volumeNumber": <int>,
  "version": <str>,
  "popularity": <int>,
  "copyright": <str>,
  "url": <str>,
  "isrc": <str>,
  "editable": <bool>,
  "explicit": <bool>,
  "audioQuality": <str>,
  "audioModes": [<str>],
  "mediaMetadata": {
    "tags": [<str>]
  },
  "artist": {
    "id": <int>,
    "name": <str>,
    "type": <str>,
    "picture": <str>
  },
  "artists": [
    {
      "id": <int>,
      "name": <str>,
      "type": <str>,
      "picture": <str>
    }
  ],
  "album": {
    "id": <int>,
    "title": <str>,
    "cover": <str>,
    "vibrantColor": <str>,
    "videoCover": <str>
  },
  "mixes": {
    "TRACK_MIX": <str>
  }
}

get_track_composers(track_id: int | str) → list[str]

Get the composers, lyricists, and/or songwriters of a track.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Note

This method is provided for convenience and is not a private TIDAL API endpoint.

Parameters:

track_idint or str

TIDAL track ID.

Example: 251380837.

Returns:

composerslist

Composers, lyricists, and/or songwriters of the track.

Example: ['Tommy Wright III', 'Beyoncé', 'Kelman Duran', 'Terius "The-Dream" G...de-Diamant', 'Mike Dean']

get_track_contributors(track_id: int | str, country_code: str = None, *, limit: int = None, offset: int = None) → dict[str, Any]

Get the contributors to a track and their roles.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

track_idint or str

TIDAL track ID.

Example: 251380837.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

limitint, keyword-only, default: 100

Page size.

Example: 10.

offsetint, keyword-only, optional

Pagination offset (in number of items).

Example: 0.

Returns:

contributorsdict

A dictionary containing a track’s contributors and their roles, and metadata for the returned results.

Sample response

{
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>,
  "items": [
    {
      "name": <str>,
      "role": <str>
    }
  ]
}

get_track_credits(track_id: int | str, country_code: str = None) → list[dict[str, Any]]

Get credits for a track.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

track_idint or str

TIDAL track ID.

countrystr, keyword-only, optional

An ISO 3166-1 alpha-2 country code. If not specified, the country associated with the user account will be used.

Example: "US".

Returns:

creditslist

A list of roles and their associated contributors.

Sample response

[
  {
    "type": <str>,
    "contributors": [
      {
        "name": <str>,
        "id": <int>
      }
    ]
  }
]

get_track_lyrics(id: int | str, country_code: str = None) → dict[str, Any]

Get lyrics for a track.

User authentication and subscription

Requires user authentication via an OAuth 2.0 authorization flow and an active TIDAL subscription.

Parameters:

idint or str

TIDAL track ID.

Example: 251380837.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

Returns:

lyricsdict

A dictionary containing formatted and time-synced lyrics (if available) in the “lyrics” and “subtitles” keys, respectively.

Sample response

{
  "trackId": <int>,
  "lyricsProvider": <str>,
  "providerCommontrackId": <str>,
  "providerLyricsId": <str>,
  "lyrics": <str>,
  "subtitles": <str>,
  "isRightToLeft": <bool>
}

get_track_mix_id(tidal_id: int | str, country_code: str = None) → str

Get the curated mix of tracks based on a track.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

tidal_idint or str

TIDAL track ID.

Example: 251380837.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

Returns:

mix_idstr

TIDAL mix ID.

Example: "0017159e6a1f34ae3d981792d72ecf".

get_track_playback_info(track_id: int | str, *, audio_quality: str = 'HI_RES', playback_mode: str = 'STREAM', asset_presentation: str = 'FULL', streaming_session_id: str = None) → dict[str, Any]

Get playback information for a track.

User authentication, authorization scope, and subscription

Requires the r_usr authorization scope if the device code flow was used.

Full track playback information and lossless audio is only available with user authentication and an active TIDAL subscription.

High-resolution and immersive audio is only available with the HiFi Plus plan and when the current client credentials are from a supported device.

See also

For more information on audio quality availability, see the Download TIDAL, TIDAL Pricing, and Dolby Atmos <https://support.tidal.com/hc/en-us/articles /360004255778-Dolby-Atmos> web pages.

Parameters:

track_idint or str

TIDAL track ID.

Example: 251380837.

audio_qualitystr, keyword-only, default: "HI-RES"

Audio quality.

Valid values:

• "LOW" for 64 kbps (22.05 kHz) MP3 without user authentication or 96 kbps AAC with user authentication.

• "HIGH" for 320 kbps AAC.

• "LOSSLESS" for 1411 kbps (16-bit, 44.1 kHz) ALAC or FLAC.

• "HI_RES" for up to 9216 kbps (24-bit, 96 kHz) MQA-encoded FLAC.

playback_modestr, keyword-only, default: "STREAM"

Playback mode.

Valid values: "STREAM" and "OFFLINE".

asset_presentationstr, keyword-only, default: "FULL"

Asset presentation.

Valid values:

• "FULL": Full track.

• "PREVIEW": 30-second preview of the track.

streaming_session_idstr, keyword-only, optional

Streaming session ID.

Returns:

infodict

Track playback information.

Sample response

{
  "trackId": <int>,
  "assetPresentation": <str>,
  "audioMode": <str>,
  "audioQuality": <str>,
  "manifestMimeType": <str>,
  "manifestHash": <str>,
  "manifest": <str>,
  "albumReplayGain": <float>,
  "albumPeakAmplitude": <float>,
  "trackReplayGain": <float>,
  "trackPeakAmplitude": <float>
}

get_track_recommendations(track_id: int | str, country_code: str = None, *, limit: int = None, offset=None) → dict[str, Any]

Get TIDAL catalog information for a track’s recommended tracks and videos.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

track_idint or str

TIDAL track ID.

Example: 251380837.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

limitint, keyword-only, optional

Page size.

Example: 10.

offsetint, keyword-only, optional

Pagination offset (in number of items).

Example: 0.

Returns:

recommendationsdict

A dictionary containing TIDAL catalog information for the recommended tracks and metadata for the returned results.

Sample response

{
  "limit": <int>,
  "offset": <int>,
  "totalNumberOfItems": <int>,
  "items": [
    {
      "id": <int>,
      "title": <str>,
      "duration": <int>,
      "replayGain": <float>,
      "peak": <float>,
      "allowStreaming": <bool>,
      "streamReady": <bool>,
      "adSupportedStreamReady": <bool>,
      "djReady": <bool>,
      "stemReady": <bool>,
      "streamStartDate": <str>,
      "premiumStreamingOnly": <bool>,
      "trackNumber": <int>,
      "volumeNumber": <int>,
      "version": <str>,
      "popularity": <int>,
      "copyright": <str>,
      "url": <str>,
      "isrc": <str>,
      "editable": <bool>,
      "explicit": <bool>,
      "audioQuality": <str>,
      "audioModes": [<str>],
      "mediaMetadata": {
        "tags": [<str>]
      },
      "artist": {
        "id": <int>,
        "name": <str>,
        "type": <str>,
        "picture": <str>
      },
      "artists": [
        {
          "id": <int>,
          "name": <str>,
          "type": <str>,
          "picture": <str>
        }
      ],
      "album": {
        "id": <int>,
        "title": <str>,
        "cover": <str>,
        "vibrantColor": <str>,
        "videoCover": <str>
      },
      "mixes": {
        "TRACK_MIX": <str>
      }
    },
    "sources": [
      "SUGGESTED_TRACKS"
    ]
  ]
}

get_track_stream(track_id: int | str, *, audio_quality: str = 'HI_RES', playback_mode: str = 'STREAM', asset_presentation: str = 'FULL', streaming_session_id: str = None) → bytes | str

Get the audio stream data for a track.

User authentication, authorization scope, and subscription

Requires the r_usr authorization scope if the device code flow was used.

Full track playback information and lossless audio is only available with user authentication and an active TIDAL subscription.

High-resolution and immersive audio is only available with the HiFi Plus plan and when the current client credentials are from a supported device.

See also

For more information on audio quality availability, see the Download TIDAL, TIDAL Pricing, and Dolby Atmos web pages.

Note

This method is provided for convenience and is not a private TIDAL API endpoint.

Parameters:

track_idint or str

TIDAL track ID.

Example: 251380837.

audio_qualitystr, keyword-only, default: "HI-RES"

Audio quality.

Valid values:

• "LOW" for 64 kbps (22.05 kHz) MP3 without user authentication or 96 kbps AAC with user authentication.

• "HIGH" for 320 kbps AAC.

• "LOSSLESS" for 1411 kbps (16-bit, 44.1 kHz) ALAC or FLAC.

• "HI_RES" for up to 9216 kbps (24-bit, 96 kHz) MQA-encoded FLAC.

playback_modestr, keyword-only, default: "STREAM"

Playback mode.

Valid values: "STREAM" and "OFFLINE".

asset_presentationstr, keyword-only, default: "FULL"

Asset presentation.

Valid values:

• "FULL": Full track.

• "PREVIEW": 30-second preview of the track.

streaming_session_idstr, keyword-only, optional

Streaming session ID.

Returns:

streambytes

Audio stream data.

codecstr

Audio codec.

get_user_followers(user_id: int | str = None, *, limit: int = 500, cursor: str = None) → dict[str, Any]

Get a TIDAL user’s followers.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

user_idstr

TIDAL user ID. If not specified, the ID associated with the user account in the current session is used.

Example: 172311284.

limitint, keyword-only, default: 500

Page size.

Example: 10.

cursorstr, keyword-only, optional

Cursor position of the last item in previous search results. Use with limit to get the next page of search results.

Returns:

followersdict

A dictionary containing the user’s followers and the cursor position.

get_user_following(user_id: int | str = None, *, include_only: str = None, limit: int = 500, cursor: str = None)

Get the people (artists, users, etc.) a TIDAL user follows.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

user_idstr

TIDAL user ID. If not specified, the ID associated with the user account in the current session is used.

Example: 172311284.

include_onlystr, keyword-only, optional

Type of people to return.

Valid values: "ARTIST" and "USER".

limitint, keyword-only, default: 500

Page size.

Example: 10.

cursorstr, keyword-only, optional

Cursor position of the last item in previous search results. Use with limit to get the next page of search results.

Returns:

followingdict

A dictionary containing the people following the user and the cursor position.

Sample response

{
  "items": [
    {
      "id": <int>,
      "name": <str>,
      "picture": <str>,
      "imFollowing": <bool>,
      "trn": <str>,
      "followType": <str>
    }
  ],
  "cursor": <str>
}

get_user_playlist(playlist_uuid: str) → dict[str, Any]

Get TIDAL catalog information for a user playlist.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

playlist_uuidstr

TIDAL user playlist UUID.

Example: "e09ab9ce-2e87-41b8-b404-3cd712bf706e".

Returns:

playlistdict

TIDAL catalog information for a user playlist.

Sample response

{
  "playlist": {
    "uuid": <str>,
    "type": "USER",
    "creator": {
      "id": <int>,
      "name": <str>,
      "picture": <str>,
      "type": "USER"
    },
    "contentBehavior": <str>,
    "sharingLevel": <str>,
    "status": <str>,
    "source": <str>,
    "title": <str>,
    "description": <str>,
    "image": <str>,
    "squareImage": <str>,
    "url": <str>,
    "created": <str>,
    "lastUpdated": <str>,
    "lastItemAddedAt": <str>,
    "duration": <int>,
    "numberOfTracks": <int>,
    "numberOfVideos": <int>,
    "promotedArtists": [],
    "trn": <str>,
  },
  "followInfo": {
    "nrOfFollowers": <int>,
    "tidalResourceName": <str>,
    "followed": <bool>,
    "followType": "PLAYLIST"
  },
  "profile": {
    "userId": <int>,
    "name": <str>,
    "color": [<str>]
  }
}

get_user_playlists(user_id: int | str = None, *, limit: int = 50, cursor: str = None) → dict[str, Any]

Get TIDAL catalog information for playlists created by a TIDAL user.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

user_idstr

TIDAL user ID. If not specified, the ID associated with the user account in the current session is used.

limitint, keyword-only, default: 50

Page size.

Example: 10.

cursorstr, keyword-only, optional

Cursor position of the last item in previous search results. Use with limit to get the next page of search results.

Returns:

playlistsdict

A dictionary containing the user’s playlists and the cursor position.

Sample response

{
  "items": [
    {
      "playlist": {
        "uuid": <str>,
        "type": "USER",
        "creator": {
          "id": <int>,
          "name": <str>,
          "picture": <str>,
          "type": "USER"
        },
        "contentBehavior": <str>,
        "sharingLevel": <str>,
        "status": <str>,
        "source": <str>,
        "title": <str>,
        "description": <str>,
        "image": <str>,
        "squareImage": <str>,
        "url": <str>,
        "created": <str>,
        "lastUpdated": <str>,
        "lastItemAddedAt": <str>,
        "duration": <int>,
        "numberOfTracks": <int>,
        "numberOfVideos": <int>,
        "promotedArtists": [],
        "trn": <str>,
      },
      "followInfo": {
        "nrOfFollowers": <int>,
        "tidalResourceName": <str>,
        "followed": <bool>,
        "followType": "PLAYLIST"
      },
      "profile": {
        "userId": <int>,
        "name": <str>,
        "color": [<str>]
      }
    }
  ],
  "cursor": <str>
}

get_user_profile(user_id: int | str) → dict[str, Any]

Get a TIDAL user’s profile information.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

user_idint or str

TIDAL user ID.

Example: 172311284.

Returns:

profiledict

A dictionary containing the user’s profile information.

Sample response

{
  "userId": <int>,
  "name": <str>,
  "color": [<str>],
  "picture": <str>,
  "numberOfFollowers": <int>,
  "numberOfFollows": <int>,
  "prompts": [
    {
      "id": <int>,
      "title": <str>,
      "description": <str>,
      "colors": {
        "primary": <str>,
        "secondary": <str>,
      },
      "trn": <str>,
      "data": <str>,
      "updatedTime": <str>,
      "supportedContentType": "TRACK"
    }
  ],
  "profileType": <str>
}

get_video(video_id: int | str, country_code: str = None) → dict[str, Any]

Get TIDAL catalog information for a video.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

video_idint or str

TIDAL video ID.

Example: 59727844.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

Returns:

videodict

TIDAL catalog information for a video.

Sample response

{
  "id": <int>,
  "title": <str>,
  "volumeNumber": <int>,
  "trackNumber": <int>,
  "releaseDate": <str>,
  "imagePath": <str>,
  "imageId": <str>,
  "vibrantColor": <str>,
  "duration": <int>,
  "quality": <str>,
  "streamReady": <bool>,
  "adSupportedStreamReady": <bool>,
  "djReady": <bool>,
  "stemReady": <bool>,
  "streamStartDate": <str>,
  "allowStreaming": <bool>,
  "explicit": <bool>,
  "popularity": <int>,
  "type": <str>,
  "adsUrl": <str>,
  "adsPrePaywallOnly": <bool>,
  "artist": {
    "id": <int>,
    "name": <str>,
    "type": <str>,
    "picture": <str>,
  },
  "artists": [
    {
      "id": <int>,
      "name": <str>,
      "type": <str>,
      "picture": <str>,
    }
  ],
  "album": <dict>
}

get_video_page(video_id: int | str, country_code: str = None, *, device_type: str = 'BROWSER') → dict[str, Any]

Get the TIDAL page for a video.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

video_idint or str

TIDAL video ID.

Example: 75623239.

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

device_typestr, keyword-only, default: "BROWSER"

Device type.

Valid values:

• "BROWSER" for a web browser.

• "DESKTOP" for the desktop TIDAL application.

• "PHONE" for the mobile TIDAL application.

• "TV" for the smart TV TIDAL application.

Returns:

pagedict

A dictionary containing the page ID, title, and submodules.

get_video_playback_info(video_id: int | str, *, video_quality: str = 'HIGH', playback_mode: str = 'STREAM', asset_presentation: str = 'FULL', streaming_session_id: str = None) → dict[str, Any]

Get playback information for a video.

User authentication, authorization scope, and subscription

Requires the r_usr authorization scope if the device code flow was used.

Full video playback information is only available with user authentication and an active TIDAL subscription.

Parameters:

video_idint or str

TIDAL video ID.

Example: 59727844.

video_qualitystr, keyword-only, default: "HIGH"

Video quality.

Valid values: "AUDIO_ONLY", "LOW", "MEDIUM", and "HIGH".

playback_modestr, keyword-only, default: "STREAM"

Playback mode.

Valid values: "STREAM" and "OFFLINE".

asset_presentationstr, keyword-only, default: "FULL"

Asset presentation.

Valid values:

• "FULL": Full video.

• "PREVIEW": 30-second preview of the video.

streaming_session_idstr, keyword-only, optional

Streaming session ID.

Returns:

infodict

Video playback information.

Sample response

{
  "videoId": <int>,
  "streamType": <str>,
  "assetPresentation": <str>,
  "videoQuality": <str>,
  "manifestMimeType": <str>,
  "manifestHash": <str>,
  "manifest": <str>
}

get_video_stream(video_id: int | str, *, video_quality: str = 'HIGH', max_resolution: int = 2160, playback_mode: str = 'STREAM', asset_presentation: str = 'FULL', streaming_session_id: str = None) → tuple[bytes, str]

Get the video stream data for a music video.

User authentication, authorization scope, and subscription

Requires the r_usr authorization scope if the device code flow was used.

Full video playback information is only available with user authentication and an active TIDAL subscription.

Note

This method is provided for convenience and is not a private TIDAL API endpoint.

Parameters:

video_idint or str

TIDAL video ID.

Example: 59727844.

video_qualitystr, keyword-only, default: "HIGH"

Video quality.

Valid values: "AUDIO_ONLY", "LOW", "MEDIUM", and "HIGH".

max_resolutionint, keyword-only, default: 2160

Maximum video resolution (number of vertical pixels).

playback_modestr, keyword-only, default: "STREAM"

Playback mode.

Valid values: "STREAM" and "OFFLINE".

asset_presentationstr, keyword-only, default: "FULL"

Asset presentation.

Valid values:

• "FULL": Full video.

• "PREVIEW": 30-second preview of the video.

streaming_session_idstr, keyword-only, optional

Streaming session ID.

Returns:

streambytes

Video stream data.

codecstr

Video codec.

move_playlist(playlist_uuid: str, folder_id: str) → None

Move a playlist in the current user’s collection.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

playlist_uuidstr

TIDAL playlist UUID.

Example: "36ea71a8-445e-41a4-82ab-6628c581535d".

folder_idstr

ID of the folder to move the playlist into. To place a playlist directly under “My Playlists”, use folder_id="root".

move_playlist_item(playlist_uuid: str, from_index: int | str, to_index: int | str) → None

Move an item in a playlist owned by the current user.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

playlist_uuidstr

TIDAL playlist UUID.

Example: "e09ab9ce-2e87-41b8-b404-3cd712bf706e".

from_indexint or str

Current item index.

to_indexint or str

Desired item index.

search(query: str, country_code: str = None, *, type: str = None, limit: int = None, offset: int = None) → dict[str, Any]

Search for albums, artists, tracks, and videos.

Authorization scope

Requires the r_usr authorization scope if the device code flow was used.

Parameters:

querystr

Search query.

Example: "Beyoncé".

country_codestr, optional

ISO 3166-1 alpha-2 country code. If not provided, the country code associated with the user account in the current session or the current IP address will be used instead.

Example: "US".

typestr, keyword-only, optional

Target search type. Searches for all types if not specified.

Valid values: "ALBUMS", "ARTISTS", "TRACKS", "VIDEOS".

limitint, keyword-only, optional

Page size.

Example: 10.

offsetint, keyword-only, optional

Pagination offset (in number of items).

Example: 0.

Returns:

resultsdict

A dictionary containing TIDAL catalog information for albums, artists, tracks, and videos matching the search query, and metadata for the returned results.

Sample response

{
  "artists": {
    "limit": <int>,
    "offset": <int>,
    "totalNumberOfItems": <int>,
    "items": [
      {
        "id": <int>,
        "name": <str>,
        "artistTypes": [<str>],
        "url": <str>,
        "picture": <str>,
        "popularity": <int>,
        "artistRoles": [
          {
            "categoryId": <int>,
            "category": <str>
          }
        ],
        "mixes": {
          "ARTIST_MIX": <str>
        }
      }
    ]
  },
  "albums": {
    "limit": <int>,
    "offset": <int>,
    "totalNumberOfItems": <int>,
    "items": [
      {
        "id": <int>,
        "title": <str>,
        "duration": <int>,
        "streamReady": <bool>,
        "adSupportedStreamReady": <bool>,
        "djReady": <bool>,
        "stemReady": <bool>,
        "streamStartDate": <str>,
        "allowStreaming": <bool>,
        "premiumStreamingOnly": <bool>,
        "numberOfTracks": <int>,
        "numberOfVideos": <int>,
        "numberOfVolumes": <int>,
        "releaseDate": <str>,
        "copyright": <str>,
        "type": "ALBUM",
        "version": <str>,
        "url": <str>,
        "cover": <str>,
        "vibrantColor": <str>,
        "videoCover": <str>,
        "explicit": <bool>,
        "upc": <str>,
        "popularity": <int>,
        "audioQuality": <str>,
        "audioModes": [<str>],
        "mediaMetadata": {
          "tags": [<str>]
        },
        "artist": {
          "id": <int>,
          "name": <str>,
          "type": <str>,
          "picture": <str>
        },
        "artists": [
          {
            "id": <int>,
            "name": <str>,
            "type": <str>,
            "picture": <str>
          }
        ]
      }
    ]
  },
  "playlists": {
    "limit": <int>,
    "offset": <int>,
    "totalNumberOfItems": <int>,
    "items": [
      {
        "uuid": <str>,
        "title": <str>,
        "numberOfTracks": <int>,
        "numberOfVideos": <int>,
        "creator": {
          "id": <int>
        },
        "description": <str>,
        "duration": <int>,
        "lastUpdated": <str>,
        "created": <str>,
        "type": <str>,
        "publicPlaylist": <bool>,
        "url": <str>,
        "image": <str>,
        "popularity": <int>,
        "squareImage": <str>,
        "promotedArtists": [
          {
            "id": <int>,
            "name": <str>,
            "type": <str>,
            "picture": <str>,
          }
        ],
        "lastItemAddedAt": <str>
      }
    ]
  },
  "tracks": {
    "limit": <int>,
    "offset": <int>,
    "totalNumberOfItems": <int>,
    "items": [
      {
        "id": <int>,
        "title": <str>,
        "duration": <int>,
        "replayGain": <float>,
        "peak": <float>,
        "allowStreaming": <bool>,
        "streamReady": <bool>,
        "adSupportedStreamReady": <bool>,
        "djReady": <bool>,
        "stemReady": <bool>,
        "streamStartDate": <str>,
        "premiumStreamingOnly": <bool>,
        "trackNumber": <int>,
        "volumeNumber": <int>,
        "version": <str>,
        "popularity": <int>,
        "copyright": <str>,
        "url": <str>,
        "isrc": <str>,
        "editable": <bool>,
        "explicit": <bool>,
        "audioQuality": <str>,
        "audioModes": [<str>],
        "mediaMetadata": {
          "tags": [<str>]
        },
        "artist": {
          "id": <int>,
          "name": <str>,
          "type": <str>,
          "picture": <str>
        },
        "artists": [
          {
            "id": <int>,
            "name": <str>,
            "type": <str>,
            "picture": <str>
          }
        ],
        "album": {
          "id": <int>,
          "title": <str>,
          "cover": <str>,
          "vibrantColor": <str>,
          "videoCover": <str>
        },
        "mixes": {
          "TRACK_MIX": <str>
        }
      }
    ]
  },
  "videos": {
    "limit": <int>,
    "offset": <int>,
    "totalNumberOfItems": <int>,
    "items": [
      {
        "id": <int>,
        "title": <str>,
        "volumeNumber": <int>,
        "trackNumber": <int>,
        "releaseDate": <str>,
        "imagePath": <str>,
        "imageId": <str>,
        "vibrantColor": <str>,
        "duration": <int>,
        "quality": <str>,
        "streamReady": <bool>,
        "adSupportedStreamReady": <bool>,
        "djReady": <bool>,
        "stemReady": <bool>,
        "streamStartDate": <str>,
        "allowStreaming": <bool>,
        "explicit": <bool>,
        "popularity": <int>,
        "type": <str>,
        "adsUrl": <str>,
        "adsPrePaywallOnly": <bool>,
        "artist": {
          "id": <int>,
          "name": <str>,
          "type": <str>,
          "picture": <str>,
        },
        "artists": [
          {
            "id": <int>,
            "name": <str>,
            "type": <str>,
            "picture": <str>,
          }
        ],
        "album": <dict>
      }
    ]
  },
  "topHit": {
    "value": <dict>,
    "type": <str>
  }
}

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

Set the private TIDAL API access token.

Parameters:

access_tokenstr, optional

Access token. If not provided, an access token is obtained using an OAuth 2.0 authorization flow or from the Spotify Web Player.

refresh_tokenstr, keyword-only, optional

Refresh token accompanying access_token.

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 using the refresh token (if available) or the default authorization flow (if possible) when access_token expires.

set_flow(flow: str, client_id: str, *, client_secret: str = None, browser: bool = False, scopes: str | list[str] = '', save: bool = True) → None

Set the authorization flow.

Parameters:

flowstr

Authorization flow. If not specified, no user authentication will be performed.

Valid values:

• "pkce" for the authorization code with proof key for code exchange (PKCE) flow.

• "client_credentials" for the client credentials flow.

client_idstr

Client ID.

client_secretstr, keyword-only, optional

Client secret. Required for all OAuth 2.0 authorization flows.

browserbool, keyword-only, default: False

Determines whether a web browser is automatically opened for the authorization code with PKCE or device code flows. If False, users will have to manually open the authorization URL, and for the authorization code flow, provide the full callback URI via the terminal. For the authorization code with PKCE flow, the Playwright framework by Microsoft is used.

scopesstr or list, keyword-only, optional

Authorization scopes to request user access for in the OAuth 2.0 flows.

Valid values: "r_usr", "w_usr", and "w_sub" (device code flow only).

savebool, keyword-only, default: True

Determines whether to save the newly obtained access tokens and their associated properties to the Minim configuration file.

set_playlist_privacy(playlist_uuid: str, public: bool) → None

Set the privacy of a playlist owned by the current user.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

playlist_uuidstr

TIDAL playlist UUID.

Example: "e09ab9ce-2e87-41b8-b404-3cd712bf706e".

publicbool

Determines whether the playlist is public (True) or private (False).

unblock_artist(artist_id: int | str) → None

Unblock an artist from appearing in mixes and the radio.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

artist_idint or str

TIDAL artist ID.

Example: 1566.

unblock_user(user_id: int | str) → None

Unblock a user.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

user_idint or str

TIDAL user ID.

Example: 172311284.

unfavorite_albums(album_ids: int | str | list[int | str]) → None

Remove albums from the current user’s collection.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

album_idsint, str, or list

TIDAL album ID(s).

Examples: "251380836,275646830" or [251380836, 275646830].

unfavorite_artists(artist_ids: int | str | list[int | str]) → None

Remove artists from the current user’s collection.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

artist_idsint, str, or list

TIDAL artist ID(s).

Examples: "1566,7804" or [1566, 7804].

unfavorite_mixes(mix_ids: str | list[str]) → None

Remove mixes from the current user’s collection.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

mix_idsstr or list

TIDAL mix ID(s).

Examples: "000ec0b01da1ddd752ec5dee553d48,            000dd748ceabd5508947c6a5d3880a" or ["000ec0b01da1ddd752ec5dee553d48", "000dd748ceabd5508947c6a5d3880a"]

unfavorite_playlist(playlist_uuid: str) → None

Remove a playlist from the current user’s collection.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

playlist_uuidstr

TIDAL playlist UUID.

Example: "36ea71a8-445e-41a4-82ab-6628c581535d".

unfavorite_tracks(track_ids: int | str | list[int | str]) → None

Remove tracks from the current user’s collection.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

track_idsint, str, or list

TIDAL track ID(s).

Examples: "251380837,251380838" or [251380837, 251380838].

unfavorite_videos(video_ids: int | str | list[int | str]) → None

Remove videos from the current user’s collection.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

video_idsint, str, or list

TIDAL video ID(s).

Examples: "59727844,75623239" or [59727844, 75623239].

unfollow_user(user_id: int | str) → None

Unfollow a user.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

user_idint or str

TIDAL user ID.

Example: 172311284.

update_playlist(playlist_uuid: str, *, title: str = None, description: str = None) → None

Update the title or description of a playlist owned by the current user.

User authentication and authorization scope

Requires user authentication and the r_usr authorization scope if the device code flow was used.

Parameters:

playlist_uuidstr

TIDAL playlist UUID.

Example: "e09ab9ce-2e87-41b8-b404-3cd712bf706e".

titlestr, keyword-only, optional

New playlist title.

descriptionstr, keyword-only, optional

New playlist description.