# tiddl: a command line downloader for Tidal tracks and videos

> A Python CLI that logs into your own Tidal account and pulls tracks, videos, albums, playlists, artists and mixes at up to 24 bit and 192 kHz, with template based output paths and a TOML configuration file. The project states plainly that it is for personal use only and that compliance with Tidal's terms is the user's responsibility.

**oskvr37/tiddl** — Download Tidal tracks, videos, albums, playlists & artists! Tidal downloader that supports master quality.

- Repository: https://github.com/oskvr37/tiddl
- Website: https://pypi.org/project/tiddl/
- Stars: 701 · Forks: 106
- Language: Python
- License: Apache-2.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/oskvr37-tiddl

## What it is, and the boundary the author draws

The tool is called tiddl and it is described in one line: a Tidal downloader that supports master quality. The readme puts it as a CLI app written in Python, and the project description spells out the scope as tracks, videos, albums, playlists and artists.

What matters for an adopter is the warning, and it is unusually explicit. The app is for personal use only and is not affiliated with Tidal, and 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, and the developer assumes no responsibility for misuse.

So the design boundary is clear. The tool authenticates with your own Tidal account and downloads content that account can play, and the redistribution question is left to you and your jurisdiction. That is a real distinction and not a lawyerly hedge, because the tool does not need to circumvent anything to work: the streaming catalogue is reachable through the account you already pay for.

The audience is a listener who wants offline copies of their own library in lossless quality, or a developer who wants to script against the Tidal API in a language they already use. The repository topics list audio, cli, downloader, music, python and tidal, and the project points at a community maintained list of Tidal API endpoints and at Tidal-Media-Downloader as the inspiration.

The homepage is the package on PyPI, and the licence is Apache-2.0.

## Installing it, and the ffmpeg dependency that is not optional

The package is on the Python package index and the readme recommends uv as the package manager, with pip as the alternative.

```bash
uv tool install tiddl
```

An exact version can be pinned, for example 3.4.1:

```bash
uv tool install tiddl==3.4.1
```

With pip the command is:

```bash
pip install tiddl
```

The important installation note is the one flagged as important. You must also have ffmpeg installed, because it is used to convert downloaded tracks to proper format. This is not a nicety, it is a runtime dependency, and it is the reason the project ships a Dockerfile with ffmpeg as its own layer.

The package metadata sets the Python floor at 3.13 or later, which is worth noting before you plan a deployment, since it excludes the 3.12 runtime that many distributions still ship by default.

For development, the readme describes cloning the repository, creating a virtual environment with uv venv, activating it, and installing the package in editable mode with uv pip install -e .

The Docker section of the readme is marked coming soon, but a Dockerfile is present in the tree, and it is written with an unusual amount of care about layer caching. The comments explain that layer one installs ffmpeg and never regenerates, layer two installs the dependencies and only regenerates when pyproject.toml changes, and layer three copies the source and regenerates on any code change. The dependency layer is generated by reading pyproject.toml with tomllib and piping the result into pip, so the image never drifts from the declared dependencies.

## Two commands, auth and download

The command surface is small and the readme shows the whole help output, which is worth reading because it tells you the shape of the tool.

There are two commands, auth for managing Tidal authentication and download for downloading Tidal resources. The global options are --omit-cache and its negation, --debug and its negation, --install-completion and --show-completion for shell completion, and --help.

Authentication is one command:

```bash
tiddl auth login
```

The readme says to run it and follow the instructions, so the login is interactive rather than a credentials flag, which is the right design for a tool that stores a session.

Downloading takes a URL, and the tool is forgiving about the form of it:

```bash
$ tiddl download url <url>
```

The tip attached to that is the practical detail. You do not have to paste full urls, since track/103805726 and album/103805723 will also work, so you can pass a path fragment once you know the identifiers. Run tiddl download to see the available download options, which is where the per resource type flags live.

The examples directory in the tree shows the same thing as code, with download_track.py, download_video.py, fetch_api.py and track_templating.py, so the tool can also be driven as a library from Python rather than only from the shell.

## Quality selection, and what the FLAC tiers actually mean

The quality table is where the difference between a downloader and a ripper becomes visible, and it is a short one.

The four tiers are LOW, NORMAL, HIGH and MAX. LOW gives a .m4a file at 96 kbps and NORMAL gives .m4a at 320 kbps. HIGH gives a .flac file at 16-bit, 44.1 kHz, and MAX gives .flac up to 24-bit, 192 kHz.

The two lossless tiers are the interesting ones. HIGH is CD quality, 16 bit at 44.1 kHz, which is what a physical CD carries. MAX is up to 24 bit at 192 kHz, which is what the label masters in the catalogue can be, and it is the tier the description means by master quality.

The file extension changes with the tier, and that is not cosmetic. A .m4a at 320 kbps is AAC, a lossy codec, while .flac is a lossless compressed container, so the file you get at MAX is a mathematically complete copy of the master rather than a compressed approximation of it.

This is also where ffmpeg comes back in. The tool downloads whatever the catalogue serves and the conversion step produces the final file in the format and quality you asked for, which is a plausible reason the project needs an external tool rather than a pure Python pipeline.

The caveat worth naming is that the highest tier is only as good as what the catalogue holds, and the table says up to 24 bit and 192 kHz rather than asserting it. A track whose master is CD quality will be a CD quality file whatever setting you pick.

## Output templating, and where the files end up

You can format filenames of your downloaded resources and put them in different directories, and the templating syntax is close to Python's format specification.

The readme gives the example: setting the output flag to this string:

```
{album.artist}/{album.title}/{item.number:02d}. {item.title}
```

which produces a directory tree of artist, then album, then a numbered filename, and the readme shows the result as a Graduation album with files from 01. Good Morning.flac through 14. Good Night.flac.

The interesting part of that syntax is the zero padding on the number, which is the :02d format specifier, and the dotted object access, which is what lets you reach into the album, the item and the numbering of a track. The documentation for the full scheme is at /docs/templating.md.

The configuration side is equally plain. Files of the app are created in your home directory, by default the app is located at ~/.tiddl, and you can and should create the config.toml file to configure the app how you want, with an example at docs/config.example.toml.

Two environment variables handle the exceptions. TIDDL_PATH sets a custom path for the tiddl app, with the example TIDDL_PATH=~/custom/tiddl tiddl auth login, so you can keep several profiles side by side. And TIDDL_AUTH lets you use another credentials pair, in the form TIDDL_AUTH=<CLIENT_ID>;<CLIENT_SECRET>, which the readme offers under the heading of what to do when auth stopped working, since a stale session is the most common reason a login stops working.

## What this tool will not do for you

There are limits here that are worth naming before you install it, and they fall into two groups.

The first group is legal and contractual, and it is not something the tool can resolve. The readme is explicit that downloaded tracks may not be shared or redistributed, and that users must ensure their use complies with Tidal's terms of service and local copyright laws. So a personal offline copy for listening on a plane is one thing, and putting those files on a media server for a household or a share server is another. The tool does not track what you do with the files, and it does not attempt to work around the terms; it leaves that decision with you.

The second group is technical. The tool needs your Tidal account, and it talks to the catalogue through endpoints that are not a public documented API. The readme points at a community maintained wiki of Tidal API endpoints, which is a signal in itself about the stability of the interface it depends on. When the service changes, the tool breaks, and the fix depends on somebody maintaining a list of endpoints that the service owner does not promise to keep.

The third is the quality ceiling discussed earlier. The MAX tier is only 24 bit and 192 kHz if the master is, and the tool is a downloader rather than a mastering chain, so there is no upsampling or restoration involved.

The fourth is the dependency on ffmpeg being on the path, and on Python 3.13 or later. Both are ordinary constraints, but a machine with a system Python of 3.11 and no package manager access will not run it without work.

And the fifth is the simplest one. If you only want to listen to Tidal offline, the official Tidal apps already offer offline downloads on mobile and desktop. The reason to reach for this tool is quality control, automation, or a scripting surface, and if none of those apply you are adding a dependency to get a feature you already have.

## Conclusion

Adopt tiddl if you want an offline copy of material you have legitimate access to, and you are comfortable handling the terms of service question yourself, because the tool reaches the streaming catalogue through your own account rather than through a separate download service. Skip it if you need redistribution rights, because the readme states the downloaded tracks may not be shared or redistributed. Verify first that ffmpeg is on the path, since it is required to convert downloads into their final format, and that your Python is 3.13 or later, which is the floor the package metadata sets.

## FAQ

### What is tiddl and what can it download?

tiddl is a Python command line app that downloads Tidal tracks and videos with maximum quality. You can download tracks, videos, albums, artists, playlists and mixes, either by URL or by a path fragment such as track/103805726.

### How do I install tiddl?

It is on the Python package index. The readme recommends uv with uv tool install tiddl, or uv tool install tiddl==3.4.1 for an exact version, and pip install tiddl also works. You must additionally have ffmpeg installed, because it is used to convert downloaded tracks to proper format.

### What quality levels does tiddl support?

LOW gives .m4a at 96 kbps, NORMAL gives .m4a at 320 kbps, HIGH gives .flac at 16 bit and 44.1 kHz, and MAX gives .flac at up to 24 bit and 192 kHz. The higher the tier, the more of the original master is preserved.

### How do I log in to Tidal with tiddl?

Run tiddl auth login and follow the instructions. The app stores its files in your home directory by default at ~/.tiddl, and the TIDDL_PATH environment variable can point it at a custom directory, while TIDDL_AUTH can be used to supply another credentials pair.

### Can I choose where tiddl puts the downloaded files?

Yes. You can format filenames and put them in different directories with a template, for example {album.artist}/{album.title}/{item.number:02d}. {item.title}. The app also reads a config.toml in its directory, with an example at docs/config.example.toml.

### What licence is tiddl released under and how recent is it?

Apache-2.0, with the LICENSE file at the root of the repository. The package requires Python 3.13 or later, the recent releases are v3.4.4 on 2026-07-07, v3.4.4a1 on 2026-06-09 and v3.4.3 on 2026-05-10, and the last push was on 2026-07-07.

## Sources

- [License: Apache-2.0](https://github.com/oskvr37/tiddl/blob/main/LICENSE)
- [oskvr37/tiddl on GitHub](https://github.com/oskvr37/tiddl)
- [Project website](https://pypi.org/project/tiddl/)
- [README](https://github.com/oskvr37/tiddl/blob/main/README.md)
- [Releases](https://github.com/oskvr37/tiddl/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/oskvr37-tiddl