Spotify Migration

Bring your Spotify playlists, liked songs, and listening data into Vynl. One-time migration — Vynl is not designed as an ongoing Spotify mirror.

Why this is migration-only, not integration

Vynl's identity is your library, your control. Spotify is the bridge that gets you off Spotify, not a place Vynl wants to live forever. After migration:

• Your matched tracks are in your local library
• Your unmatched tracks are in the Wishlist (you can buy/rip/download them on your own terms)
• You disconnect Spotify and Vynl never talks to it again

What gets imported

Spotify item	Imported to
Playlists	Vynl playlists (after you confirm which to migrate)
Liked Songs	Wish List + matched library tracks
Listening history	Used for matching, not stored long-term
Followed artists	Not yet (planned)
Podcasts	Not migrated — Vynl has its own podcast system

Quick start

1. Get Spotify API credentials

1. Go to https://developer.spotify.com/dashboard
2. Create app — any name, any description, no special permissions needed
3. Redirect URI: add http://localhost:3101/api/spotify/callback (or your Vynl URL if remote)
4. Copy the Client ID and Client Secret

2. Connect Spotify

Settings → API Keys → paste Spotify Client ID and Spotify Client Secret → Save.

Then: Settings → Spotify → Connect Spotify → log in → approve.

3. Run migration

Sidebar → Spotify Migration → Start sync.

The sync runs phases 1-5 (no destructive phase 6/7 — those existed in old Vynl versions and could overwrite playlists. Removed):

1. Fetch playlists
2. Fetch playlist tracks
3. Fetch liked songs
4. Fetch audio features (BPM, energy, etc.)
5. Match against your local library (by ISRC, then fuzzy title+artist)

You'll end up with a table of every Spotify track, marked Matched (in your library) or Missing.

4. Triage

For matched tracks: nothing to do — they're already in Vynl.

For missing tracks: pick a subset, then:

• Add to Wishlist — kept in the wishlist for future download
• Download via spotDL — uses the bundled spotDL + yt-dlp to source from YouTube (legality varies by jurisdiction; see legal note)
• Push to Lidarr — if you have Lidarr connected, sends the artist for monitoring + grab

5. Mirror selected playlists

For each Spotify playlist, click Mirror to Vynl playlist to create a Vynl playlist with the matched tracks. Unmatched tracks are excluded (they'll come back automatically when downloaded).

6. Disconnect

When you're done: Settings → Spotify → Disconnect & wipe. This:

• Revokes the Spotify auth token
• Deletes all spotify_* tables (playlists, tracks, snapshots)
• Removes Wish List rows marked type='spotify_missing' (your manually-added wishlist items stay)
• Removes the Spotify Migration sidebar entry

Vynl never talks to Spotify again.

Legality

Downloading audio from YouTube via spotDL/yt-dlp is jurisdiction-dependent. In short:

• Personal use, never shared: low practical risk, technically infringement in most places
• Distributing the downloaded files: copyright infringement
• See your library = your responsibility

Troubleshooting

Issue	Fix
OAuth callback errors	Redirect URI in your Spotify Developer dashboard must match Vynl's URL exactly (no trailing slash)
Many tracks unmatched	Run Library Doctor → Metadata Enrichment first to fill in missing ISRCs
spotDL says "0 results"	spotDL needs yt-dlp installed; it's bundled in Vynl 0.6.25+. Older versions: docker exec vynl pip install yt-dlp
Sync stuck on "phase 4 — audio features"	Spotify rate limit. Wait 60s, click resume

Related

• AI Discovery — once your library has the migrated tracks, AI can play with them
• Wishlist — what to do with the unmatched tracks