plug.dj has an API to empower Javascript developers to write extensions. The API is an event dispatcher that triggers after various events occur that developers might want to listen for. It’s simple to use and what you do with it is up to your imagination!

OVERVIEW

There are two different parts to the API. There are functions that return various data, and there is an event dispatching engine. API is a reference on the global scope of the document so you can access it easily from your extensions.

DATA

The data calls are as follows:

API.getAudience()

Returns an Array of user objects of all the users in the audience (not including DJs).

API.getDJs()

Returns an Array of user objects of the DJs. The first DJ in the array in the current DJ, and the rest are in order to the last DJ.

API.getUsers()

Returns an Array of user objects of the DJs and audience. The first DJ in the array in the current DJ, and the rest are in order to the last DJ, and the audience is sorted by alphanumeric.

API.getUser(id)

Returns the user object of a specific user.

API.getSelf()

Returns the user object of the logged in user.

API.getStaff()

Returns an Array of user objects of the room’s staff members that are currently in the room. Each user has property “permission” which is an integer between 1-5. 5 = Host, 4 = Co-Host, 3 = Manager, 2 = Bouncer, 1 = Featured DJ.

API.getAdmins()

Returns an Array of user objects of the Admins currently in the room.

API.getAmbassadors()

Returns an Array of user objects of the Ambassadors currently in the room.

API.getHost()

Returns the user object of the room host if they are currently in the room. Null otherwise.

API.getMedia()

Returns the media object of the current playing media.

API.getWaitList()

Returns an Array of user objects of users currently on the wait list.

API.getRoomScore()

Returns a room score object with the properties positive, negative, curates, and score.

API.sendChat(message)

Send a chat message.

API.waitListJoin()

Joins the wait list.

API.waitListLeave()

Leaves the wait list.

API.moderateForceSkip()

If you have permission, this will force skip the current DJ.

API.moderateAddDJ(id)

If you have permission, adds a user to the dj booth or wait list by passing that user’s id. Users who do not have an active playlist with one item in it cannot be added.

API.moderateRemoveDJ(id)

If you have permission, removes a DJ from the booth or wait list by passing that user’s id.

API.moderateKickUser(id, reason)

If you have permission,  kicks a user from the room for 60 minutes. You can include a reason message to avoid showing the dialog.

API.moderateBanUser(id, reason)

If you have permission,  permanently bans a user from the room forever. You can include a reason message to avoid showing the dialog.

API.moderateDeleteChat(cid)

If you have permission, delete an offensive chat message by its chat id.

API.moderateSetRole(userID, permission)

If you have permission, you can set another user’s permission level. Valid values for permission are 0-4. 4 = Co-Host, 3 = Manager, 2 = Bouncer, 1 = Featured DJ, 0 = None.

 

EVENTS

To add or remove an event listener, pass the name of the event and the function that will be called when the event occurs.

API.addEventListener(event, callback);
API.removeEventListener(event, callback);

These are all the events that the API dispatches. The event names are all on the API object. Here’s an explanation of each one and what is passed to the callback function.

CHAT
USER_SKIP
USER_JOIN
USER_LEAVE
USER_FAN
FRIEND_JOIN
FAN_JOIN
VOTE_UPDATE
CURATE_UPDATE
ROOM_SCORE_UPDATE
DJ_ADVANCE
DJ_UPDATE
VOTE_SKIP
MOD_SKIP
WAIT_LIST_UPDATE

CHAT
This is called when an incoming chat arrives. It passes a chat object.

USAGE
API.addEventListener(API.CHAT, callback);
function callback(data)
{
data.type
// "message", "emote", "moderation", "system"
data.from
// the username of the person
data.fromID
// the user id of the person
data.message
// the chat message
data.language
// the two character code of the incoming language
}
———————————————————————————

USER_SKIP
This is called when the current DJ skips their own turn. It passes the user object of the dj who skipped.

USAGE
API.addEventListener(API.USER_SKIP, callback);
function callback(user)
{
alert(user.username + " skipped their turn");
}

———————————————————————————

USER_JOIN
This is called when a user joins the room. It passes a user object.

USAGE
API.addEventListener(API.USER_JOIN, callback);
function callback(user)
{
alert(user.username + " joined the room");
}

———————————————————————————

USER_LEAVE
This is called when a user leaves the room. It passes a user object.

USAGE
API.addEventListener(API.USER_LEAVE, callback);
function callback(user)
{
alert(user.username + " left the room");
}

———————————————————————————

USER_FAN
This is called when somebody becomes your fan. It passes a user object.

USAGE
API.addEventListener(API.USER_FAN, callback);
function callback(user)
{
alert(user.username + " is now your fan");
}

———————————————————————————

FRIEND_JOIN
This is called when somebody you are a fan of joins the room. It passes a user object.

USAGE
API.addEventListener(API.FRIEND_JOIN, callback);
function callback(user)
{
alert("Your friend " + user.username + " just joined the room");
}

———————————————————————————

FAN_JOIN
This is called when somebody who is your fan but you are not a fan of joins the room. It passes a user object.

USAGE
API.addEventListener(API.FAN_JOIN, callback);
function callback(user)
{
alert("Your fan " + user.username + " just joined the room");
}

———————————————————————————

VOTE_UPDATE
This is called when somebody in the room (including you) votes. It passes an object with a user object and the vote, -1 for negative, 1 for positive.

USAGE
API.addEventListener(API.VOTE_UPDATE, callback);
function callback(obj)
{
var vote = obj.vote == 1 ? "woot" : "meh";
alert(obj.user.username + " voted " + vote);
}

———————————————————————————

CURATE_UPDATE
This is called when somebody in the room (including you) adds what is currently playing to their collection. It passes the user object who added it.

USAGE
API.addEventListener(API.CURATE_UPDATE, callback);
function callback(obj)
{
var media = API.getMedia();
alert(obj.user.username + " added " + media.author + " - " + media.title);
}

———————————————————————————

ROOM_SCORE_UPDATE
This is called whenever the room score changes and it passes a room score object with the properties positive, negative, curates, and score.

USAGE
API.addEventListener(API.ROOM_SCORE_UPDATE, callback);
function callback(obj)
{
alert(obj.positive + " woots, " + obj.negative + " mehs, " + obj.curates + " adds, score=" + obj.score);
}

———————————————————————————

DJ_ADVANCE
This is called when the dj advances to the next play. It passes an object with the array of user objects and the current media object.  The first DJ in the array is the current DJ, and the remaining ones are waiting to play in that order. This is also called when the last DJ leaves the booth, in which case it passes null.

USAGE
API.addEventListener(API.DJ_ADVANCE, callback);
function callback(obj)
{
if (obj == null) return; // no dj
var str = "";
var currentDJ = obj.dj;
str += currentDJ.username;
var total = currentDJ.djPoints + currentDJ.listenerPoints + currentDJ.curatorPoints;
str += " points: " + total;
str += ", fans: " + currentDJ.fans;
str += " || " + obj.media.author + " - " + obj.media.title;
alert(str);
}

———————————————————————————
DJ_UPDATE
This is called when the djs in the booth change, whether it somebody joins, leaves, etc. It returns an array of user objects of the DJs in order from playing to 5th position.

USAGE
API.addEventListener(API.DJ_UPDATE, callback);
function callback(djs)
{
var len = djs.length;
for (var i = 0; i < len; ++i)
{
console.log(djs[i]);
}
}

———————————————————————————
WAIT_LIST_UPDATE
This is called when the users in the wait list change, whether somebody joins, leaves, is removed, or is added to the booth (and so removed automatically). It returns an array of the user objects in order from beginning to last in the wait list.

USAGE
API.addEventListener(API.WAIT_LIST_UPDATE, callback);
function callback(users)
{
var len = users.length;
for (var i = 0; i < len; ++i)
{
console.log(users[i]);
}
}

———————————————————————————

VOTE_SKIP
This is called when the room votes down enough to skip the curent DJ. Null is passed.

USAGE
API.addEventListener(API.VOTE_SKIP, callback);
function callback()
{
alert("The room has voted to skip");
}

———————————————————————————
MOD_SKIP
This is called when a moderator force skips the current DJ. It passes the username of the moderator.

USAGE
API.addEventListener(API.MOD_SKIP, callback);
function callback(username)
{
alert(username + " has skipped the current DJ");
}