# tiddl-gui **Download Tidal tracks, albums, and playlists at maximum quality — straight from your browser.** [![Live App](https://img.shields.io/badge/Live%20App-Open%20Now-4fd08c?style=for-the-badge&logo=github&logoColor=white)](https://19jvjeffery.github.io/tiddl-gui/web/index.html) [![License](https://img.shields.io/badge/License-Apache%202.0-blue?style=for-the-badge)](LICENSE) [![Stars](https://img.shields.io/github/stars/19JVJeffery/tiddl-gui?style=for-the-badge&color=yellow)](https://github.com/19JVJeffery/tiddl-gui/stargazers) No installation needed — open the link and go. Mockups
> [!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. --- If you would like to support development of this tool, please donate at my Ko-fi page. support_me_on_kofi_beige --- ## How to use ### 1 — Log in Open the **Account** tab and click **Login with Tidal**. A Tidal authorisation page opens in a new tab. Approve it there, then return — the app polls automatically and logs you in. Your token is stored in `localStorage` and refreshed automatically; nothing is ever sent to a third-party server. ### 2 — Download Open the **Download** tab and paste any of the following: | Input format | Example | |---|---| | Full Tidal URL | `https://tidal.com/browse/track/103805726` | | Track | `track/103805726` | | Album | `album/103805723` | | Playlist UUID | `playlist/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | | Mix ID | `mix/0123456789abcdef` | Select a quality level and click **Download**. Files are saved directly to your browser's downloads folder. | Quality | Format | Details | |:---:|:---:|:---:| | Low | .m4a | 96 kbps | | High | .m4a | 320 kbps | | Lossless | .flac | 16-bit, 44.1 kHz | | Max | .flac | Up to 24-bit, 192 kHz | > [!NOTE] > Lossless / Max quality requires an eligible Tidal subscription. Encrypted (DRM) streams cannot be saved in the browser. ### 3 — Search Open the **Search** tab, type an artist, track, album, or playlist name, and press **Search**. Click a track to add it to the download queue, or click an artist, album, or playlist card to browse its contents and download items individually or all at once. ### 4 — Library Open the **Library** tab (requires sign-in) to browse your saved tracks, albums, and playlists. ### 5 — CORS proxy Tidal's API blocks direct browser requests. All API calls are routed through a CORS proxy; the default is [corsproxy.io](https://corsproxy.io) and needs no setup. To use a different proxy, open **Settings** and update the **Proxy prefix URL** field. ## Troubleshooting - **Playlist stops at ~100 tracks** The app now fetches paginated playlist items more defensively (including APIs that return numeric totals as strings), so large playlists should continue beyond the first page. - **HiFi / Max expected FLAC but got .m4a** The downloader now avoids inappropriate quality-tier downgrades on generic 403 errors and only falls back when the quality itself is unavailable. - **`Segment fetch failed: 403` (especially on FLAC/HiFi/Max)** Segment URLs are short-lived and can be bound to the IP that requested playback info. The downloader now follows the original `tiddl` flow by requesting `STREAM` playback first, automatically retrying with `OFFLINE` when needed, preferring direct playback-info requests (with proxy fallback only when needed), and still retrying once with fresh segment URLs before failing. - **`Asset is not ready for playback`** This response can be transient while playback tokens are being prepared. The downloader now retries stream-token requests a few times with short backoff before failing (and still keeps quality fallback behavior). ## Run locally ### Prerequisites - **Git** — to clone the repository ([git-scm.com](https://git-scm.com)) - A **static file server** — one of the options below (no build step required) ### Start the server Clone the repo and serve the `web/` directory with any static file server: **Python 3** (no extra install needed on most systems): ```bash git clone https://github.com/19JVJeffery/tiddl-gui.git cd tiddl-gui python3 -m http.server 8080 --directory web ``` **Node.js** (`npx serve` — downloads and runs automatically): ```bash git clone https://github.com/19JVJeffery/tiddl-gui.git cd tiddl-gui npx serve web -l 8080 ``` **VS Code** — install the [Live Server](https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer) extension, open the `web/` folder, and click **Go Live**. Open in your browser. ### Stop the server Press Ctrl+C in the terminal where the server is running. ### Uninstall / remove 1. Stop the server (see above). 2. Delete the cloned folder: ```bash # from the parent directory of tiddl-gui/ rm -rf tiddl-gui # macOS / Linux rmdir /s /q tiddl-gui # Windows Command Prompt ``` 3. If you used `npx serve`, no global package was installed — nothing else to remove. 4. Clear the app's stored data (login tokens, settings) from your browser — choose one: - In the app: open **Settings → Advanced / Developer → Clear all data** (removes all tokens and settings). - Or via browser DevTools: **Application** → **Local Storage** → select `localhost` → **Clear All**. ## Credits tiddl-gui is a browser-based GUI built on top of the original [**tiddl**](https://github.com/oskvr37/tiddl) command-line tool by [oskvr37](https://github.com/oskvr37). The API integration and download logic are inspired by that project.