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.
• Screen stays on: the Music page and the popout keep the screen from dimming or locking while open (on an iPhone or iPad after one tap on the Tap to keep screen awake prompt). The popout's window bar shows the screen lock indicator when the browser refuses or drops the lock.

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. The music popout and the Cockpit's music tile say Spotify is not connected with the same next step and the same button (from a popout it opens the connections in a new tab).

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.

When Spotify refuses a control (Play, Pause, Previous, Next, Seek, Volume, adding to the queue, switching device), the player shows a message instead of doing nothing: "Spotify Premium is required for this action." for a Free account, or "Spotify does not allow this action right now." when the current playback does not allow it (for example Previous on the first track, or during an ad). Play/Pause returns to the real state. A refused Start playback shows the same text in the start form. The Music page, the Music popout and the Cockpit music tile behave the same.

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. Everyone sees it; clicking it to jump within the track needs spotify:playback.
• 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. They need spotify:playback. Mute/Unmute and the volume slider need spotify:playback and 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 a device is 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. The Playlist dropdown opens with a search field at the top: type part of a name to narrow a long list (No playlist found when nothing matches). The row needs spotify:playlist (it plays a playlist); the Device dropdown also needs spotify:device - without it the playlist starts on the active device. The dropdowns start on the active device (or the first one listed) and your first playlist, also when a device or a playlist only shows up after you open Spotify, so Start Playback is ready as soon as both are shown. If Spotify refuses the start, the row says why below the button (Playback did not start: … with Spotify's reason). The same row is in the music popout and the Cockpit music tile. While your playlists are still loading the row shows placeholders in its own shape. If your Spotify account has no playlist, the row says Nothing to start here yet. Start a song in the Spotify app, or create a playlist under "Playlists".

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

Up to three tabs sit below the player. Search is always there; Playlists needs spotify:playlist and Devices needs spotify:device - a tab you have no permission for is not shown.

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 own playlists (Spotify does not let you add songs to playlists you only follow). Requires spotify:playlist. If you have no playlist of your own, the list says Songs can only be added to your own playlists, and you have none yet. Create one under "Playlists". The same list opens from the now-playing header and from each queue row.

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.
• With no playlists at all, the tab says Your Spotify account has no playlists yet. Type a name above and press + to create one.

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. It needs spotify:queue; without it the tabs take the full width. Click a queue row to skip straight to that track (this also needs spotify:playback). 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 slim window bar on top, like the Cockpit: the Lumio logo, Music, the channel switch ▾ (signed in with more than one channel only, see Popout window bar), the preset choice ▾, the screen-lock indicator and the Settings cog. There is no Edit and no ↗. Preset ▾ loads one of your music presets (or one shared from the channel) like Load in the Presets area - it replaces this popout's music settings and reloads the window - and the bar then names it; until then it says Own settings.
• The cog opens the music settings: edge to edge, the Cockpit's settings page with only the areas Display (Font Size and Animations), Presets (on plans with presets) and Window & account (theme, Streamer Mode, Animations in Lumio, region & language, transfer, channel switch, sign-out). From 768 px window width the areas stand in a column on the left; in a narrower window you first see the list, and ‹ Back returns to it. × or Esc closes. (The per-item display toggles of the Chat and Events settings do not apply here.) These settings belong to the popout: the Music page has no cog of its own, and of them it follows only Animations.

The window bar stays in place whether Spotify is disconnected, needs reconnecting, is waiting for manual connection, is playing, or is unreachable, and while the player loads. The search field appears in the bottom bar 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. The Music page, the popout and the Cockpit's music tile follow the same rules, so the same permissions show the same controls on all three (see Permissions).

Animations for this view

Open the settings and choose Display → 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 have a Presets area - 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 (they are also under Window & account → Transfer settings, on every plan). A music share link opens the music popout (/popout/music) with the import preview, because that is where these settings take effect; a link that still points at the Music page (/dashboard/music) is forwarded there. In the popout the preset ▾ in the window bar loads a preset directly. 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, search, recently played
spotify:playback	Play / pause / skip / previous / shuffle / repeat, jump within the track, skip to a queue entry
spotify:volume	Mute / unmute and the volume slider (together with spotify:playback)
spotify:queue	See the queue and add tracks to it
spotify:playlist	Create, edit, delete, and play your playlists; add or remove songs; the starter row
spotify:device	List and switch Spotify Connect devices; the starter row's device choice
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

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.