Song requests.

What it does

Viewers request a song with !sr and the bot resolves it on YouTube and adds it to the queue. Playback happens either in a dashboard tab or on a dedicated overlay you add to your stream, with a now-playing card.

Commands

Settings

Use in commands

Read state with $(media.current), $(media.next), $(media.queue) and $(media.count).

Song cooldown

The cooldown stops the same songs coming round too often. When the next song in your playlist played within the cooldown window, it is skipped for now and the first song that is clear of the cooldown plays instead. Skipped songs keep their place, so they play as soon as their cooldown runs out. Every song that starts playing counts, whether it came from a request, the dock, the dashboard or the playlist.

If your playlist is shorter than the cooldown, every song can end up on cooldown at once. Music never stops: the song that played longest ago plays next. The settings card tells you when your active playlist is shorter than the cooldown you picked.

Turn on Also apply to viewer requests to refuse a viewer !sr for a song on cooldown. The bot replies with your cooldown message, and $(media.cooldown.remaining) in that message says how long until the song can be requested again (for example 3h 12m). The default message is @$(user) that song played recently. It can be requested again in $(media.cooldown.remaining). You, your mods, and anything added from the dock, the dashboard or the Companion skip this check.

Spacing out artists

With Try to space out artists on shuffle on, every shuffle spreads songs by the same artist across the playlist instead of letting them bunch up. The artist is the part of the title before the first - , so Daft Punk - One More Time counts as Daft Punk; titles without that pattern are shuffled freely. When one artist makes up most of a playlist, some of their songs may still end up next to each other.

The playlist also reshuffles itself each time it finishes a full pass, so the order is different every time round. With the song cooldown on, songs still on cooldown are kept away from the front of the new order, and the song that just played always goes to the back.

The song cooldown, its viewer requests option and artist spacing are also on the Request settings card of the Companion's Media Request page, and a change in either place shows up in the other. The cooldown reply message is edited on the dashboard.

Managing the queue

The request queue shows viewer requests first, then the next few playlist songs that will play after them. Both kinds of row have the same controls on the dashboard, the OBS dock and the Companion:

Requests always play before the playlist, so a request can't be dragged among the playlist songs or the other way round. On a phone, use the up and down arrows instead of dragging; with a keyboard, focus the handle and press the up or down arrow key. With the song cooldown on, the playlist songs shown are the ones that will really play next, so songs on cooldown are left out until they are free again.

Fallback playlists

A playlist is the music that plays when the request queue is empty, so there is always something on while you wait for the next !sr. Viewer requests always take priority: the moment someone requests a song it plays next, and the playlist resumes only once the queue runs dry again.

Open Manage Playlists to build as many as you like, up to 25 per channel. For each playlist you can:

• Create a new empty playlist, or Clone an existing one to start from its tracks.
• Rename it, Reorder the list to suit you, and Delete ones you no longer need.
• Set as default: there is always exactly one default playlist. The first one you make is the default, and if you delete the default the next playlist is promoted automatically.

Per-category defaults

You can map a Twitch category (the game or section you are streaming) to a specific playlist, so your idle music matches what you are doing. Category mapping drives idle playback only when Auto-switch while live is on. With it on, going live in a mapped category fills idle playback from that category's playlist; otherwise the default playlist plays. Changing category only affects future fills, so the track that is already playing is never cut off mid-song.

A separate Auto-match playlist on load toggle is about your dashboard view, not playback: when you open Manage Playlists it opens on your live category's mapped playlist if one exists, so you land on the right list straight away. It works independently of auto-switch.