- JavaScript 62%
- Python 34.8%
- CSS 2.4%
- Shell 0.4%
- Dockerfile 0.3%
Tidaloader
Docker Package
License
Stars
Last Commit
Python
Preact
A full-stack web application for downloading high-quality music from Tidal with intelligent playlist generation via ListenBrainz integration. Features automatic metadata tagging, lyrics fetching, and organized file management.
Heavily inspired from https://github.com/uimaxbai/tidal-ui and using https://github.com/sachinsenal0x64/hifi
Important
Project Terms
-
We do not encourage piracy. This project is made purely for educational and personal use. If you somehow download copyrighted content, you are solely responsible for complying with the relevant laws in your country.
-
The Tidaloader Project assumes no responsibility for any misuse or legal violations arising from the use of this project.
-
This project does not claim ownership of any music or audio content. All rights remain with their respective copyright holders. Users are encouraged to support artists and rights owners by maintaining a valid Tidal subscription. Tidaloader serves solely as a downloading interface for personal, non-commercial use.
Screenshots
Album Page Artist Page
Download Management
Key Features
- Multi-Format Support:
- FLAC: Hi-Res (24-bit/192kHz) & Lossless (16-bit/44.1kHz)
- Opus: High-efficiency 192kbps VBR
- MP3: 320kbps / 128kbps (Transcoded)
- AAC: 320kbps / 96kbps
- Smart Playlists: Generate "Daily Jams" using ListenBrainz history.
- Rich Metadata: Auto-tagging with MusicBrainz IDs, Artist/Album organization, and embedded covers.
- Intelligent Library: Strict ID-based album matching prevents duplicates. Artist covers are automatically fetched and cached for a beautiful, persistent browsing experience.
- Lyrics: Synced (
.lrc) and plain text lyrics via LrcLib. - Queue Management: Concurrent downloads, auto-retry, and persistence.
- Resilience: Automatic rotation of Tidal API tokens and endpoints.
Quick Start (Docker)
The recommended way to run Tidaloader.
-
Create a
docker-compose.yml:version:'3.8'services:tidaloader:image:ghcr.io/rayz3r0/tidaloader:latestcontainer_name:tidaloaderports:- "8001:8001"environment:- MUSIC_DIR=/music- AUTH_USERNAME=admin- AUTH_PASSWORD=changeme- MAX_CONCURRENT_DOWNLOADS=3- QUEUE_AUTO_PROCESS=truevolumes:- ./music:/musicrestart:unless-stopped -
Run the container:
docker-compose up -d -
Open
http://localhost:8001.
Configuration Options
Configure these in your docker-compose.yml or .env file.
| Variable | Description | Default |
|---|---|---|
MUSIC_DIR |
Internal container path for downloads | /music |
AUTH_USERNAME |
Web UI Username | admin |
AUTH_PASSWORD |
Web UI Password | changeme |
MAX_CONCURRENT_DOWNLOADS |
Max parallel downloads | 3 |
QUEUE_AUTO_PROCESS |
Start queue automatically on boot | true |
MUSIC_DIR_HOST |
(Docker) Host directory to map | ./music |
Audio Quality Guide
| Quality Setting | Details | Format |
|---|---|---|
HI_RES |
Source quality (up to 24-bit/192kHz) | FLAC |
LOSSLESS |
CD quality (16-bit/44.1kHz) | FLAC |
HIGH |
Standard High (320kbps) | AAC |
LOW |
Data Saver (96kbps) | AAC |
MP3_320/256 |
Transcoded High Quality | MP3 |
OPUS_192 |
Transcoded High Efficiency | Opus |
Manual Installation
Windows
- Clone:
git clone https://github.com/RayZ3R0/tidaloader.git - Backend:
cd backend python -m venv venv; .\venv\Scripts\Activate.ps1 pip install -r requirements.txt cp .env.example .env # Edit .env with your settings - Frontend:
cd ..\frontend npm install; npm run build - Run:
cd ..\backend; .\start.ps1
Linux
- Clone:
git clone https://github.com/RayZ3R0/tidaloader.git - Backend:
cd backend python3 -m venv venv; source venv/bin/activate pip install -r requirements.txt cp .env.example .env # Edit .env - Frontend:
cd ../frontend npm install; npm run build - Run:
python -m uvicorn api.main:app --host 0.0.0.0 --port 8001
Android (Termux)
- Install Termux (F-Droid).
- Run Setup:
curl -O https://raw.githubusercontent.com/RayZ3R0/tidaloader/main/backend/termux-setup.sh bash termux-setup.sh - Start:
./start-service.sh
Development
- Backend:
uvicorn api.main:app --reload(Port 8001) - Frontend:
npm run dev(Port 5173)
Credits
Inspired by tidal-ui. Playlist generation by ListenBrainz.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Disclaimer: This project is for educational purposes only. The developers do not endorse piracy and are not responsible for how this software is used. Please support artists by purchasing their music.