Skip to content
/ tidaloader Public

A full-stack web application for downloading high-quality music from Tidal with intelligent playlist generation via ListenBrainz/Troi integration. Features automatic metadata tagging, lyrics fetching, and organized file management.

41 stars 3 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

RayZ3R0/tidaloader

BranchesTags

Repository files navigation

A full-stack web application for downloading high-quality music from Tidal with intelligent playlist generation via ListenBrainz/Troi integration. Features automatic metadata tagging, lyrics fetching, and organized file management.

Heavy 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.

Features

Core Functionality

  • Tidal Music Downloads: Download tracks in FLAC (lossless/hi-res), MP3 (128kbps/256kbps), or AAC (320kbps/96kbps) formats
  • Smart Playlist Generation: Generate personalized playlists using ListenBrainz listening history via Troi
  • Automatic Organization: Files organized by Artist/Album with proper track numbering
  • Rich Metadata: Automatic ID3 tags, album artwork, and MusicBrainz IDs
  • Lyrics Integration: Synced (.lrc) and plain text (.txt) lyrics via LrcLib API
  • Download Queue Management: Concurrent downloads with progress tracking
  • Endpoint Failover: Automatic rotation across multiple Tidal API endpoints

User Interface

  • Modern Web UI: Clean, responsive Preact-based interface
  • Real-time Progress: Live download progress with percentage indicators
  • Search Capabilities: Search tracks, albums, and artists
  • Batch Operations: Download entire albums or artist discographies
  • Quality Selection: Choose audio quality per download
  • Authentication: Secure login with credential management

Audio Quality Options

  • Hi-Res FLAC (HI_RES_LOSSLESS): Up to 24-bit/192kHz direct from Tidal
  • Lossless FLAC (LOSSLESS): 16-bit/44.1kHz archival quality
  • MP3 256kbps / 128kbps (MP3_256, MP3_128): Transcoded using ffmpeg/libmp3lame
  • AAC 320kbps / 96kbps (HIGH, LOW): Direct AAC streams from Tidal

Project Structure

tidaloader/
├── backend/
│   ├── api/
│   │   ├── __init__.py
│   │   ├── auth.py           # Authentication middleware
│   │   └── main.py           # FastAPI application
│   ├── downloads/            # Downloaded music files
│   ├── .env                  # Environment configuration
│   ├── .env.example          # Example configuration
│   ├── config.py             # Configuration loader
│   ├── lyrics_client.py      # LrcLib API client
│   ├── requirements.txt      # Python dependencies
│   ├── tidal_client.py       # Tidal API client
│   └── troi_integration.py   # Troi playlist generator
├── frontend/
│   ├── public/
│   ├── src/
│   │   ├── api/              # API client
│   │   ├── components/       # UI components
│   │   ├── stores/           # State management (Zustand)
│   │   ├── utils/            # Utilities
│   │   ├── app.jsx           # Main app component
│   │   ├── main.jsx          # Entry point
│   │   └── style.css         # Tailwind styles
│   ├── index.html
│   ├── package.json
│   ├── tailwind.config.js
│   └── vite.config.js
├── automate-troi-download.py  # Standalone CLI tool
└── api_endpoints.json          # Tidal API endpoint list

Prerequisites

Common Requirements

  • Python 3.8+
  • Node.js 16+ and npm
  • Git
  • ffmpeg 4.0+ (for MP3 transcoding support)

Platform-Specific

Windows

  • PowerShell or Command Prompt
  • Windows 10/11

Linux

  • Bash shell
  • systemd (optional, for service management)

Android/Termux

  • Termux app from F-Droid
  • Termux:Boot (optional, for auto-start)

Installation

Docker Installation (Recommended)

The easiest way to run Tidaloader is using Docker with our prebuilt image.

Prerequisites

  • Docker Desktop (Windows/Mac) or Docker Engine (Linux)
  • Docker Compose (included with Docker Desktop)

Quick Start with Prebuilt Image

  1. Create a docker-compose.yml file

    services:
  tidaloader:
    image: ghcr.io/rayz3r0/tidaloader:latest
    container_name: tidaloader
    ports:
      - "8001:8001"
    environment:
      - MUSIC_DIR=${MUSIC_DIR:-/music}
      - AUTH_USERNAME=${AUTH_USERNAME:-admin}
      - AUTH_PASSWORD=${AUTH_PASSWORD:-changeme}
    volumes:
      - ${MUSIC_DIR_HOST:-./music}:/music
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8001/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

  2. Create environment file (optional)

    Create a .env file in the same directory:

    AUTH_USERNAME=admin
AUTH_PASSWORD=your-secure-password
MUSIC_DIR_HOST=./music  # or C:/Users/YourName/Music on Windows

  3. Start the application

    docker-compose up -d

  4. Access the application

    Open your browser to http://localhost:8001

Alternative: Build from Source

If you prefer to build the image yourself:

  1. Clone the repository

    git clone https://github.com/RayZ3R0/tidaloader.git
cd tidaloader

  2. Update docker-compose.yml

    services:
  tidaloader:
    build: . # or build: https://github.com/RayZ3R0/tidaloader.git
    container_name: tidaloader
    # ... rest of configuration same as above

  3. Start the application

    docker-compose up -d --build

Docker Commands

View logs:

docker-compose logs -f

Stop the application:

docker-compose down

Update to latest version:

docker-compose pull
docker-compose up -d

Configuration

Windows path example:

MUSIC_DIR_HOST=C:/Users/YourName/Music

Linux/Mac path example:

MUSIC_DIR_HOST=/home/yourname/Music

Default (current directory):

MUSIC_DIR_HOST=./music

Troubleshooting

View logs:

docker-compose logs -f

Permission issues (Linux/Mac):

sudo chown -R $(id -u):$(id -g) ./music

Permission issues (Windows):

icacls .\music /grant Everyone:F /T

Reset everything:

docker-compose down -v
docker-compose pull
docker-compose up -d

Windows Setup

  1. Clone the repository

    git clone https://github.com/RayZ3R0/tidaloader.git
cd tidaloader

  2. Backend setup

    cd backend
python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt

  3. Configure environment

    cp .env.example .env

    Edit .env and set your configuration:

    MUSIC_DIR=C:\Users\YourName\Music
AUTH_USERNAME=your_username
AUTH_PASSWORD=your_secure_password

  4. Frontend setup

    cd ..\frontend
npm install
npm run build

  5. Start the server

    cd ..\backend
.\start.ps1

  6. Access the application

    Open your browser to http://localhost:8001

Linux Setup

  1. Clone the repository

    git clone https://github.com/RayZ3R0/tidaloader.git
cd tidaloader

  2. Backend setup

    cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

  3. Configure environment

    cp .env.example .env
nano .env  # or use your preferred editor

    Edit .env:

    MUSIC_DIR=/home/yourname/Music
AUTH_USERNAME=your_username
AUTH_PASSWORD=your_secure_password

  4. Frontend setup

    cd ../frontend
npm install
npm run build

  5. Start the server

    cd ../backend
source venv/bin/activate
python -m uvicorn api.main:app --host 0.0.0.0 --port 8001

  6. Access the application

    Open your browser to http://localhost:8001

Android/Termux Setup

  1. Install Termux

    Download from F-Droid: https://f-droid.org/en/packages/com.termux/

  2. Run setup script

    curl -O https://raw.githubusercontent.com/RayZ3R0/tidaloader/main/backend/termux-setup.sh
bash termux-setup.sh

  3. Configure environment

    cd ~/tidaloader/backend
nano .env

    The default configuration uses:

    MUSIC_DIR=/data/data/com.termux/files/home/music/tidal-downloads

  4. Start the service

    cd ~/tidaloader
./start-service.sh

  5. Optional: Auto-start on boot

    ./install-termux-service.sh

  6. Access the application

    On your device: http://localhost:8001

    From network: http://[device-ip]:8001

Configuration

Environment Variables

All configuration is done via .env:

# Music directory - where files will be downloaded
MUSIC_DIR=/path/to/music

# Authentication credentials
AUTH_USERNAME=admin
AUTH_PASSWORD=your-secure-password-here

Download Organization

Files are automatically organized in the following structure:

MUSIC_DIR/
└── Artist Name/
    └── Album Name/
        ├── 01 - Track Title.flac
        ├── 01 - Track Title.lrc  (synced lyrics if available)
        ├── 02 - Track Title.flac
        ├── 02 - Track Title.txt  (plain lyrics if available)
        └── ...

Quality Settings

Available quality options (configurable per download):

  • HI_RES_LOSSLESS: Up to 24-bit/192kHz FLAC
  • LOSSLESS: 16-bit/44.1kHz FLAC (default)
  • HIGH: 320kbps AAC
  • LOW: 96kbps AAC

Usage

Web Interface

  1. Login

    Use the credentials you set in .env

  2. Search for Music

    • Switch to "Search" tab
    • Search by track, album, or artist
    • Select tracks to download
    • Add to queue

  3. Generate Troi Playlists

    • Switch to "Troi Playlist" tab
    • Enter your ListenBrainz username
    • Choose "Daily Jams" or "Periodic Jams"
    • Review generated tracks
    • Download selected tracks

  4. Manage Downloads

    • View queue in the download popout (bottom-right)
    • Start/pause downloads
    • Monitor progress
    • Review completed and failed downloads

Command-Line Tool

The standalone CLI tool automate-troi-download.py can be used independently:

# Activate backend virtual environment
cd backend
source venv/bin/activate  # Linux/Mac
# or
.\venv\Scripts\Activate.ps1  # Windows

# Run the tool
cd ..
python automate-troi-download.py your-listenbrainz-username

# Options
python automate-troi-download.py --help

Options:

  • --download-dir PATH: Specify download directory (default: ./downloads)
  • --no-debug: Disable debug output
  • --no-test-mode: Download all tracks (default: first 5 only)

API Endpoints

The backend provides a REST API documented at http://localhost:8001/docs (FastAPI Swagger UI).

Public Endpoints

  • GET /api: API status
  • GET /api/health: Health check

Protected Endpoints (require authentication)

  • POST /api/troi/generate: Generate Troi playlist
  • GET /api/search/tracks: Search tracks
  • GET /api/search/albums: Search albums
  • GET /api/search/artists: Search artists
  • GET /api/album/{album_id}/tracks: Get album tracks
  • GET /api/artist/{artist_id}: Get artist details
  • POST /api/download/track: Download a track
  • GET /api/download/progress/{track_id}: Stream download progress

Development

Running in Development Mode

Backend:

cd backend
source venv/bin/activate
python -m uvicorn api.main:app --reload --host 0.0.0.0 --port 8001

Frontend:

cd frontend
npm run dev

The frontend dev server runs on http://localhost:5173 and proxies API requests to the backend.

Project Dependencies

Backend (backend/requirements.txt):

  • fastapi: Web framework
  • uvicorn: ASGI server
  • aiohttp: Async HTTP client
  • mutagen: Audio metadata handling
  • lrclibapi: Lyrics fetching
  • python-jose: JWT authentication
  • passlib: Password hashing
  • pydantic: Data validation

Frontend (frontend/package.json):

  • preact: Lightweight React alternative
  • zustand: State management
  • tailwindcss: Utility-first CSS
  • vite: Build tool

Troubleshooting

Backend won't start

  • Ensure Python virtual environment is activated
  • Check .env file exists and is properly configured
  • Verify all dependencies are installed: pip install -r requirements.txt

Frontend build fails

  • Delete node_modules and package-lock.json
  • Run npm install again
  • Ensure Node.js version is 16+

Downloads fail

  • Check internet connection
  • Verify Tidal API endpoints are accessible
  • Review backend logs for specific errors
  • Try different quality settings

Authentication errors

  • Verify AUTH_USERNAME and AUTH_PASSWORD in .env
  • Clear browser cache and cookies
  • Check backend logs for authentication failures

Missing metadata/lyrics

  • LrcLib API may not have lyrics for all tracks
  • Some tracks may have incomplete Tidal metadata
  • Album artwork requires internet access during download

Advanced Configuration

Adding Custom Tidal Endpoints

Edit api_endpoints.json:

{
  "endpoints": [
    {
      "name": "custom-endpoint",
      "url": "https://your-endpoint.example.com",
      "priority": 1
    }
  ]
}

Lower priority numbers are tried first.

Service Management (Linux)

Create systemd service at /etc/systemd/system/tidaloader.service:

[Unit]
Description=Tidaloader Tidal Downloader
After=network.target

[Service]
Type=simple
User=youruser
WorkingDirectory=/path/to/tidaloader/backend
Environment="PATH=/path/to/tidaloader/backend/venv/bin"
ExecStart=/path/to/tidaloader/backend/venv/bin/python -m uvicorn api.main:app --host 0.0.0.0 --port 8001

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable tidaloader
sudo systemctl start tidaloader

Credits

  • Tidal API endpoints via community projects
  • Lyrics from LrcLib API
  • Troi playlist generation via ListenBrainz
  • MusicBrainz metadata integration

License

This project is for educational purposes only. Ensure you comply with Tidal's Terms of Service and respect copyright laws in your jurisdiction.

Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Submit a pull request

Support

For issues, questions, or feature requests, please open an issue on GitHub.

About

A full-stack web application for downloading high-quality music from Tidal with intelligent playlist generation via ListenBrainz/Troi integration. Features automatic metadata tagging, lyrics fetching, and organized file management.

Resources

Readme
Activity

Stars

41 stars

Watchers

0 watching

Forks

3 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors 3

  •  
  •  
  •  

Languages