Custom Bots for Turntable.fm

Some time ago, I set out to  create a Turntable.fm bot.  The primary purpose was to have a second DJ available so I could continue to DJ with no additional DJs in the room.  As I had time, I slowly added more and more features.

Many of the features are fun/frivolous (lottery numbers, fortune, coin flip, etc) and were intended as ways to increase social interactions in the room.  Other features, however, serve very real room management needs.  DJ queue and battle management are two of the more robust capabilities of the bot.

Over time, various room mods have contacted me about setting up bots for their rooms.  Each mod has had specific requests and requirements which I've attempted to merge into a single, fully configurable bot.  The result is the collection of features you see below, the majority of which can be enabled or disabled with a simple true/false toggle.  (Some features can be toggled on the fly via the PM window.)

That said, if you're looking for a custom bot for your Turntable.fm room, consider giving mine a try.  The source files can be found at the link below.  Take a look at the readme.txt file for info on how to get up and running

     http://bcj19-tt.googlecode.com/svn/trunk/bots/

If you do choose to give my bot a try, please let me know through the comments section below.

Features:

Last Update: April 17,2013 (Fix greet|loc feature; Add require bot name setting)

Bot Commands via Public Chat Window

Bot Command: /dance

• /bot? - Identifies [bot] to the room.
• /dance | /awesome | /bop | /boogy | /+1 | /+ | /shake | /baila | /toma - Places an "awesome" vote for the current song.
• Note:  There is a minimum vote requirement that must be met before [bot] will awesome a song.  The default is 20% of all listeners in the room when the song began.  For example, if there are 10 listeners (not including current DJ), the minimum vote count is 2.  The votes must be cast by different users.
• /commands - Provides a list of available bot commands.  Currently references the /bot?, /dance and /fortune commands.
• /down - Will return [bot] to the dance floor if [bot] has taken a spot on the DJ stand
• /auto? - Returns a link to the TT Auto bookmarklet/script
• /flip | /coinflip - Heads | Tails
• /rps - Rock, Paper, Scissors
• /rpsls - Rock, Paper, Scissors, Lizard, Spock
• http://en.wikipedia.org/wiki/Rock-paper-scissors-lizard-Spock
• /8ball-[Ask Your Question] - Returns the traditional Magic 8 Ball responses.
• Example:  /8ball-Will I win the lottery?
• Response:  @[DJ] - As I see it, yes.
• /fortune - Returns a random Chinese fortune.
  Courtesy of http://www.chinese-fortune-cookie.com/fortune-cookie-quotes.html
• /dive - Asks [bot] to remove the requesting DJ from the stage. (This is a simulated stage dive.)
• /mega - Returns a random list of MegaBall numbers, including the MegaBall (MB)
• /pb - Returns a random list of PowerBall numbers, including the PowerBall (PB)
• /lotto - Returns a random list of six (6) lotto numbers between 1 and 60.
• /links - Returns a random URL from [bot]'s favorite links.
• /roulette - Returns the result of a random roulette spin based on a wheel with "0" and "00".
• /mods - Shows the list of all room mods, regardless of whether they are currently in the room
• /theme? | /room theme | /current theme - Announces the current room theme.
• /slide? - Announces current song counts if the Slide feature is enabled:
• Example:  Slide ([songLimit]) # # # # #
• /q? - If DJ Queue is enabled, returns the current order of DJ's in the queue.
• /q+ - If DJ Queue is enabled, adds DJ to the DJ Queue.
• /q- - If DJ Queue is enabled, removes DJ from the DJ Queue.

Bot Commands via Private Message (PM) Window

Notes:  All PM commands are case sensitive; Commands listed in red are only executable by pre-defined bot admins and/or room mods.

• awesome - Up-votes the current song.
• usercount - Returns total count of DJ's and Listeners in the room using the following format:
• D# | L# | T# | MV# (D=DJ's, L=Listeners and T=D+L, MV=Minimum number of votes for bot to awesome current song)
• up - Places [bot] on the DJ stand.
• skip - Skips current song if [bot] is the current DJ.
• down - Remove [bot] from the DJ stand.
• snag - Grabs the current song and places in [bot]'s TT queue.
• echo|[message] - Passes [message] to the public chat window, allowing room mods to communicate with the room as if they were the bot.
• "@" can be used in place of "echo" for this command.
• songstats - Toggles [bot]'s ability to announce song stats at the completion of each song.  This setting defaults to 'true,' meaning that song stats are announced.
• djoverride - Overrides settings that force [bot] to automatically start/stop dj'ing based on number of other dj's on the stand.  This command is a simple on/off toggle.
• move|[roomName] - Moves the bot to the specified room.  This feature currently has a set list of 4 or 5 rooms into which [bot] can be moved.  DEPRECATED.
• follow - Moves the bot to the same room as the admin who initiates the "follow" command.
• home - Returns [bot] to the pre-defined "home" room.
• themeset|[newTheme | themeNumber] - Sets the current room theme and announces the change to the room via the public chat window.
• For example, the following themes are used in the latin_party_mix room and can be selected via the following PM command:  themeset|9 (Sets room theme to #9 - 80s Theme.)
1. Latin Party Mix Theme (We like to mix it up. All welcome, just keep the vibe going)
2. Latin Only Theme (Strictly Latin Music)
3. Hip Hop Theme (Strictly Hip Hop)
4. Disco Theme (Old & New Disco)
5. Reggae Dance Hall Theme
6. House Dance Theme
7. 2Ks Theme
8. 90s Theme
9. 80s Theme
• Additionally, themes that are not on the specified list can be selected as in the following example:  themeset|It's 2-fer Tuesday!  (Sets room theme to "It's 2-fer Tuesday!")
• minvote|[pct of djs] - Modifies the minimum required votes for [bot] to awesome the current song.  Must be passed in decimal format (25% = 0.25).
• The following example sets the minimum vote requirement to 25% of DJs in the room at the time the current song began:  minvote|0.25
• av|[avatarId] - Changes the avatar for [bot].  
• This command requires the use of the TT ID (integer) for the desired avatar.
• [bot] must meet the specified point requirements to successfully update using the specified avatarId.
• slide|[on|off] - Enables or disables the Slide feature.  When enabled, each DJ may play one (1) song before being kicked off stage.  They can immediately return to the stage, however, though if others are in the room, it is preferred that another DJ is given the opportunity to spin.
• slide|limit=[#] - Changes the default song limit for the Slide feature.
• q|[on|off] - Enables or disables the DJ Queue feature.
• q|rem=[dj name] - Removes specified DJ from DJ Queue.
• greet|[on|off|msg|loc] - Enables or disables the greeting that is displayed to each DJ as they enter the room.  
• Passing the msg=[message] parameter changes the message sent to each DJ.
• Example:  greet|msg=Welcome to the party!
• Passing the loc=[location] parameter determines where to display the greeting.
• Example:  greet|loc=[pm|chat|both] (pm=private message, chat=public chat, both=pm & chat)
• If [bot] receives an unrecognized command, "Unknown command: [command]" is returned via the PM window.
• Note:  the "Unknown command" message will be displayed if the command is entered with incorrect case.  Generally, all commands should be entered as lower case.

Bot Message: End Song

Automated Bot Actions/Notifications

• At the end of a song, [bot] will make the following announcement(s):
• "[song name]" by "[artist]" was played by "[dj name]" and was awesomed by "[#]" listener(s).
• "@[dj name]" Just so you know, "[#]" joker(s) lamed your song.
• At the end of a song, [bot] will add the song to his queue if 80% or more of the listeners have placed an "awesome" vote for the song.
• Note:  This feature is available, but has been temporarily disabled.
• At the beginning of a song, [bot] will check to see how many djs are on the stand:
• If less than 2, [bot] will jump on the stand so the other dj can listen to more than the first 10 seconds of his/her songs.
• If greater than 2, and [bot] is one of them, [bot] will step down.
• This feature can be overridden with the djoverride command.
• When a DJ enters the room, [bot] will greet them with a simple "Welcome" message.  The greeting can be disabled via the greet|off command or the message can be dynamically changed via the greet|msg=[message] command.
• When reqbotname is set to true in the botConfig file, all bot commands via the public chat window must be prefixed with the bot's name.
• Example with reqbotname=true:  /[bot] q+
• Example with reqbotname=false: /q+

Special Features:  DJ Queue Management

• Slide - When Slide is enabled, each DJ will have the opportunity to take any open DJ spots (free for all [FFA]) as they come open.  However, after playing one (1) song, the DJ will be booted from the stage by [bot] so that other DJ's have a chance to spin some tunes.
• Note:  It is generally considered bad form to use an auto-DJ script to quickly hop back on the stand after being booted.  It will be at the discretion of the the room Mods as to whether this is grounds for being booted from the room or, worse yet, banned.

• DJ Queue - The DJ Queue feature is a more robust DJ management module that gives each DJ the opportunity to take the stage in an orderly fashion.  This feature removes the FFA approach in favor of the tried and true "take a number" method.  See above for both public and Mod-only commands.
• Note:  This feature is still under development and may not be fully production ready.  Should anyone choose to test it out in a moderately busy room, please let me know how it goes and if any changes/fixes/improvements can or should be made.

Special Features:  DJ Battle Management

The bot has the ability to manage DJ battles for up to five (5) DJ's at a time.  Currently, any room mod has the necessary permissions to initiate a battle.  All commands are passed to the bot via PM:

Bot Command:  battle|init

• battle|init - Initializes / starts the battle for all DJ's currently on the tables by completing the following tasks:
• Captures the name and ID for each DJ currently on the tables.
• Retrieves current room name.
• Retrieves current room ID.
• Retrieves server date / time stamp from TT.
• Sets contest duration (number of songs / rounds per DJ).  Default duration is 2.
• Creates unique battle ID by concatenating room ID and date / time.
• Sets default (0) values for each contestant:
• Total songs played
• Total awesomes
• Total lames
• Total song snags
• Total points (awesomes-lames+(snags*2))
• Sends "The battle is on! Good luck!" message to the public chat window.
• battle|abort - Aborts the current battle.
• battle|roominfo - Administrative command that sends basic battle info to the console.
• battle|info and battle|check - Administrative command that returns the current battle configuration to the PM window.  Information includes:
• Battle ID
• Room ID
• Room name
• TT server date / time stamp
• DJ list - This currently displays an array of all DJ-related values (ID, name, points, etc)
• Max rounds (battle duration)
• battle|rules - Sends basic rules to the public chat window.  Includes the battle|scoring message.
• battle|scoring - Sends scoring information to the public chat window.
• battle|maxrounds=# - Allows room mods to change the battle duration.  The duration should be set before the first song of the battle is complete.  It can be set before battle|init.
• battle|stats - Public command that returns DJ stats for current battle to the PM window.  Stats include:  [DJ Name]: #pts | #song
• battle|stats=chat - Mod-only command to send current battle stats to the public chat window.

Bot Message:
End of Battle Round

Other Battle Management Notes / Features:

• After each DJ completes a battle round, [bot] announces the following via the public chat window:  "@[dj name" - After # round(s), you're looking good with # battle points! PM battle|stats to [bot] for current standings."
• After each DJ completes all of his/her rounds, [bot] will announce to the room via public chat that the DJ has finished.  The announcement includes:  "@[dj name] Congrats! you finished the battle with #pts on #turns."
• After all DJ's have completed all battle rounds, [bot] will announce to the room via public chat that the battle has finished.  The announcement includes:  "That's it!  The battle is over! PM 'battle|stats' to [bot] to get results!"
• Any DJ who is participating in a battle will be removed from the battle if they leave the tables at any point before completing all battle rounds.  When this happens, the following message is made via the public chat window:  "@[dj name] left the battle early. That's a forfeit in my book! The odds of winning just improved for everyone else!"
• Note:  A DJ can leave the tables before the battle is complete without being removed from the competition if he/she has completed all of his/her rounds.

Note:  Commands listed in red above are only executable by pre-defined bot admins and/or room mods.

What Next?  What other features should [bot] have?  Let me know in the comments below!

~ b