# SoundBridge setup

SoundBridge is 100% client side. There is no server and no shared API key,
so you create two free developer apps of your own (one on Spotify, one on
Tidal) and paste each app's Client ID into the page. Both are free, both take
a few minutes, and neither needs approval to start.

The app needs no client secret. It uses OAuth authorization-code flow with
PKCE, which is the public-client flow both services support in browsers.

## Redirect URI (register this on both apps)

```
https://anubhavjindal.com/apps/soundbridge/
```

The redirect URI must match exactly, including the trailing slash. If you test
locally first, also register:

```
http://localhost:8901/apps/soundbridge/
```

(The local port is whatever you serve pages-root on. The app builds its
redirect URI from the page address, so it works on any registered origin.)

## 1. Spotify developer app

1. Go to https://developer.spotify.com/dashboard and sign in with your Spotify
   account.
2. Click **Create app**.
3. App name: `SoundBridge (personal)`. App description: anything, for
   example `Personal playlist transfer tool`.
4. Redirect URIs: add `https://anubhavjindal.com/apps/soundbridge/` (and
   the localhost one above if you want to test locally). Click **Add**, then
   **Save**.
5. On the app's Settings page, copy the **Client ID**. You do not need the
   Client Secret.
6. Paste the Client ID into the Spotify card on the SoundBridge page.

Notes:

- Spotify does not ask you to tick scopes in the dashboard. The app requests
  them at sign-in: `user-library-read` (Liked Songs) and
  `playlist-read-private` (your playlists). Phase 1 only reads from Spotify.
- The app stays in Development Mode, which is fine for personal use. No quota
  extension is needed.
- Your Spotify account must be the one that owns the playlists you want to
  move.

## 2. Tidal developer app

1. Go to https://developer.tidal.com/dashboard and sign in with your Tidal
   account. (If you do not have one yet, start the free trial first; Tidal
   offers a 30-day trial.)
2. Click **Create app**.
3. Name it `SoundBridge (personal)`.
4. Redirect URIs: add `https://anubhavjindal.com/apps/soundbridge/` (and
   the localhost one above if you want to test locally).
5. Tick these scopes: `user.read`, `search.read`, `playlists.read`,
   `playlists.write`. If the dashboard also lists the older `r_usr` and
   `w_usr` scopes, tick those too; they are harmless.
6. Copy the **Client ID** and paste it into the Tidal card on the Playlist
   Porter page.

Notes:

- New Tidal apps run in quota-limited dev mode. The app batches its requests
  and backs off whenever Tidal answers 429, and a transfer can be resumed
  after any pause, so a quota limit only slows a large transfer down.
- The app creates playlists as **Unlisted** by default. You can switch to
  Public on the transfer step. Tidal does not accept Private on create.
- Country: the app matches tracks in the US catalog by default. Change the
  country code on the Tidal card if your account is in another country.

## 3. Run a transfer

1. Connect Spotify, then connect Tidal (each opens that service's sign-in in
   this tab and comes back here).
2. Pick a source: Liked Songs, one or more playlists, or both. Load tracks.
3. Start matching. Each track is matched by ISRC first (the exact recording),
   then by title and artist search with scoring. Anything uncertain waits for
   your pick in the report; nothing is guessed silently.
4. Review the report, pick the right version for any ambiguous track, then
   press Transfer. Playlists are created on Tidal with the same names, and
   tracks are added in batches. Progress is saved after every batch, so you
   can close the tab and resume later from the saved job.

## Privacy

- Client IDs live in this browser's localStorage, and only in this browser.
- Sign-in tokens live in session storage, so they disappear when the tab
  closes.
- The transfer job (track list, matches, progress) lives in localStorage so
  it can resume. Use **Clear all saved data** on the page to wipe everything.
- No data goes to any server of ours. Your browser talks directly to Spotify
  and Tidal.

## Troubleshooting

- **redirect_uri_mismatch**: the redirect URI registered in the developer
  dashboard does not exactly match the page address. Check the trailing
  slash, and check you added the URI to the right app.
- **invalid_scope**: the Tidal app is missing one of the four scopes listed
  above. Tick them in the Tidal dashboard and try again.
- **A 429 or "rate limited" message**: the service asked the app to slow
  down. The app backs off automatically. If a run stops, just press the same
  button again; matched tracks are not re-matched and added tracks are not
  re-added.
- **A track is not found**: it may not be in the destination catalog for your
  country, or it may be listed under a different title. Check the Not found
  list after matching; you can search for those few by hand in the Tidal app.
- **Sign-in state was lost**: the tab was reloaded or closed during sign-in.
  Press Connect again.

## Terms note

This is a personal, non-commercial tool for moving your own library between
your own accounts. Tidal's developer guidelines restrict combining Tidal
content with another service's content without written approval, and restrict
commercial use and redistribution. This app moves your Spotify list into your
own Tidal account, keeps everything in your browser, and is not a public
service. Keep it that way.
