plug.dj api page

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.

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.getModerators()
Returns an Array of user objects of the moderators currently in the room.

API.getSuperUsers()
Returns an Array of user objects of the Super Users 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.

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
DJ_ADVANCE
DJ_UPDATE
WAIT_LIST_UPDATE
VOTE_SKIP
MOD_SKIP

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);
}

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

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”);
}