Tidal-DL 🌊🎵🎬

Download music tracks, playlists, and music videos directly from Tidal.

Tidal-DL is a command-line interface (CLI) tool that allows you to download your music and music videos from Tidal. It authenticates with your Tidal account using a secure device authorization flow and saves your session for future use.

✨ Features

Song Downloads:
- Choose from available audio qualities:
  - Standard (AAC 96 kbps)
  - High (AAC 320 kbps)
  - HiFi (CD Quality FLAC 16-bit/44.1kHz - Lossless)
  - Max (HiRes FLAC up to 24-bit/192kHz - Lossless)
- Downloads are saved as .m4a (AAC) or .flac (lossless) files.
- Automatic renaming to Artist - Title (with confirmation) based on metadata fetched from Tidal.
Music Video Downloads:
- Lists available video resolutions and bandwidths for you to select the best option.
- Downloads are saved as .ts files.
- Attempts to name files using the video title scraped from the Tidal page.
Playlist Downloads:
- Downloads all tracks from a playlist at a selected audio quality.
- Optional bulk renaming to Artist - Title.
- Optional MP3 conversion after download (requires ffmpeg).
Efficient Downloads: Utilizes aria2c for fast, resumable, and segmented downloading.
Authentication: Secure OAuth2 device login. Session details (including access and refresh tokens) are stored locally in tidal_session.json for persistence, reducing the need to log in repeatedly.
Interactive CLI: A user-friendly command-line interface guides you through the selection and download process.
Custom Output Directory: Set the base download folder when the app starts.

🚀 Prerequisites

Before you begin, ensure you have the following installed on your system:

Node.js: A recent LTS version (e.g., v18.x, v20.x, or newer). You can download it from nodejs.org.
aria2c: This is a critical dependency for the download process.
- Official website: aria2.github.io
- Ensure aria2c is installed and accessible from your system's PATH (i.e., you can run aria2c --version in your terminal).

🛠️ Setup

Clone the repository:
If you're downloading this from GitHub, you've likely already done this or downloaded the source. If not:
```
git clone https://github.com/andresdevvv/tidal-dl.git
cd tidal-dl
```
Install dependencies:
Navigate to the project's root directory in your terminal and run:
```
npm install
```
This will install axios, xml2js.

⚙️ How to Use

Run the script:
Open your terminal in the Tidal-DL project directory and execute:
```
node run startup
```
or
```
node startup.mjs
```
First-Time Authentication:
- On your first run, the script will guide you through the Tidal authentication process.
- You will see a message like this:
```
---------------------------------------------------------------------
 TIDAL DEVICE AUTHENTICATION REQUIRED
---------------------------------------------------------------------
1. Open your web browser and go to: https://link.tidal.com/XXXXX
2. Enter the following code: YOUR_USER_CODE if asked
---------------------------------------------------------------------

Waiting for authorization (this may take a moment)...
```
- Open the provided URL (e.g., https://link.tidal.com/XXXXX) in your web browser.
- Enter the user code (e.g., YOUR_USER_CODE) on the Tidal website if prompted.
- Authorize the application in your browser.
- Once authorized, the script will automatically detect it, complete the login, and save your session details to tidal_session.json. Future runs will attempt to use this saved session.
Download Process:
- After successful authentication, the main menu will appear:
```
What would you like to do?
  1. Download a Song
  2. Download a Music Video
  3. Download a Playlist
  4. Exit
Enter your choice (1-4):
```
- Enter your choice (1 for a song, 2 for a video, 3 for a playlist).
- Provide URL: Paste the full Tidal URL for the song, video, or playlist you want to download.
  - Song URL Example:
    - https://tidal.com/browse/track/12345678
  - Video URL Example:
    - https://tidal.com/browse/video/87654321
  - Playlist URL Example:
    - https://tidal.com/browse/playlist/PLAYLIST_UUID
- The script will extract the ID from the URL.
- Select Quality:
  - For Songs and Playlists: You'll be presented with a list of available audio qualities (Standard, High, HiFi, Max). Select your preferred quality.
  - For Music Videos: The script will fetch available video streams and list them by resolution and bandwidth (best first). Select your preferred stream.
- File Naming Confirmation (Optional):
  - For Songs: If metadata (artist, title) is successfully fetched, you'll be asked: Do you want to rename the file based on Artist - Title? (yes/no):.
  - For Playlists: You'll be asked once whether to rename all tracks using Artist - Title.
  - For Music Videos: If a title is successfully scraped from the Tidal page, you might be asked: Use "Scraped Video Title.ts" as filename? (y/n):.
- MP3 Conversion (Optional):
  - If enabled at startup, the script will convert downloaded audio files to MP3 using ffmpeg.
- Download: The download will start. aria2c handles the actual downloading of segments, which are then combined into the final file.
Output Location:
- Downloaded songs are saved in the ./downloads/music/ directory relative to where you run the script.
- Downloaded playlists are saved in the ./downloads/playlists/<playlist name>/ directory.
- Downloaded music videos are saved in the ./downloads/videos/ directory.

📁 File Structure Overview

Tidal-DL/
├── downloads/              # Default directory for all downloaded files
│   ├── music/              # Stores downloaded songs (.flac)
│   ├── playlists/          # Stores downloaded playlist tracks (.flac)
│   └── videos/             # Stores downloaded music videos (.ts)
├── node_modules/           # Project dependencies (created by `npm install`)
├── v2/                     # Core logic modules
│   ├── login.mjs           # Handles Tidal authentication & session management
│   ├── music.mjs            # Logic for music track downloads
│   ├── playlist.mjs         # Logic for playlist downloads
│   └── video.mjs            # Logic for music video downloads
├── .gitignore              # Specifies intentionally untracked files for Git
├── package-lock.json       # Records exact versions of installed dependencies
├── package.json            # Project metadata and list of dependencies
├── startup.mjs             # The main executable script (CLI entry point)
└── tidal_session.json      # Stores your Tidal login session data (created after first login)

⚠️ Important Notes

aria2c is Essential: This tool will not work if aria2c is not installed or not correctly configured in your system's PATH.
For Personal Use Only: This tool is intended for personal, private use, such as backing up music and videos you have legitimate access to via your Tidal subscription.
Respect Copyright: Always respect copyright laws and Tidal's Terms of Service. Downloading and distributing copyrighted material without authorization may be illegal. The developers of this tool are not responsible for its misuse.
API Rate Limiting: While the script includes some retry mechanisms, excessive or rapid use might lead to temporary rate limiting by Tidal's API. Use the tool reasonably.

📄 License

This project is licensed under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

A copy of the AGPL-3.0 license is included in the file LICENSE in the root of this repository. You can also find the full text of the license online at:
https://www.gnu.org/licenses/agpl-3.0.html

Happy Downloading!

AndresDevvv/Tidal-DL