YouTube WebSocket API


#1

To allow for the transfer of data between the YouTube module and a control panel, such as the PhantomBot YouTube Player, an API is made available that may be accessed via WebSockets. The WebSockets implementation follows RFC6455, the standard WebSocket protocol definition. All communication to and from the WebSocket is in JSON format.

API Endpoint
The API is provided on the server that PhantomBot runs on and runs on the configured baseport plus three. For example, if your baseport is configured to 25000:

http://localhost:25003

Player Interface to WebSocket

Authentication
Prior to using any of the available API calls, an authentication packet must be delivered. Send a JSON object in the following format upon successful connection to the WebSocket:

{ "authenticate : "authentication_key" }

The authentication_key is found in the botlogin.txt as the ytauth value.

Upon recept of the packet, the API will return a JSON object to indicate if authentication was successful:

{ "authresult" : true/false }

YouTube Player Ready
To let the YouTube Player module in PhantomBot know that the interface has been connected and the YouTube Player API has started, the following JSON data is to be passed:

{ "status" : { "ready" : true | false } }

Note that if at any time the YouTube Player API is not ready, that the status should be passed as false.

YouTube Player State
The YouTube Player module in PhantomBot expects to know what state the YouTube Player API provided by Google is in so that it may know when the interface is connected and to know when to play the next song. This data is to be provided in the following JSON format, noting what the numerical values map to; NEW(-2), UNSTARTED(-1), ENDED(0), PLAYING(1), PAUSED(2), BUFFERING(3), CUED(5), KEEPALIVE(200):

{ "status" : { "state" : integer value } }

The value is to be determined by the state returned by the Google YouTube Player API. For more information, please review the YouTube IFrame Player API.

The Player Module will request to play songs on the NEW and ENDED states.

Current Song
To alert the Player Module to the current song being played:

{ "status" : { "currentid" : "YouTube ID" } }

The YouTube ID is to the be the YouTube ID of the song.

Interface Volume
To alert the Player Module to changes in the volume on the interface:

{ "status" : { "volume" : integer value } }

Request Song and Play Lists
To request the song list or current playlist from the Player Module:

{ "query" : "songlist" }
{ "query" : "playlist" }

Delete a Song Request or Playlist Song
To request the Player Module to remove a file from the song list or current playlist:

{ "deletesr" : "YouTube ID" }
{ "deletepl" : "YouTube ID" }

Skip Currently Playing Song
To request the Player Module to skip to the next song:

{ "command" : "skipsong" }

Steal (Bookmark) Song to Current Playlist
To request the Player Module to steal (bookmark) the current song to the current playlist:

{ "command" : "stealsong"}

To request that a specific song be stolen (bookmarked):

{ "command" : "stealsong", "youTubeID" : "YouTube ID" }

Add a Song Request
To add a song to the request list:

{ "command" : "songrequest", "search" : "search string" }

WebSocket to Player Interface

Request Interface to Play a Song
The following is sent from the WebSocket when a song is to be played:

{ "command" : { "play" : "YouTube ID", "duration" : "mm:ss", "title" : "Song Title", "requester" : "Username" } }

Request Interface to Pause/Unpause
The following is sent from the WebSocket when the YouTube Player API is to pause (or unpause):

{ "command" : "pause" }

Request Interface to Change Volume
The following is sent from the WebSocket when the YouTube Player API is to adjust the volume:

{ "command" : { "setvolume" : 1-100 } }

Request Interface to Send Information About Current Song
The following is sent from the WebSocket when the Player Module would like to know about the current song playing:

{ "command" : "querysong" }

Send Current Song List or Playlist
The following is sent from the WebSocket when the interface needs to know the current song request list or the current playlist:

{ "songlist" : [ { "song" : "YouTube ID", "duration" : "mm:ss", "title" : "Song Title", "requester" : "Username" } ] }
{ "playlistname" : "name", "playlist" : [ { "song" : "YouTube ID", "duration" : "mm:ss", "title" : "Song Title" } ] }


Youtube Playlist as Json link