Installation

Install from PyPI using pip:

$ pip install tidalapi

Usage

For examples on how to use the api, see the examples directory.

Documentation

Documentation is available at https://tidalapi.netlify.app/

Development

This project uses poetry for dependency management and packaging. To install dependencies and setup the project for development, run:

$ pip install pipx
$ pipx install poetry
$ poetry install --no-root

Contributions

Issues, suggestions and PRs are always welcome and are much appreciated.

Maintainer(s)

• Current:

  • tehkillerbee

• Former:

  • tamland

  • morguldir

v0.8.11

• Bump mpegdash version to 0.4.1 (Fixes bug caused by non-compliant DASH manifests)

v0.8.10

• Tests: Updated misc. tests, added pagination tests - tehkillerbee

• Bugfix: Final chunk count must not exceed maximum number of playlists (Fixes #389) - tehkillerbee

• Bugfix: Fix track version if empty (Fixes #388) - tehkillerbee

v0.8.9

• Bugfix: Return correct Exception, depending on status_code (404, 429). Add missing Raise, comments. Fixes #385 - tehkillerbee

• Added missing fields to Media, Tracks, Videos. Updated tests - tehkillerbee

• Bugfix: Handle Unavailable tracks gracefully. - tehkillerbee

• Bugfix: Favorite videos default limit incorrect - tehkillerbee

• Tests: Added get_favorite_* tests - tehkillerbee

v0.8.8

• Bugfix: OAuth Client ID, secret updated - tehkillerbee

v0.8.7

• OAuth Client ID, secret updated - tehkillerbee

• Bugfix: albums_paginated using get_artists_count instead of get_albums_count - rafrombrc

• TooManyRequests now includes the retry_after header in its data. - semohr

• Added a central error class (TidalAPIError) to allow for unified error handling. - semohr

v0.8.6

• Bugfix: Use get_*_count in workers to get the actual number of items. (Fixes #360) - tehkillerbee

• Feature: Add support for get<track, album, artist, playlist>count(), Workers: Use get_*_count to get the actual number of items. - tehkillerbee

• Feature: Get playlist tracks, items count. Get playlist tracks paginated. - tehkillerbee

• Only return warning if page itemtype (v2) is not implemented (Fixes: #362) - tehkillerbee

• Add legacy home endpoint for backwards compatibility - tehkillerbee

v0.8.5

• Cleanup: Removed deprecated function(s). - tehkillerbee

• Feature: MixV2: Add support for parsing mixes originating from PageCategoryV2. - tehkillerbee

• Feature: Get home page using new v2 endpoint. Add support for PageCategoryV2 - tehkillerbee, Nokse22

• Feature: Add pagination workers from mopidy-tidal - tehkillerbee, BlackLight

• Fix(playlist): Improve v2 endpoint usage. - tehkillerbee

• fix(playlist): More robust handling of the passed objects. - BlackLight

v0.8.4

• Album: Add UPC barcode, genre URL for tidal tracks - tehkillerbee

• Remove Python 2 cruft - C0rn3j

• Adhere to typing standards and mark Python current versions as supported - C0rn3j

• Add Track.get_radio_mix and Artist.get_radio_mix to get radio as Mix - tehkillerbee, Nokse22

• Consistent use of path file open - tehkillerbee

• CI: Fix branch syntax, bump action and python versions to current, fix indent - C0rn3j

• Implement sorting for remaining favourites + playlists nilathedragon

• Feature: Switch to v2 endpoint for playlist get/add/delete. tehkillerbee

• Add support for album, track, artist batch additions. Add support for add/delete mixes and radios to favorites. (Fixes #336, #337, #339) tehkillerbee

• Test: List ordering when getting tracks, items, playlist, mixes tehkillerbee

• Test: Add, remove favorite mix. Add remove artist, album, playlist, track (multiple at a time) tehkillerbee

• Feature: Get origin album cover by tehkillerbee

• Fix: Validate returned tracks (isrc) and skip invalid results tehkillerbee

v0.8.3

• Extended file extension detection to properly detect M4A files. - exislow

• Tests: Updated unit test(s) - tehkillerbee

v0.8.2

• Fixed wrong determination of file extensions for stream metadata. - exislow

• Moved LinkLogin and futures to login_oauth. - exislow

• Added/updated docstrings for auth methods. - exislow

• Methods for device authorization have been renamed considered private. - exislow

v0.8.1

• Typings: get_urls() returned value shall be [str]. - exislow

• Remove MQA legacy code leftovers, HIRES naming inconsistency - exislow

• Tests: Updated unit test(s) - tehkillerbee

v0.8.0

• BREAKING: MQA, Sony 360 audio no longer supported July 24th 2024; removed references to these formats. - tehkillerbee

• Bugfix: Logical loop of is_encrypted / encryption_key - TooYoungTooSimp

• Tests: Added additional playlist, folder tests. - tehkillerbee

• Feature: Add support for playlist merging. - tehkillerbee

• Added trn to playlist object for convenience. - tehkillerbee

• Set limits from argument in all relevant methods. - tehkillerbee

• Feature: Use v2 endpoint for playlist creation. - tehkillerbee

• Feature: Add support for playlist folders (#181) - tehkillerbee

• Feature: Add track to user playlist, user tracks from ISRC (#96) - tehkillerbee

• Feature: Add optional fn_print to Session::login_session_file - GioF71

• Feature: Add support for moving playlist items (#116) - tehkillerbee

• Feature: Allow adding items multiple times to the same playlist - tehkillerbee

• Feature: Add support for adding items to a playlists at a specific position (#116) - tehkillerbee

• Feature: Set UserPlaylist public/private. Add method for getting public user playlists. - tehkillerbee

• Feature: Remove multiple items from UserPlaylist. (Fixes #259) - tehkillerbee

• Remove deprecated username/pass login method (Fixes #279) - tehkillerbee

• Populate the track/items.album attributes from the parent Album object. Updated tests (Fixes #281) - tehkillerbee

• Added clarifications to video_url method. Check video URLs for all available video qualities (Fixes #257) - tehkillerbee

• Tests: Fix all tests that previously failed. - tehkillerbee

• Use enum to specify default audio / video quality - tehkillerbee

• Bugfix: Recent TIDAL changes resulted in missing Mix not causing a ObjectNotFound exception. - tehkillerbee

• Bugfix: Ensure manifest.codecs always uses a Codec type for both MPD and BTS. - tehkillerbee

• Added additional tests to verify stream formats (Relates to #252) - tehkillerbee

• BREAKING: Fix naming of getters to align with python naming convention and avoid confusion (Fixes #255) - tehkillerbee

• Bugfix: Use correct internal type int for relevant IDs (Fixes #260) - tehkillerbee

• Bugfix: Fix linting for audio_modes. Update tests (Fixes #261) - tehkillerbee

• Feat.: Provide “Share Link”, “Listen link” as an attribute to album/artist/media/playlist/. Update relevant tests (Fixes #266) - tehkillerbee

• Allow switching authentication method oauth/pkce for tests. Default: oauth - tehkillerbee

• Tests: Added track stream tests (BTS, MPD) - tehkillerbee

• Bugfix: Always use last element in segment timeline. (Fixes #273) - tehkillerbee

• Add method to get detailed request error response if an error occurred during request. - tehkillerbee

• Tests: Add tests tests for ISRC, barcode methods and cleanup exception handling. - tehkillerbee

• Feat.: Add support to get tracks by ISRC. - tehkillerbee, M4TH1EU

• Feat.: Add support to get albums by Barcode ID (UPC). - tehkillerbee, M4TH1EU

• Feat.: Add support for a custom base url in request() and basic_request() to use the new openapi. - M4TH1EU

v0.7.6

• Fix: Set token type correctly for OAuth/PKCE authentication - tehkillerbee

• Revert to using enums with str support for relevant classes - tehkillerbee, exislow

• Removed return types from method names for consistency, added deprecation warnings - exislow

v0.7.5

• Fix: Use wide image when no square picture is available. - tehkillerbee

• Feat.: Added HiRes page. - tehkillerbee

• Feat.: Handle missing Stream fields gracefully. Get stream audio resolution (bit depth, rate) as tuple. - tehkillerbee

• Feat.: Added misc helper functions for audio mode, get available audio mode for media. - tehkillerbee

• Feat.: Added misc. fields to album. Get audio resolution for album + individual tracks. - tehkillerbee

• Feat.: Added MPEG-DASH to HLS stream parsing, Added MPEG-DASH stream example. - tehkillerbee

• Set default artist IMG if missing. Use default album IMG URI instead of direct URL. - tehkillerbee

• Bugfix: Make sure is_pkce state is set when pkce_login_url() is used directly. - tehkillerbee

• Tests: Added misc tests for ObjectNotFound - tehkillerbee

• Error handling: Handle TooManyRequests exceptions gracefully. - tehkillerbee

• Error handling: Handle ObjectNotFound exceptions gracefully. - tehkillerbee

• Tests: Fix misc tests broken by Tidal. - tehkillerbee

• Bugfix: Fix pkce token refresh. - tehkillerbee

• Bugfix: Load/store PKCE state from file using wrong client_id. - tehkillerbee

• Feat.: Improved error handling (Missing albums, missing lyrics, missing track url etc.). - tehkillerbee

• Bugfix: Page Recursion into Categories. - quodrum-glas

v0.7.4

• Load/store OAuth/PKCE session to file - tehkillerbee

• Add PKCE login for HiRes - exislow, arnesongit

• Include request response on error. Print as warning - tehkillerbee

• Fix tests - tehkillerbee

• Bugfixes (artist.get_similar) - tehkillerbee

• Favourite mixes refactoring - jozefKruszynski

• Add typings for Playlist, UserPlaylist, Pages - arusahni

• Update favorites.tracks to accept order and orderDirection params - Jimmyscene

v0.7.3

• Official support for HI_RES FLAC quality - tehkillerbee

• Add helper functions to set audio/video quality for current session - tehkillerbee

• Added missing WELCOME_MIX MixType - tehkillerbee

• Various image bugfixes - tehkillerbee

• Add “for_you” page - tehkillerbee

• Various test, poetry bugfixes - 2e0byo

• Add typings for Artists and Users - arusahni

• Add media metadata - jozefKruszynski

• Add option to limit track radio length - jozefKruszynski

• Downgrade minimum required version of requests JoshMock

v0.7.2

• (BREAKING!) Drop support for python3.8 and older

• Improved tests - 2e0byo

• Add type to album object - jozefKruszynski

• Add mix images and tests - jozefKruszynski

• Add mypy and fix immediate typing errors - arusahni

• New attribute to media.Track() class: ‘full_name’ - WilliamGuisan

• Fix Track.stream() method - ssnailed

• Fixed key error for gender when parsing user json - mkaufhol

• Drop (almost) all user data we don’t use. - 2e0byo

• Add typing for media, genres, mixes, and albums - arusahni

• Replace TypedDict and NamedTuple with dataclasses - arusahni

• Fix circular Imports and Typing - PretzelVector

v0.7.1

• Quick fix for “got key error ‘picture’” error. - BlackLight

• Bring back Radio support - bjesus

• Added function for multiple deletions at once bloedboemmel

• Use UTC instead of local time for expiry_time lutzbuerkle

v0.7.0

• (BREAKING!) Removed obsolete parameter session_id from load_oauth_session - lutzbuerkle

• (BREAKING!) Drop support for python2.7 - morguldir

• (BREAKING!) Change the architecture of the library to allow for using more files, see the migration guide - morguldir

• Add support for tidal pages (e.g. home, videos and explore in the web ui) - morguldir

• Add support for parsing mixes and retrieving the media - morguldir

• Get rid of the old genre and mood support, you can now find them in the pages instead - morguldir

• Update almost all of the json parsing and classes to include more fields - morguldir

• Add complete docstrings to many of the functions - morguldir

• Tests now cover almost all of the code - morguldir

• Pylint scores are now much higher - morguldir

• Add option to retrieve master quality tracks (I can’t test this, but I believe it works as of writing) - morguldir

• Add a few documentation pages explaining the basics - morguldir

• Add support for modifying playlists - morguldir

• Add a parameter to always fetch the track album if it’s not provided - divadsn

• Add function to retrieve the year and date from either the release data or the stream start date - divadsn

• Improve the performance of the internal get_items() function by using extend - BlackLight

• Properly deal with the api returning non-json results - BlackLight

• Add support for retrieving the reviews of an album - retired-guy

v0.6.10

• Update the client secret - 1nikolas

• Use a track url endpoint compatible with the new secret - morguldir

v0.6.9

• Update the client secret - morguldir

• Fix token_refresh() not correctly including the client secret - morguldir

v0.6.8

• Support OAuth login through login_oauth_simple() and login_oauth() - morguldir

• Support loading an OAuth session through load_oauth_session() - morguldir

• Include more info when a request fails - morguldir

v0.6.7

• Fix wimp images not resolving - ktnrg45

• Made the favorite playlists function also return created playlists - morguldir

v0.6.6

• Update api token and slightly obfuscate it - morguldir

v0.6.5

• Update api token - morguldir

v0.6.4

• Add parameter to search() allowing for more results (up to 300) - morguldir

• Fix get_track_url() not returning anything - morguldir

v0.6.3

• Fix quality options using enum names instead of values - morguldir

• Handle situations where tidal doesn’t set the version tag - morguldir

v0.6.2

• Update lossless token - morguldir

• Always use the same api token - morguldir

• Include additional info when logging fails - morguldir

• Make user_id and country_code optional when using load_session() - morguldir

• Add version tag for Track - Husky22

• Switch to netlify for documentation - morguldir