Hi everyone,
I want to use this post to document the features and commands of SoundtrackBot, a bot that lives in our Twitch chat. I made this bot for Bosman v Wozniak. Its primary purpose was to handle song submissions. Since then, it has evolved to handle bets, raffles, counters and some other stuff as well.
I am always happy to add new features if somebody needs them for their stream. I am Toni-P42 on Twitch.
General
All commands can be whispered to the bot using Twitch's whisper feature (e.g. /w SoundtrackBot !mysong). If you whisper a command the bot will reply with a whisper, reducing the level of bot spam in the main chat potentially to zero. You can still post commands to chat to have the response posted in chat.
!soundtrackbot posts a link to this thread.
Song Submissions
Song submissions allow chat to submit songs in the form of links to YouTube, Soundcloud, or similar services. The streamer, or any other moderator, can pick a song randomly. Song submissions are persisted indefinitely.
As a housekeeping measure, song submissions expire after 30 days. Expired songs are not deleted and still can be picked, but have a lower chance of being picked. Update your song submission regularly to show that you are still actively participating.
!song http://...: Submits a song. Every user can only have one song submission at a time. Submitting another song will overwrite the previous submission.
!song: Updates the submission date of your existing song. This is equivalent to resubmitting your currently submitted song. Use this to confirm that your song is still up-to-date in case a moderator chooses to delete old songs.
!currentsong: Will post the last picked song.
!mysong: The bot will whisper you the song you've submitted. This command has to be whispered to the bot. It will be ignored if posted in main chat.
!mysongsucks: Your song will be removed from the pool.
!songinfo: Posts the current number of submitted songs.
!davidwise: Posts a random song from David Wise from a fixed list of his songs.
!songhelp: Posts a short list of available commands.
!songrules: Posts a short list of rules for song submissions.
Moderator Commands
!picksong: Randomly picks a song from the pool of submitted songs. The song is then removed from the list. The song is posted to chat if the command was sent to chat or whispered as a reply to the moderator if the command was whispered to the bot.
!favorite: Will add the last picked song to a playlist of favorite songs.
!favorite http://...: Will add a song to a list of favorite songs.
!pickfavorite: Randomly picks a song from the playlist of favorite songs. The song is posted to chat if the command was sent to chat or whispered as a reply to the moderator if the command was whispered to the bot. The song will not be removed from the list.
!currentsong on/off/restricted Will enable, disable or restrict the !currentsong command. When restricted the !currentsong command cannot be used for three minutes after a song has been picked.
!deletesongs 7 days: Will delete all songs older than the given number of days (7 in this example). Valid units are "second(s)", "minute(s)", "hour(s)", "day(s)", and "month(s)".
!deletesongs all: Will delete all songs.
Bets
Bets allow chat to bet on a number. That number can, for instance, be the streamer's high score. Moderators can ask the bot for the winning bet. Bets are persisted indefinitely.
!bet 123: Submits a bet. Every user can only have one bet a time. Submitting another bet overwrites the previous submission. The command must be parameterized with a number. Commas and points are ignored, so "1234", "1.234", and "1,234" are all equivalent.
!mybet: The bot will whisper you the bet you've submitted. This command has to be whispered to the bot. It will be ignored if posted in main chat.
!betinfo: Posts the number of submitted bets. If bets are closed, it will also post the average bet.
!bethelp: Posts a short list of available commands.
Moderator Commands
!openbets: Opens bets. The bot will only receive bet submissions if bets are open. If bets are opened more than one day after the last bets were opened, the bot will automatically clear all old bets.
!closebets: Closes bets. The bot will not accept bet submissions anymore.
!clearbets: Clears all bet submissions.
!score 123: Posts the winning bet(s) for the given score.
Counters
Counters allow chat to keep track of a count; for instance, the number of player deaths.
Counters are updated by "voting" for a new count. To increase or decrease a counter at least two people have to post the new count into chat within 30 seconds. The bot will only recognize a new count when the difference between the current count and the new count is less or equal than 50.
The bot can handle multiple counters. Only one counter can be active at the same time.
!count: Posts the count of the currently active counter.
!<name>: Posts the count of the counter with the given name; for instance, !deaths, or !wins. To select a counter that has white space in its name, just remove that white space; for instance !blueshells for a counter with the name "Blue Shells".
!<name> 123: Casts a vote to increase or decrease the counter with the given name. This is only necessary if that counter is not the currently active one. Otherwise, vote by just posting the new count into chat. To select a counter that has white space in its name, just remove that white space; for instance !blueshells 123 for a counter with the name "Blue Shells".
!counters: Posts a list of available counters.
Moderator Commands
!usecounter Name: Activates a counter with the given name. Creates the counter if it does not yet exist.
!createcounter Name: Creates a counter with the given name.
!resetcounter: Resets the currently active counter.
!setcount 123: Sets the count of the current counter to the given number.
!deletecounter Name: Deletes the counter with the given name.
!stopcounting: Deactivates the current counter.
!counterhelp: Posts a short list of available commands.
Raffles
Raffles allow moderators to, well, hold a raffle. Participants can submit messages ("Play Zelda 2 next"). The bot will pick one or more winners and post their messages.
!raffle: Participate in the raffle.
!raffle Message: Participate in the raffle and attach a message. The message will be posted if you win.
Moderator Commands
!openraffle: Opens the raffle. The bot will only receive participations if the raffle is open.
!closeraffle: Closes the raffle. The bot will not accept participations anymore.
!draw: Picks a winner and posts their message. Clears all participants.
!draw 3: Picks the given number of winners and posts their messages.
!rafflehelp: Posts a short list of available commands.
Easter Eggs
The bot has a number of easter eggs which I will not reveal here. ;-)
Technical
The bot respects Twitch's rate limit for posted messages. However, Twitch applies a different and undocumented set of spam detection rules to whispers. It might happen that the bot gets temporarily shadowbanned from using whispers. In this case, it will still be able to receive commands via whispers but won't whisper a response back. Commands in main chat are unaffected by this. The bot also avoids posting the same message twice in a row If you're not getting a response to a command, you probably have triggered one of these anti-spam-detector counter measures.
