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.

9 stars 0 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.

Features

Core Functionality

  • Tidal Music Downloads: Download tracks in FLAC (lossless/hi-res) 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

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

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. This works on Windows, macOS, and Linux.

Prerequisites

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

Quick Start

  1. Clone the repository

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

  2. Create environment file

    cp .env.example .env

    Edit .env and set your credentials and music directory:

    Windows:

    AUTH_USERNAME=admin
AUTH_PASSWORD=your-secure-password
MUSIC_DIR=/music
MUSIC_DIR_HOST=C:/Users/YourName/Music

    Linux/Mac:

    AUTH_USERNAME=admin
AUTH_PASSWORD=your-secure-password
MUSIC_DIR=/music
MUSIC_DIR_HOST=/home/yourname/Music

    Default (uses project folder):

    AUTH_USERNAME=admin
AUTH_PASSWORD=your-secure-password
MUSIC_DIR=/music
MUSIC_DIR_HOST=./music

  3. Start the application

    docker-compose up -d

    First run will take a few minutes to build the image.

  4. Access the application

    Open your browser to http://localhost:8001

Docker Commands

View logs:

docker-compose logs -f

Stop the application:

docker-compose down

Restart the application:

docker-compose restart

Rebuild after code changes:

docker-compose up -d --build

Update to latest version:

git pull
docker-compose up -d --build

Music Files

By default, music is downloaded to ./music in your project folder. To use a custom location:

  1. Edit .env:

    MUSIC_DIR_HOST=/your/custom/path

  2. Restart the container:

    docker-compose up -d

The music directory is automatically created if it doesn't exist.

Customization

Change port:

Edit docker-compose.yml:

ports:
  - "8080:8001" # Access on port 8080 instead

Environment variables:

All configuration is done via .env file in the project root:

AUTH_USERNAME=myusername
AUTH_PASSWORD=mypassword
MUSIC_DIR=/music
MUSIC_DIR_HOST=./music

Troubleshooting

Container won't start:

docker-compose logs

Permission issues with music directory (Linux/Mac):

sudo chown -R $(id -u):$(id -g) ./music
# or
chmod -R 777 ./music

Permission issues (Windows):

# Run in PowerShell as Administrator
icacls .\music /grant Everyone:F /T

Music directory not found:

The container automatically creates /music inside. Make sure MUSIC_DIR_HOST in .env points to a valid location on your host machine.

Reset everything:

docker-compose down -v
docker-compose up -d --build

Optional: Custom API Endpoints

If you want to customize Tidal API endpoints, create api_endpoints.json in the project root:

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

The application works fine without this file using built-in defaults.

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

9 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Languages