Skip to main content

Spotify integration for Gladys Assistant

Spotify integration for Gladys Assistant

Control your Spotify Connect devices (play, pause, next, previous, volume) from Gladys.

View on GitHubAll external integrations

This integration lets you control your Spotify Connect devices from Gladys Assistant: play, pause, previous / next track and volume.

Features​

  • Spotify Connect devices: every speaker, phone or computer connected to your Spotify account appears as a Gladys device.
  • Playback control: play, pause, previous, next.
  • Volume: set the volume of the active device.
  • Playback state: Gladys reflects in real time whether a device is playing or paused.
  • Actions: test the connection and disconnect, directly from the configuration screen.

Requirements​

  • A Spotify Premium account (required: the Spotify API does not allow controlling playback with a free account).
  • A Spotify application created on the developer dashboard (free), to get a Client ID and a Client Secret.

Create your Spotify application​

  1. Go to the Spotify Developer Dashboard and sign in.
  2. Click Create app.
  3. Give it a name and a description (for example "Gladys").
  4. In Redirect URIs, enter https://my.gladysassistant.com/redirect/oauth (see "The redirect address" below), then click Add.
  5. Tick the Web API, then save (Save).
  6. Open the app Settings: copy the Client ID, and reveal and copy the Client Secret.

The redirect address (Redirect URI)​

Spotify only agrees to send you back to Gladys if the redirect address is declared beforehand in your application, and it must be identical character for character to the one Gladys uses.

Since April 2025, Spotify also requires that address to be HTTPS (or on the 127.0.0.1 loopback address). An address such as http://192.168.1.50:1444/... is therefore always rejected — which covers most self-hosted installations.

Gladys solves this with an HTTPS redirect page shared by every instance. The address to declare in Spotify is therefore fixed, and the same for everyone:

https://my.gladysassistant.com/redirect/oauth

Copy it as is into the Redirect URIs field of your Spotify application, then Add and Save. The integration configuration screen also displays it, with a copy button.

ℹ️ This address depends neither on your port, nor on your IP address, nor on the integration selector: the same value works whether you reach Gladys locally or through Gladys Plus. You no longer have to update it when your installation changes.

How it works​

After you authorize, Spotify sends your browser back to that HTTPS page. The page reads your Gladys address — carried in the state parameter, the only one an OAuth provider hands back untouched — and bounces you to your instance, whatever it is, including over plain HTTP on your local network.

This is the same approach as my.home-assistant.io for Home Assistant.

On privacy, to be precise: the page is static, nothing runs server-side and nothing is stored. The authorization code does however appear in the address requested on a Gladys-operated domain; that code alone is useless, since exchanging it for tokens requires your Client Secret, which never leaves your installation. Tokens themselves transit neither through the redirect page nor through the Gladys frontend.

ℹ️ If you already reach Gladys over HTTPS, the configuration screen offers an advanced option to use your own instance address instead of the redirect page. You then have to declare that address in Spotify.

Connection​

  1. Open the Spotify integration configuration screen in Gladys.
  2. Paste your Client ID and Client Secret, then save.
  3. Click "Connect with Spotify": you are redirected to Spotify to authorize Gladys.
  4. After authorizing, you go through the redirect page, which sends you back to your Gladys automatically.
  5. The connection is established and your Spotify Connect devices become available for discovery.

This works whichever way you reach Gladys: locally by its IP address, from the machine itself, or through Gladys Plus.

Access tokens are stored and refreshed automatically: you only need to connect once.

If the automatic return fails​

This should no longer happen, but the integration keeps a fallback method — for instance if the redirect page is unreachable, or on a Gladys version older than the one that introduced it.

If, on the way back from Spotify, your browser shows an error page ("this site can't be reached", "connection refused"…) instead of returning to Gladys: the authorization did go through, and the connection code is in the address shown.

  1. In the address bar of the error page, select and copy the full address. It looks like:

    http://192.168.1.50:1444/dashboard/integration/device/external/ext-spotify/oauth-callback?code=AQD...&state=8f2c...

  2. Go back to Gladys, to the Spotify integration configuration screen.

  3. Paste that address into the Returned address field (section "Browser could not return to Gladys?"), then save.

  4. Click the "Finish the connection" button.

  5. The confirmation message appears: the connection is established and your devices become available for discovery. The field clears itself, since the code is single-use.

⚠️ The code in that address is single-use and expires after a few minutes. If it fails, simply click "Connect with Spotify" again and retry with the new address.

Device discovery​

Only devices currently online (Spotify app open, speaker awake and connected) are returned by the Spotify API. If a device does not appear, open Spotify on it and run discovery again.

Troubleshooting​

  • Spotify shows "redirect_uri: Not matching configuration" (or does not show the authorization screen): the address declared in your Spotify application does not exactly match the one Gladys uses. Check that the Redirect URIs field contains https://my.gladysassistant.com/redirect/oauth, with no trailing slash, and that you clicked Add then Save. If you enabled the "instance address" option, that is the address to declare instead.
  • "Connection refused" or "site can't be reached" when returning from Spotify: the automatic return did not complete. Copy the address of the error page and use the "Finish the connection" action (see "If the automatic return fails").
  • "Spotify OAuth state mismatch": the address you pasted comes from an earlier authorization request. Keep only one authorization tab open at a time (each click generates a new request, only the last one is valid), then start over.
  • "This URL carries no authorization code": you most likely copied the address after reloading the error page, which dropped the query parameters. Click "Connect with Spotify" again and copy the address without reloading the page.
  • The code expired (invalid_grant error when finishing the connection): the code is valid for a few minutes and single-use. Click "Connect with Spotify" again.

Limitations​

  • A Premium account is mandatory for any playback command. Without it, Spotify returns a PREMIUM_REQUIRED error.
  • Only devices online at discovery time are listed.
  • Control covers Spotify Connect playback; it does not start a specific playlist or track (transport control only: play, pause, previous, next, volume).

Configuration settings​

These are the settings Spotify asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
Connect your Spotify accountsectionNoThis integration controls your Spotify Connect devices through the Spotify Web API. A Spotify Premium account is required to control playback. First create a free Spotify application, declare the redirect URI shown below in it, paste its Client ID and Client Secret here, then click "Connect with Spotify".
Client IDstringYes
Client SecretsecretYes
Connect with Spotifyoauth2NoOnce the Client ID and Client Secret are saved, click Connect to authorize Gladys on your Spotify account.
Browser could not return to Gladys?sectionNoThe return from Spotify is normally automatic. If your browser lands on a blank or error page instead of coming back to Gladys, the authorization did still succeed: copy the full address from your browser address bar, paste it below, save, then click "Finish the connection".
Returned addressstringNo

How to install Spotify in Gladys​

  1. In Gladys, open Integrations: Spotify appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/william-de71/gladys-spotify:1.0.1), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/William-De71/gladys-spotify.

Spotify requires Gladys >=4.84.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.

Not running Gladys yet? It is free and open source: follow the installation guide to get started.

About external integrations​

Spotify is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by William-De71, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on