See it work
How it works
-
Scan
Pick a playlist you own. A window lists its broken tracks and its local files, and says why each one is a problem.
-
Review matches, grouped by confidence
Choose Find fixes. The app says how many requests that will take before it sends any, then searches for a playable version of each track, starting with the recording's ISRC. Each match lands in one of four groups:
- Exact
- Same ISRC, duration within 2 seconds, same explicit flag. Ticked for you.
- High
- A strong score with a close duration, and the same version and explicit flag. Ticked for you.
- Review
- A fair match, or one held back because the version or explicit flag differs. A live or remix version never reaches the ticked groups for a studio original. Not ticked.
- None
- Nothing scores well enough. The track is left in place.
-
Approve in bulk
Each row shows the broken track beside its proposed replacement, with the differences marked. Tick a whole group or single rows, and pick a different candidate where the first is wrong.
-
Apply
Only now does anything change. The app backs up the playlist, inserts the replacements, removes the broken tracks, and checks the result.
Why it’s safe
-
Nothing changes without your approval
A playlist is only written to after you approve on the review screen.
-
A backup comes first
A JSON file of the playlist as scanned (position, URI, title, artists, album, date added) is downloaded before any change. It is on by default and the file never leaves your computer.
-
Inserts before removals
Replacements go in before any broken track comes out, so a failure leaves extra tracks and never missing ones. After an error, Resume carries on where it stopped.
-
A verifying rescan
The app reads the playlist again and checks that each broken track is gone and each replacement is in place. It lists any difference.
-
Nothing leaves your browser except calls to Spotify
There is no backend. A Content Security Policy limits network requests to
accounts.spotify.comandapi.spotify.com, and there is no analytics, font host, CDN or error reporting. Login uses PKCE, so there is no client secret. Tokens stay insessionStorageand are gone when the tab closes.
One thing does change: replacements get today’s date as their “date added”. The backup file keeps the original dates.
Local files
Playlist Repair can replace local files with streaming versions, with limits:
- It does so only when you tick Include local files for that playlist.
- A local file has only its tags to go on, with no ISRC. Its match can reach High at best, never Exact, and is never ticked for you. You tick them one by one or with “select all” for the group.
- Spotify’s API cannot add a local file back, and removing one by its URI does not work. A local file leaves a playlist only through a replace-all, which the app uses only when every local file in the playlist is being replaced or removed and the result has 100 tracks or fewer.
- Otherwise the replacement is still inserted, the local file stays, and the final screen lists the files for you to delete by hand, and says why.
Get started
Playlist Repair runs locally today. A hosted version isn’t available.
Spotify’s development mode allows at most 5 users per app and needs Premium for the owner, so one shared client ID cannot serve everyone. Each person creates their own Spotify app and pastes in its client ID, which is not a secret. Only playlists you own are listed.
- Follow the setup guide to create a Spotify app and copy its client ID. It takes about five minutes and is done once.
-
Get the code from
GitHub. You need Node.js 24
or later. Then run:
npm install npm run dev -
Open
http://127.0.0.1:5173/, notlocalhost, paste the client ID, and log in.
The README has the full run steps.