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: Stream → Music (/dashboard/music).
• Popout window: /popout/music.
• Requires spotify:read and the Music feature on your plan.

Quick start

1. Open Manage → 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 Stream → 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 Manage → Connections and find the Spotify card. 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 a Repeat 1 state). Mute/Unmute and the volume slider are a separate block that needs spotify:volume.
• 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. Once at least one device and one playlist are visible, a small starter row appears with a Device dropdown, a Playlist dropdown, and a Start Playback button that begins that playlist on that device. It requires spotify:playback.

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.

Reconnect required

If your Spotify connection expires and cannot be refreshed, the Music page (and its popout) shows a distinct Reconnect Spotify state — separate from the "connect Spotify" hint you see when nothing is linked yet. On the dashboard it offers a direct Reconnect Spotify button; in the popout it is a read-only notice (reconnect from the dashboard). See Connections → Reconnect flags.

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 Spotify playlists, with create / rename / delete on the ones you own:

• The New playlist name input plus the + button creates a new playlist.
• Each playlist row shows its cover, name and track count. Click the row to start playing it.
• The pencil icon (only on playlists you own) opens a rename dialog, which also holds the delete action — it asks Delete this playlist? before removing it.
• The refresh icon (Refresh playlists) forces a resync if Spotify changes are slow to appear.

The whole tab 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 queue panel sits next to the tabs and lists upcoming tracks (from Spotify's read-only queue) plus anything you add via Lumio's Add to queue action. Click a queue row to skip straight to that track. Once the queue has more than three entries, a small search input appears in the panel header so you can 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 cover art, song, artist, how long ago it played, and a status badge (safe / blocked / reported, from the copyright database). Small icon buttons at the end of each row let you copy the Spotify link, copy the track ID, and — if you have the copyright feature and the matching permission — report or recommend the song.

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 (popout tokens are created under Manage → Tokens, see Tokens).

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

• The same now-playing header, playback controls, queue, search, playlists, and devices — in a single-column layout.
• A Settings cog with a Font Size slider, a Theme picker, and a Language picker. (The per-item display toggles you see in the Chat and Events popouts do not apply here.)

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 / shuffle / repeat / start a playlist
spotify:volume	Mute / unmute and the volume slider
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 Manage → Connections, find the Spotify card, 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:volume, 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.