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). Shuffle can display Off, On, or Smart. Smart Shuffle is a read-only state in Lumio: activate it in the Spotify app, because Spotify's public Web API only lets Lumio switch regular shuffle on or off. 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).

The page heading and popout button stay in place while Spotify status loads. If a player is expected, loading rows occupy its space; a temporary loading state does not show a connection error. Within the Music page, the loading player and an unreachable-player message occupy the same space, keeping the recently played section in place when the player read finishes.

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) 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 player stays on the page but turns unavailable: dimmed, with the last known track (or the empty state) and every control disabled - separate from the "connect Spotify" hint you see when nothing is linked yet. The red Spotify channel disconnected entry of the connection notices above it says why. On the dashboard its Reconnect Spotify button starts the Spotify OAuth flow; in the popout the entry is read-only - a link that opens Connections in a new tab (a delegated popout shows the text only). See Connections → Reconnect flags.

Spotify rate limit

Spotify can temporarily throttle the account's app. When a Spotify request gets a 429, the Music player shows a warning banner with the seconds until it will read again. The same banner appears in the dashboard and the popout, including an OBS popout. The last known track stays visible; a rate limit does not mean the connection has expired or the player is unreachable. If the first read is throttled, the player still appears with the banner while it waits for its first full state.

During the wait, the player pauses its regular 60-second poll and skips device and playlist refreshes. It reads the full state once when the countdown ends, then resumes regular polling. You do not need to reconnect or reload the page. The banner's × hides it for the current wait; a later rate limit can show it again. It has no action button in either view.

Tabs

Three tabs sit below the player:

Search

Search Spotify's catalogue. Typing runs a debounced search once you have entered at least two characters. While a search is running the panel shows Searching…. If Spotify is unreachable, the panel shows Search failed with a Retry link instead of an empty result. A rate-limited search shows the player-wide Spotify rate-limit banner; while that banner is visible, the panel does not repeat the rate-limit message. If you dismiss the banner, the panel can show Too many requests — please wait a moment with Retry. 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. The list scrolls inside the tab, so a long device list never spills out of the card; once you have more than five devices a filter field appears above it so you can narrow the list by name or type (with a No matching devices line when nothing matches).

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.

The same report and recommend actions appear on the inline Now Playing event line in Multichat: on a Spotify track row the flag and plus buttons sit always visible next to the copy-URL action - no hover needed, so they are reachable on touch and in the pop-out just as they are on the dashboard. They show only if you have the copyright feature and the copyright:report or copyright:recommend permission; each button appears only when you hold that specific permission and the track has both a song name and artist. A playlist line carries only the copy-URL action.

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 Settings → Channel → Access → Popout Tokens, see Tokens). The seasonal look also shows in this popout; append &season=off, &seasonStrength=subtle or &seasonMotion=off to the URL to change it for this popout only.

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 that opens a full-screen settings panel - the same presentation as the Chat and Events popouts - with a Font Size slider, a Streamer Mode toggle, a Theme picker, and a Region & language block (language, time zone, date format, and time format). Close it with the × in its header. (The per-item display toggles you see in the Chat and Events popouts do not apply here.)

Once the view settings have loaded, the cog and wake-lock indicator remain in the bottom bar whether Spotify is disconnected, needs reconnecting, is waiting for manual connection, is playing, or is unreachable. The search field appears with the player; its space remains reserved in the other states. The saved font size applies from the first frame.

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.

Animations for this view

Open the settings gear and choose Animations → As global, Reduced, or Off. The choice affects this view on the dashboard and in its popout, and is stored per browser and per user/account pair. It can only reduce motion further than your global Animations in Lumio preference; an unavailable looser choice is disabled. For an OBS popout, append &motion=reduced or &motion=off (use ? if it is the first URL parameter) to apply a stricter choice to that URL without saving it. The global preference is read-only in a token popout.

Where these settings apply

Most of these settings apply to you on this account. Your Music display settings (font size, theme and the layout options in the settings panel) are stored in your browser and keyed to the pair (you, the channel account you are viewing) — switch to a second channel account, or sign in as a different team member of the same account, and they start from defaults. You set them once per browser context (the dashboard, and again in an OBS popout, which is separate).

Streamer Mode, the Region & language block, and Animations in Lumio are global user settings. Streamer Mode, your language, time zone, date/time format and global motion preference are stored on your user profile, so they follow you across devices and every channel account — the Region & language block here is a second entry point to the same values as Dashboard → Settings, not a per-account copy.

Which Spotify account is connected is a separate matter: that is a per-channel connection, managed on the Connections page, not a view setting stored here.

Presets

The music settings panel has a Presets tab - named snapshots of your Music display settings saved to your account, so you can switch layouts and reuse them across devices. New preset opens an assistant to choose what to store and name it; each preset card offers Load, share, overwrite, rename and delete, with a quota line for your plan's limit. Share copies a code/link for the preset and can make it visible to your whole account (with the presets:share permission); presets teammates share into your account show up in a Shared from the channel section you can load or save as your own. The Export / Import buttons below the cards move settings to a file, code or link (on a plan without presets they sit in the General tab instead). In a popout you can load a preset but not change or share one. See the Setting Presets feature page for details.

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.

Spotify rate-limit banner

Spotify is temporarily throttling requests for the connected app. Keep the player open; its countdown shows when it will read again and it resumes automatically. See Spotify rate limit.

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.