A generic API for creating Plug.dj bots
I will no longer be developing this fork of plugapi, due to the continued updates Plug keeps making that break it. I have written a new API that uses phantomjs to create a virtual browser to allow the use of Plug's official API. You can get it here: https://github.com/atomjack/plugbotapi
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:
cd plugapi && npm install
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';
//Plug changed the update code again, as well as how it is stored, which broke my static method which could be used to get it. So, for now, it must be hardcoded.
Current update code: h90
// 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, '4w@fWs$');
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);
});
PlugAPI.getUpdateCode(auth, ROOM, function(error, updateCode) {
if(error === false) {
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);
});
} else {
console.log(error);
}
});
});
It's not necessary to call getAuth and getUpdateCode every time the bot is run. Plug stores the auth cookie in your browser for 6 months, so it's possible you'd never need to change it. However, every time Plug does a system update, the updateCode changes. The above example is the simplest way of connecting the bot. A better way would be to store the auth cookie and have your bot load it on startup (only running getAuth when it hasn't been saved yet). For updateCode, I haven't yet figured out how to make the bot aware if the updateCode is incorrect.
##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');
Moves a DJ to a new position in the waitlist. Waitlist numbering beings with position 1.
string (required)
integer (required, range: 1-50)
callback (optional)
This is not a parameter!
bot.moveDJ('xxxxxxxxxxxxxxxxxxxxxxxx',4);
string (required) - The user id of the currently playing DJ.
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, port) {
// 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
// 'port' is the port the message came in on (to differentiate multiple listeners)
});