Tidal Downloader

This repository is a personal fork and rewrite of oskvr37/tiddl.

Download tracks and videos from Tidal with max quality! tiddl is CLI app written in Python.

Warning

This app is for personal use only and is not affiliated with Tidal. Users must ensure their use complies with Tidal's terms of service and local copyright laws. Downloaded tracks are for personal use and may not be shared or redistributed. The developer assumes no responsibility for misuse of this app.

Installation

tiddl is available at python package index and you can install it with your favorite Python package manager.

Important

Also make sure you have installed ffmpeg - it is used to convert downloaded tracks to proper format.

uv

We recommend using uv

uv tool install tiddl

To install exact version e.g. 3.4.1

uv tool install tiddl==3.4.1

pip

You can also use pip

pip install tiddl

docker

The container expects runtime state to live under a mounted app data directory and keeps config, auth, cache, temp, and logs below TIDDL_PATH.

Example:

docker run --rm \
  -e TIDDL_PATH=/data/tiddl \
  -v "$PWD/.tiddl:/data/tiddl" \
  tiddl auth login

Usage

Run the app with tiddl

$ tiddl
 Usage: tiddl [OPTIONS] COMMAND [ARGS]...

 tiddl - download tidal tracks ♫

╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --omit-cache            --no-omit-cache      [default: no-omit-cache]                                       │
│ --debug                 --no-debug           [default: no-debug]                                            │
│ --install-completion                         Install completion for the current shell.                      │
│ --show-completion                            Show completion for the current shell, to copy it or customize │
│                                              the installation.                                              │
│ --help                                       Show this message and exit.                                    │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ──────────────────────────────────────────────────────────────────────────────────────────────────╮
│ auth       Manage Tidal authentication.                                                                     │
│ download   Download Tidal resources.                                                                        │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Authentication

Login to app with your Tidal account: run the command below and follow instructions.

tiddl auth login

Downloading

You can download tracks / videos / albums / artists / playlists / mixes.

$ tiddl download url <url>

Tip

You don't have to paste full urls, track/103805726, album/103805723 etc. will also work

Run tiddl download to see available download options.

Quality

Quality	File extension	Details
LOW	.m4a	96 kbps
NORMAL	.m4a	320 kbps
HIGH	.flac	16-bit, 44.1 kHz
MAX	.flac	Up to 24-bit, 192 kHz

Output

You can format filenames of your downloaded resources and put them in different directories.

For example, setting output flag to "{album.artist}/{album.title}/{item.number:02d}. {item.title}" will download tracks like following:

Music
└── Kanye West
    └── Graduation
        ├── 01. Good Morning.flac
        ├── 02. Champion.flac
        ├── 03. Stronger.flac
        ├── 04. I Wonder.flac
        ├── 05. Good Life.flac
        ├── 06. Can't Tell Me Nothing.flac
        ├── 07. Barry Bonds.flac
        ├── 08. Drunk and Hot Girls.flac
        ├── 09. Flashing Lights.flac
        ├── 10. Everything I Am.flac
        ├── 11. The Glory.flac
        ├── 12. Homecoming.flac
        ├── 13. Big Brother.flac
        └── 14. Good Night.flac

Note

Learn more about file templating

Configuration files

Files of the app are created in your home directory by default. The app data root is ~/.tiddl unless you override it with TIDDL_PATH.

The runtime directory contains config, auth, cache, temp, debug, and log files. When TIDDL_PATH is set, all of those paths stay below that directory.

You can (and should) create the config.toml file to configure the app how you want.

You can copy example config from docs config.example.toml

Environment variables

Custom app path

You can set TIDDL_PATH environment variable to use custom path for tiddl app.

Example CLI usage:

TIDDL_PATH=~/custom/tiddl tiddl auth login

Auth stopped working?

Set TIDDL_AUTH environment variable to use another credentials.

TIDDL_AUTH=<CLIENT_ID>;<CLIENT_SECRET>

Development

Clone the repository

git clone https://github.com/oskvr37/tiddl
cd tiddl

Recommended local checks:

uv sync --dev
uv run pytest
uv run ruff format --check .
uv run ruff check .
uv run ty check
uv run uv build

Release gate:

uv run uv build

Docker runtime:

Set TIDDL_PATH and mount an app-data directory so config, auth, cache, temp, and logs stay under the mounted directory.

docker build -t tiddl .
docker run --rm \
  -e TIDDL_PATH=/data/tiddl \
  -v "$PWD/.tiddl:/data/tiddl" \
  tiddl auth login

Resources

Tidal API wiki (api endpoints)

Tidal-Media-Downloader (inspiration)