Tidekeeper

Tidekeeper is an unofficial TIDAL downloader with a terminal interface and an optional desktop app. It is a maintained fork of Tidal-Media-Downloader.

Get started

1. Install Tidekeeper

Choose the option that best fits how you want to use it.

Python install

This is the recommended option if you already have Python 3.10 or newer. For the terminal version:

python -m pip install -U tidekeeper
tidekeeper

For the desktop app:

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

Standalone app

If you do not want to install Python, download the terminal or desktop app for your operating system from the latest GitHub Release. Builds are available for Windows x86-64, macOS Apple Silicon and Intel, Linux x86-64, and Linux ARM64. Unix downloads are .tar.gz archives so executable permissions survive extraction. Each release includes SHA256SUMS and GitHub build-provenance attestations.

Standalone apps cannot replace themselves during an update. Download a newer file from the Releases page when a new version is available.

Linux and Termux installer

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

On Android, first allow Termux to use shared storage:

termux-setup-storage

Docker

The Docker image includes ffmpeg and stores configuration and downloads in folders on the host:

docker build -t tidekeeper .
docker run --rm -it \
  -v "$PWD/config:/config" \
  -v "$PWD/downloads:/downloads" \
  tidekeeper

The container runs as user ID 1000, so both folders must be writable by that user. The desktop app is not included in the Docker image. Dependency layers are reused when rebuilding after application-only changes.

2. Sign in

You only need to complete device login the first time and whenever Tidekeeper needs a fresh session.

In the terminal:

1. Run tidekeeper.
2. Open the displayed link.tidal.com address.
3. Enter the displayed code and approve the login.
4. Return to Tidekeeper after the login succeeds.

In the desktop app:

1. Click Signed out to open the Account panel.
2. Click Start device login.
3. Click Open in browser and approve the login.

Click Cancel login to stop a pending sign-in while keeping your saved session. Downloads and settings changes wait until sign-in finishes or is cancelled. Manual token entry is hidden in the terminal; desktop token fields are cleared after a successful sign-in.

Tidekeeper may ask you to sign in once after an update changes the TIDAL client. This is expected and prevents an old session from breaking downloads.

3. Download something

In the terminal, paste a TIDAL link at the prompt. You can also start a download directly:

tidekeeper -l "https://tidal.com/browse/track/70973230"

In the desktop app, paste a link at the top and click Download now. You can also search, select a result, and add it to the queue.

Use tidekeeper --open-output to open the download folder. Use only content that your account can play and that you are permitted to download.

Keep Tidekeeper updated

For a Python terminal install:

tidekeeper --update

For a Python desktop install, use the Update button in the Account panel or:

tidekeeper --update-gui

Restart Tidekeeper after updating. If you use a standalone app, download the new executable from the Releases page instead. Check the installed version with tidekeeper --version.

Common tasks

Choose quality

Max is the default and requests the best available standard audio quality, including 24-bit/192 kHz FLAC when the track and account offer it. Tidekeeper uses a fixed FLAC manifest first, chooses the highest-fidelity representation from its measured codec/bit-depth/sample-rate/bandwidth fields, and uses the playback API as a separate fallback. When ffprobe is installed, the finished audio stream is checked and its actual properties are stored in the completion receipt. New profiles use the Tidal HiRes client for Max playback. Existing profiles that still use Tidal TV can select Tidal HiRes in the desktop Advanced settings or terminal API-client menu, save, and sign in once with the new client. A single legacy Master selection requests lossless FLAC: Max first, then HiFi. TIDAL retired MQA in July 2024. To choose your own fallback order, use --quality-priority Max,HiFi,High,Normal. Other single-quality selections remain strict, and lists of fallback qualities keep their order (Master is treated as Max). DRM-protected DASH streams are rejected; fallback can use unencrypted streams offered by TIDAL for your account.

Video resolution selects the highest available variant at or below your choice, or the lowest available variant if none fit. Preview streams, unfinished/live HLS playlists, and multi-period DASH are reported as unsupported instead of being saved as complete downloads. Invalid terminal quality or resolution choices leave your saved settings unchanged.

TIDAL links may omit https://, for example tidal.com/browse/album/123 or listen.tidal.com/track/1. This works in commands, batch lists, and the desktop. HLS playlists explicitly marked VOD are treated as complete even when the provider omits the end marker.

Dolby Atmos is optional because it is often a separate version of an album or track. Select Atmos in the desktop app or use:

tidekeeper -q Atmos -l "TIDAL_LINK"

Tidekeeper will use a matching Atmos release when one is available. To download only videos from a link, use:

tidekeeper --video-only -l "TIDAL_LINK"

Change the download folder

Choose a folder in the desktop Settings panel, or pass one for a terminal download:

tidekeeper --output "/path/to/music" -l "TIDAL_LINK"

To set the default folder before Tidekeeper creates its profile:

export TIDEKEEPER_DOWNLOAD_PATH="/path/to/music"

An existing profile keeps the folder already saved in its settings.

Download a list

Pass a text file instead of a link:

tidekeeper -l "/path/to/links.txt"

The file can contain TIDAL links or IDs separated by lines, spaces, or commas. Lines beginning with # are comments. A list can also point to another text file. Repeated items are skipped.

If some items fail, Tidekeeper saves them to failed-tracks.txt in the download folder. Retry that file with the same command.

Customize names and folders

Filename templates use labels such as {ArtistName}, {AlbumTitle}, and {TrackTitle}. The defaults work for most users. See the filename template guide for examples and the full list of available labels.

Desktop app

The desktop app keeps search, links, results, and the download queue in one window. Download now starts immediately, while Add to queue lets you prepare several downloads before clicking Start.

You can also drag TIDAL links from a browser, or .txt link lists from a file manager, onto the window. They are added to Links so you can review them before queueing.

Completed items can be cleared without removing unfinished work. Failed, partial, interrupted, and cancelled items can be retried. Select an item to see its error details. For a completed artist or album attempt with failed tracks or videos, Retry incomplete downloads only those failed items. Interrupted collection attempts retry the collection so unattempted items are included. Older saved rows without complete retry details also revisit the collection, using the normal existing-file checks. Retried videos keep their original album folders and partial transfers.

Settings affect the next download. Click Save if you want to keep them after restarting. Changing the TIDAL client signs you out automatically, so sign in again after saving that change.

The Account panel's Supporters list shows GitHub accounts that have starred this repository. It displays a bundled snapshot immediately and refreshes in the background. New stars trigger a repository update; a scheduled refresh every six hours also picks up unstars. GitHub scheduling and caching can delay changes. Click Refresh to fetch the latest published list. Offline, the app uses its bundled snapshot. No GitHub login is needed in the app.

Useful shortcuts:

• Ctrl+F focuses search.
• Enter adds a selected result to the queue.
• Delete removes selected queue items.
• Ctrl+Z restores the last removed queue item.
• Ctrl+, opens Settings.
• Esc closes the side panel.

Settings	Account

Troubleshooting

Start by checking your installation, login, download folder, and local tools:

tidekeeper --doctor
tidekeeper --paths

Session removed after updating or changing clients

Sign in again after the client changes. Current versions automatically remove sessions created by an old TIDAL client. If you use a standalone app, make sure you downloaded the latest executable rather than only pressing its Update button.

Login succeeds, but playback returns HTTP 404 / subStatus 4022

A playback rejection alone does not mean your login is invalid. Tidekeeper keeps the session and tries its alternate manifest endpoint and any configured quality fallbacks. Try HiFi or --quality-priority Max,HiFi,High,Normal. Legacy Master settings now use FLAC automatically.

If all attempts fail, include the endpoint, client label, country, and quality from the error in your issue report. Repeatedly logging in with the same client may not change its playback availability. A client rejection on a catalog request still clears the unusable session after a failed refresh.

Max downloads are only 16-bit/44.1 kHz

Max is a ceiling, not an upsampling target: tracks whose best source is HiFi correctly remain 16-bit. For tracks marked Max, select the Tidal HiRes client in Advanced settings (or terminal menu option 7), save, sign in again, and keep audio quality set to Max. The older Tidal TV client remains available for accounts where its more conservative playback support is preferable.

Repeated HTTP 429 errors

TIDAL is temporarily limiting requests. Keep Use request delay enabled and raise Request delay seconds to 30 or 60 before retrying.

ffmpeg is missing

Install ffmpeg with your operating system's package manager. It is recommended for video downloads and optional FLAC remuxing. The Docker image already includes it.

Termux reports cannot locate symbol from ffmpeg or ffprobe

Update Termux's installed packages together, then reinstall ffmpeg:

pkg upgrade -y
pkg reinstall -y ffmpeg

If that does not work, run termux-change-repo, choose another mirror, and try again.

Still need help?

Open a GitHub issue and include:

• The version shown by tidekeeper --version.
• How you installed Tidekeeper.
• Your operating system.
• The complete error message with private tokens removed.

Install the latest source

Use this only if you specifically want the newest code from GitHub:

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

Development

See CONTRIBUTING.md for setup and checks, CHANGELOG.md for release history, and SECURITY.md for private vulnerability reporting. Build and release procedures are in MAINTAINING.md.

git clone --depth 1 https://github.com/OpenNerdz/tidekeeper.git
cd tidekeeper/TIDALDL-PY
python -m venv .venv
source .venv/bin/activate
python -m pip install -e .
python -m unittest discover -s tests

Build release artifacts with ./build.sh from the repository root. It retains PyInstaller work for faster rebuilds; use ./build.sh --clean to reset that cache. A shallow clone avoids downloading the upstream project's large history; use git fetch --unshallow if you need it later.

Application changes pushed to main automatically produce a dated release after CI, platform builds, and PyPI verification pass. Versions, tags, and release notes are generated by the workflow. See automatic releases for the naming scheme, optional note hints, and recovery steps.

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.