Song requests let viewers queue YouTube tracks from chat, played by the built-in player. You control the queue length, the per-viewer limit, and what's eligible to be requested.
What it solves
Picking your own background music gets stale, but opening it up tends to go sideways: repeats, one person filling the whole queue, requests that aren't music at all. This module puts "open" and "controlled" in the same place: who can request, how much, and from what pool are all explicit gates.
Getting started
- Enable the module and set the
queue limitandper-viewer limit. - Add the player's OBS URL as a browser source.
- Optionally build playlists and restrict requests to them.
Playlists and continuous play
Playlists are how the library is organised, and a track can belong to several at once;
"all songs" is the whole library. Once a target playlist is set, requests and favourites
attach to it, and when the queue empties playback continues randomly from that same pool.
Turn continuous play off and it simply stops when the queue runs out.
Review before playing (optional)
By default, requested songs go straight into the queue. Turn on
review mode and command requests, loyalty-reward requests, and sponsored
(tip) video requests all land in a Review tab first; they only play once you (or an authorised
moderator) approve them, and rejected ones are discarded. Handy when you want requests open but
still want to screen what plays.
Common misconceptions
- YouTube is the music source, not a sign-in method. Viewers request YouTube videos, but ChiwaBots itself only supports Twitch sign-in and does not manage YouTube livestreams.
- "Playlist only" disables search. With it on, only tracks already in the playlist are accepted; nothing is searched on YouTube. That narrows the library to what you've vetted, at the cost of viewers not being able to request anything new.
- "Music category only" filters by YouTube's classification, not your judgement. It goes by how YouTube categorised the video, so it will occasionally block something you'd call music, and let through something you wouldn't.
- Exempt roles ignore the limits entirely; it isn't a doubled allowance. Selected roles are not subject to the queue or per-viewer caps at all.
- The blocklist takes video IDs, and a full URL works too. It recognises the ID automatically; no need to extract it yourself.
- Rejecting a review does not refund points or payments. Rejecting a loyalty-reward request doesn't return the spent channel points, and rejecting a sponsored video doesn't refund the payment (it's already charged); songs only enter the queue once approved.
- The captions setting only covers YouTube's CC track, and YouTube remembers the last choice. Text burned into the video itself isn't CC and can't be turned off. After choosing Show or Hide, switching back to "Default" keeps the last state instead of restoring YouTube's own default; if you want a fixed result, pick Show or Hide.
Settings
The text below is taken from the in-app help, so it stays in sync with the actual interface.
| Setting | What it does |
|---|---|
| Max queue size | Maximum number of songs the queue can hold. |
| Max per user | Maximum songs each viewer can queue at once. |
| Playlist only (no YouTube search) | Only accept songs already in the target playlist (unset = All songs); YouTube search is disabled. |
| Music category only | Only accept videos in YouTube's Music category. Some videos are rejected as non-music when their category can't be resolved. |
| Target playlist | Song requests and !like saves are tagged with this playlist; idle auto-play also uses it as its scope. Unset = All songs. |
| Custom reward title | Create a channel-points custom reward on Twitch and enter its title here (must match exactly). When a viewer redeems it, their message (song name or YouTube URL) becomes a song request. Leave empty to disable. |
| Request target | Song requests and likes go to this playlist |
| No tracks in this playlist yet | Search for songs with the input above, or paste a YouTube playlist URL to import in bulk. |
| Show progress bar | Turn off to reduce the “Message only” layout to a single clean line. |
| Show playback time | Shows elapsed / total length. For tipped clip requests this is the purchased segment, not the whole video. |
| YouTube captions (CC) | Only controls YouTube's CC track; text burned into the video itself can't be removed. |
| Corner radius (px) | 0 = square corners. The video, message box and progress bar are all clipped to the rounded frame. |
| Viewers exempt from limits | Selected roles are not subject to the queue and per-user limits. |
| Auto-play from playlist when queue is empty | When the request queue runs out, keep playing random songs from the playlist (scope follows "Target playlist"; unset = All songs). Off = stop when the queue ends. |
| Auto pause when offline | Pause playback when the stream goes offline and resume when it goes live. Viewers can still request songs. |
| Prioritize sponsored videos | When enabled, sponsored song requests (tip videos) are automatically moved to the front of the queue. When disabled, they queue by payment completion time like any other request. |
| Review mode | When enabled, command requests, loyalty-reward requests, and sponsored (tip) video requests all go to the Review tab first and only play once you approve them; rejected requests are discarded. Note: rejecting does not refund points or payments. |
| Line limit | Anything past this many lines is cut off with an ellipsis. |
| Previous | Replay the most recently played song |
| Save | Save the now-playing song to the target playlist |
| Remove from playlist | Remove this song from the playlist |
| Move to top | Insert to the front (plays next) |
Chat commands
These are the default command names; they can be renamed or given aliases in the dashboard.
!song— Displays the title of the current song.!songrequest— Request a song for the play queue (default alias !sr).!songlist— Give a link to view all song requests.!songskip— Skip the current song!songpause— Pause the music player (if it's open and playing)!songplay— Play the music player (if it's open and paused)!songvolume— Change the current volume to the specified number.!songlike— Add to playlist via link, search keywords, or by leaving blank to reference the current track.!songdislike— Remove the currently playing track from the playlist.!songignore— Add the specified user to the song request ignore list.
Other notes
- A song can belong to multiple playlists; "All songs" is your whole library.
- Paste a YouTube playlist URL (youtube.com/playlist?list=…) to import it in bulk.
- Controls the OBS song widget in real time.
- Changes how the widget arranges its content. Hiding the video does not mute anything; audio keeps playing. Layout and the window frame below are independent, so you can mix and match.
- Adds rounded corners and a window frame around the whole widget. Frosted, Mica and Pixel add a decorative title bar (taking a little extra height); the others are frame and shadow only. Frame colors follow the background and progress bar colors set below.
- Review is off. These are requests left over from before it was turned off. Approve or reject to clear them; new requests no longer go to review.
- Chat commands for the song request system. Enable them and adjust cooldown, aliases and permissions on the Commands page.
- Requesting a song is mainly triggered by the chat command !songrequest. It's currently disabled, so viewers typing it in chat won't get a response.
- Recently played songs (up to 20). Not kept permanently, cleared when the server restarts.
- This list refreshes every 12 seconds; manual and chat requests both appear here.
- Block specific videos by YouTube video ID or URL. Paste a full URL and it's recognized automatically.
- Requests are rejected if the title contains any of these keywords. Case-insensitive; spacing and punctuation used to bypass are ignored automatically.
- Requests are rejected if the uploading channel's display name contains any of these keywords (matches the display name, not the channel ID).
- Song requests from users on this list are silently ignored, with no reply at all; songs already in the queue are not affected.
Other settings
These settings have no additional help text in the dashboard; only their names are listed here.
- Min duration (seconds)
- Max duration (seconds)
- Playlists
- Add track
- Import
- All songs
- This song is already in the library
- Clear this playlist
- Clear library
- Delete playlist
- Load more
- Open on YouTube
- Edit playlists
- Playlists updated
- Remove from this playlist
- Delete from library
- Playback control
- Play
- Pause
- Skip
- Volume
- Apply volume
- Mute
- Enable sound
- Enable the song module to use the player.
- Song player
- Close player
- Drag to resize
- Widget appearance
- Save appearance
- Font size (px)
- Font family
- Padding (rem)
- Line height (rem)
- Text effect
- Layout
- Video (default)
- Music player
- Still thumbnail
- Message only
- Default
- Show
- Hide
- Window frame
- Classic (no frame)
- Floating card
- Frosted window
- Mica window
- Pixel window
- Neon frame
- Bot language
- None
- Surprise
- Wave
- Twist
- Message inside video box
- Message on top
- Hide message
- Messages
- Request message
- Donation song request message
- Normal colors
- Background
- Progress bar
- Base text
- User
- Title
- Donation colors
- Donation background
- Amount
- Comment
- Failed to add playlist (Pro only?)
- Failed to delete (not empty?)
- Failed to add track
- Import failed
- Failed to update playlists
- Widget appearance is unavailable.
- Requester
- Song title
- Tip amount
- Message
- Song request rules
- Playback
- Review mode is off
- When enabled, viewer requests land here for your approval before playing. Turn on "Review mode" in Settings.
- Go to Settings
- Rejecting does not refund points or payments
- Rejecting a loyalty-reward request does not refund the channel points spent; rejecting a sponsored video does not refund the payment (already charged). Songs only enter the play queue once approved.
- No requests awaiting review
- New requests will appear here.
- Request
- Tip
- Approve
- Approved and queued
- Reject
- Rejected
- Viewer commands
- Moderator commands
- MOD only
- search
- username
- Manage command settings
- Song request command isn't enabled
- Up next
- Tip request
- No songs in the queue.
- History
- No playback history yet.
- Add song
- Refresh
- Remove
- Could not add the song. Check the keyword or URL.
- Layout & font
- Song variables
- Unknown variable
- {username} requested: {title}
- {username} tipped {amount}$ and requested: {title}
- Preview request
- Preview donation
- Message position
- Top
- Bottom
- Hidden
- Display mode
- Marquee
- Fixed lines
- Marquee speed
- Now playing
- No song currently playing.
- Playlist
- Saved to playlist
- Already in the playlist
- Removed from playlist
- Blocked videos
- No blocked videos
- Blocked title keywords
- No blocked title keywords
- Blocked uploader/channel keywords
- No blocked channel keywords
- Ignore users
- Copy all
- Copied