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, add Gladys' redirect address (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)​

This is the trickiest step: 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 either HTTPS, or HTTP on a loopback address (127.0.0.1). An address such as http://192.168.1.50:1444/... is therefore always rejected. The integration handles this: it always replaces the host with 127.0.0.1, whatever address you use to reach Gladys.

The address has the following shape:

http://127.0.0.1:<PORT>/dashboard/integration/device/external/<selector>/oauth-callback
  • <PORT> is the port of your Gladys interface (for example 1444).
  • <selector> is the integration identifier (for example ext-dev-spotify in developer mode).

Concrete example:

http://127.0.0.1:1444/dashboard/integration/device/external/ext-dev-spotify/oauth-callback

To get the exact value for your installation, click "Connect with Spotify" once: the Spotify page that opens contains, in its address, the redirect_uri=... parameter. Decode it (: and / appear as %3A and %2F) and copy it as is into the Redirect URIs field of your Spotify application, then Add and Save.

Points to respect (Spotify compares character for character):

  • the same port as your Gladys;
  • the full path up to /oauth-callback (do not stop at the host and port);
  • no trailing slash after oauth-callback;
  • http (not https) and 127.0.0.1 (not localhost).

ℹ️ The selector differs between developer mode (ext-dev-spotify) and the integration installed from the store. The redirect address therefore changes too: simply add the new value in Spotify when the time comes (you can declare several Redirect URIs).

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, what happens next depends on the machine you browse from (see below).

You browse from the machine running Gladys​

You return straight to Gladys: the connection is established and your Spotify Connect devices become available for discovery. Nothing else to do.

Gladys runs on a server you reach by its IP address​

127.0.0.1 always means the machine running your browser, not the server. After authorizing Spotify, your browser therefore tries to reach Gladys on your own computer and shows an error page ("this site can't be reached", "connection refused"…). This is expected, and the authorization did go through: 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://127.0.0.1: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.

Access tokens are stored and refreshed automatically: you only need to connect once, whichever method you used.

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. Re-read "The redirect address": it is almost always the path (/dashboard/integration/.../oauth-callback) that is missing, or a different port.
  • "The integration refused the connection" (or "connection refused", "site can't be reached") when returning from Spotify: this is the normal case when Gladys runs on a remote server. Copy the address of the error page and use the "Finish the connection" action (see the "Connection" section).
  • "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, paste its Client ID and Client Secret below, 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?sectionNoSpotify only accepts a redirect address on 127.0.0.1, which means the machine running your browser. If you reach Gladys through a server IP address, the return lands on a blank or error page: this is expected, and the authorization did 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.0), 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