Clone this wiki locally
Step 1: Prerequisites
This bot is written in Node.JS. To run it, you'll need to have Node.JS installed on your computer or server. The Node.JS website has detailed installation instructions. This bot has been tested on versions 0.4.x and 0.6.x, so either should work.
If you want to use the database features of the bot, you'll need to install a MySQL server and have it running on your computer or server. This can be downloaded from the MySQL site.
Step 2: Get the source
Next, you'll need a copy of the bot. After installing node.js, open up a Terminal window/command prompt, make a folder for the bot, and type:
npm install sparklebot
This will download the most recent copy of Sparkle Turntable Bot and all dependencies (ttapi, request, xml2js, mysql). Navigating to this folder and typing
npm update will update Sparkle and all dependencies to their latest versions.
(Alternative) Install manually
If you prefer using the GitHub version of Sparkle, download a copy of the source and unzip it. Remember where you put it, since you'll need to do some work in that folder to run your bot.
The Sparkle Turntable Bot requires a few Node.js modules to work properly. The easiest way to install these is using
npm, Node.JS's built-in package manager.
This step requires a terminal window or command prompt window. In OS X, open Terminal.app. In Windows, go to Start -> Run and type
cmd. In Linux, well... you know how to get a bash window open.
Navigate to the directory with the bot's source code (you can use
cd to change directories), and then enter these commands one by one:
npm install ttapi npm install request npm install xml2js npm install mysql
Step 3: Set up the database (optional)
If you want a database connected to your bot, you'll need an MySQL account and database for the bot to use. Create a user account for your bot, and set up a new database for the bot to use.
The Users, Chatlog, and Songlist tables will be created by the bot the first time it runs. If you want functionality such as the holiday greeting table or Scott Pilgrim/catfacts quotes, import those to your newly created database using the provided SQL files.
Step 4: Edit the config
Now it's time to customize your bot. Rename config.sample.json to config.json. Open the config.json file using the text editor of your choice (OS X Users: Don't use the included SparkleConfig.app file, since it hasn't been updated in a while).
The first thing you'll need for this is an account for your TT.fm bot. Create an account for your bot, then have it join your Turntable room through a web browser. Next, use this bookmarklet to get the
roomid values for the config file. Also, add a short nickname for your bot under
If you're not planning on using a database with your bot, set
FALSE and skip ahead to the last.fm section. Otherwise, set it to
TRUE. Provide the database name you'd like the bot to use next to
dbname. If you'd like the bot to log chat message, set
TRUE. Next, provide the table names you'd like the bot to use (it is not necessary to create these yourself, except for the holiday table, which we'll do in a second). Finally, supply a MySQL username and password for the bot to use.
The next step is to import the provided SQL tables to the database you're using. These SQL files are located in the
SQL Commands/ folder. They can be imported using the command
mysql -u myuser -p databasename < [Filename].sql
or by importing them with an application like phpMyAdmin.
The bot can use the Last.FM API to retrieve similar song and artist data for the current song. This requires an API key from last.fm's website. If you'd like to use the service, set
TRUE and provide the key from last.fm next to
TCP functionality is being phased out in favor of the bot's HTTP-based API. Set
FALSE unless you really want to use raw TCP.
The bot has a built-in API that can respond to a variety of commands over HTTP. To enable this functionality, set
TRUE, select a port to use, and set
host to your computer/server's internal IP address.
This section determines how your bot reacts in chat. Enabling
respond will allow your bot to respond to commands in chat.
reportsongstats allows your bot to report the awesomes, lames, and snags after every song.
welcomeusers allows your bot to welcome users in chat.
welcomepm sends users a PM on join.
alwayspm, if true, will PM the
pmgreet message to users every time they join. If false, the bot will only send a PM if the user hasn't been seen in at least 36 hours.
pmgreet is the PM greeting sent if
welcomepm is enabled.
greeting is the welcome message used if
welcomeusers is enabled.
sing will allow the bot to sing along to certain songs (using the singalong.js file)
rules are a short description of rules for your room.
consolelog will log all events in the console. Don't enable this if you're running the bot for an extended period of time.
bonusvote determines when the bot will awesome a song. This can be set to
To have the bot enforce room rules, set
waitlist will create a waitlist/queue in your room.
songstoplay indicates how many songs a user can play before they must step down.
stepuprules determine if a user needs to wait to step up after playing music. The
waittype can be in either
ffarules determine when spots are FFA (free-for-all).
multiplespotffa will allow anyone to step up if 2 or more DJ spots are open, while
timerffa will let anyone step up if a certain amount of time has passed.
autorejoin lets the bot automatically rejoin a room if it has been booted from that room.
Step 5: Try it out
Now that everything's set up, you can test the bot. Open up a terminal window/command prompt, navigate to your working directory (where the source files are), and type
With any luck, the bot should pop up in your room.
Step 6: Long-term use
On *nix machines, this command will start the bot in the background and redirect all output to
nohup.out, allowing you to close your terminal window without killing the bot:
nohup node sparkle.js &
(There's a way to do this on Windows machines, but I have no idea what it is)