Match streaming playlists against your local DJ library and create playlists in your DJ software — with cues, loops, and all metadata intact.
You're a DJ. A client sends you a Spotify playlist with 50 song requests for their event. You need to:
- Figure out which songs you already have
- Find them in your library across thousands of tracks
- Create a playlist in your DJ software
- Download only the songs you're missing
Without this tool, you'd manually search each song, accidentally download duplicates, and lose your carefully set cue points and loops on re-downloaded tracks.
setlist-sync "https://open.spotify.com/playlist/..." --playlist-name "Wedding Jan & An"
In under a second, setlist-sync:
- Fetches the playlist from Spotify (no API key or Premium needed)
- Fuzzy-matches every track against your DJ library (4800+ tracks in 0.4s)
- Creates a playlist in your DJ software with your existing tracks — cues, loops, BPM, and all metadata preserved
- Reports which tracks you're missing so you only download what you need
Note
setlist-sync is not a music downloader. It does not download songs from Spotify or any other service. It matches tracks you already own in your DJ library against a streaming playlist, so you can quickly build a setlist from your existing collection.
- Spotify URL input — paste any public playlist link, no API key required
- CSV input — also accepts CSV files (e.g. from Exportify)
- Fuzzy matching — handles spelling differences, remix tags, featured artists, etc.
- DJ software integration — writes playlists directly to djay Pro and Rekordbox
- File-based output — alternatively copies matched files to an event folder with M3U playlist
- Smart normalization — strips
(feat. ...),(Remastered),- Radio Editetc. before matching - Fast — matches 50 tracks against 5000 in under a second using rapidfuzz
pip install setlist-syncRequires Python 3.10+.
Python is not pre-installed on Windows. To install it:
- Open a terminal and run
winget install Python.Python.3.13(or download from python.org) - Important: During install, check "Add Python to PATH"
- Restart your terminal, then run
pip install setlist-sync
If setlist-sync is not recognized as a command, use:
python -m setlist_sync init
python -m setlist_sync "https://open.spotify.com/playlist/..."git clone https://github.com/mathiassp/setlist-sync.git
cd setlist-sync
python -m venv venv
source venv/bin/activate
pip install -e .setlist-sync initThis walks you through choosing your DJ software (djay Pro or Rekordbox), finding your database, and setting preferences. Configuration is saved to .env.
setlist-sync "https://open.spotify.com/playlist/..."That's it. setlist-sync reads your DJ software from .env and creates the playlist directly in its database.
Warning
Close your DJ software before running — setlist-sync writes directly to the database.
setlist-sync "https://open.spotify.com/playlist/..." --playlist-name "Wedding Jan & An"If your .env is set to Rekordbox, it works automatically. Or override with a flag:
setlist-sync "https://open.spotify.com/playlist/..." --rekordboxCopies matched files to an output folder with an M3U playlist.
setlist-sync "https://open.spotify.com/playlist/..." --filessetlist-sync playlist.csv --playlist-name "Birthday Party"Tip
Use --dry-run to preview matches without writing anything.
| Flag | Description |
|---|---|
--playlist-name |
Name for the created playlist (default: Spotify playlist name) |
--rekordbox [XML] |
Use Rekordbox instead of djay. Without path: reads database directly. With path: uses XML file |
--files |
Copy matched files to an output folder with M3U playlist |
--threshold |
Match sensitivity 0-100 (default: 85) |
--dry-run |
Show what would happen without writing |
--handle-duplicates |
Interactively choose between multiple library matches per track |
--djay-db PATH |
Custom path to djay Pro database (default: ~/Music/djay/djay Media Library.djayMediaLibrary/MediaLibrary.db) |
--rekordbox-output |
Output path for Rekordbox XML mode (default: {input}_synced.xml) |
--music-dir |
Music folder path for --files mode (default: ~/Music) |
--symlink |
Use symlinks instead of copies in --files mode |
Spotify URL / CSV ─→ spotify_client ─→ Track list (title + artist)
│
┌─────────────────────────────┤
│ │ │
djay database │ Rekordbox │ ~/Music │
(macOS only) │ database │ folder │
djay/library │ rekordbox/ │ library_ │
│ library │ scanner │
└──────┬───────┘ │
│ │
matcher (fuzzy match) ◄─────┘
│
┌────────────┼──────────────┐
│ │ │
djay/playlist rekordbox/ output
(djay Pro DB) playlist ├── playlist.m3u
(DB or XML) ├── unmatched.txt
└── match_report.csv
Uses rapidfuzz for fuzzy string matching with weighted scoring:
- Title similarity: 60% weight
- Artist similarity: 40% weight
- Normalizes strings before matching: strips remix/edit tags, featured artists, punctuation
Writes directly to your DJ software's database. For djay Pro, this uses a clone-based approach to handle the proprietary TSAF format. For Rekordbox, it uses pyrekordbox to access the encrypted database. A backup is automatically created before every write.
| Software | Versions | Platform | Read Library | Write Playlists | Status |
|---|---|---|---|---|---|
| djay Pro | 5.x | macOS | Yes | Yes | Supported |
| Rekordbox | 6.x / 7.x | macOS, Windows | Yes | Yes | Supported |
| Serato DJ | — | — | — | — | Coming soon |
| Traktor | — | — | — | — | Coming soon |
Note: setlist-sync was developed and tested with djay Pro 5 and Rekordbox 7. Older versions may work but have not been tested. If you try it with a different version, please open an issue and let us know how it went!
- Spotify — public playlist URLs (no account needed)
- CSV — any CSV with track name and artist columns
- Tidal
- Apple Music
- YouTube Music
- djay playlist names are limited to ~40 characters (depends on your longest existing playlist name). Names that exceed the limit are truncated with a warning.
- Your DJ software must be closed when writing playlists
- djay Pro integration is macOS only; Rekordbox works on macOS and Windows
- Matching accuracy depends on how tracks are tagged in your library
- djay integration uses a reverse-engineered database format — a backup is automatically created before every write
Issues and PRs welcome. If you use different DJ software and want to add support, open an issue to discuss the approach.
MIT
If this saved you time, consider giving it a star.