Music (Spotify)

Lumio integrates with Spotify to show and control the music playing on your stream. It surfaces the currently playing track, full playback controls, device selection, your playlists, and a recently-played log — all from the Dashboard, and all available as an OBS-friendly popout. Track changes emit spotify:track events so overlays and automations can react in real time.

This guide covers connecting Spotify (including the manual workaround for free accounts), the Music page layout, playback controls, popout configuration, and troubleshooting.

Where to find it

• Sidebar: Dashboard → Music.
• Popout window: /popout/music.
• Translations: music labels live under the music.* namespace in apps/web/messages/{en,de}.json.

Quick start

1. Open Dashboard → Connections and connect Spotify. Authorize every requested scope — Lumio needs read and playback access to show the current track and control playback.
2. Start playback on any Spotify device (desktop app, phone, Sonos, Alexa, browser web player). Spotify's API cannot cold-start a device — it can only transfer an already-active session.
3. Open Dashboard → Music. You should see the current track, album art, and playback controls.
4. If you are not live right now, click Connect in the banner at the top to wake the Spotify worker for 30 minutes.
5. Optional: open /popout/music?token=YOUR_TOKEN in OBS as a browser source to show a chrome-free player on your producer view.

Connecting Spotify

Go to Dashboard → Connections → Spotify. Click Connect, log in to Spotify, and approve the scopes. On success the card shows Connected as {name} with an auto-refresh note — Lumio keeps the OAuth token fresh via the Token Refresh Worker, so you never re-authorize manually.

If the Music page shows Connect Spotify to control your music, Spotify is not linked yet — the button Go to Connections takes you straight to the setup.

Spotify Free accounts

The Spotify Web API refuses playback control for Free accounts for long stretches of time, but read access (current track, recently played) still works. Lumio shows the current track and emits spotify:track events even on Free; you just cannot hit Play/Pause/Skip from the Music page without a Premium account.

The Music page

Now-playing header

At the top of the page:

• Album art — click to copy the Spotify track URL (Copy URL label).
• Song title and artist — links out to Spotify's web player.
• Progress bar — current position / duration in mm:ss.
• Playback controls — Previous, Play/Pause, Next, Shuffle, Repeat (with Repeat 1 toggle), Mute/Unmute, and a volume slider.
• Popout button — the external-link icon at the top right opens the /popout/music window (380×700 by default).

If Spotify is connected but nothing is playing, you will see Paused or No active playback with the hint Open Spotify on any device to start playback and a Start Playback button that transfers playback to the first available device.

Connect banner (channel-status gating)

To save API quota, Lumio only keeps the Spotify worker running while at least one of your channels (Twitch, YouTube, Kick, Trovo) is live. When you are offline you will see a Connect banner:

• Connect — wakes the worker manually for 30 minutes so you can test overlays or listen on camera-off streams. Requires spotify:worker.

Once any channel goes live, the worker starts automatically and the banner disappears. See Channel Status for details.

Tabs

Three tabs sit below the player:

Search

Search Spotify's catalogue. Results show cover, title, artist, and two actions:

• Add to queue — queue the track on the active device. Requires spotify:queue.
• Add to playlist — drop it into one of your Lumio-managed playlists. Requires spotify:playlist.

Playlists

Your saved Spotify playlists plus Lumio-managed playlists (you can create, rename, and delete them from this tab):

• New playlist name input + + creates a new playlist.
• Each playlist row shows {count} tracks, with actions:
  • Play — starts playback from the top.
  • Edit playlist (pencil) — rename it.
  • Delete (trash) — asks Delete this playlist?.
• Refresh playlists forces a resync if Spotify changes are slow to appear.

Requires spotify:playlist.

Devices

Lists every Spotify Connect device currently visible to your account (desktop, mobile, browser, speakers, consoles). Each row shows the device name and Active badge if it is the current playback target. Click any device to transfer playback to it. Refresh devices forces a fresh poll.

Requires spotify:device.

Queue panel

The right-hand queue panel lists upcoming tracks (from Spotify's read-only queue) plus anything you add via Lumio's Add to queue action. Filter with the queue search input to find a specific track quickly.

Recently played

Below the player, the Recently Played section lists the last 7 days of tracks (up to 50). Each row shows the song, artist, album art, the played-at time, and a status badge (safe / blocked / unknown, from the copyright database). Click a row to copy the track URL or open it in Spotify.

Popout (OBS and secondary monitors)

Open /popout/music or click the external-link icon on the Music page. Inside OBS or a browser without your cookies, append ?token=YOUR_TOKEN (tokens are generated under Account → Tokens).

The popout is a compact, chrome-free player with:

• The same now-playing header, controls, queue, and tabs (collapsible).
• A Settings cog with toggles for Font Size, Copy Button, Report Song, Recommend Song, Show Header, Show Footer, Theme, and Language.

Permissions granted to the token determine which buttons appear — a token with only spotify:read will show the player but hide Play/Pause, Skip, queue, and device controls.

Permissions

Permission	What it unlocks
spotify:read	See the current track, queue, recently played
spotify:playback	Play / pause / skip / previous / volume / shuffle / repeat
spotify:queue	Add tracks to the playback queue
spotify:playlist	Create, edit, delete, and play your playlists
spotify:device	List and switch Spotify Connect devices
spotify:worker	Manually wake the Spotify worker when offline

The Music page itself requires spotify:read (the PermissionErrorBoundary enforces it). Without spotify:read the page shows a graceful access-denied state instead of an empty player.

Tips & best practices

• Always start playback on a real device before the stream goes live. Spotify cannot cold-start a device from the Web API; transfer a playing session.
• Use playlists for stream music. Curate copyright-safe playlists and swap between them from the Playlists tab during breaks.
• Turn off private session on Spotify. Private sessions hide the current track from the API — you will see No active playback even while music plays.
• Pin the popout in OBS with a token restricted to spotify:read if the popout will be visible on stream, so a viewer cannot trick an overlay into skipping a track.
• Let the worker auto-start. The 30-minute manual window is designed for setup and testing; under normal use the worker follows your live state.

Troubleshooting

Connect Spotify to control your music

Spotify is not connected at all. Go to Dashboard → Connections → Spotify and authorize.

No active playback but music is playing

• Open Spotify on any device and press Play again to force a Connect handshake.
• Check that Spotify is not running in a private session (Settings → Social → Private session off).
• Free accounts cannot be remote-controlled but can still be read; you may need to control playback from the Spotify app itself.

Open Spotify on any device to start playback

No device has been active recently. Spotify Connect devices go to sleep after inactivity; open the Spotify desktop or mobile app to wake one up, then hit Start Playback again.

Playback buttons are disabled

Either the Spotify worker is not active (channels offline and no manual connect), you do not have the relevant permission (spotify:playback, spotify:queue, spotify:device), or you are on a Free account. The banner at the top of the page explains which case you are hitting.

Connection lost — reconnecting…

The Spotify worker WebSocket dropped. Lumio reconnects automatically. If it persists, your session token may have expired — log out and back in.

Devices list is empty

Open any Spotify client (desktop, mobile, browser) so it registers as a Connect device, then click Refresh devices.

Track art never updates

The Spotify worker is probably stopped (no live channels). Click Connect in the banner to wake it for 30 minutes, or go live on any connected platform.

Related

• Events — Spotify changes emit spotify:track events your overlays and automations can react to.
• Channel Status — controls when the Spotify worker runs automatically.
• Overlays — add the Spotify Now Playing widget to your overlays.
• Automation Templates — trigger flows on track changes, play, pause, skip, and playlist edits.