-
Notifications
You must be signed in to change notification settings - Fork 4
Kibio Web Socket Subprotocol Specification
This subprotocol specification describes the communication between the kibio player / server and the web interface. All communication occurs over standard websockets and requires a modern browsers. Current modern versions of Firefox and Webkit derived browsers (such as Chrome and Safari) are supported. Other browsers are likely supported, but have not been tested.
The Kibio protocol consists of command and control frames comprised of JSON. Each JSON frame consists of a header describing the destination and content. An optional data sectopm is also permitted. Data interpretation and proecssing is the responsibility of the target module on both the client and the server.
Protocol frames are JSON formatted data packets sent between the frame.
There are several types of frames defined in the specification.
Clients can send both REQUEST and STATUS frames. Due to the nature of the loose coupling associated with an asynchronous web interface, client commands are issued as requests. The client will assume that a requested command is successful unless the server responds with a corresponding failure. In the case that a failure is detected, the client must then issue a STATUS frame to the appropriate module asking for a state update. Through this asynchronous process, we minimize the probability of a client getting out of sync.
Servers respond to REQUEST frames by sending RESPONSE frames. Each REQUEST frame contains a unique client-generated identifier (simply an incrementing integer starting with 1 at the beginning of a session). If the requested operation is successful, the server will send a successful response. If it fails, then the server will send an error code and a human readable error string. It is the the responsibility of the client to request a full status update using a STATUS frame.
{
"type" : "REQUEST",
"module" : "MODULE_NAME",
"command" : "COMMAND_NAME",
"requestId" : "REQUEST_ID",
"data" : {
/* see data specifications below */
}
}##Modules
###Player
####PLAYER Module
Example request frame:
{
"type" : "REQUEST",
"module" : "PLAYER",
"command" : "(PLAY|STOP|PAUSE)",
"requestId" : "REQUEST_ID",
"data" : { … }
}The kibio player is a video player capable of playing a variety of media types including video, still images and sound files.
###Player Commands
####Commands Without Data
- [
PLAY] - [
STOP] - [
PAUSE]
####Commands With Data
SPEED Specifies the playback speed multiplier. A value of 1.0 means a normal playback speed. A value of 2.0 means 2 x speed. A value of -2.0 means 2 x speed in reverse.
{
"data" : {
"speed" : "2.0"
}
}FRAME Specifies the frame number that the player should jump to. If the frame number is greater than the total number of frames, a modulo operation will be performed to keep the frame within bounds. The frame request can been either an absolute frame number or a normalized value where 0 represents the first frame and 1.0 represents the last frame.
{
"data" : {
"frame" : "5"
}
}{
"data" : {
"framen" : "0.5"
}
}JUMP Specifies the number of frames to skip from the current playback position. If the frame number is greater than the total number of remaining frames, a modulo operation will be performed to keep the frame within bounds. The jump request can been either an absolute frame number or a normalized value where 0 represents the first frame and 1.0 represents the last frame. Negative values mean the playhead will go backwards.
{
"data" : {
"jump" : "-5"
}
}{
"data" : {
"jumpn" : "0.5"
}
}VOLUME Specifies the playback volume. A value of 0.0 means no volume. A value of 1.0 is a normal volume level.
{
"data" : {
"value" : "0.5"
}
}LOOP_STATE Specifies the current loop state. Values include NORMAL, PALINDROME and NONE.
{
"data" : {
"value" : "NORMAL"
}
}###Media Library
####MEDIA_LIBRARY Module
###Media Library Commands
Client to Server Requests
#####DELETE
DELETE will request that the server delete a given media asset with a given UUID. This will result in the removal of that assest from all playlists. The server must send updates that reflect those changes.
{
"data" : {
"UUID" : "FILE_UUID"
}
}#####MODIFY
MODIFY will request that the server modify the settings for a given filename. The server will reply with a successful ACK upon successful modification.
{
"data" : {
"key" : "VARIABLE_NAME",
"value" : "THE_NEW_VALUE"
}
}Currently supported variables include "name".
#####ADD
ADD will request that a given media asset will be added. This command requires a valid URI. The server must respond with a confirmation and or loading updates including a generated UUID. All updates must referece the original requestId variable.
{
"data" : {
"URI" : "http://example.com/mymovie.mpg"
}
}#####LIST
LIST will request that the server send a LIST update. A LIST command has no data.
Server to Client Updates
LIST will list all of the files in the media library.
{
"data": {
"assets": [
{
"UUID": "UNIQUE_ASSET_ID",
"URI": "FILE URI",
"name": "USER_ALIAS",
"playCount": "0",
"streams" {
{
"index":"STREAM_INDEX",
"type":"STREAM_TYPE",
"codec":"CODEC_TYPE",
"resolution": {
"width":"800",
"height":"800"
}
}
"type": "ASSET_TYPE",
"duration": "DURATION_MILLISECONDS",
"frameCount" : "NUMBER_OF_FRAMES",
"size": {
"width": "800",
"height": "800"
}
}
]
}
}DELETE will list files to be deleted from the media library. The server will also send similar commands to the client regarding playlist deletions.
{
"data" : {
"assets": [
{
"UUID" : "UNIQUE_ASSET_ID"
}
]
}
}ADD will list files to be deleted from the media library. The server will also send similar commands to the client regarding playlist deletions.
{
"data": {
"asset": {
"UUID": "UNIQUE_ASSET_ID",
"URI": "FILE URI",
"name": "USER_ALIAS",
"type": "ASSET_TYPE",
"duration": "DURATION_MILLISECONDS",
"frameCount": "NUMBER_OF_FRAMES",
"playCount": "0",
"size": {
"width": "800",
"height": "800"
}
}
},
"destination": {
"position": {
"index": "0"
}
}
}###Playlist
####PLAYLIST Module
Example request frame:
{
"type" : "REQUEST",
"module" : "PLAYLIST",
"command" : "(ADD|REMOVE|MOVE)",
"requestId" : "REQUEST_ID",
"data" : { … }
}###Playlist Commands
Client to server
#####ADD
ADD will add a given media asset to a playlist.
{
"data" : {
"asset" : {
"UUID" : "UNIQUE_ASSET_ID"
},
"destination" : {
"playlist" : {
"UUID" : "UNIQUE_PLAYLIST_ID"
},
"position" : {
"index" : "DESTINATION_INDEX"
}
}
}
}#####REMOVE
REMOVE will remove a given media asset from a playlist.
{
"data" : {
"playlistItem" : {
"UUID" : "PLAYLIST_ITEM_ID"
}
}
}#####MOVE
MOVE will request move a given playlist item within a playlist.
{
"data" : {
"playlistItem" : {
"UUID" : "PLAYLIST_ITEM_ID"
},
"destination" : {
"playlist" : {
"uuid" : "UNIQUE_PLAYLIST_ID"
},
"position" : {
"index" : "DESTINATION_INDEX"
}
}
}
}Server to client
Server will respond with RESPONSE frames when interacting with the playlist commands. The request id is inside the RESPONSE header.
{
"data" : {
"success" : "TRUE_OR_FALSE",
"error" : {
"code" : "INTEGER_ERROR_CODE",
"message" : "ERROR_MESSAGE"
}
}
}
Upon receiving an error message, it is the client's responsibility to request a relevant state update from the server.