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.
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.
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 (YouTube cat. 10) | Only accept videos in YouTube's Music category. |
| 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. |
| 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. |
| 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— Will use the link or search term supplied to add a song to the queue.!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.
- Chat commands for the song request system. Enable them and adjust cooldown, aliases and permissions on the Commands page.
- 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
- 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
- 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
- Bot language
- 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
- Base text
- User
- Title
- 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
- Viewer commands
- Moderator commands
- MOD only
- search
- username
- Manage command settings
- 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
- 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