Connecting Spotify to Tune

Spotify does not hand out a ready-made key to Tune: you create a small Spotify app of your own, free, and give its Client ID to Tune. This page walks through the whole path, including the step that surprises everyone when Tune runs on another machine: a page that "does not load". It is expected, and the fix takes ten seconds.

What you need

A Spotify account to create the app. Spotify's rules for apps in development mode may require a Premium account for the app's owner. Playing Spotify tracks through Tune also requires Premium (see the Spotify section of Streaming services).
Tune version 1.0.0-rc2 or later, where the Client ID is entered in the interface.
The address of your Tune server, as you open it in the browser.

How it works, in two sentences

Spotify, once you have signed in, sends your browser back to a redirect address that Tune gave it: http://127.0.0.1:8888/api/v1/streaming/spotify/callback?code=… (8888 is Tune's default port; if you changed it, the port shown by Tune is the right one). The 127.0.0.1 address always means "this very computer": it works only if the browser and Tune are on the same machine.

If Tune runs elsewhere (NAS, Docker, Raspberry Pi, Tune OS), the browser looks for Tune on itself, finds nothing and shows a blank or "invalid webpage" page. This is not a bug. The address in the address bar still contains the code that Spotify issued: you copy it and paste it into Tune.

Step by step

Open the Spotify card in Tune. Go to Settings › Access and tokens › Streaming Services and find Spotify. If the server has no Client ID yet, the card shows the field Your Spotify app’s Client ID. Below it, the line Redirect URI to declare, exactly as shown, in your Spotify app (developer dashboard) gives you the address to copy in step 3.
Create the app at Spotify. Click Open the Spotify dashboard (or go to developer.spotify.com/dashboard), sign in with your Spotify account, then click Create app. Fill in an App name (for instance "Tune") and an App description (for instance "Tune music server"). Tick the Web API option if Spotify asks which APIs you plan to use, and accept Spotify's Developer Terms of Service.
Declare the redirect address. In the Redirect URIs field, paste the address Tune shows you, exactly as shown, then click Add and Save. It looks like http://127.0.0.1:8888/api/v1/streaming/spotify/callback. Not localhost, not the IP address of your server (see "Common errors").
Add yourself to the app's users. A new Spotify app starts in development mode: only the users you list can use it. In the app's page, open User Management and add your Spotify name and the e-mail address of your Spotify account. Without this step, the sign-in fails, or Spotify answers with errors later on.
Copy the Client ID. On the app's page, open Settings (Basic Information): the Client ID is a 32-character string. Copy it. You never need the Client Secret: Tune does not use it.
Paste it in Tune. In the Spotify card, paste it into Your Spotify app’s Client ID and click Save. The message "Client ID saved: you can now sign in" appears.
Sign in. Click Sign in, then Open the sign-in page. Spotify asks you to authorize the app: accept.
Tune on the same computer as the browser: the page that opens shows a short line of text (authenticated: true and your name), and the card reads connected with your name. You are done.
Tune on another machine: the page that opens does not load ("invalid webpage", "this site can't be reached", blank page): that is normal. Copy the full address from the address bar: it starts with http://127.0.0.1: and contains ?code= followed by a long string. Come back to Tune: under the sign-in link, a field appears whose text begins "Tune runs on another machine…". Paste the address there and click Submit. The card reads connected.

With Safari, the address bar shows only the host name until you click it: click it, then copy. Do not wait too long between authorizing and pasting, and do not reload the page: the code works once.

From a phone or tablet, Tune also serves a plain page that does the same thing without the Tune interface: http://<server address>:8888/api/v1/streaming/spotify/connect. It shows the link to Spotify and a field to paste the address.

Common errors

What you see	Cause and fix
The page after sign-in does not load ("invalid webpage")	Normal when Tune is on another machine. Copy the full address and paste it into Tune (step 8).
Spotify says redirect_uri: Insecure, or "Spotify rejects this URI" under the card	Spotify accepts `http://` only for `127.0.0.1`. An address such as `http://192.168.1.20:8888/…` or a host name is refused. Declare `http://127.0.0.1:<port>/api/v1/streaming/spotify/callback`, or an HTTPS address.
`localhost` refused	Spotify no longer accepts `localhost`. Write `127.0.0.1`.
INVALID_CLIENT: Invalid redirect URI on Spotify's page, or redirect_uri mismatch	The address declared in the dashboard is not identical to the one Tune sends. Compare character by character (port, path, no trailing slash) with the one shown by Tune in the card, and save in the dashboard.
"The pasted address contains no code"	You pasted the redirect address without `?code=…`, or the page of the dashboard. Paste the full address of the page opened after you authorized.
"This is a Client ID, not the return address"	You pasted the Client ID (32 characters) in the return-address field. The Client ID goes in the first field; paste the long address starting with `http://127.0.0.1` here.
"This return address comes from another sign-in attempt", or "no sign-in in progress"	The server restarted, or you started another sign-in since. Click Sign in again and use the new address. A code works only once.
Authorization denied by Spotify (`access_denied`), or sign-in fails with your account	You clicked "Cancel" at Spotify, or your account is not in the app's User Management (step 4): add the e-mail address of your Spotify account.
No Client ID on this server	Enter it as in step 6. If the field is not offered, a `TUNE_SPOTIFY_CLIENT_ID` variable is already set on the server, and it takes precedence.

Changing the port or the account

If you change Tune's port (TUNE_PORT), the redirect address changes with it: declare the new one in the dashboard and sign in again.
To use another Spotify account, sign out in the Spotify card then sign in again. To change the Client ID, use Change or Clear next to it.

See also: Streaming services and Troubleshooting.