Music Teleportation 🎵

Transfer your music playlists seamlessly between Spotify, Apple Music, and Tidal.

🚀 Quick Start

Prerequisites

• Python 3.9 or higher
• pip (Python package manager)
• API Credentials from Spotify, Apple Music, and/or Tidal (see SETUP_GUIDE.md)

Installation

1. Download or clone this repository

2. Run the automated setup script:

   chmod +x setup.sh
   ./setup.sh

3. Configure your API credentials:

   • Copy .env.example to .env
   • Fill in your API keys (see SETUP_GUIDE.md for detailed instructions)

4. Start the application:

   python3 START_APP.py

5. Open your browser to the URL shown in the terminal (usually http://127.0.0.1:5010)

---

✨ Features

• ✅ Multi-Platform Support - Transfer between Spotify, Apple Music, and Tidal
• ✅ Smart Track Matching - Uses fuzzy matching to find the best track matches across platforms
• ✅ Custom Playlist Import - Import Spotify playlists by URL, including Daily Mix and personalized playlists
• ✅ Real-Time Progress - Live updates during transfer operations
• ✅ Local & Network Access - Run on your machine or share on your local network
• ✅ Session Management - Your credentials and progress are securely stored in sessions
• ✅ Detailed Reports - CSV/JSON export of match results
• ✅ Duplicate Detection - Automatically skips existing playlists

---

📋 What You'll Need

Required

• Python 3.9+ (Download here)
• Spotify Account + API credentials
• Apple Music or Tidal subscription

Getting API Credentials

See SETUP_GUIDE.md for detailed step-by-step instructions on obtaining:

Spotify

• Client ID and Client Secret from Spotify Developer Dashboard
• Redirect URI: http://127.0.0.1:5010/spotify/callback

Apple Music

• Team ID, Key ID, and Private Key (.p8 file) from Apple Developer

Tidal

• OAuth login (handled by the app)

---

🎯 How It Works

First-Time Setup

1. Launch the app with python3 START_APP.py
2. Browser opens automatically to http://127.0.0.1:5010
3. Enter API credentials on the configuration page
4. Connect your accounts - Spotify, Apple Music, or Tidal
5. Start transferring! 🎉

Transferring Music

1. Select playlists to transfer from your Spotify library
2. Choose destination - Apple Music or Tidal
3. Click Transfer - Watch the progress in real-time
4. View results - Success/failure status for each track

Custom Playlist Import

Can't find a playlist? Import it by URL:

1. Click "Import Custom Playlist" on the homepage
2. Paste a Spotify playlist URL (works with Daily Mix, Discover Weekly, friend's playlists, etc.)
3. Preview the playlist details
4. Add it to your transfer list

---

📊 What Can Be Transferred

Content Type	Spotify → Apple Music	Spotify → Tidal
Playlists	✅ Yes	✅ Yes
Custom Playlists (by URL)	✅ Yes	✅ Yes
Daily Mix	✅ Yes	✅ Yes
Personalized Playlists	✅ Yes	✅ Yes

---

🔍 Matching Algorithm

The app uses RapidFuzz for fuzzy string matching to find the best track matches across platforms:

• Title similarity - Handles variations in track names
• Artist similarity - Matches different artist name formats
• Album matching - Normalizes remaster labels and special editions

What Gets Normalized

• Remaster labels removed (e.g., "2009 Remaster")
• Featuring artists handled (e.g., "feat.", "ft.")
• Special characters stripped
• Case-insensitive comparison

---

🛠️ Troubleshooting

Port Already in Use

# Find and kill processes on port 5010
lsof -ti:5010 | xargs kill -9

Spotify OAuth "Can't Connect" Error on Network Devices

This is expected behavior. The authorization completes successfully on the server. Just navigate back to your network URL (e.g., http://192.168.x.x:5010) after seeing this error.

Apple Music User Token

If you need to generate an Apple Music User Token manually, visit http://127.0.0.1:5010/apple/user-token in your browser.

Missing Dependencies

source .venv/bin/activate
pip install -r requirements.txt

Python Not Found (Windows)

Install Python from python.org and check "Add Python to PATH" during installation.

---

📁 Project Structure

Music_teleportation/
├── app.py                    # Main Flask application
├── transfer.py               # Transfer logic and API clients
├── tidal_client.py          # Tidal API integration
├── START_APP.py             # Launcher script
├── setup.sh                 # Automated setup script
├── requirements.txt         # Python dependencies
├── .env.example             # Environment template
├── templates/               # HTML templates
│   ├── index.html          # Main UI
│   └── apple_user_token.html  # Apple Music token helper
├── static/                  # CSS and assets
│   └── style.css           # Application styles
└── .flask_session/         # Session storage (auto-created)

---

⚙️ Network Access

To share the app on your local network:

1. Start the app with python3 START_APP.py (or python app.py --host 0.0.0.0 --port 5010)
2. The startup banner will show your network URL (e.g., http://192.168.X.XXX:5010)
3. Other devices on your network can access this URL

Important for Spotify OAuth: Always use http://127.0.0.1:5010/spotify/callback as your redirect URI in the Spotify Dashboard, even for network access. See SETUP_GUIDE.md for details.

---

🔒 Security Notes

• ✅ Local Only - All processing happens on your device
• ✅ No Data Collection - Your credentials stay on your machine
• ✅ Direct API Communication - No third-party servers
• ⚠️ Never commit .env file - it contains your API credentials
• ⚠️ Keep your API keys private - don't share them
• ⚠️ Local network only - this app is designed for local/network use, not public internet

Where Data Is Stored

• Sessions: .flask_session/ (temporary)
• Credentials: Session storage and .env file (not shared)

---

🔧 Manual Installation (Alternative)

If the automated setup script doesn't work:

# Create virtual environment
python3 -m venv .venv

# Activate virtual environment
# On macOS/Linux:
source .venv/bin/activate
# On Windows:
.venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Copy environment template
cp .env.example .env

# Edit .env with your API credentials
nano .env  # or use your preferred editor

# Run the app
python app.py

---

📊 Technical Details

• Framework: Flask 3.0.3
• Session Storage: Filesystem-based sessions
• Track Matching: RapidFuzz for fuzzy string matching
• Web Scraping: BeautifulSoup4 for blocked playlists
• Real-Time Updates: Server-Sent Events (SSE)
• Python Version: 3.9+

---

🤝 Contributing

This is a personal project, but feel free to fork and customize for your needs!

---

📄 License

This project is provided as-is for personal use.

---

Built with ❤️ for music lovers who hate platform lock-in.