Zum Hauptinhalt springen

Spotify Smart-Home-Integration, kostenlos und Open Source

Spotify-Integration für Gladys Assistant

Control your Spotify Connect devices and launch playlists, recent tracks or favorites.

Auf GitHub ansehenAlle externen Integrationen
Info

Die Dokumentation dieser Integration wird von ihrem Autor geschrieben und ist bisher nur auf Englisch verfügbar.

This integration lets you control your Spotify Connect devices from Gladys Assistant: play, pause, previous / next track, volume, and launch one of your playlists, a recently played track, or one of your favorites.

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.
  • "Spotify" device: a separate, single device carries three lists — playlists, recent tracks, favorites. Picking an option there does not play anything: it is only remembered as a pending selection, and the play button of any Spotify Connect device launches it as soon as it is pressed.
  • Actions: test the connection, reauthorize, refresh the playlists/recent tracks/favorites, 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.
  • Gladys Assistant 4.86.0 or later (for the "Spotify" device's dynamic lists).

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.

The "Spotify" device: playlists, recent tracks and favorites​

In addition to your Spotify Connect devices, the integration creates one separate, single device named "Spotify". It carries three independent lists:

  • Playlists: your playlists (owned, followed, private and collaborative), listed alphabetically (Playlist — <name>).
  • Recent tracks: your recently played tracks, most recent first (Récent — <artist> — <track>).
  • Favorites: your liked/saved tracks, in the same format (Favori — <artist> — <track>).

Picking an option in one of these lists does not play anything. It is only remembered as a pending selection, and the other two lists are automatically reset to "not selected" — the three are mutually exclusive, only one active selection at a time. It is the play button of a Spotify Connect device that acts on it: if a pending selection exists, it launches that instead of a plain resume, on that device. This works for any of your Spotify Connect devices (Mac, phone, speaker…), with no scene required.

Since each option's value is a plain Spotify URI with no extra wrapping (e.g. spotify:playlist:..., spotify:track:...), it also stays available as-is in the list's own state, so it can be read and forwarded by a scene to another integration (e.g. a local Sonos "Play URI" feature). If the selected item is later deleted or becomes inaccessible, the playback attempt fails with a clear error instead of playing something else.

All three lists are refreshed automatically after connecting, after a reauthorization, when scanning for devices, on integration startup, and every 20 minutes in the background — never on every dashboard view or scene run. Use the "Refresh Spotify content" action in the configuration screen to refresh them on demand; it reports how many playlists, recent tracks and favorites it found.

Podcasts are not returned by Spotify's "recently played" endpoint, and local files cannot be relaunched by this integration, so neither appears in these lists.

Missing permissions after an update​

The playlists / recent tracks / favorites lists need permissions that an older connection may not have granted yet — favorites in particular, added later and requiring an additional permission (user-library-read). If Gladys reports missing permissions, or a list stays empty on an existing connection, click "Connect with Spotify" again in the configuration screen: Spotify shows the authorization screen again with the newly requested permissions (already-granted ones are approved in one click), without touching your existing devices, scenes, or the transport controls you already use.

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.
  • Up to 200 playlists, the last 50 recently played tracks and 200 favorites (Spotify's own limits, or limits set by the integration) are listed; beyond that, the extra ones are dropped (alphabetically for playlists) and logged, never silently.
  • Podcasts and locally stored files never appear in the "Spotify" device's lists.
  • The pending selection lives in memory only. If the integration restarts between picking an option and pressing Play, the select still shows the choice on the dashboard, but Play does a plain resume instead of launching it — pick it again if that happens.

Konfigurationseinstellungen​

Diese Einstellungen fragt Spotify in seinem Konfigurationsbildschirm in Gladys ab.

EinstellungTypPflichtfeldBeschreibung
Connect your Spotify accountsectionNeinThis 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 IDstringJa
Client SecretsecretJa
Connect with Spotifyoauth2NeinOnce the Client ID and Client Secret are saved, click Connect to authorize Gladys on your Spotify account. If Gladys later reports missing permissions after an update, click it again: your devices and Gladys scenes are kept.
Browser could not return to Gladys?sectionNeinThe 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 addressstringNein

So installierst du Spotify in Gladys​

  1. Öffne in Gladys Integrationen: Spotify erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
  2. Klicke auf Installieren. Gladys lädt das Docker-Image (ghcr.io/william-de71/gladys-spotify:1.2.0) herunter, startet es in einer vom Kern isolierten Sandbox und erzeugt die Oberfläche der Integration (Geräte, Erkennung und Konfiguration).
  3. Öffne den Bildschirm Konfiguration der Integration, fülle die Einstellungen aus und speichere.
  4. Du kannst sie auch direkt über die URL ihres Repositorys installieren: https://github.com/William-De71/gladys-spotify.

Spotify benötigt Gladys >=4.86.0. Der Katalog in Gladys wird stündlich aktualisiert, eine neue Version ist also spätestens eine Stunde nach ihrer Veröffentlichung verfügbar.

Du nutzt Gladys noch nicht? Es ist kostenlos und Open Source: folge der Installationsanleitung, um loszulegen.

Über externe Integrationen​

Spotify ist eine externe Integration: eine Community-Integration, die als Docker-Container verpackt und auf GitHub veröffentlicht wird. Gladys installiert sie mit einem Klick und führt sie in einer vom Kern isolierten Sandbox aus. Sie wird von William-De71 veröffentlicht und gepflegt, nicht vom Gladys-Kernteam.

Abonniere den Newsletter von Gladys Assistant

Ein paar E-Mails im Monat zu neuen Releases und Neuigkeiten aus dem Projekt. Verschickt von Pierre-Gilles Leymarie, dem Gründer des Projekts. Jederzeit abbestellbar 🙂
Zuletzt aktualisiert am