Tidekeeper

Tidekeeper is an unofficial maintained fork of yaronzz/Tidal-Media-Downloader, with a reliable terminal workflow and optional desktop GUI. The primary command is tidekeeper; tidal-dl remains available for compatibility.

Install

Tidekeeper requires Python 3.10 or newer.

ffmpeg is recommended for video downloads and optional FLAC remux (tidekeeper --doctor reports whether it is available).

From PyPI (recommended)

python -m pip install -U tidekeeper
tidekeeper --help

Desktop GUI:

python -m pip install -U "tidekeeper[gui]"
tidekeeper-gui

From Git

python -m pip install -U "git+https://github.com/OpenNerdz/tidekeeper.git#subdirectory=TIDALDL-PY"
tidekeeper --help

One-line installer (Linux / Termux)

curl -fsSL https://raw.githubusercontent.com/OpenNerdz/tidekeeper/main/install.sh | bash

For Android shared storage, run termux-setup-storage and optionally set:

export TIDEKEEPER_DOWNLOAD_PATH="/storage/emulated/0/Download/Tidekeeper"

Prebuilt binaries

Terminal and desktop GUI executables for Windows, macOS, and Linux are attached to each GitHub Release.

Docker

Build the image from the repository, then persist account configuration and downloads with bind mounts. The image includes ffmpeg.

docker build -t tidekeeper .
docker run --rm -it \
  -v "$PWD/config:/config" \
  -v "$PWD/downloads:/downloads" \
  tidekeeper
docker run --rm \
  -v "$PWD/config:/config" \
  -v "$PWD/downloads:/downloads" \
  tidekeeper -l "https://tidal.com/browse/track/70973230"

The container runs as non-root UID 1000. Ensure both host directories are writable by that user. A GUI is not included in the container image.

Usage

tidekeeper --help
tidekeeper --doctor
tidekeeper --paths
tidekeeper --open-output
tidekeeper --update
tidekeeper -l "https://tidal.com/browse/track/70973230"
tidekeeper --video-only -l "https://tidal.com/browse/artist/123456"

Dolby Atmos downloads are opt-in with tidekeeper -q Atmos (or GUI audio quality Atmos). TIDAL keeps Atmos mixes on separate catalog IDs that often report quality LOW with an Atmos flag — search now labels those rows clearly, and when Atmos quality is selected Tidekeeper will switch a stereo album/track pick to the matching Atmos catalog release when one exists.

Failed downloads are saved to failed-tracks.txt in the download folder and can be retried with:

tidekeeper -l "/path/to/downloads/failed-tracks.txt"

Customizability

Custom filename formats are supported:

Tokens	Description	Album	Track	Video	Playlist
{ArtistID}	Comma separated list of each artists' ID for that media (i.e: 123, 456)	✅	❌	✅	❌
{ArtistName}	Comma separated list of each artists' name for that media (i.e: ABC, DEF)	✅	❌	❌	❌
{ArtistName}	Primary artist's name for that media	❌	✅	✅	❌
{ArtistsName}	Comma separated list of each artists' name for that media (i.e: ABC, DEF)	❌	✅	✅	❌
{AlbumArtistID}	Primary artist's ID for that media	✅	❌	❌	❌
{AlbumArtistName}	Primary artist's name for that media	✅	❌	❌	❌
{Flag}	Quality/content flags: M (Master), A (Dolby Atmos), E (Explicit)	✅	❌	❌	❌
{AlbumID}		✅	❌	❌	❌
{AlbumYear}		✅	✅	❌	❌
{AlbumTitle}		✅	✅	❌	❌
{AudioQuality}	Audio quality reported by TIDAL (e.g. LOSSLESS, HI_RES)	✅	✅	❌	❌
{DurationSeconds}		✅	✅	❌	❌
{Duration}	Duration formatted as MM:SS (or H:MM:SS)	✅	✅	❌	❌
{NumberOfTracks}		✅	❌	❌	❌
{NumberOfVideos}		✅	❌	❌	❌
{NumberOfVolumes}		✅	❌	❌	❌
{ReleaseDate}		✅	❌	❌	❌
{RecordType}		✅	❌	❌	❌
{TrackID}		❌	✅	❌	❌
{TrackNumber}		❌	✅	❌	❌
{TrackTitle}		❌	✅	❌	❌
{ExplicitFlag}		❌	✅	✅	❌
{StreamQuality}		❌	✅	❌	❌
{Codec}		❌	✅	❌	❌
{VideoID}		❌	❌	✅	❌
{VideoNumber}		❌	❌	✅	❌
{VideoTitle}		❌	❌	✅	❌
{VideoYear}		❌	❌	✅	❌
{PlaylistUUID}		❌	❌	❌	✅
{PlaylistName}		❌	❌	❌	✅

Desktop GUI

The GUI provides login, search, queueing, downloads, settings, diagnostics, and updates. After installing with the GUI extra above, launch it with tidekeeper-gui or tidekeeper --gui. Update GUI installs with tidekeeper --update-gui.

Search	Queue

Settings	Account

Troubleshooting

Run diagnostics first:

tidekeeper --doctor
tidekeeper --paths

For repeated HTTP 429 errors, keep Use request delay enabled and raise Request delay seconds to 30 or 60 before retrying.

If doctor warns that ffmpeg is missing, install it from your OS package manager (or use the Docker image). Video downloads and FLAC remux may otherwise be limited.

If Termux reports cannot locate symbol "x265_api_get_216", refresh its media packages with pkg upgrade -y && pkg reinstall -y ffmpeg x265. If that fails, change mirrors with termux-change-repo and retry.

Development

See CONTRIBUTING.md for setup and checks, CHANGELOG.md for release history, and SECURITY.md for private vulnerability reporting.

git clone https://github.com/OpenNerdz/tidekeeper.git
cd tidekeeper/TIDALDL-PY
python -m pip install -e .
python -m unittest discover -s tests

Build release artifacts with ./build.sh from the repository root.

Project policy

Tidekeeper does not aim to bypass access controls, subscription checks, or DRM. Use it only where permitted by law and applicable service terms. This project is not affiliated with or endorsed by TIDAL or Block, Inc.

The original project was created by YaronH and contributors. See NOTICE and LICENSE for attribution and licensing.