Metadata-Version: 2.4
Name: tidekeeper
Version: 2026.9.24.1
Summary: Maintained Tidal-Media-Downloader fork with terminal and desktop GUI workflows.
Home-page: https://github.com/OpenNerdz/tidekeeper
Author: Tidekeeper maintainers
License: Apache-2.0
Project-URL: Source, https://github.com/OpenNerdz/tidekeeper
Project-URL: Changelog, https://github.com/OpenNerdz/tidekeeper/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/OpenNerdz/tidekeeper/issues
Project-URL: Upstream, https://github.com/yaronzz/Tidal-Media-Downloader
Keywords: tidal music downloader cli gui lossless atmos
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: aigpy>=2022.7.8.1
Requires-Dist: requests>=2.34.2
Requires-Dist: pycryptodome
Requires-Dist: prettytable>=3.18.0
Requires-Dist: defusedxml>=0.7.1
Provides-Extra: gui
Requires-Dist: PySide6-Essentials>=6.5; extra == "gui"
Provides-Extra: dev
Requires-Dist: ruff>=0.8.0; extra == "dev"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: platform
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

![Tidekeeper](https://raw.githubusercontent.com/OpenNerdz/tidekeeper/main/assets/tidekeeper-banner.png?raw=1)

# 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](https://github.com/yaronzz/Tidal-Media-Downloader).

[![CI](https://github.com/OpenNerdz/tidekeeper/actions/workflows/ci.yml/badge.svg)](https://github.com/OpenNerdz/tidekeeper/actions/workflows/ci.yml)
[![Build](https://github.com/OpenNerdz/tidekeeper/actions/workflows/build.yml/badge.svg)](https://github.com/OpenNerdz/tidekeeper/actions/workflows/build.yml)
[![PyPI](https://img.shields.io/pypi/v/tidekeeper.svg)](https://pypi.org/project/tidekeeper/)
[![Release](https://img.shields.io/github/v/release/OpenNerdz/tidekeeper?display_name=tag)](https://github.com/OpenNerdz/tidekeeper/releases/latest)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue.svg)](https://www.python.org/downloads/)

## 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:

```bash
python -m pip install -U tidekeeper
tidekeeper
```

For the desktop app:

```bash
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](https://github.com/OpenNerdz/tidekeeper/releases/latest).
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

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

On Android, first allow Termux to use shared storage:

```bash
termux-setup-storage
```

#### Docker

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

```bash
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.

### 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.

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:

```bash
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:

```bash
tidekeeper --update
```

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

```bash
tidekeeper --update-gui
```

Restart Tidekeeper after updating. If you use a standalone app, download the
new executable from the [Releases page](https://github.com/OpenNerdz/tidekeeper/releases/latest)
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](https://support.tidal.com/hc/en-us/articles/25876825185425-Audio-Format-Updates).
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.

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

```bash
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:

```bash
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:

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

To set the default folder before Tidekeeper creates its profile:

```bash
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:

```bash
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](https://github.com/OpenNerdz/tidekeeper/blob/main/docs/filename-templates.md) 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.

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.

![Workspace with search, results, and queue](https://raw.githubusercontent.com/OpenNerdz/tidekeeper/main/docs/screenshots/workspace.png)

| Settings | Account |
| --- | --- |
| ![Settings panel](https://raw.githubusercontent.com/OpenNerdz/tidekeeper/main/docs/screenshots/settings.png) | ![Account panel](https://raw.githubusercontent.com/OpenNerdz/tidekeeper/main/docs/screenshots/account.png?raw=1&v=2026.9.14.0) |

## Troubleshooting

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

```bash
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 "x265_api_get_216"`

Refresh the media packages:

```bash
pkg upgrade -y
pkg reinstall -y ffmpeg x265
```

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

### Still need help?

Open a [GitHub issue](https://github.com/OpenNerdz/tidekeeper/issues) 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:

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

## Development

See [CONTRIBUTING.md](https://github.com/OpenNerdz/tidekeeper/blob/main/CONTRIBUTING.md) for setup and checks,
[CHANGELOG.md](https://github.com/OpenNerdz/tidekeeper/blob/main/CHANGELOG.md) for release history, and
[SECURITY.md](https://github.com/OpenNerdz/tidekeeper/blob/main/SECURITY.md) for private vulnerability reporting.

```bash
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](https://github.com/OpenNerdz/tidekeeper/blob/main/NOTICE) and [LICENSE](https://github.com/OpenNerdz/tidekeeper/blob/main/LICENSE) for attribution and licensing.
