API Reference

tidalapi.session

class tidalapi.session.Session(config=<tidalapi.session.Config object>)

Object for interacting with the TIDAL api and

access_token = None

The TIDAL access token, this is what you use with load_oauth_session

expiry_time = None

A datetime object containing the date the access token will expire

refresh_token = None

A refresh token for retrieving a new access token through refresh_token

token_type = None

The type of access token, e.g. Bearer

session_id = None

The id for a TIDAL session, you also need this to use load_oauth_session

country_code = None

user = None

A User object containing the currently logged in user.

convert_type(search, search_type='identifier', output='identifier', case=Case.pascal, suffix=True)

load_session(session_id, country_code=None, user_id=None)

Establishes TIDAL login details using a previous session id. May return true if the session-id is invalid/expired, you should verify the login afterwards.

Parameters:

• session_id – The UUID of the session you want to use.

• country_code – (Optional) Two-letter country code.

• user_id – (Optional) The number identifier of the user.

Returns:

False if we know the session_id is incorrect, otherwise True

load_oauth_session(token_type, access_token, refresh_token=None, expiry_time=None)

Login to TIDAL using details from a previous OAuth login, automatically refreshes expired access tokens if refresh_token is supplied as well.

Parameters:

• token_type – The type of token, e.g. Bearer

• access_token – The access token received from an oauth login or refresh

• refresh_token – (Optional) A refresh token that lets you get a new access token after it has expired

• expiry_time – (Optional) The datetime the access token will expire

Returns:

True if we believe the log in was successful, otherwise false.

login(username, password)

Logs in to the TIDAL api.

Parameters:

• username – The TIDAL username

• password – The password to your TIDAL account

Returns:

Returns true if we think the login was successful.

login_oauth_simple(function=<built-in function print>)

Login to TIDAL using a remote link. You can select what function you want to use to display the link

Parameters:

function – The function you want to display the link with

Raises:

TimeoutError: If the login takes too long

login_oauth()

Login to TIDAL with a remote link for limited input devices. The function will return everything you need to log in through a web browser, and will return an future that will run until login.

Returns:

A LinkLogin object containing all the data needed to log in remotely, and a concurrent.futures.Future that will poll until the login is completed, or until the link expires.

Raises:

TimeoutError: If the login takes too long

token_refresh(refresh_token)

Retrieves a new access token using the specified parameters, updating the current access token

Parameters:

refresh_token – The refresh token retrieved when using the OAuth login.

Returns:

True if we believe the token was successfully refreshed, otherwise False

search(query, models=None, limit=50, offset=0)

Searches TIDAL with the specified query, you can also specify what models you want to search for. While you can set the offset, there aren’t more than 300 items available in a search.

Parameters:

• query – The string you want to search for

• models – A list of tidalapi models you want to include in the search. Valid models are Artist, Album, Track, Video, Playlist

• limit – The amount of items you want included, up to 300.

• offset – The index you want to start searching at.

Returns:

Returns a dictionary of the different models, with the dictionary values containing the search results. The dictionary also contains a ‘top_hit’ result for the most relevant result, limited to the specified types

check_login()

Returns true if current session is valid, false otherwise.

playlist(playlist_id=None)

Function to create a playlist object with access to the session instance in a smoother way. Calls tidalapi.Playlist(session=session, playlist_id=playlist_id) internally

Parameters:

playlist_id – (Optional) The TIDAL id of the playlist. You may want access to the methods without an id.

Returns:

Returns a Playlist object that has access to the session instance used.

track(track_id=None, with_album=False)

Function to create a Track object with access to the session instance in a smoother way. Calls tidalapi.Track(session=session, track_id=track_id) internally

Parameters:

• track_id – (Optional) The TIDAL id of the Track. You may want access to the methods without an id.

• with_album – (Optional) Whether to fetch the complete Album for the track or not

Returns:

Returns a Track object that has access to the session instance used.

video(video_id=None)

Function to create a Video object with access to the session instance in a smoother way. Calls tidalapi.Video(session=session, video_id=video_id) internally

Parameters:

video_id – (Optional) The TIDAL id of the Video. You may want access to the methods without an id.

Returns:

Returns a Video object that has access to the session instance used.

artist(artist_id=None)

Function to create a Artist object with access to the session instance in a smoother way. Calls tidalapi.Artist(session=session, artist_id=artist_id) internally

Parameters:

artist_id – (Optional) The TIDAL id of the Artist. You may want access to the methods without an id.

Returns:

Returns a Artist object that has access to the session instance used.

album(album_id=None)

Function to create a Album object with access to the session instance in a smoother way. Calls tidalapi.Album(session=session, album_id=album_id) internally

Parameters:

album_id – (Optional) The TIDAL id of the Album. You may want access to the methods without an id.

Returns:

Returns a Album object that has access to the session instance used.

mix(mix_id=None)

Function to create a mix object with access to the session instance smoothly Calls tidalapi.Mix(session=session, mix_id=mix_id) internally

Parameters:

mix_id – (Optional) The TIDAL id of the Mix. You may want access to the mix methods without an id.

Returns:

Returns a Mix object that has access to the session instance used.

get_user(user_id=None)

Function to create a User object with access to the session instance in a smoother way. Calls tidalapi.User(session=session, user_id=user_id) internally

Parameters:

user_id – (Optional) The TIDAL id of the User. You may want access to the methods without an id.

Returns:

Returns a User object that has access to the session instance used.

home()

Retrieves the Home page, as seen on https://listen.tidal.com

Returns:

A Page object with the PageCategory list from the home page

explore()

Retrieves the Explore page, as seen on https://listen.tidal.com/view/pages/explore

Returns:

A Page object with the PageCategory list from the explore page

videos()

Retrieves the Videos page, as seen on https://listen.tidal.com/view/pages/videos

Returns:

A Page object with a <.PageCategory> list from the videos page

genres()

Retrieves the global Genre page, as seen on https://listen.tidal.com/view/pages/genre_page

Returns:

A Page object with the PageCategory list from the genre page

local_genres()

Retrieves the local Genre page, as seen on https://listen.tidal.com/view/pages/genre_page_local

Returns:

A Page object with the PageLinks list from the local genre page

moods()

Retrieves the mood page, as seen on https://listen.tidal.com/view/pages/moods

Returns:

A Page object with the PageLinks list from the moods page

mixes()

Retrieves the current users mixes, as seen on https://listen.tidal.com/view/pages/my_collection_my_mixes

Returns:

A list of Mix

class tidalapi.session.Config(quality=Quality.high, video_quality=VideoQuality.high, item_limit=1000, alac=True)

Configuration for TIDAL services.

The maximum item_limit is 10000, and some endpoints have a maximum of 100 items, which will be shown in the docs. In cases where the maximum is 100 items, you will have to use offsets to get more than 100 items. Note that changing the ALAC option requires you to log in again, and for you to create a new config object IMPORTANT: ALAC=false will mean that video streams turn into audio-only streams.

Additionally, num_videos will turn into num_tracks in playlists.

class tidalapi.session.Quality(value)

An enumeration.

lossless = 'LOSSLESS'

high = 'HIGH'

low = 'LOW'

master = 'HI_RES'

class tidalapi.session.VideoQuality(value)

An enumeration.

high = 'HIGH'

medium = 'MEDIUM'

low = 'LOW'

class tidalapi.session.LinkLogin(json)

The data required for logging in to TIDAL using a remote link, json is the data returned from TIDAL

expires_in = None

Amount of seconds until the code expires

user_code = None

The code the user should enter at the uri

verification_uri = None

The link the user has to visit

verification_uri_complete = None

The link the user has to visit, with the code already included

tidalapi.artist

A module containing information and functions related to TIDAL artists.

class tidalapi.artist.Artist(session, artist_id)

name = None

roles = None

role = None

picture = None

user_date_added = None

id = None

parse_artist(json_obj)

Parameters:

json_obj –

Returns:

parse_artists(json_obj)

Parses a TIDAL artist, replaces the current artist object. Made for use inside of the python tidalapi module.

Parameters:

json_obj – Json data returned from api.tidal.com containing an artist

Returns:

Returns a copy of the original :exc:’Artist’: object

get_albums(limit=None, offset=0)

Queries TIDAL for the artists albums.

Returns:

A list of Albums

get_albums_ep_singles(limit=None, offset=0)

Queries TIDAL for the artists extended plays and singles.

Returns:

A list of Albums

get_albums_other(limit=None, offset=0)

Queries TIDAL for albums the artist has appeared on as a featured artist.

Returns:

A list of Albums

get_top_tracks(limit=None, offset=0)

Queries TIDAL for the artists tracks, sorted by popularity.

Returns:

A list of Tracks

get_videos(limit=None, offset=0)

Queries tidal for the artists videos.

Returns:

A list of Videos

get_bio()

Queries TIDAL for the artists biography

Returns:

A string containing the bio, as well as identifiers to other TIDAL objects inside the bio.

get_similar()

Queries TIDAL for similar artists

Returns:

A list of Artists

get_radio()

Queries TIDAL for the artist radio, which is a mix of tracks that are similar to what the artist makes.

Returns:

A list of Tracks

image(dimensions)

A url to an artist picture

Parameters:

dimensions (int) – The width and height that you want from the image

Returns:

A url to the image.

Valid resolutions: 160x160, 320x320, 480x480, 750x750

page()

Retrieve the artist page as seen on https://listen.tidal.com/artist/$id

Returns:

A Page containing all the categories from the page, e.g. tracks, influencers and credits

tidalapi.user

A module containing classes and functions related to tidal users.

User is a class with user information. Favorites is class with a users favorites.

class tidalapi.user.User(session, user_id)

A class containing various information about a TIDAL user.

The attributes of this class are pretty varied. ID is the only attribute you can rely on being set. If you initialized a specific user, you will get id, first_name, last_name, and picture_id. If parsed as a playlist creator, you will get an ID and a name, if the creator isn’t an artist, name will be ‘user’. If the parsed user is the one logged in, for example in session.user, you will get the remaining attributes, and id.

id = -1

factory()

parse(json_obj)

class tidalapi.user.FetchedUser(session, user_id)

Bases: User

first_name = None

last_name = None

picture_id = None

parse(json_obj)

image(dimensions)

class tidalapi.user.LoggedInUser(session, user_id)

Bases: FetchedUser

username = None

email = None

created = None

newsletter = None

accepted_eula = None

gender = None

date_of_birth = None

facebook_uid = None

apple_uid = None

parse(json_obj)

playlists()

Get the playlists created by the user.

Returns:

Returns a list of Playlist objects containing the playlists.

playlist_and_favorite_playlists(offset=0)

Get the playlists created by the user, and the playlists favorited by the user. This function is limited to 50 by TIDAL, requiring pagination.

Returns:

Returns a list of Playlist objects containing the playlists.

create_playlist(title, description)

class tidalapi.user.PlaylistCreator(session, user_id)

Bases: User

name = None

parse(json_obj)

class tidalapi.user.Favorites(session, user_id)

An object containing a users favourites. This is the “music library” of the user labled “my collection” by Tidal

add_album(album_id)

Adds an album to the users favorites.

Parameters:

album_id – TIDAL’s identifier of the album.

Returns:

A boolean indicating whether the request was successful or not.

add_artist(artist_id)

Adds an artist to the users favorites.

Parameters:

artist_id – TIDAL’s identifier of the artist

Returns:

A boolean indicating whether the request was successful or not.

add_playlist(playlist_id)

Adds a playlist to the users favorites.

Parameters:

playlist_id – TIDAL’s identifier of the playlist.

Returns:

A boolean indicating whether the request was successful or not.

add_track(track_id)

Adds a track to the users favorites.

Parameters:

track_id – TIDAL’s identifier of the track.

Returns:

A boolean indicating whether the request was successful or not.

add_video(video_id)

Adds a video to the users favorites.

Parameters:

video_id – TIDAL’s identifier of the video.

Returns:

A boolean indicating whether the request was successful or not.

remove_artist(artist_id)

Removes a track from the users favorites.

Parameters:

artist_id – TIDAL’s identifier of the artist.

Returns:

A boolean indicating whether the request was successful or not.

remove_album(album_id)

Removes an album from the users favorites.

Parameters:

album_id – TIDAL’s identifier of the album

Returns:

A boolean indicating whether the request was successful or not.

remove_playlist(playlist_id)

Removes a playlist from the users favorites.

Parameters:

playlist_id – TIDAL’s identifier of the playlist.

Returns:

A boolean indicating whether the request was successful or not.

remove_track(track_id)

Removes a track from the users favorites.

Parameters:

track_id – TIDAL’s identifier of the track.

Returns:

A boolean indicating whether the request was successful or not.

remove_video(video_id)

Removes a video from the users favorites.

Parameters:

video_id – TIDAL’s identifier of the video.

Returns:

A boolean indicating whether the request was successful or not.

artists(limit=None, offset=0)

Get the users favorite artists

Returns:

A list of Artist objects containing the favorite artists.

albums(limit=None, offset=0)

Get the users favorite albums

Returns:

A list of Album objects containing the favorite albums.

playlists(limit=None, offset=0)

Get the users favorite playlists

Returns:

A list Playlist objects containing the favorite playlists.

tracks(limit=None, offset=0)

Get the users favorite tracks part of the “my collection” tab

Returns:

A list of Track objects containing all of the favorite tracks.

videos()

Get the users favorite videos

Returns:

A list of Video objects containing all the favorite videos

tidalapi.playlist

A module containing things related to TIDAL playlists.

class tidalapi.playlist.Playlist(session, playlist_id)

An object containing various data about a playlist and methods to work with them.

name = None

num_tracks = -1

num_videos = -1

creator = None

description = None

duration = -1

last_updated = None

created = None

type = None

public = False

popularity = -1

promoted_artists = None

last_item_added_at = None

picture = None

square_picture = None

user_date_added = None

id = None

parse(json_obj)

Parses a playlist from tidal, replaces the current playlist object.

Parameters:

json_obj – Json data returned from api.tidal.com containing a playlist

Returns:

Returns a copy of the original :exc:’Playlist’: object

factory()

parse_factory(json_obj)

tracks(limit=None, offset=0)

Gets the playlists̈́’ tracks from TIDAL.

Parameters:

• limit – The amount of items you want returned.

• offset – The index of the first item you want included.

Returns:

A list of Tracks

items(limit=100, offset=0)

Fetches up to the first 100 items, including tracks and videos

Parameters:

• limit – The amount of items you want, up to 100.

• offset – The index of the first item you want returned

Returns:

A list of Tracks and Videos

image(dimensions)

A URL to a playlist picture

Parameters:

dimensions (int) – The width and height that want from the image

Returns:

A url to the image

Original sizes: 160x160, 320x320, 480x480, 640x640, 750x750, 1080x1080

wide_image(width=1080, height=720)

Create a url to a wider playlist image.

Parameters:

• width – The width of the image

• height – The height of the image

Returns:

Returns a url to the image with the specified resolution

Valid sizes: 160x107, 480x320, 750x500, 1080x720

class tidalapi.playlist.UserPlaylist(session, playlist_id)

Bases: Playlist

edit(title=None, description=None)

delete()

add(media_ids)

remove_by_index(index)

remove_by_id(media_id)

tidalapi.album

class tidalapi.album.Album(session, album_id)

Contains information about a TIDAL album.

If the album is created from a media object, this object will only contain the id, name, cover and video cover. TIDAL does this to reduce the network load.

name = None

cover = None

video_cover = None

duration = -1

available = False

num_tracks = -1

num_videos = -1

num_volumes = -1

tidal_release_date = None

release_date = None

copyright = None

version = None

explicit = True

universal_product_number = -1

popularity = -1

user_date_added = None

artists = None

artist = None

id = None

parse(json_obj, artist=None, artists=None)

property year

Convenience function to get the year using available_release_date

Returns:

An int containing the year the track was released

property available_release_date

Get the release date if it’s available, otherwise get the day it was released on TIDAL

Returns:

A datetime.datetime object with the release date, or the tidal release date, can be None

tracks(limit=None, offset=0)

Returns the tracks in classes album.

Parameters:

• limit – The amount of items you want returned.

• offset – The position of the first item you want to include.

Returns:

A list of the Tracks in the album.

items(limit=100, offset=0)

Gets the first 100 tracks and videos in the album from TIDAL.

Parameters:

offset – The index you want to start retrieving items from

Returns:

A list of Tracks and Videos`

image(dimensions, default='https://tidal.com/browse/assets/images/defaultImages/defaultAlbumImage.png')

A url to an album image cover

Parameters:

dimensions (int) – The width and height that you want from the image

Returns:

A url to the image.

Valid resolutions: 80x80, 160x160, 320x320, 640x640, 1280x1280

video(dimensions)

Creates a url to an mp4 video cover for the album.

Valid resolutions: 80x80, 160x160, 320x320, 640x640, 1280x1280

Parameters:

dimensions (int) – The width an height of the video

Returns:

A url to an mp4 of the video cover.

page()

Retrieve the album page as seen on https://listen.tidal.com/album/$id

Returns:

A Page containing the different categories, e.g. similar artists and albums

similar()

Retrieve albums similar to the current one

Returns:

A list of similar albums

review() → str

Retrieve the album review

Returns:

A str containing the album review, with wimp links

Raises:

requests.HTTPError if there isn’t a review yet

tidalapi.media

A module containing information about various media types.

Classes: Media, Track, Video

class tidalapi.media.Media(session, media_id=None)

Base class for generic media, specifically Track and Video

This class includes data used by both of the subclasses, and a function to parse both of them.

The date_added attribute is only relevant for playlists. For the release date of the actual media, use the release date of the album.

name = None

duration = -1

available = True

tidal_release_date = None

user_date_added = None

track_num = -1

volume_num = 1

explicit = False

popularity = -1

artist = None

artist_roles = None

For the artist credit page

artists = None

type = None

album = None

id = None

parse(json_obj)

Assigns all :param json_obj: :return:

parse_media(json_obj)

Selects the media type when checking lists that can contain both.

Parameters:

json_obj – The json containing the media

Returns:

Returns a new Video or Track object.

class tidalapi.media.Track(session, media_id=None)

Bases: Media

An object containing information about a track.

replay_gain = None

peak = None

isrc = None

audio_quality = None

version = None

copyright = None

parse_track(json_obj)

get_url()

lyrics()

Retrieves the lyrics for a song

Returns:

A Lyrics object containing the lyrics

Raises:

A requests.HTTPError if there aren’t any lyrics

class tidalapi.media.Video(session, media_id=None)

Bases: Media

An object containing information about a video

release_date = None

video_quality = None

cover = None

parse_video(json_obj)

get_url()

image(width=1080, height=720)

tidalapi.genre

class tidalapi.genre.Genre(session)

name = ''

path = ''

playlists = False

artists = False

albums = False

tracks = False

videos = False

image = ''

parse_genre(json_obj)

parse_genres(json_obj)

get_genres()

items(model)

Gets the current genre’s items of the specified type :param model: The tidalapi model you want returned. See Genre :return:

tidalapi.page

Module for parsing TIDAL’s pages format found at https://listen.tidal.com/v1/pages

class tidalapi.page.Page(session, title)

A page from the https://listen.tidal.com/view/pages/ endpoint

The categories field will the most complete information However it is an iterable that goes through all the visible items on the page as well, in the natural reading order

categories = None

title = ''

next()

parse(json_obj)

Goes through everything in the page, and gets the title and adds all the rows to the categories field :param json_obj: The json to be parsed :return: A copy of the Page that you can use to browse all the items

get(endpoint, params=None)

Retrieve a page from the specified endpoint, overwrites the calling page

Parameters:

• params – Parameter to retrieve the page with

• endpoint – The endpoint you want to retrieve

Returns:

A copy of the new Page at the requested endpoint

class tidalapi.page.PageCategory(session)

type = None

title = None

description = ''

requests = None

session = None

parse(json_obj)

show_more()

Get the full list of items on their own Page from a PageCategory

Returns:

A Page more of the items in the category, None if there aren’t any

class tidalapi.page.FeaturedItems(session)

Bases: PageCategory

Items that have been featured by TIDAL

items = None

parse(json_obj)

class tidalapi.page.PageLinks(session)

Bases: PageCategory

A list of PageLink to other parts of TIDAL

items = None

parse(json_obj)

Parse the list of links from TIDAL

Parameters:

json_obj – The json to be parsed

Returns:

A copy of this page category containing the links in the items field

class tidalapi.page.ItemList(session)

Bases: PageCategory

A list of items from TIDAL, can be a list of mixes, for example, or a list of playlists and mixes in some cases

items = None

parse(json_obj)

Parse a list of items on TIDAL from the pages endpoints.

Parameters:

json_obj – The json from TIDAL to be parsed

Returns:

A copy of the ItemList with a list of items

class tidalapi.page.PageItem(session, json_obj)

An Item from a PageCategory from the /pages endpoint, call get() to retrieve the actual item

header = ''

short_header = ''

short_sub_header = ''

image_id = ''

type = ''

artifact_id = ''

text = ''

featured = False

get()

Retrieve the PageItem with the artifact_id matching the type

Returns:

The fully parsed item, e.g. Playlist, Video, Track

class tidalapi.page.PageLink(session, json_obj)

A Link to another Page on TIDAL, Call get() to retrieve the Page

requests = None

session = None

title = None

icon = None

api_path = None

image_id = None

get()

Requests the linked page from TIDAL :return: A Page at the api_path

tidalapi.mix

A module containing functions relating to TIDAL mixes.

class tidalapi.mix.MixType(value)

An enum to track all the different types of mixes

video_daily = 'VIDEO_DAILY_MIX'

daily = 'DAILY_MIX'

discovery = 'DISCOVERY_MIX'

new_release = 'NEW_RELEASE_MIX'

track = 'TRACK_MIX'

artist = 'ARTIST_MIX'

songwriter = 'SONGWRITER_MIX'

producter = 'PRODUCER_MIX'

history_alltime = 'HISTORY_ALLTIME_MIX'

history_monthly = 'HISTORY_MONTHLY_MIX'

history_yearly = 'HISTORY_YEARLY_MIX'

class tidalapi.mix.Mix(session, mix_id)

A mix from TIDAL, e.g. the listen.tidal.com/view/pages/my_collection_my_mixes

These get used for many things, like artist/track radio’s, recommendations, and historical plays

id = ''

title = ''

sub_title = ''

sharing_images = None

mix_type = None

content_behaviour = ''

short_subtitle = ''

get(mix_id=None)

Returns information about a mix, and also replaces the mix object used to call this function.

Parameters:

mix_id – TIDAL’s identifier of the mix

Returns:

A Mix object containing all the information about the mix

parse(json_obj)

Parse a mix into a Mix, replaces the calling object

Parameters:

json_obj – The json of a mix to be parsed

Returns:

A copy of the parsed mix

items()

Returns all the items in the mix, retrieves them with get as well if not already done

Returns:

A list of videos and/or tracks from the mix