tidal-playlist-manager 1.3.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- tidal_playlist_manager-1.3.0/LICENSE +21 -0
- tidal_playlist_manager-1.3.0/MANIFEST.in +4 -0
- tidal_playlist_manager-1.3.0/PKG-INFO +238 -0
- tidal_playlist_manager-1.3.0/README.md +210 -0
- tidal_playlist_manager-1.3.0/pyproject.toml +48 -0
- tidal_playlist_manager-1.3.0/setup.cfg +4 -0
- tidal_playlist_manager-1.3.0/tests/test_api.py +150 -0
- tidal_playlist_manager-1.3.0/tests/test_client.py +305 -0
- tidal_playlist_manager-1.3.0/tests/test_spotify.py +131 -0
- tidal_playlist_manager-1.3.0/tests/test_transfer.py +122 -0
- tidal_playlist_manager-1.3.0/tidal_manager/__init__.py +3 -0
- tidal_playlist_manager-1.3.0/tidal_manager/cli.py +556 -0
- tidal_playlist_manager-1.3.0/tidal_manager/client.py +1031 -0
- tidal_playlist_manager-1.3.0/tidal_manager/config.py +45 -0
- tidal_playlist_manager-1.3.0/tidal_manager/server.py +795 -0
- tidal_playlist_manager-1.3.0/tidal_manager/spotify_client.py +602 -0
- tidal_playlist_manager-1.3.0/tidal_manager/static/app.js +2078 -0
- tidal_playlist_manager-1.3.0/tidal_manager/static/index.html +838 -0
- tidal_playlist_manager-1.3.0/tidal_manager/static/style.css +1716 -0
- tidal_playlist_manager-1.3.0/tidal_playlist_manager.egg-info/PKG-INFO +238 -0
- tidal_playlist_manager-1.3.0/tidal_playlist_manager.egg-info/SOURCES.txt +23 -0
- tidal_playlist_manager-1.3.0/tidal_playlist_manager.egg-info/dependency_links.txt +1 -0
- tidal_playlist_manager-1.3.0/tidal_playlist_manager.egg-info/entry_points.txt +3 -0
- tidal_playlist_manager-1.3.0/tidal_playlist_manager.egg-info/requires.txt +5 -0
- tidal_playlist_manager-1.3.0/tidal_playlist_manager.egg-info/top_level.txt +1 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 magicclue
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,238 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: tidal-playlist-manager
|
|
3
|
+
Version: 1.3.0
|
|
4
|
+
Summary: A modern TIDAL & Spotify Playlist Manager: Read, create, rename playlists, and move/copy tracks within and across TIDAL and Spotify with Web UI and CLI.
|
|
5
|
+
Author: magicclue
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/tas231/TidalPlaylist
|
|
8
|
+
Project-URL: Repository, https://github.com/tas231/TidalPlaylist.git
|
|
9
|
+
Project-URL: Issues, https://github.com/tas231/TidalPlaylist/issues
|
|
10
|
+
Keywords: tidal,spotify,playlist,manager,music,fastapi,transfer
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Topic :: Multimedia :: Sound/Audio
|
|
18
|
+
Classifier: Environment :: Web Environment
|
|
19
|
+
Requires-Python: >=3.9
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
License-File: LICENSE
|
|
22
|
+
Requires-Dist: tidalapi>=0.8.11
|
|
23
|
+
Requires-Dist: fastapi>=0.110.0
|
|
24
|
+
Requires-Dist: uvicorn[standard]>=0.28.0
|
|
25
|
+
Requires-Dist: requests>=2.31.0
|
|
26
|
+
Requires-Dist: pydantic>=2.0.0
|
|
27
|
+
Dynamic: license-file
|
|
28
|
+
|
|
29
|
+
# TIDAL & Spotify Playlist Manager ๐ต๐ข
|
|
30
|
+
|
|
31
|
+
[](https://github.com/tas231/TidalPlaylist/releases)
|
|
32
|
+
[](LICENSE)
|
|
33
|
+
[](https://python.org)
|
|
34
|
+
[](https://fastapi.tiangolo.com)
|
|
35
|
+
[](https://github.com/tas231/TidalPlaylist)
|
|
36
|
+
|
|
37
|
+
A powerful, modern music playlist management application featuring a dual-pane **Web UI** and a comprehensive **CLI** for **TIDAL** and **Spotify**.
|
|
38
|
+
|
|
39
|
+
Manage in-platform playlists or transfer tracks across platforms in both directions (**TIDAL โ Spotify**) with smart ISRC track matching and zero build-step requirements!
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
## โจ Features
|
|
44
|
+
|
|
45
|
+
- ๐ **Dual-Platform & Cross-Platform Transfers (TIDAL & Spotify)**:
|
|
46
|
+
- Independently toggle either **Panel A** or **Panel B** between **๐ต TIDAL** and **๐ข Spotify**.
|
|
47
|
+
- **In-Platform transfers**: TIDAL โ TIDAL, Spotify โ Spotify.
|
|
48
|
+
- **Cross-Platform transfers**: Transfer songs seamlessly from **TIDAL โ Spotify** or **Spotify โ TIDAL**!
|
|
49
|
+
- Supports both **Copy** (keep in source) and **Move** (remove from source after copying).
|
|
50
|
+
- **Smart ISRC Track Matching**: Automatically queries target catalogs by international standard ISRC (International Standard Recording Code) for 100% exact track matches, with intelligent fallback to normalized Title + Artist search.
|
|
51
|
+
- **Detailed Transfer Report**: Displays a clear summary dialog showing successfully transferred tracks and any tracks not found in the destination service.
|
|
52
|
+
- ๐ง **Read & Manage Playlists**: View personal playlists side-by-side, inspect tracklists, high-res album covers, explicit badges, track durations, and total running times.
|
|
53
|
+
- โ **Create & Rename**: Add new playlists with descriptions on TIDAL or Spotify, or rename existing ones in-place.
|
|
54
|
+
- ๐ **Copy & Move Tracks**: Copy or move selected tracks between playlists with multi-selection.
|
|
55
|
+
- ๐ฑ๏ธ **Drag & Drop (Cross-Panel & In-Playlist)**:
|
|
56
|
+
- **In-Playlist Reordering**: Reorder songs directly within any playlist by grabbing the grip handle (`โฎโฎ`) and dragging them up or down. A cyan indicator line shows the exact drop location, and the new sequence is instantly synced to the cloud!
|
|
57
|
+
- **Cross-Panel Transfers**: Drag tracks directly from Panel A to Panel B (or vice versa)โeven between TIDAL and Spotifyโto copy them, or hold <kbd>Alt</kbd> / <kbd>Shift</kbd> to move them.
|
|
58
|
+
- โก **Auto-Split Playlists (> 99 Tracks)**:
|
|
59
|
+
- Automatically splits any playlist with > 99 tracks into chunks of max 99 tracks (ideal for car head-units and audio gear with 99-track limits).
|
|
60
|
+
- Automatically names them with numerical suffixes: `[Name] 1`, `[Name] 2`, `[Name] 3`...
|
|
61
|
+
- Moves excess tracks seamlessly into the new suffix playlists.
|
|
62
|
+
- ๐ **Duplicate Finder & 1-Click Cleaner**:
|
|
63
|
+
- Scans for duplicate tracks by exact Media ID and normalized Title + Artist matching.
|
|
64
|
+
- Groups duplicate copies and provides a 1-click **Clean Duplicates** action (safely retaining the earliest added copy).
|
|
65
|
+
- ๐พ **Backup & Flexible Export / Import**:
|
|
66
|
+
- **Export**: Export playlists directly as **JSON** (full metadata), **CSV** (for spreadsheets and DJ tools), or **M3U8** (for media players).
|
|
67
|
+
- **Import**: Import playlists from JSON, CSV, or M3U files with flexible destinations:
|
|
68
|
+
- โจ Create as a brand-new playlist
|
|
69
|
+
- ๐ฅ Append imported tracks directly into the playlist active in **Panel A**
|
|
70
|
+
- ๐ฅ Append imported tracks directly into the playlist active in **Panel B**
|
|
71
|
+
- ๐ **Playlist Merge & Cloud Shuffle**:
|
|
72
|
+
- **Merge**: Combine multiple playlists into a unified master playlist (with optional automatic deduplication).
|
|
73
|
+
- **Cloud Shuffle**: Randomize track ordering permanently in the cloud.
|
|
74
|
+
- ๐ **Sorting & Ordering**:
|
|
75
|
+
- Sort tracks on-the-fly by Title, Artist, Album, or Duration in ascending or descending order.
|
|
76
|
+
- One-click **"Save Order"** button to permanently commit the sorted order to the cloud.
|
|
77
|
+
- ๐ง **Audio Preview Player**:
|
|
78
|
+
- 30-second audio preview button directly on every track's artwork thumbnail.
|
|
79
|
+
- Sticky bottom preview player bar with scrubber, duration counter, and a 1-click direct link to web players.
|
|
80
|
+
- ๐ **Integrated Catalog Search**:
|
|
81
|
+
- Global catalog search (<kbd>Cmd+K</kbd> / <kbd>Ctrl+K</kbd>) to discover tracks and add them directly to Panel A or Panel B with 1 click.
|
|
82
|
+
- ๐ **In-App Guide & Shortcuts Modal**:
|
|
83
|
+
- Built-in **Guide** button in the header bar with step-by-step feature walkthroughs and tips.
|
|
84
|
+
- ๐ **Privacy & Security First**:
|
|
85
|
+
- Connects using official OAuth authorization.
|
|
86
|
+
- No passwords or sensitive credentials are ever stored. Session tokens are stored locally and strictly excluded from git tracking.
|
|
87
|
+
|
|
88
|
+
---
|
|
89
|
+
|
|
90
|
+
## ๐ Installation & Launch Options
|
|
91
|
+
|
|
92
|
+
Choose whichever method is easiest for you:
|
|
93
|
+
|
|
94
|
+
### ๐ฆ Option 1: Standalone Desktop App (No Python Required)
|
|
95
|
+
If you don't have Python installed and want a simple 1-click experience:
|
|
96
|
+
1. Head over to the **[Latest Releases](https://github.com/tas231/TidalPlaylist/releases)** page on GitHub.
|
|
97
|
+
2. Download the pre-built archive for your operating system:
|
|
98
|
+
- **Windows**: `TidalPlaylistManager-Windows-x64.zip` (extract and double-click `TidalPlaylistManager.exe`)
|
|
99
|
+
- **macOS**: `TidalPlaylistManager-macOS.zip` (extract and open `TidalPlaylistManager`)
|
|
100
|
+
- **Linux**: `TidalPlaylistManager-Linux-x64.tar.gz`
|
|
101
|
+
3. The app starts locally and immediately opens the Web UI in your default browser!
|
|
102
|
+
|
|
103
|
+
---
|
|
104
|
+
|
|
105
|
+
### ๐ Option 2: Install via pip / pipx (PyPI)
|
|
106
|
+
If you have Python 3.9+ installed:
|
|
107
|
+
```bash
|
|
108
|
+
# Install globally or in your environment:
|
|
109
|
+
pip install tidal-playlist-manager
|
|
110
|
+
|
|
111
|
+
# Or run instantly in an isolated environment with pipx:
|
|
112
|
+
pipx run tidal-playlist-manager
|
|
113
|
+
```
|
|
114
|
+
Then start the app anytime simply by typing:
|
|
115
|
+
```bash
|
|
116
|
+
tidal-manager
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
---
|
|
120
|
+
|
|
121
|
+
### ๐ป Option 3: Run from Git Source Checkout
|
|
122
|
+
|
|
123
|
+
#### Prerequisites
|
|
124
|
+
- **Python 3.9 or higher** ([python.org](https://www.python.org/downloads/)).
|
|
125
|
+
- *Windows users:* Make sure to check **"Add Python to PATH"** during setup.
|
|
126
|
+
- *Linux users (Ubuntu/Debian):* `sudo apt install python3 python3-venv python3-pip`.
|
|
127
|
+
|
|
128
|
+
#### Launching from source:
|
|
129
|
+
- **๐ macOS**: Double-click `Start.command` or `Tidal Playlist Manager.app` (or `./run.sh` in Terminal).
|
|
130
|
+
- **๐ช Windows**: Double-click `run.bat` in File Explorer.
|
|
131
|
+
- **๐ง Linux**: Run `chmod +x run.sh && ./run.sh` in Terminal.
|
|
132
|
+
|
|
133
|
+
---
|
|
134
|
+
|
|
135
|
+
### ๐ Connect your Accounts
|
|
136
|
+
|
|
137
|
+
#### 1. TIDAL (Primary)
|
|
138
|
+
1. Once started, your default browser opens at **`http://127.0.0.1:8000`**.
|
|
139
|
+
2. Click **Connect with TIDAL**.
|
|
140
|
+
3. Click the authorization link to approve the code in your browser (no password required).
|
|
141
|
+
4. Once approved, the manager will instantly load your TIDAL playlists!
|
|
142
|
+
|
|
143
|
+
#### 2. Spotify (Optional for Dual-Platform & Transfers)
|
|
144
|
+
1. In the top-right header, click **๐ข Connect Spotify** (or select the **๐ข Spotify** tab on Panel A or Panel B).
|
|
145
|
+
2. Enter your free Spotify Developer App credentials:
|
|
146
|
+
- Go to [Spotify Developer Dashboard](https://developer.spotify.com/dashboard) and create a free app.
|
|
147
|
+
- Set the Redirect URI to: `http://127.0.0.1:8000/api/spotify/callback`
|
|
148
|
+
- Paste your **Client ID** and **Client Secret**.
|
|
149
|
+
3. Click **Save & Authorize Spotify**. A popup window will prompt you to approve access.
|
|
150
|
+
4. Once connected, your Spotify account badge appears and you can select Spotify in either panel!
|
|
151
|
+
|
|
152
|
+
---
|
|
153
|
+
|
|
154
|
+
## ๐ User Guide (Web UI Walkthrough)
|
|
155
|
+
|
|
156
|
+
| Feature | How to Use |
|
|
157
|
+
|---|---|
|
|
158
|
+
| **Platform Switcher** | Use the `[ ๐ต TIDAL ]` and `[ ๐ข Spotify ]` tabs at the top of Panel A and Panel B to choose the music service for each side independently. |
|
|
159
|
+
| **Dual-Pane View** | Select a playlist in Dropdown A and Dropdown B to inspect and manage two playlists side-by-side. |
|
|
160
|
+
| **Cross-Platform Transfer** | Set Panel A to TIDAL and Panel B to Spotify (or vice-versa). Select songs and click `Copy โ` or `Move โ` (or drag & drop). Matches via ISRC standard with Title/Artist fallback and shows a detailed transfer report. |
|
|
161
|
+
| **In-Playlist Reordering (Drag & Drop)** | Grab any song by the grip handle (`โฎโฎ`) on the left and drag it up or down. A cyan indicator line shows the drop position. The new order is saved directly to your cloud playlist. |
|
|
162
|
+
| **Copy / Move Tracks** | Select tracks using checkboxes and click `Copy โ` or `Move โ`, or drag & drop songs directly between panels (hold <kbd>Alt</kbd> or <kbd>Shift</kbd> to move). |
|
|
163
|
+
| **Sort & Save Order** | Select a sort criteria like `Title (A-Z)` in the panel header. Click `Save Order` to commit this order permanently to your cloud playlist. |
|
|
164
|
+
| **Clean Duplicates** | Click `Duplicates` in the playlist header. Inspect grouped duplicate copies and click `Clean Duplicates` to remove redundant tracks safely. |
|
|
165
|
+
| **Backup & Export** | Click `Export`, select JSON, CSV, or M3U, and download your playlist backup. |
|
|
166
|
+
| **Import** | Click `Import` in the top bar, upload a backup file, and choose whether to create a new playlist or append tracks directly into Panel A or Panel B. |
|
|
167
|
+
| **Split Large Playlists** | Click `โก Split (>99)` to divide playlists with > 99 tracks into clean 99-track chunks (`... 1`, `... 2`). |
|
|
168
|
+
| **Catalog Search & Preview** | Press `Cmd+K` to search millions of tracks. Click any track cover artwork for an instant 30-second audio preview. |
|
|
169
|
+
|
|
170
|
+
---
|
|
171
|
+
|
|
172
|
+
## โจ๏ธ Keyboard Shortcuts
|
|
173
|
+
|
|
174
|
+
- <kbd>Cmd</kbd> + <kbd>K</kbd> / <kbd>Ctrl</kbd> + <kbd>K</kbd> : Open global catalog search
|
|
175
|
+
- <kbd>Esc</kbd> : Close active dialog or modal window
|
|
176
|
+
|
|
177
|
+
---
|
|
178
|
+
|
|
179
|
+
## ๐ ๏ธ CLI Reference
|
|
180
|
+
|
|
181
|
+
All features are also available directly via the command-line interface:
|
|
182
|
+
|
|
183
|
+
| Command | Description | Example |
|
|
184
|
+
|---|---|---|
|
|
185
|
+
| `web` | Start the Web UI server | `./run.sh web --port 8000` |
|
|
186
|
+
| `login` | Authenticate with TIDAL via OAuth | `./run.sh login` |
|
|
187
|
+
| `status` | Check authentication status | `./run.sh status` |
|
|
188
|
+
| `logout` | Log out and delete stored session | `./run.sh logout` |
|
|
189
|
+
| `list` | List all user playlists | `./run.sh list` |
|
|
190
|
+
| `show <pl>` | View tracks in a playlist | `./run.sh show "Chill Vibes"` |
|
|
191
|
+
| `create <title>` | Create a new playlist | `./run.sh create "Workout" -d "High energy"` |
|
|
192
|
+
| `rename <pl> <title>` | Rename an existing playlist | `./run.sh rename "Workout" "Gym Bangers"` |
|
|
193
|
+
| `delete-playlist <pl>` | Delete a playlist | `./run.sh delete-playlist "Old Mix" -y` |
|
|
194
|
+
| `copy` | Copy tracks between playlists | `./run.sh copy --from "Pop" --to "Best Of" --indices 0,1,2-5` |
|
|
195
|
+
| `move` | Move tracks between playlists | `./run.sh move --from "Inbox" --to "Favorites" --indices 0,3` |
|
|
196
|
+
| `split <pl>` | Auto-split playlist (>99 tracks) | `./run.sh split "Massive Library"` |
|
|
197
|
+
| `duplicates <pl>` | Check or clean duplicates | `./run.sh duplicates "My Mix" --clean` |
|
|
198
|
+
| `export <pl>` | Export playlist to file | `./run.sh export "Chill" -f csv` |
|
|
199
|
+
| `import <file>` | Import playlist from file | `./run.sh import "chill_backup.json"` |
|
|
200
|
+
| `merge` | Merge multiple playlists | `./run.sh merge --from "Rock,Indie" -t "Rock & Indie"` |
|
|
201
|
+
| `shuffle <pl>` | Shuffle tracks on TIDAL | `./run.sh shuffle "Party Mix"` |
|
|
202
|
+
| `search <query>` | Search TIDAL catalog | `./run.sh search "Daft Punk"` |
|
|
203
|
+
|
|
204
|
+
---
|
|
205
|
+
|
|
206
|
+
## ๐งช Running Tests
|
|
207
|
+
|
|
208
|
+
```bash
|
|
209
|
+
.venv/bin/python3 -m unittest discover -s tests
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
---
|
|
213
|
+
|
|
214
|
+
## โ ๏ธ Disclaimer & Limitation of Liability
|
|
215
|
+
|
|
216
|
+
This free software is provided **"as is"** and is intended strictly as a **testing and evaluation tool** for educational and personal experimentation:
|
|
217
|
+
|
|
218
|
+
- **No Liability or Responsibility:** The author(s) and contributor(s) accept **no liability or responsibility whatsoever** for any direct, indirect, incidental, or consequential damages, playlist modifications, unintended track removals, loss of data, account restrictions, or API disruptions arising from the use of or inability to use this software.
|
|
219
|
+
- **Testing Use Only:** This application is provided for testing and evaluation purposes. Always verify changes and use it entirely at your own discretion and risk.
|
|
220
|
+
- **Backups Strongly Recommended:** Before modifying, sorting, splitting, or deduplicating playlists, please use the built-in **Backup & Export** feature to create a local JSON, CSV, or M3U backup of your playlists.
|
|
221
|
+
- **Third-Party Services:** This project is an independent open-source tool and is not affiliated with, endorsed by, or sponsored by TIDAL, Aspiro AB, or Spotify AB.
|
|
222
|
+
|
|
223
|
+
---
|
|
224
|
+
|
|
225
|
+
## ๐ Project Status & Forking
|
|
226
|
+
|
|
227
|
+
This project is feature-complete for its intended scope and is provided as a finished utility. Active ongoing feature development or maintenance is not planned.
|
|
228
|
+
|
|
229
|
+
If you would like to customize, extend, or build upon this tool, you are very welcome to **fork, copy, or adapt the code** freely under the terms of the [MIT License](LICENSE).
|
|
230
|
+
|
|
231
|
+
---
|
|
232
|
+
|
|
233
|
+
## ๐ License
|
|
234
|
+
|
|
235
|
+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
236
|
+
Copyright (c) 2026 magicclue.
|
|
237
|
+
|
|
238
|
+
See [CHANGELOG.md](CHANGELOG.md) for version history.
|
|
@@ -0,0 +1,210 @@
|
|
|
1
|
+
# TIDAL & Spotify Playlist Manager ๐ต๐ข
|
|
2
|
+
|
|
3
|
+
[](https://github.com/tas231/TidalPlaylist/releases)
|
|
4
|
+
[](LICENSE)
|
|
5
|
+
[](https://python.org)
|
|
6
|
+
[](https://fastapi.tiangolo.com)
|
|
7
|
+
[](https://github.com/tas231/TidalPlaylist)
|
|
8
|
+
|
|
9
|
+
A powerful, modern music playlist management application featuring a dual-pane **Web UI** and a comprehensive **CLI** for **TIDAL** and **Spotify**.
|
|
10
|
+
|
|
11
|
+
Manage in-platform playlists or transfer tracks across platforms in both directions (**TIDAL โ Spotify**) with smart ISRC track matching and zero build-step requirements!
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## โจ Features
|
|
16
|
+
|
|
17
|
+
- ๐ **Dual-Platform & Cross-Platform Transfers (TIDAL & Spotify)**:
|
|
18
|
+
- Independently toggle either **Panel A** or **Panel B** between **๐ต TIDAL** and **๐ข Spotify**.
|
|
19
|
+
- **In-Platform transfers**: TIDAL โ TIDAL, Spotify โ Spotify.
|
|
20
|
+
- **Cross-Platform transfers**: Transfer songs seamlessly from **TIDAL โ Spotify** or **Spotify โ TIDAL**!
|
|
21
|
+
- Supports both **Copy** (keep in source) and **Move** (remove from source after copying).
|
|
22
|
+
- **Smart ISRC Track Matching**: Automatically queries target catalogs by international standard ISRC (International Standard Recording Code) for 100% exact track matches, with intelligent fallback to normalized Title + Artist search.
|
|
23
|
+
- **Detailed Transfer Report**: Displays a clear summary dialog showing successfully transferred tracks and any tracks not found in the destination service.
|
|
24
|
+
- ๐ง **Read & Manage Playlists**: View personal playlists side-by-side, inspect tracklists, high-res album covers, explicit badges, track durations, and total running times.
|
|
25
|
+
- โ **Create & Rename**: Add new playlists with descriptions on TIDAL or Spotify, or rename existing ones in-place.
|
|
26
|
+
- ๐ **Copy & Move Tracks**: Copy or move selected tracks between playlists with multi-selection.
|
|
27
|
+
- ๐ฑ๏ธ **Drag & Drop (Cross-Panel & In-Playlist)**:
|
|
28
|
+
- **In-Playlist Reordering**: Reorder songs directly within any playlist by grabbing the grip handle (`โฎโฎ`) and dragging them up or down. A cyan indicator line shows the exact drop location, and the new sequence is instantly synced to the cloud!
|
|
29
|
+
- **Cross-Panel Transfers**: Drag tracks directly from Panel A to Panel B (or vice versa)โeven between TIDAL and Spotifyโto copy them, or hold <kbd>Alt</kbd> / <kbd>Shift</kbd> to move them.
|
|
30
|
+
- โก **Auto-Split Playlists (> 99 Tracks)**:
|
|
31
|
+
- Automatically splits any playlist with > 99 tracks into chunks of max 99 tracks (ideal for car head-units and audio gear with 99-track limits).
|
|
32
|
+
- Automatically names them with numerical suffixes: `[Name] 1`, `[Name] 2`, `[Name] 3`...
|
|
33
|
+
- Moves excess tracks seamlessly into the new suffix playlists.
|
|
34
|
+
- ๐ **Duplicate Finder & 1-Click Cleaner**:
|
|
35
|
+
- Scans for duplicate tracks by exact Media ID and normalized Title + Artist matching.
|
|
36
|
+
- Groups duplicate copies and provides a 1-click **Clean Duplicates** action (safely retaining the earliest added copy).
|
|
37
|
+
- ๐พ **Backup & Flexible Export / Import**:
|
|
38
|
+
- **Export**: Export playlists directly as **JSON** (full metadata), **CSV** (for spreadsheets and DJ tools), or **M3U8** (for media players).
|
|
39
|
+
- **Import**: Import playlists from JSON, CSV, or M3U files with flexible destinations:
|
|
40
|
+
- โจ Create as a brand-new playlist
|
|
41
|
+
- ๐ฅ Append imported tracks directly into the playlist active in **Panel A**
|
|
42
|
+
- ๐ฅ Append imported tracks directly into the playlist active in **Panel B**
|
|
43
|
+
- ๐ **Playlist Merge & Cloud Shuffle**:
|
|
44
|
+
- **Merge**: Combine multiple playlists into a unified master playlist (with optional automatic deduplication).
|
|
45
|
+
- **Cloud Shuffle**: Randomize track ordering permanently in the cloud.
|
|
46
|
+
- ๐ **Sorting & Ordering**:
|
|
47
|
+
- Sort tracks on-the-fly by Title, Artist, Album, or Duration in ascending or descending order.
|
|
48
|
+
- One-click **"Save Order"** button to permanently commit the sorted order to the cloud.
|
|
49
|
+
- ๐ง **Audio Preview Player**:
|
|
50
|
+
- 30-second audio preview button directly on every track's artwork thumbnail.
|
|
51
|
+
- Sticky bottom preview player bar with scrubber, duration counter, and a 1-click direct link to web players.
|
|
52
|
+
- ๐ **Integrated Catalog Search**:
|
|
53
|
+
- Global catalog search (<kbd>Cmd+K</kbd> / <kbd>Ctrl+K</kbd>) to discover tracks and add them directly to Panel A or Panel B with 1 click.
|
|
54
|
+
- ๐ **In-App Guide & Shortcuts Modal**:
|
|
55
|
+
- Built-in **Guide** button in the header bar with step-by-step feature walkthroughs and tips.
|
|
56
|
+
- ๐ **Privacy & Security First**:
|
|
57
|
+
- Connects using official OAuth authorization.
|
|
58
|
+
- No passwords or sensitive credentials are ever stored. Session tokens are stored locally and strictly excluded from git tracking.
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## ๐ Installation & Launch Options
|
|
63
|
+
|
|
64
|
+
Choose whichever method is easiest for you:
|
|
65
|
+
|
|
66
|
+
### ๐ฆ Option 1: Standalone Desktop App (No Python Required)
|
|
67
|
+
If you don't have Python installed and want a simple 1-click experience:
|
|
68
|
+
1. Head over to the **[Latest Releases](https://github.com/tas231/TidalPlaylist/releases)** page on GitHub.
|
|
69
|
+
2. Download the pre-built archive for your operating system:
|
|
70
|
+
- **Windows**: `TidalPlaylistManager-Windows-x64.zip` (extract and double-click `TidalPlaylistManager.exe`)
|
|
71
|
+
- **macOS**: `TidalPlaylistManager-macOS.zip` (extract and open `TidalPlaylistManager`)
|
|
72
|
+
- **Linux**: `TidalPlaylistManager-Linux-x64.tar.gz`
|
|
73
|
+
3. The app starts locally and immediately opens the Web UI in your default browser!
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
### ๐ Option 2: Install via pip / pipx (PyPI)
|
|
78
|
+
If you have Python 3.9+ installed:
|
|
79
|
+
```bash
|
|
80
|
+
# Install globally or in your environment:
|
|
81
|
+
pip install tidal-playlist-manager
|
|
82
|
+
|
|
83
|
+
# Or run instantly in an isolated environment with pipx:
|
|
84
|
+
pipx run tidal-playlist-manager
|
|
85
|
+
```
|
|
86
|
+
Then start the app anytime simply by typing:
|
|
87
|
+
```bash
|
|
88
|
+
tidal-manager
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
93
|
+
### ๐ป Option 3: Run from Git Source Checkout
|
|
94
|
+
|
|
95
|
+
#### Prerequisites
|
|
96
|
+
- **Python 3.9 or higher** ([python.org](https://www.python.org/downloads/)).
|
|
97
|
+
- *Windows users:* Make sure to check **"Add Python to PATH"** during setup.
|
|
98
|
+
- *Linux users (Ubuntu/Debian):* `sudo apt install python3 python3-venv python3-pip`.
|
|
99
|
+
|
|
100
|
+
#### Launching from source:
|
|
101
|
+
- **๐ macOS**: Double-click `Start.command` or `Tidal Playlist Manager.app` (or `./run.sh` in Terminal).
|
|
102
|
+
- **๐ช Windows**: Double-click `run.bat` in File Explorer.
|
|
103
|
+
- **๐ง Linux**: Run `chmod +x run.sh && ./run.sh` in Terminal.
|
|
104
|
+
|
|
105
|
+
---
|
|
106
|
+
|
|
107
|
+
### ๐ Connect your Accounts
|
|
108
|
+
|
|
109
|
+
#### 1. TIDAL (Primary)
|
|
110
|
+
1. Once started, your default browser opens at **`http://127.0.0.1:8000`**.
|
|
111
|
+
2. Click **Connect with TIDAL**.
|
|
112
|
+
3. Click the authorization link to approve the code in your browser (no password required).
|
|
113
|
+
4. Once approved, the manager will instantly load your TIDAL playlists!
|
|
114
|
+
|
|
115
|
+
#### 2. Spotify (Optional for Dual-Platform & Transfers)
|
|
116
|
+
1. In the top-right header, click **๐ข Connect Spotify** (or select the **๐ข Spotify** tab on Panel A or Panel B).
|
|
117
|
+
2. Enter your free Spotify Developer App credentials:
|
|
118
|
+
- Go to [Spotify Developer Dashboard](https://developer.spotify.com/dashboard) and create a free app.
|
|
119
|
+
- Set the Redirect URI to: `http://127.0.0.1:8000/api/spotify/callback`
|
|
120
|
+
- Paste your **Client ID** and **Client Secret**.
|
|
121
|
+
3. Click **Save & Authorize Spotify**. A popup window will prompt you to approve access.
|
|
122
|
+
4. Once connected, your Spotify account badge appears and you can select Spotify in either panel!
|
|
123
|
+
|
|
124
|
+
---
|
|
125
|
+
|
|
126
|
+
## ๐ User Guide (Web UI Walkthrough)
|
|
127
|
+
|
|
128
|
+
| Feature | How to Use |
|
|
129
|
+
|---|---|
|
|
130
|
+
| **Platform Switcher** | Use the `[ ๐ต TIDAL ]` and `[ ๐ข Spotify ]` tabs at the top of Panel A and Panel B to choose the music service for each side independently. |
|
|
131
|
+
| **Dual-Pane View** | Select a playlist in Dropdown A and Dropdown B to inspect and manage two playlists side-by-side. |
|
|
132
|
+
| **Cross-Platform Transfer** | Set Panel A to TIDAL and Panel B to Spotify (or vice-versa). Select songs and click `Copy โ` or `Move โ` (or drag & drop). Matches via ISRC standard with Title/Artist fallback and shows a detailed transfer report. |
|
|
133
|
+
| **In-Playlist Reordering (Drag & Drop)** | Grab any song by the grip handle (`โฎโฎ`) on the left and drag it up or down. A cyan indicator line shows the drop position. The new order is saved directly to your cloud playlist. |
|
|
134
|
+
| **Copy / Move Tracks** | Select tracks using checkboxes and click `Copy โ` or `Move โ`, or drag & drop songs directly between panels (hold <kbd>Alt</kbd> or <kbd>Shift</kbd> to move). |
|
|
135
|
+
| **Sort & Save Order** | Select a sort criteria like `Title (A-Z)` in the panel header. Click `Save Order` to commit this order permanently to your cloud playlist. |
|
|
136
|
+
| **Clean Duplicates** | Click `Duplicates` in the playlist header. Inspect grouped duplicate copies and click `Clean Duplicates` to remove redundant tracks safely. |
|
|
137
|
+
| **Backup & Export** | Click `Export`, select JSON, CSV, or M3U, and download your playlist backup. |
|
|
138
|
+
| **Import** | Click `Import` in the top bar, upload a backup file, and choose whether to create a new playlist or append tracks directly into Panel A or Panel B. |
|
|
139
|
+
| **Split Large Playlists** | Click `โก Split (>99)` to divide playlists with > 99 tracks into clean 99-track chunks (`... 1`, `... 2`). |
|
|
140
|
+
| **Catalog Search & Preview** | Press `Cmd+K` to search millions of tracks. Click any track cover artwork for an instant 30-second audio preview. |
|
|
141
|
+
|
|
142
|
+
---
|
|
143
|
+
|
|
144
|
+
## โจ๏ธ Keyboard Shortcuts
|
|
145
|
+
|
|
146
|
+
- <kbd>Cmd</kbd> + <kbd>K</kbd> / <kbd>Ctrl</kbd> + <kbd>K</kbd> : Open global catalog search
|
|
147
|
+
- <kbd>Esc</kbd> : Close active dialog or modal window
|
|
148
|
+
|
|
149
|
+
---
|
|
150
|
+
|
|
151
|
+
## ๐ ๏ธ CLI Reference
|
|
152
|
+
|
|
153
|
+
All features are also available directly via the command-line interface:
|
|
154
|
+
|
|
155
|
+
| Command | Description | Example |
|
|
156
|
+
|---|---|---|
|
|
157
|
+
| `web` | Start the Web UI server | `./run.sh web --port 8000` |
|
|
158
|
+
| `login` | Authenticate with TIDAL via OAuth | `./run.sh login` |
|
|
159
|
+
| `status` | Check authentication status | `./run.sh status` |
|
|
160
|
+
| `logout` | Log out and delete stored session | `./run.sh logout` |
|
|
161
|
+
| `list` | List all user playlists | `./run.sh list` |
|
|
162
|
+
| `show <pl>` | View tracks in a playlist | `./run.sh show "Chill Vibes"` |
|
|
163
|
+
| `create <title>` | Create a new playlist | `./run.sh create "Workout" -d "High energy"` |
|
|
164
|
+
| `rename <pl> <title>` | Rename an existing playlist | `./run.sh rename "Workout" "Gym Bangers"` |
|
|
165
|
+
| `delete-playlist <pl>` | Delete a playlist | `./run.sh delete-playlist "Old Mix" -y` |
|
|
166
|
+
| `copy` | Copy tracks between playlists | `./run.sh copy --from "Pop" --to "Best Of" --indices 0,1,2-5` |
|
|
167
|
+
| `move` | Move tracks between playlists | `./run.sh move --from "Inbox" --to "Favorites" --indices 0,3` |
|
|
168
|
+
| `split <pl>` | Auto-split playlist (>99 tracks) | `./run.sh split "Massive Library"` |
|
|
169
|
+
| `duplicates <pl>` | Check or clean duplicates | `./run.sh duplicates "My Mix" --clean` |
|
|
170
|
+
| `export <pl>` | Export playlist to file | `./run.sh export "Chill" -f csv` |
|
|
171
|
+
| `import <file>` | Import playlist from file | `./run.sh import "chill_backup.json"` |
|
|
172
|
+
| `merge` | Merge multiple playlists | `./run.sh merge --from "Rock,Indie" -t "Rock & Indie"` |
|
|
173
|
+
| `shuffle <pl>` | Shuffle tracks on TIDAL | `./run.sh shuffle "Party Mix"` |
|
|
174
|
+
| `search <query>` | Search TIDAL catalog | `./run.sh search "Daft Punk"` |
|
|
175
|
+
|
|
176
|
+
---
|
|
177
|
+
|
|
178
|
+
## ๐งช Running Tests
|
|
179
|
+
|
|
180
|
+
```bash
|
|
181
|
+
.venv/bin/python3 -m unittest discover -s tests
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
---
|
|
185
|
+
|
|
186
|
+
## โ ๏ธ Disclaimer & Limitation of Liability
|
|
187
|
+
|
|
188
|
+
This free software is provided **"as is"** and is intended strictly as a **testing and evaluation tool** for educational and personal experimentation:
|
|
189
|
+
|
|
190
|
+
- **No Liability or Responsibility:** The author(s) and contributor(s) accept **no liability or responsibility whatsoever** for any direct, indirect, incidental, or consequential damages, playlist modifications, unintended track removals, loss of data, account restrictions, or API disruptions arising from the use of or inability to use this software.
|
|
191
|
+
- **Testing Use Only:** This application is provided for testing and evaluation purposes. Always verify changes and use it entirely at your own discretion and risk.
|
|
192
|
+
- **Backups Strongly Recommended:** Before modifying, sorting, splitting, or deduplicating playlists, please use the built-in **Backup & Export** feature to create a local JSON, CSV, or M3U backup of your playlists.
|
|
193
|
+
- **Third-Party Services:** This project is an independent open-source tool and is not affiliated with, endorsed by, or sponsored by TIDAL, Aspiro AB, or Spotify AB.
|
|
194
|
+
|
|
195
|
+
---
|
|
196
|
+
|
|
197
|
+
## ๐ Project Status & Forking
|
|
198
|
+
|
|
199
|
+
This project is feature-complete for its intended scope and is provided as a finished utility. Active ongoing feature development or maintenance is not planned.
|
|
200
|
+
|
|
201
|
+
If you would like to customize, extend, or build upon this tool, you are very welcome to **fork, copy, or adapt the code** freely under the terms of the [MIT License](LICENSE).
|
|
202
|
+
|
|
203
|
+
---
|
|
204
|
+
|
|
205
|
+
## ๐ License
|
|
206
|
+
|
|
207
|
+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
208
|
+
Copyright (c) 2026 magicclue.
|
|
209
|
+
|
|
210
|
+
See [CHANGELOG.md](CHANGELOG.md) for version history.
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "tidal-playlist-manager"
|
|
3
|
+
version = "1.3.0"
|
|
4
|
+
description = "A modern TIDAL & Spotify Playlist Manager: Read, create, rename playlists, and move/copy tracks within and across TIDAL and Spotify with Web UI and CLI."
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
license = "MIT"
|
|
7
|
+
authors = [
|
|
8
|
+
{ name = "magicclue" }
|
|
9
|
+
]
|
|
10
|
+
keywords = ["tidal", "spotify", "playlist", "manager", "music", "fastapi", "transfer"]
|
|
11
|
+
classifiers = [
|
|
12
|
+
"Programming Language :: Python :: 3",
|
|
13
|
+
"Programming Language :: Python :: 3.9",
|
|
14
|
+
"Programming Language :: Python :: 3.10",
|
|
15
|
+
"Programming Language :: Python :: 3.11",
|
|
16
|
+
"Programming Language :: Python :: 3.12",
|
|
17
|
+
"Operating System :: OS Independent",
|
|
18
|
+
"Topic :: Multimedia :: Sound/Audio",
|
|
19
|
+
"Environment :: Web Environment",
|
|
20
|
+
]
|
|
21
|
+
requires-python = ">=3.9"
|
|
22
|
+
dependencies = [
|
|
23
|
+
"tidalapi>=0.8.11",
|
|
24
|
+
"fastapi>=0.110.0",
|
|
25
|
+
"uvicorn[standard]>=0.28.0",
|
|
26
|
+
"requests>=2.31.0",
|
|
27
|
+
"pydantic>=2.0.0",
|
|
28
|
+
]
|
|
29
|
+
|
|
30
|
+
[project.scripts]
|
|
31
|
+
tidal-manager = "tidal_manager.cli:main"
|
|
32
|
+
tidal-playlist-manager = "tidal_manager.cli:main"
|
|
33
|
+
|
|
34
|
+
[project.urls]
|
|
35
|
+
Homepage = "https://github.com/tas231/TidalPlaylist"
|
|
36
|
+
Repository = "https://github.com/tas231/TidalPlaylist.git"
|
|
37
|
+
Issues = "https://github.com/tas231/TidalPlaylist/issues"
|
|
38
|
+
|
|
39
|
+
[build-system]
|
|
40
|
+
requires = ["setuptools>=61.0"]
|
|
41
|
+
build-backend = "setuptools.build_meta"
|
|
42
|
+
|
|
43
|
+
[tool.setuptools.packages.find]
|
|
44
|
+
where = ["."]
|
|
45
|
+
include = ["tidal_manager*"]
|
|
46
|
+
|
|
47
|
+
[tool.setuptools.package-data]
|
|
48
|
+
tidal_manager = ["static/*", "static/**/*"]
|