#Sparkle Turntable Bot
A customizable Turntable.fm bot.
This bot is still relatively early in development, and some features are developed for/catered to the Indie/Classic Alt room, and may not apply to all rooms. Please report any bugs you find.
NOTE: If you're having problems with config.json, please run your config.json file through a JSON validator such as http://jsonlint.com/.
To run the bot, you'll need the following installed:
- node.js (http://nodejs.org/)
- ttapi module for node.js (npm install ttapi)
- request module for node.js (npm install request)
- (Optional) mysql module for node.js (npm install mysql)
- (Optional) mysql server instance (http://www.mysql.com/)
- Fill out the config.json file (instructions here) with your bot account's user ID, auth code, target room ID, admin ID info, and other options
- If you do not plan to use the database features or do not want to install mysql, set database.usedb to FALSE
- If you want your bot to enforce room rules, fill out the enforcement section; otherwise, set enforcement.enforceroom to FALSE
- If you plan on using a database, create new tables using the .sql files provided (the songlist, userlist, and chatlog tables will be created for you)
Finally, run your bot using the following command in a console/terminal/command prompt:
node sparkle.js
Use this command to run your bot in the background:
nohup node sparkle.js &
A keepalive shell script is included to allow the bot to run permanently. (Note: if you use this, do watch the nohup.out file to ensure the bot is continuing to work properly)
nohup ./sparkle.sh &
The bot can:
- Respond to a set of commands in chat and through turntable's new PM system
- Awesome songs based on various systems
- Log vote, chat, song, room events in the console
- Report song stats in chat after each song
- Welcome users to the room via chat and PM
- Enforce room rules regarding song limits and timeouts before a person can DJ again
- Log song statistics and chat entries in a MySQL database
- Receive and respond to instructions via TCP
- Manage a waitlist/queue for a room
- Keep track of the mood and/or theme of a room (set by admins)
The bot can awesome songs based on one of four modes. These modes can be set in the config.js file prior to running the bot.
- NONE: The bot will never awesome
- VOTE: The bot awesomes when a vote threshold is met (# of awesomes)
- CHAT: The bot awesomes when enough people say a bonus phrase
- DICE: The bot awesomes if the current DJ rolls a 4 or higher using /roll
- AUTO: The bot auto-awesomes
The bot can enforce a variety of room rules, including:
- How many songs a DJ can play before they must step down
- How long a DJ must wait (songs or time) before stepping up again
- Whether those DJs can step up again if multiple DJ spots are open
- Whether those DJs can step up again if a spot is open for a certain amount of time
The bot uses a mysql database to log/retrieve some information. The bot can log song data, user information (id/name), and keep a chatlog. This project includes several .sql files (currently, these files contain a list of cat facts and holidays). If you enable the useDatabase flag, be sure to create new tables in your bot's database using these .sql files.
- DJ timers for AFK monitoring
- Graphical frontend to set config options
- SparkleConfig.app generates incorrect JSON file if every field not filled in
- "waitdjs" displays improper formatting in MINUTES wait-to-DJ mode
- Bot may not DJ properly
- Minutes-based wait-to-step-up mode may not work if only one DJ in room
Feel free to contact me anytime via twitter.
The bot will respond to these commands in chat in a Turntable.fm room.
-
.sparklecommands - Displays a list of commands supported by this bot.
-
help, commands - Displays a list of commands available in the Indie/Classic Alt 1+Done room
-
meow, pm me - The bot will send you a Private Message so you can send private requests to it
-
bonus - Adds a bonus point to a song (if enabled). When a song has enough bonus points, the bot will awesome. Other phrases that add a bonus point: tromboner, meow, /bonus, good song, great song, nice pick, good pick, great pick, dance, /dance
-
points - Displays what is needed for the bot to awesome the song (number of awesomes, points, etc).
-
/roll - Dice roll
-
CAN YOU FEEL IT!? - Bot responds with "YES I CAN FEEL IT!"
-
I enjoy that band. - Bot responds with "Me too!"
-
.owner - Outputs a bot owner response configurable in config.js
-
.source - Provides a link to this GitHub project
-
ping - Responds to the issuing user that they are still in the room.
-
reptar - Responds with a variant of "rawr!"
-
rules - Displays the room rules (defaults to Indie/Classic Alt 1 & Done room rules).
-
hugs meow - Hugs the issuing user back in chat.
-
platforms - Lists the number of users on each platform (PC/Mac/Linux/iPhone/Chrome) in the room.
-
songinfo - Displays mid-song stats (awesomes, lames, snags). Useful for iPhone users.
-
.similar - Gives three similar songs to the one playing using last.fm's database.
-
.similarartists - Gives four similar artists to the one playing using last.fm's database.
-
platforms - Returns the number of each type of computer (pc, linux, mac, chrome, iPhone) in the room.
-
mood, .mood, themood - returns the current mood of the room (set by admins)
-
theme, .theme, thetheme - returns the current theme of the room (set by admins)
(these are all currently disabled, as the waitlist functionality is turned off for this particular instance of this bot)
-
waitdjs - Displays a list of DJs that must wait before stepping up again, and how long they must wait.
-
.remaining, songsremaining - Shows a DJ how many songs they have remaining before they must step down.
-
djinfo - Displays a list of current DJs and how many songs they have remaining before they must step down.
-
any spots opening soon?, anyone stepping down soon? - Displays the next DJ to step down, and how many songs they have remaining.
(also currently disabled, see above)
-
.add, .addme, +q - Adds user to waitlist/queue
-
.rem, .remove, .removeme - Removes user from waitlist/queue
-
shiftq, .shiftq, shiftqueue, .removefirst - Removes the first user from the waitlist/queue (e.g. if they're gone/AFK)
-
.position - Shows your position in the waitlist/queue
-
.pq, printqueue - Prints the waitlist/queue
-
stats - Gives overall room statistics (number of songs played, number of awesomes/lames, averages).
-
past24hours - Displays the 3 most-awesomed DJs in the past 24 hours in the room.
-
mypast24hours - Displays your stats in the room over the past 24 hours.
-
pastweek - Displays the five most-awesomed DJs in the past week in the room.
-
mypastweek - Displays your stats in the room over the past 7 days.
-
bestplays - Returns the three song plays with the most awesomes logged by the bot.
-
bestdjs - Returns the three DJs with the most awesomes logged by the bot.
-
worstdjs - Returns the three DJs with the most lames logged by the bot.
-
mostplayed - Returns the three most-played songs logged by the bot.
-
mostsnagged - Returns the three songs with the most cumulative snags.
-
mostawesomed - Returns the three most awesomed (cumulative) songs logged by the bot.
-
mostlamed - Returns the three most lamed (cumulative) songs logged by the bot.
-
mystats - Returns the user's stats in the room (songs played, awesomes, lames, averages)
-
mymostplayed - Returns the user's three most played songs.
-
mymostawesomed - Returns the user's three most awesomed (cumulative) songs logged by the bot.
-
mymostlamed - Returns the user's three most lamed (cumulative) songs logged by the bot.
-
dbsize - Returns the number of songs logged in the database.
-
catfact, .catfact, catfacts - Returns a cat fact!
-
.weather [zip] - Returns the current weather conditions at the specified zip code. This call uses the Yahoo! YQL service. Note: This service is rate-limited to 1,000 calls per hour.
-
.find [zip] [thing] - Returns the nearest location of a matching business to the zip code. This call uses the Yahoo! YQL service. Note: This service is rate-limited to 1,000 calls per hour.
-
pastnames [name] - Returns all names that the given user has gone by. Note: Currently, this call only registers names used by DJs that have played a song in the room.
These commands can only be performed by admins of the bot.
-
.a - Tells the bot to awesome the current song.
-
.l - Tells the bot to lame the current song.
-
.q - Tells the bot to snag the current song (add to the bot's queue).
-
skipwait [user] - (Enforcement only) Removes the user from the past DJ list so they can step up again.
-
pulldj - Pulls a DJ off stage after their song.
-
pullcurrent - Pulls the current DJ off stage during their song.
-
setmood [mood] - sets the mood of the room
-
settheme [theme] - sets the theme of the room
-
meow, step up - The bot steps up to DJ.
-
meow, step down - The bot steps down from the decks.
-
meow, shut down - The bot shuts down, terminating the process.
-
meow, restart - If running through the .sh script, the bot will restart. Otherwise, the bot will shut down.
These commands can be performed via TCP access to the bot.
-
speak [text] - The bot speaks the text in chat.
-
boot [userid] - Boots a user from the room.
-
help - Displays a list of commands.
-
online - Displays the number of people in the room.
-
.a - The bot will awesome the current song.
-
.l - The bot will lame the current song.
-
step up - The bot will step up to DJ.
-
step down - The bot will step down from the decks.
-
pulldj - If a user has played a song and has not yet stepped down, this command will remove them from the decks.
-
exit - Ends the TCP connection.
-
shutdown - Initiates the bot's shutdown sequence.