TIDAL Playlist Merger

Merge multiple TIDAL playlists into one with duplicate track removal. No API keys or developer registration required.

Features

In-depth Deduplication Choose between Inter, Intra, or Full deduplication to clean your library.	Album, Mix & Favourites Support Paste URLs for Albums, Mixes or your Favourites to easily merge their tracks.
Duplicate Inspection Review exactly which tracks were removed after a merge operation.	Browse User Library Select playlists directly from your library without copy-pasting URLs.

Core Highlights

Drag-and-Drop Reordering: Determine track order by dragging playlists in the queue.
Real-time Progress: Detailed SSE-streamed progress with duplicate counts.
Glassmorphism UI: Beautiful, responsive design powered by Tailwind CSS v4.
Session Persistence: Automatic re-authentication across restarts.
Privacy First:All session tokens are stored strictly on your local machine in server-python/tidal_session.json.

Demo

Quick Start

Prerequisites: Python 3.9+, Node.js 18+, Git, TIDAL account

git clone https://github.com/Zephurlbr/TIDAL-Playlist-Merger.git

cd TIDAL-Playlist-Merger

Windows

start.bat

macOS/Linux

chmod +x start.sh && ./start.sh

Open http://localhost:8000 and connect your TIDAL account.

Usage

Authentication

Click "Connect with TIDAL"
Open the provided link (e.g., https://link.tidal.com/ABC123)
Log in and authorize
Return to the app - authentication completes automatically

Merging Playlists

Paste a playlist URL and press Enter
Repeat for additional playlists (max 200)
Enter a name for your merged playlist
Click "Merge Playlists"
Watch progress in real-time

Supported URL formats:

https://listen.tidal.com/playlist/<uuid>
https://tidal.com/browse/playlist/<uuid>
https://open.tidal.com/playlist/<uuid>
<raw-uuid>

Tech Stack

This project wouldn't be possible without tidalapi.

Backend: Python, FastAPI, uvicorn, tidalapi
Frontend: React, TypeScript, Vite, Tailwind CSS v4, Lucide Icons, Dnd Kit
Auth: TIDAL device linking flow

Notes

Max 200 playlists per merge
Max 10,000 tracks per playlist (TIDAL limit)
Duplicates can be removed using Inter, Intra, or Full modes
Session tokens are stored locally in server-python/tidal_session.json

Project Structure

TIDAL-Playlist-Merger/
├── client/              # React frontend (Vite + Tailwind 4)
│   └── src/
│       ├── App.tsx      # Main application logic
│       ├── components/  # Modal & UI components
│       ├── hooks/       # Custom React hooks (Auth, Merge)
│       ├── utils/       # Frontend utilities
│       └── types.ts     # TypeScript definitions
├── server-python/       # FastAPI backend
│   ├── main.py          # Entry point & Static serving
│   ├── routes/          # API & Auth endpoints
│   ├── services/        # Core business logic (Merge service)
│   ├── utils/           # URL parsing & Helpers
│   └── tests/           # Backend test suite (pytest)
├── start.bat           # Windows launcher
└── start.sh            # Unix launcher

API Reference

Base URL: http://localhost:8000

Endpoint	Method	Description
`/auth/login`	GET	Get device login URL
`/auth/status`	GET	Check auth status
`/auth/logout`	POST	Logout and delete session
`/api/me/playlists`	GET	Fetch user's library playlists
`/api/me/favorites/count`	GET	Get favorite tracks count
`/api/playlist/resolve`	POST	Resolve Playlist/Album/Mix/Favourites from URL
`/api/merge`	POST	Merge playlists (SSE stream)
`/docs`	GET	Swagger UI

Full API documentation available at /docs when running.

Configuration

Backend (server-python/.env):

PORT=8000
TIDAL_COUNTRY_CODE=US

Frontend (client/.env, dev only):

VITE_API_BASE=http://localhost:8000

Troubleshooting

Issue	Solution
Port 8000 in use	Kill process or change `PORT` in `.env`
CORS error	Access at `http://localhost:8000` (not 5173)
Playlist not found	Check playlist ID is correct
Login doesn't complete	Refresh page after authorizing

Changelog

V2.0.2

UI Redesign: Full migration to Tailwind CSS v4 with glassmorphism theme.
Support for Albums, Mixes & Favourites: You can now merge tracks from albums, mixes, and your library favourites.
Library Browser: New modal to select playlists directly from your library.
Deduplication modes: Advanced Inter/Intra/Full duplicate removal options.
Drag-and-Drop: Reorder your merge queue visually.
Bug Fixes: Improved session recovery and batch processing cleanup.

V1.1.0 (Legacy)

Real-time progress tracking via Server-Sent Events (SSE).
Basic duplicate removal.
Support for up to 200 playlists.

License

GNU General Public License v3.0

Zephurlbr/TIDAL-Playlist-Merger