Get Started

sharedferret edited this page May 22, 2012 · 10 revisions

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 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 file, since it hasn't been updated in a while).

config.json is written in JSON, a file format that's easily readable by JavaScript files. When editing this file, remember that every quotation mark, comma, and curly brace are important to keeping the file readable, so don't remove them.

####Basic Info The first thing you'll need for this is an account for your 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 auth, userid, and roomid values for the config file. Also, add a short nickname for your bot under botname.

####Database If you're not planning on using a database with your bot, set database.usedb to FALSE and skip ahead to the 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 logchat to 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's website. If you'd like to use the service, set useapi to TRUE and provide the key from next to lastfmkey.

####TCP TCP functionality is being phased out in favor of the bot's HTTP-based API. Set usetcp to FALSE unless you really want to use raw TCP.

####HTTP The bot has a built-in API that can respond to a variety of commands over HTTP. To enable this functionality, set usehttp to TRUE, select a port to use, and set host to your computer/server's internal IP address.

####Responses 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 NONE, VOTE, CHAT, or DICE.

####Enforcement To have the bot enforce room rules, set enforceroom to TRUE.

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 SONGS or MINUTES.

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.

####Maintenance 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

node sparkle.js

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)