A generic API for creating Plug.dj bots
Due to a Plug update, the original version of PlugAPI from npm no longer works. You will have to use this fork for now.
You'll need a few npm packages first. Run the following:
npm install node-uuid request uuid node-html-encoder cheerio ws
To connect, do this!
var PlugAPI = require('./plugapi'); // git clone (or unzip) into the same directory as your .js file. There should be plugapi/package.json, for example (and other files)
var ROOM = 'chillout-mixer-ambient-triphop';
var UPDATECODE = '$&2h72=^^@jdBf_n!`-38UHs'; // We're not quite sure what this is yet, but the API doesn't work without it. It's possible that a future Plug update will change this, so check back here to see if this has changed, and set appropriately, if it has. You can omit using it if you wish - the value as of writing needs to be '$&2h72=^^@jdBf_n!`-38UHs', and is hardcoded into the bot in the event it is not specified below.
// Instead of providing the AUTH, you can use this static method to get the AUTH cookie via twitter login credentials:
PlugAPI.getAuth({
username: 'xxx',
password: 'xxx'
}, function(err, auth) { // if err is defined, an error occurred, most likely incorrect login
if(err) {
console.log("An error occurred: " + err);
return;
}
var bot = new PlugAPI(auth, UPDATECODE);
bot.connect(ROOM);
bot.on('roomJoin', function(data) {
// data object has information on the room - list of users, song currently playing, etc.
console.log("Joined " + ROOM + ": ", data);
});
});
##Examples Here are some bots using this API. Check out how they did it!
Have a bot that uses the API? Let me know!
You can listen on essentially any event that plug emits. Many of the events also emit an alias event named after the ttapi version
// basic chat handler to show incoming chats formatted nicely
bot.on('chat', function(data) {
if (data.type == 'emote')
console.log(data.from+data.message)
else
console.log(data.from+"> "+data.message)
})
Here's an example for automatic reconnecting on errors / close events!
var reconnect = function() { bot.connect('coding-soundtrack'); };
bot.on('close', reconnect);
bot.on('error', reconnect);
Here's a list of events:
data:
user: [User object],
room: [Room object]
Example:
{ user:
{ profile:
{ username: 'bot',
status: 0,
language: 'en',
dateJoined: '2013-12-09T22:48:36.776000',
djPoints: 0,
fans: 2,
listenerPoints: 0,
avatarID: 'animal05',
id: '...',
curatorPoints: 0 },
following: [],
followers: [] },
room:
{ boothCycle: false,
ownerName: 'some user',
owner: '...',
ambassadors: { '...' }
id: 'chillout-mixer-ambient-triphop',
users: [ [Object], [Object] ],
djs: [ [Object], [Object] ],
media:
{ author: 'Killigrew',
cid: 'h2grXTuoSaQ',
format: '1',
duration: 368,
title: 'You || Chillout',
id: '1:h2grXTuoSaQ' },
playlistID: '52906884877b92238ad962fc',
admins: [ '...', '...' ],
custom: null,
lounge: null,
score: 1,
staff: { '...' : 3, '...' : 2 },
description: '...',
welcome: '...',
votes: { '...': 1, '...': 1 },
boothLocked: false,
mediaStartTime: '2013-12-10 02:00:02.418000',
currentDJ: '...',
name: 'Chillout Mixer Ambient + Triphop',
historyID: '...',
curates: { '...': true } } }
data:
fromID: 'user id'
message: 'message text'
from: 'username'
type: 'message type'
chatID: 'chat id'
type: 'chat'
Example:
{
fromID: 'xxxxxxxxxxxxxxxxxxxxxxxx',
message: 'hello world',
from: 'mnme',
type: 'chat',
chatID: 'xxxxxxxxxx'
}
data:
fromID: 'user id'
message: 'message text'
from: 'username'
type: 'emote'
chatID: 'chat id'
Example:
{ fromID: 'xxxxxxxxxxxxxxxxxxxxxxxx',
message: 'hello world',
from: 'mnme',
type: 'chat',
chatID: 'xxxxxxxxxx'
}
data:
id: 'user id'
type: 'userLeave'
Example:
{ data: { id: 'xxxxxxxxxxxxxxxxxxxxxxxx' }, type: 'userLeave' }
data:
username: 'username'
status: 0/1/2/3/4/5
fans: fans
listenerPoints: points from listeners
language: 'language'
avatarID: 'bud03'
id: 'xxxxxxxxxxxxxxxxxxxxxxxx'
curatorPoints: points from curators
djPoints: points from DJing
type: 'userJoin'
Example:
{ data:
{ username: 'mnme',
status: 0,
fans: 3,
listenerPoints: 164,
language: 'en',
avatarID: 'bud03',
id: 'xxxxxxxxxxxxxxxxxxxxxxxx',
curatorPoints: 0,
djPoints: 76 },
type: 'userJoin' }
sorry, only saw one time :(
data:
vote: 1/0
id: 'user id'
type: 'voteUpdate'
Example:
{ data: { vote: 1, id: 'user id' },
type: 'voteUpdate' }
data:
id: 'user id'
type: 'curateUpdate'
Example:
{ data: { id: 'xxxxxxxxxxxxxxxxxxxxxxxx' },
type: 'curateUpdate' }
data:
currentDJ: 'user id'
djs: [ [Object], [Object], [Object], [Object], [Object] ]
mediaStartTime: 'start time'
media:
title: 'song title'
format: 'x'
author: 'song author'
cid: 'xxxxxxxx'
duration: duration in seconds
id: 'format:cid'
playlistID: 'playlist id'
earn: true/false
historyID: 'id for song history'
type: 'djAdvance'
Example:
{ data:
{ currentDJ: 'xxxxxxxxxxxxxxxxxxxxxxxx',
djs: [ [Object], [Object], [Object], [Object], [Object] ],
mediaStartTime: '2012-11-28 21:12:28.674382',
media:
{ title: 'Freefire - Dataloss (Darth & Vader Remix)',
format: 'x',
author: 'Mateus Rossetto',
cid: 'xxxxxxxx',
duration: 332.935,
id: 'x:xxxxxxxx' },
playlistID: 'xxxxxxxxxxxxxxxxxxxxxxxx',
earn: true,
historyID: 'xxxxxxxxxxxxxxxxxxxxxxxx' },
type: 'djAdvance' }
data:
plays: times the dj played a song, id: 'user id'
plays: times the dj played a song, id: 'user id'
plays: times the dj played a song, id: 'user id'
plays: times the dj played a song, id: 'user id'
plays: times the dj played a song, id: 'user id'
type: 'djUpdate'
Example:
{ data:
[ { plays: 2, id: 'xxxxxxxxxxxxxxxxxxxxxxxx' },
{ plays: 13, id: 'xxxxxxxxxxxxxxxxxxxxxxxx' },
{ plays: 7, id: 'xxxxxxxxxxxxxxxxxxxxxxxx' },
{ plays: 10, id: 'xxxxxxxxxxxxxxxxxxxxxxxx' },
{ plays: 0, id: 'xxxxxxxxxxxxxxxxxxxxxxxx' } ],
type: 'djUpdate' }
There aren't that many functions implemented yet, and I'm too lazy to document each one yet (HALP?)....
Here's a list:
Connects to plug.dj and optionally joins a room.
string (optional)
The name of the room to join after succesful connection.
Join a room on plug.dj
string (required)
The name of the room to join.
callback (optional)
This is not a parameter!
bot.joinRoom('coding-soundtrack');
Sends a Message in the Chat.
string
The Message to send.
This is not a parameter!
bot.chat('Hello World!');
Woots the actual song.
callback (optional)
This is not a parameter!
bot.woot();
Mehs the actual song.
callback (optional)
This is not a parameter!
bot.meh();
Vote on the actual song with a string.
string (required)
Either 'up' or 'down', calls the appropriate function (woot() or meh()).
callback (optional)
This is not a parameter!
bot.vote('up'); //woot the song
bot.vote('down'); //meh the song
Change actual room information. Only available if you are the host.
string (required)
A (new) name for the room.
string (required)
The rooms description.
callback (optional)
This is not a parameter!
bot.changeRoomInfo('Hello World', 'This is a new description for my room.');
If you are in a room and you are host, you can change the room options with this function.
boolean (required)
Toggles the booths state (locked or unlocked).
boolean (required)
Is there a waitlist in this room?
integer (required)
Maximum Plays per DJ.
integer (required)
Limit DJs on the booth to this number (usually 5).
callback (optional)
This is not a parameter!
bot.changeRoomOptions(false, false, 1, 5);
Joins the DJ booth if there is a free place.
callback (optional)
This is not a parameter!
bot.joinBooth();
Leave the DJ booth.
callback (optional)
This is not a parameter!
bot.leaveBooth();
Removes a DJ from the DJ booth if possible. The user has to be in the booth and you need the permission to remove DJs from the booth.
callback (optional)
This is not a parameter!
bot.removeDJ('xxxxxxxxxxxxxxxxxxxxxxxx');
Skips the current song. You need to be DJ or have the permission to skip a song.
callback (optional)
This is not a parameter!
bot.skipSong();
Returns an object containing all the users currently in the room at the moment of calling. Identical to Plug.DJ's API.getUsers()
Returns array containing ambassadors currently in the room
The 'playlist' argument must be a playlist object, the type that is returned from getPlaylists(). Song id is the the id of the song you wish to move, position an integer of where in the playlist it should be moved to (0 = first).
this is a list of avatar names that can be used in user.set_avatar
- su01
- su02
- luclin01
- luclin02
- luclin03
- lazyrich
- revolvr
- anniemac
- halloween01
- halloween02
- halloween03
- halloween04
- halloween05
- halloween06
- halloween07
- halloween08
- halloween09
- halloween10
- halloween11
- halloween12
- halloween13
- lucha01
- lucha02
- lucha03
- lucha04
- lucha05
- lucha06
- lucha07
- lucha08
- monster01
- monster02
- monster03
- monster04
- monster05
- animal01
- animal02
- animal03
- animal04
- animal05
- animal06
- animal07
- animal08
- animal09
- animal10
- animal11
- animal12
- animal13
- bud01
- bud02
- bud03
- bud04
- bud05
- bud06
- bud07
- bud08
- bud09
- bud10
- bud11
- space01
- space02
- space03
- space04
- space05
- space06
##Misc
You can set your own custom logger for the API to use when it logs important events, such as errors or stack traces from the server.
The logger object must have a function called "log" that takes any number of parameters and prints them.
var prompt = new Prompt();
bot.setLogObject(prompt);
Since Plug.dj cuts off chat messages at 250 characters, you can choose to have your bot split up chat messages into multiple lines:
var bot = new PlugAPI(auth, UPDATECODE);
bot.multiLine = true; // Set to true to enable multiline chat. Default is false
bot.multiLineLimit = 5; // Set to the maximum number of lines the bot should split messages up into. Any text beyond this number will just be omitted. Default is 5.
You can start up a TCP server the bot will listen to, for remote administration
Example:
bot.tcpListen(6666, 'localhost');
bot.on('tcpConnect', function(socket) {
// executed when someone telnets into localhost port 6666
});
bot.on('tcpMessage', function(socket, msg) {
// Use socket.write, for example, to send output back to the telnet session
// 'msg' is whatever was entered by the user in the telnet session
});