Collections

The Tidal service implements the standard collection interfaces that are common across all plistsync services. By inheriting from the base classes and conforming to the established protocols, Tidal provides a unified interface that works consistently with other services.

Library

The TidalLibrary represents the full Tidal catalog from the perspective of the authenticated user.

from plistsync.services.tidal import TidalLibrary

library = TidalLibrary()

Track Lookup

The Tidal library collections implements the GlobalLookup protocol, allowing you to search for tracks across Tidal’s entire music universe by their ids. Specifically, tidal supports lookups by isrc and tidal_id.

# By tidal id
if track1 := library.find_by_global_ids({"isrc": "GBBZH9601601"}):
    print(track1)

# By isrc
if track2 := library.find_by_global_ids({"tidal_id": "490839595"}):
    print(track2)

assert track1 == track2

TidalTrack(artist='Origin Unknown', title='Valley Of The Shadows')
TidalTrack(artist='Origin Unknown', title='Valley Of The Shadows')

Note

Track equality is determined by metadata and unique identifiers. On Tidal, identical tracks may have different IDs (e.g., due to different releases or versions), which can lead to false negatives during equality checks. While this may cause unexpected mismatches, it reflects the underlying truth: these are distinct track instances—even if sonically identical.

If you need/want to lookup many tracks at once, consider using TidalLibrary.find_many_by_global_ids for better performance.

Playlist

The TidalPlaylist represents a playlist than is accessible by the currently authenticated user.

Retrieving playlists

You can retrieve all playlists of a user using the library’s TidalLibrary.playlists property.

playlists = library.playlists
for playlist in playlists:
    print(f"Playlist: {playlist.name} ({len(playlist)} tracks)")

Playlist: plistsync (3 tracks)

If you just want a specific playlist, you can use the library’s TidalLibrary.get_playlist method to retrieve a playlist.

pl = library.get_playlist(
    name="plistsync"
    # id = "23d960d6-07be-42f3-89ab-72ec339ca9ac"
    # url = "https://tidal.com/playlist/23d960d6-07be-42f3-89ab-72ec339ca9ac"
)
if pl is not None:
    print(f"Found playlist: {pl.name} ({len(pl)} tracks)")
else:
    print("Playlist not found.")

Found playlist: plistsync (3 tracks)

Note

This method supports lookup by various identifiers, including name=, id=, or url=. Lookup by name will return None if no matching playlist is found, while lookups by other identifiers will raise a ValueError if the playlist cannot be resolved.

Creating playlists

By convention, playlist are always created within a library. To create a new playlist online, use the {py.meth}TidalLibrary.create_playlist <plistsync.services.tidal.TidalLibrary.create_playlist> method.

pl = library.create_playlist(
    name="My New Playlist",
    description="Created via plistsync",
)

Updating a playlist

For updating a playlist, you should use the playlist’s TidalPlaylist.edit context manager. This ensures that all changes are properly saved back to Tidal when you exit the context. This also minifies changes and therefore reduces API calls.

# Updating a playlist description/name
with pl.edit():
    pl.description = "Updated Description"

pl.description

'Updated Description'

You can add tracks to a playlist using the same context manager, again this will add the tracks when you exit the context.

from plistsync.services.tidal import TidalPlaylistTrack

new_track_1 = library.find_by_global_ids({"isrc": "GBBZH9601601"})
new_track_2 = library.find_by_global_ids({"isrc": "GBXJH1000082"})
assert new_track_1 is not None
assert new_track_2 is not None

with pl.edit():
    # TODO: We should reevaluate the type hierarchy here.
    # for now, we have to manually cast TidalTrack to TidalPlaylistTrack.
    # this will become more convenient, eventually.
    pl.tracks.append(TidalPlaylistTrack(new_track_1))
    pl.tracks.append(TidalPlaylistTrack(new_track_2))

pl.tracks

[TidalPlaylistTrack(artist='Origin Unknown', title='Valley Of The Shadows'),
 TidalPlaylistTrack(artist='Kyo', title='If I Could')]

# Remove a track
with pl.edit():
    pl.tracks.pop()

To reorder tracks in a playlist, you can change the order of the TidalPlaylist.tracks list within the context manager.

with pl.edit():
    pl.tracks.insert(0, pl.tracks.pop())

Delete a playlist

To remove the playlist from your tidal account, use the TidalPlaylist.delete method.

Note how this returns an instance of OfflinePlaylist, so that you can still work with the local in-memory version of the last online state.

offline_pl = pl.delete()
offline_pl

OfflinePlaylist(name='My New Playlist', tracks=2)

Note: Although you might still have pl as a variable available locally, you should never continue to use it. This will result in undefined behaviour, as the playlist no longer exists online.

try:
    library.get_playlist_or_raise(id=pl.id)
except Exception as e:
    print(e)

Playlist with id 334ffc4b-0c92-4f09-ae3b-26be2940ab56 not found

Our recommended way for recovery is to create a new playlist based on the track data kept in the offline_pl. We are working on helpers to persist them on disk, to make recovery easier.