CMBot

A full featured bot for turntable.fm

Installation

npm install cmbot

Features

If desired, your bot will enforce a queue, as well as a configurable number of songs each DJ is allowed to play before the bot escorts them down, to give others a chance to DJ.
If a user on the queue leaves the room, the bot automatically marks them afk, skipping them when announcing who is next in the queue, and automatically marking them unafk when they return. If they don't return within 5 minutes, however, they are removed from the queue.
Can automatically add a song to it's queue if it gets enough votes, and mods can make the bot DJ. When the bot steps up to the decks, it will randomly put a song at the top of it's queue, and again once it finishes playing the song. This way it always plays a random song.
Modpm feature lets mods send a message that goes out to all the other mods currently in the room. Mods can also choose to participate in mod chat when they are out of the room (a mod must enable this with the /remotechat command, first).
Automatically awesomes a song if it gets 5 awesomes or 20% of the room's population awesomes - whichever is lowest.
Automatically scrobble songs played to last.fm.
Automatically save song plays to a mysql or sqlite database.
Get last.fm tags for the currently playing song or any artist.
Ban any artist from being played in the room. If a DJ attempts to play any song by a banned artist, the bot will immediately escort the DJ down from the decks.
Shitlist a user, causing the bot to automatically kick them from the room when they join. Keep those trolls away!
Warn a user that their song is either not loading or is off genre for the room, and that they have 15 seconds to skip the song or else the bot will escort them down from the decks.
Autodj - if there are 2 open spots on the decks, the bot will wait 1 minute before automatically stepping up to DJ. Once the decks fill up and someone adds themselves to the queue, however, the bot will automatically step down (unless the bot is the one whose song is playing when that happens - in which case it will step down after it's song is over). Also, this can be disabled, so the bot never autodj's.

Triggers

Triggers are special commands any mod can set that will make the bot say a certain phrase. Any user can activate a trigger (to make the bot say the phrase), either in chat or PM. See trigger, triggerban and triggerlimit.

I'd be happy to help you get set up if you run into problems. You can usually find me in the Chillout Mixer.

Setup

Obviously the bot should be a mod of the room it will be in, to be useful.

To get the bot's auth, userid, and roomid, see this link. Use the bookmarklet after logging in to turntable as the user the bot will run as, then copy and paste the auth, roomid and userid values.

The bot will create two json files (in the same directory as your script) to store state information, "settings.json" (stores the queue, shitlisted users, triggers, etc) and "djs.json" (id's of users who have dj'd, so a user will only get the introductory PM once).

I'd suggest creating a new directory for your bot, perhaps using the name of your bot. Create a new .js file in this directory (perhaps also with the name of your bot, ie chilloutmixerbot.js), consisting of the following content. Set the 3 bot parameters (auth, userid & roomid) and whatever else to have the bot behave as you see fit. Run your .js file and the bot should start running.

var cmbot = require('cmbot');
var mybot = new cmbot({
	// This will put the settings & dj files in the same directory where this script is
	settings_file: __dirname + '/settings.json', 
	dj_file: __dirname + '/djs.json',
	
	bot: {
		auth: 'xxxx',
		userid: 'xxxx',
		roomid: 'xxxx'
	},
	modules_directory: __dirname + '/modules',
	autoload_modules: true, // If set to true, scans the modules_directory for any .js files and loads any custom commands/events they contain
	queue_enabled: true, // Set to false to never use the queue.
	autodj: true, // Automatically DJ if 2 spots open up.
	snag_threshold: 10, // How many votes a song must get for the bot to add it to it's queue.
	set_limit: 4, // How many songs each person can play before they have to step down from the decks. Set to false for unlimited.
	// If either of the following are set to false, only awesome for the other. If both are set to false, never autobop. If both are set, autobop for whichever is lowest.
	autobop_threshold_number: 5, // How many other users must awesome before the bot awesomes
	autobop_threshold_percentage: 20, // The percentage of the room's population that must awesome before the bot awesomes
	master_userid: ['xxx'], // Who runs the bot should have extra privileges. Put your userid here. Can be a single userid (a string) or an array of them.
	ffa: [5], // Array of days of the week for free for all. Sunday = 0, Monday = 1, etc. Set to false for none.
	ffa_text: 'It\'s Free For All Friday! No Queue today.', // The bot will display this when someone tries to manipulate or show the queue on an FFA day. 
	timezone: 'PST', // The default timezone for modpm
	modpm_superusers: true, // Set to false to exclude superusers from modpm
	allow_mobile_djs: true, // Set to false to require users to be whitelisted in order to DJ from a mobile device (mods are exempt)
	lastfm: {
		enabled: false,
		username: '',
		password: '',
		api_key: '',
		api_secret: '',
		session_key: false,
		earliest_scrobble: '' // If you want /plays to add that the number of plays shown is from the date of your first scrobble, put it here, and it will append it ("since _____")
	},
	scrobble: true, // Set to false to not have the bot scrobble tracks to last.fm
	playsMode: 'lastfm', // use either 'lastfm' or 'mysql' or 'sqlite'
	songkick: {
		api_key: '' // Get an API key here: http://www.songkick.com/developer/
	},
	google: {
		url_shorten_api_key: 'AIzaSyCgS_W9UZYBhl3d8cLxxPYo1IaX6WzwJbc' // Go ahead and use this api key
	},
	mysql: {
		enabled: false, // Change to true and fill out details below to enable mysql logging of song plays
		host: '',
		database: '',
		user: '',
		password: ''
	},
	sqlite: {
		enabled: false, // Set to true to log all song plays to a sqlite database
		file: __dirname + '/mybot.db'
	},
	remotechat: true, // Set to false to disable remote mod chat

	/*
	 * Messages:
	 * This should be an array of text that the bot will say in the chat room periodically, such as reminding 
	 * users of the rules, how the queue works, etc.
	 */
	messages: [
		'Welcome to room XXXXXX! Let\'s play some tunes!'
	],
	
	/*
	 * Sets how often the messages should display, in minutes. After the bot starts up, it waits the interval time,
	 * then speaks the first message (in the array above) out into chat. It then waits the interval time again until 
	 * displaying the next message in the array (if there is one). So, the amount of time between each time a 
	 * specific message is displayed is dependent on both the message interval (defined below) and the number of 
	 * different messages in the array. If there are two messages, and the interval is 15 minutes each message 
	 * will be displayed every 30 minutes - the first one 15 minutes after the bot starts, and the next one 15 
	 * minutes later, then the first one in another 15 minutes, etc.
	 */
	message_interval: 15, // Number of minutes between each informational message
	
	// index of which messages should be hidden when it's FFA (free for all) mode (if the queue is disabled, 
	// this setting doesn't do anything - every message will display)
	messages_hide_ffa: [], 
	
	/*
	 * The first time a user dj's in your room, you can have the bot PM them an introductory message, 
	 * for instance to remind them of what type of music is welcome in the room. to disable, just set this to false.
	 */
	new_dj_message: 'Please play some good music here.',
	 
	twitter: {
		consumer_key: 'xxxx',
		consumer_secret: 'xxxx',
		access_token_key: 'xxxx',
		access_token_secret: 'xxxx',
		tweet_songs: false, // Set this to true to make the bot tweet each song play
		tweet_text: '%djname% is spinning \'%song%\' by %artist% in the %roomname%: %roomurl%'
	}
});

Dynamic Modules

You can load custom modules at runtime that contain custom commands and/or events, using the /loadmodule command. In order to use custom modules, however, make sure you defined the modules_directory setting in your bot's .js file. In the example given above, simply create a modules directory in the same directory your bot's .js file is located, and put your modules there.

You can also have your bot autoload any modules it finds by setting the autoload_modules option to true (see the setup example above).

Please note:If you have previously used the addCommand or on methods to add custom commands/events, please switch to using dynamic modules as those methods are deprecated and will be removed in a future version.

Custom Commands

Your custom module can contain one or more custom commands that your bot will respond to. Simply create a .js file and place it in your modules directory (which you defined in the modules_directory option). As an example, create the file beer.js in your modules directory with the following contents:

var customCommands = {
	name: 'beer', // This is what the bot will respond to (ie, /beer)
	command: function(options) {
		if(!options.pm) {
			var user;
			if(options.arg != '') {
				var u = options.cmbot.getUserByName(options.arg);
				user = u === false ? options.arg : '@' + u.name;
			} else {
				user = '@' + options.cmbot.users[options.userid].name;
			}
			options.cmbot.bot.speak("/me taps a keg and gives " + user + " a cold one! *cheers* :be

Cmbot

Install / Use

README