Spotify

The Spotify driver turns a Spotify account into a GEM AV source — a streaming service a user can browse and play on a touchpanel, with live now-playing artwork and full transport control. There is no box to wire: the "device" is a cloud connection to Spotify's Web API that controls a named Spotify Connect target (a smart speaker, an AV receiver with Connect, a Sonos player, a phone running Spotify, and so on). One GEM device = one Spotify account, and the driver creates no zones.

Control runs over the Spotify Web API using a one-time browser sign-in (OAuth). Each GEM install registers its own small Spotify application to get a Client ID; you never share Spotify's own keys.

There are two ways to run it, and the choice changes the whole setup:

• Single-user mode (the default) — GEM holds one account's sign-in and fully drives playback: browse playlists, artists, albums, podcasts, liked songs and recently played; search; transport; volume/mute; and live now-playing feedback.
• Multi-user mode — GEM holds no credentials at all. The on-screen panel simply tells whoever is in the room to open Spotify on their own phone and cast to the named Connect target. Pick this when every household member uses their own Spotify account.

What you can do (single-user mode)

• Browse the account's Playlists, Artists, Albums, Podcasts, Liked Songs, and Recently played
• Search the Spotify catalog
• Transport: play / pause / next / previous, and shuffle and repeat (set or toggle)
• Volume up/down and set level, plus mute (emulated by dropping the Connect target to 0 and restoring)
• Live now-playing — current track, artist, and album art, refreshed while the source is on screen
• Follow / save albums, artists, playlists, and podcasts to the account's library
• Artist radio (artist seeds only — see Known limitations)

Prerequisites

• A Spotify Premium account. Playback control requires Premium; free accounts cannot be driven.
• A Spotify application registered for this GEM install at developer.spotify.com/dashboard. Each install needs its own Client ID. Spotify's Development Mode caps an application at 5 authorized users — for a larger building, request a Production application from Spotify before adding more users.
• A redirect URL that the sign-in can return to: your GEM's public address followed by /handlers/spotify (for example https://your-gem-host/handlers/spotify). It must be reachable by the browser you sign in with and must be added to the application's Redirect URI allowlist on the Spotify dashboard.

No client secret needed

GEM uses the PKCE sign-in flow, so you only ever enter the Client ID — there is no client secret to store.

Setup — single-user mode

1. Register the Spotify application

1. At developer.spotify.com/dashboard, create a new app and copy its Client ID.
2. On the app's settings page, add your GEM redirect URL — for example https://your-gem-host/handlers/spotify — to the Redirect URIs list. It must match exactly, including https and the trailing path.

2. Create the GEM device

1. Open Devices, add a device, and choose the Spotify driver. Give it a name, save, and enable it.
2. On the device, set these fields (the form labels are shown first, the attribute key in parentheses):
   • Spotify Client ID (client_id) — the Client ID from step 1.
   • OAuth Redirect URL (redirect_url) — the exact URL you whitelisted in step 1.
   • Spotify Connect Device (spotify_device_name) — the exact name of the Connect target to control (the speaker/receiver/Sonos room/phone as it appears in Spotify's device picker). You can fill this in after step 3 by running get_devices.
   • Spotify User ID (spotify_user_id) — your Spotify username from your account settings. GEM also fills this in for you automatically once you complete sign-in.

3. Authorize the account

1. On the device's Commands tab, run authorize_spotify. GEM builds a Spotify authorization link, emails it to the site's configured address, and writes it to the server log.
2. Open that link in a browser, sign in to Spotify, and approve the requested access. Spotify redirects back to your /handlers/spotify URL; GEM saves the returned code, reloads the device, and exchanges the code for access automatically. After this the device stays signed in on its own and refreshes access in the background — you do not authorize again unless the sign-in is revoked or lost.
3. Run get_devices to confirm the named Spotify Connect Device is visible and online, and copy its exact name back into spotify_device_name if it differs.

Redirect URL must match exactly

If authorize_spotify never completes, the cause is almost always the redirect URL: the value in redirect_url, the URI whitelisted on the Spotify dashboard, and the address the browser actually lands on must all be identical, character for character.

Setup — multi-user mode

For installs where each person uses their own Spotify account, switch the device to passive mode:

1. Create the device as above and enable it.
2. Set spotify_device_name to the Connect target name people should cast to.
3. In the device's Attributes, add an attribute named multi_user with value true (boolean).

In this mode GEM stores no Client ID, runs no sign-in, and does not control playback. When a user selects the Spotify source in a room, the panel reads "Open Spotify on your device, connect to <name>." Each person drives playback from their own phone and casts to that target. Leaving multi_user unset (or false) keeps the device in single-user, GEM-controlled mode.

Pointing a Spotify source at a Sonos player

Spotify Connect refuses to start playback on Sonos players directly. The driver handles this for you: if spotify_device_name matches the name of a Sonos zone in GEM, play requests are routed natively through the Sonos integration instead, and the Sonos room's now-playing is mirrored back onto this Spotify source. So you can name a Sonos room as the Connect target and it will work. The one exception is artist radio, which has no Sonos equivalent.

Using Spotify as an AV source

To put Spotify on a touchpanel as a selectable source:

1. Open AV Sources and add a source whose Device is this Spotify device.
2. Set the Component field to spotify — this draws the Spotify browse-and-now-playing panel (playlists / artists / albums / podcasts / liked / recent on one side, now-playing on the other).
3. Save, then make the source selectable in the rooms that should have it (see AV Zones).

While a Spotify source is selected in a room, GEM polls now-playing every few seconds so the artwork and track stay current; when no room is using it, polling stops on its own.

Attributes

Device — set these (single-user mode)

Field (key)	Type	Description
Spotify Client ID (client_id)	string	Client ID from the app you registered at developer.spotify.com.
OAuth Redirect URL (redirect_url)	string	Must match a Redirect URI whitelisted on the Spotify app, e.g. https://your-gem-host/handlers/spotify.
Spotify User ID (spotify_user_id)	string	Your Spotify username. Auto-filled after sign-in.
Spotify Connect Device (spotify_device_name)	string	Exact name of the Connect target to control. Run get_devices to see the available names.

Device — optional

Attribute	Type	Default	Description
multi_user	boolean	false	Set true for passive "use your own phone" mode — no Client ID, no sign-in, no GEM control.

Device — managed automatically (do not edit)

The sign-in writes and maintains these for you. They are sensitive and are kept encrypted; never type into them.

• Access Token (access_token) and Refresh Token (refresh_token) — the stored sign-in, encrypted and read-only. If they are ever lost, just run authorize_spotify again.
• code_verifier, auth_code, expires_in, token_time — short-lived bookkeeping for the sign-in handshake.

Device — live state (read-only)

These reflect the current Connect target and are useful as trigger conditions:

Attribute	Description
volume	Current Connect volume (0–100).
mute_state	on / off (mute is emulated by setting volume to 0 and restoring).
current_media	The current track as data (name, artist, album-art URL, shuffle, repeat) — this is what the now-playing panel renders.

The Spotify driver creates no zones — it is a source device, configured entirely as device attributes and surfaced through an AV source.

Commands

Driver-declared commands appear on the device's Commands tab and can be used in macros, triggers, and on UI buttons. The on-screen Spotify panel issues these for the user; you mainly reach for them directly when scripting macros (for example, a "Morning" macro that starts a playlist).

Transport

Command	Action
play	Start / resume playback on the Connect target.
pause	Pause playback.
next / previous	Skip to the next / previous track.
shuffle (arg on) / shuffle_toggle	Set shuffle on/off (on = true/false), or flip the current state.
repeat (arg on) / repeat_toggle	Set repeat on/off, or flip the current state.

Volume

Command	Action
volume (arg volume) / set_volume (arg volume)	Set the Connect target's volume to an absolute level (0–100).
volume_up / volume_down	Step volume by 3.
mute_on / mute_off / mute_toggle	Mute / unmute by dropping the Connect target to 0 and restoring the previous level.

Browse and search

Command	Action
get_devices	List the Spotify Connect targets the account can see (use it to confirm and copy the exact spotify_device_name).
get_now_playing	Refresh the current track / artist / artwork.
get_list (args entity, id, start, count)	Fetch one of the account's lists. entity ∈ artist, album, playlist, saved_track, playlist_tracks, album_tracks, artist_albums, recent_tracks. id names the parent (e.g. the playlist for playlist_tracks); start/count page the results.
search (args entity, query)	Search the Spotify catalog. Spotify caps results at 10 per request.
play_radio (args entity, id)	Start artist radio for the artist id. Only entity = artist is supported.
authorize_spotify	Start (or repair) the browser sign-in flow.

Library — follow and save

Command	Action
save_album / remove_album (arg id)	Add / remove an album in the account's library.
save_artist / remove_artist (arg id)	Follow / unfollow an artist.
save_playlist / remove_playlist (arg id)	Follow / unfollow a playlist.
save_show / remove_show (arg id)	Follow / unfollow a podcast.

Known limitations

• Premium and an online target are both required. Playback control needs Spotify Premium, and the named spotify_device_name must currently be online in Spotify — playback returns a 404 ("No active device") if it is off or misspelled. Run get_devices to confirm visibility.
• Radio is artist-only. Spotify retired its recommendations service, so play_radio works only with an artist seed; album/playlist/track seeds return an error.
• get_artist_albums and get_entity_tracks do nothing. They appear in the command list but are not wired into the driver. Use get_list with entity = artist_albums (and the relevant track entities) instead.
• Development Mode caps users at 5. A single registered application can authorize at most five Spotify accounts until you obtain a Production application from Spotify.
• Sign-in can expire after long idle. Spotify rotates the stored sign-in; if control stops after a long period of no use, run authorize_spotify once to renew it.

Troubleshooting

Symptom	Check
authorize_spotify never completes	The redirect URL must match exactly between redirect_url, the URI whitelisted on the Spotify dashboard, and where the browser lands — including https and the trailing /handlers/spotify.
Playback returns 404 / "No active device"	spotify_device_name is misspelled, or the Connect target is offline. Run get_devices and copy the exact name back.
No authorization email arrived	The link is also written to the server log; check it there, or confirm GEM's outgoing email is configured. Then re-run authorize_spotify.
Control worked, then stopped after days idle	Spotify rotated the sign-in. Run authorize_spotify once to mint a fresh token pair.
"Premium required" / playback ignored	The account is not Spotify Premium. Playback control requires Premium.
Panel only says "Open Spotify on your device…"	The device is in multi-user mode. Remove or set the multi_user attribute to false to let GEM control playback.
Casting to a Sonos room does nothing on play_radio	Artist radio has no Sonos equivalent; use a playlist, album, or track when the target is a Sonos zone.

See also

• AV Sources — add Spotify as a selectable source and pick the spotify panel.
• AV Zones — make the Spotify source selectable in rooms.
• Sonos — when the Connect target is a Sonos room, play routes through Sonos.
• Channels — how on-screen source browsers work.
• Commands — running and scripting device commands.
• Devices — adding and configuring devices.