/api/web/socket/document

domain    shell.cerevo.com

path        /api/web/socket

Operation flow

• /devices to request and obtain a list of the device ID
• Select the device you want to control, to record the device ID
• /server to request and obtain the information of the websocket server
• Connect to websocket server, obtain the session ID
• /connect request to connect, linking the device ID and session ID
  • Command and status sending and receiving
  • JSON obtained at the time of message reception of websocket is the status of the device.
  • Commands are sent to the device by sending to websocket.

/api/web/socket/devices

Description

To get a list of LiveShell devices that are registered with a Dashboard account.

Request parameter

Request content-type    application/x-www-form-urlencoded

Request method        POST

All required parameters.

• mailaddr
• password
  • Email address and password for the requested Dashboard account.

Response body

Response content-type    application/json

• devices
  • Is a list of LiveShell devices that are registered with the account.
• result
• message
  • The state and the message of the request, success or failure.
  • If the account information and device information is incorrect an error is returned.

/api/web/socket/server

Description

To get the information of the websocket server for remote control of each device.

Request parameter

Request content-type    application/x-www-form-urlencoded

Request method        POST

All required parameters.

• mailaddr
• password
  • Email address and password for the requested Dashboard account.
• deviceid
  • The device ID of the LiveShell you want to operate.

Response body

Response content-type    application/json

• host
• port
  • It is the destination server information of websocket.
  • If the account information and device information are incorrect the websocket information will not exist.
• result
• message
  • The state and the message of the request, success or failure.
  • If the account information and device information is incorrect an error is returned.

/api/web/socket/connect

Description

Send the websocket session ID to the server to interact with the device.

Request parameter

Request content-type    application/x-www-form-urlencoded

Request method        POST

All required parameters.

• mailaddr
• password
  • Email address and password for the requested Dashboard account.
• deviceid
  • The device ID of the LiveShell you want to operate.
• sessionid
  • Websocket session ID obtained at the time of a successful connection.

Response body

Response content-type    application/json

• result
• message
  • Same as /server response body.

Command and status specifications

Command transmission specification

{
‘Command’: ‘BOX_PAUSE’,
‘Value’: null,
‘Uid’: deviceid,
‘_dst’: Websocket_sessionid,
‘_channel’: ‘Send_command’,
‘Protocol’: ‘tcp’,
‘Cmd_type’: ‘basic’,
}

Send to websocket in json format as described above.

Status notification specification

{
“Status”: { “bri”: 224, “mute”: 1, “lock”: 0, “crop”: 1, “height”: 288, “vdelay”: 197, “aspect”: – 560, “minq “: 24,” still “: url” quality “: 0,” sat “: 224,” recording “: 0,” hdmistd “:” 1080i “,” monitor “: 0,” arate “: 2,” hcrop ” : 5, “vsel”: 1, “akbps”: 56, “minrate”: 660, “extdev”: 0, “state”: “start”, “master”: 104, “fps”: 12, “channel” : 1, “profile”: 0, “hue”: 0, “balc”: 9, “balb”: 9, “mic”: 7, “vmute”: 0, “line”: 4, “cvbsstd”: ” 525i “,” sub “: url” vkbps “: 9782,” hcrect “:” 280,0,720,720 “,” overscan “: 11,” vfr “: 0,” queue “: 256,” record “: 0,” iint “: 36,” bal “: 9,” lineb “: 1,” con “: 128},
“State”: “start”
“Battery”: {
“Current”: 101
},
“Rate”: {
“Bit”: 595308,
“Frame”: 12
},
“Viewer”: {
“Current”: 0,
“Total”: 10
},
“Condition”: 1,
“Create_dt”: 1351742269.363888,
}
You will receive via websocket in json format, a status notification as described above.

The “Status” values list the device’s audio and video configuration that have been specified by commands.

For other values –

state
Stream distribution status (pause / start / stop / ready)

battery
The remaining battery capacity (0-100 = battery charge remaining / 101 = external AC power / 102 = during battery charging)

rate
Frame rate and bit rate

viewer
Ustream viewer number

condition
Delivery queue

create_dt
Status transmission time

Command List

The following list shows the available commands, as well as the range of values which can be set for each command.

The command list is also available in YAML format, please download here.

Command status notification key	Description	Range of values	Description of value
BOX_PAUSE pause	Pause (not a toggle)	null	–
BOX_START start	Start streaming or cancel pause	null	–
BOX_STOP stop	Online standby (the LiveShell is connected to a network, but is not streaming)	null	–
BOX_EXIT exit	Set up mode, offline	null	–
BOX_POFF poff	Power-off, offline	null	–
BOX_REBOOT reboot	Reboot, offline. Will force a firmware update check and update if possible	null	–
BOX_SET_HCROP hcrop	Input format and output aspect ratio of HDMI video	0〜5	0 : Auto 1 : 4:3 2 : 16:9 3 : 4:3 (Side-crop) 4 : 16:9 (Letter-box) 5 : Manual aspect / crop (overscan setting is ignored)
BOX_SET_OVERSCAN overscan	Control overscan	0〜255	0 : Underscan/ overscan 0% 255 : overscan 50%
BOX_SET_VIDEO_DELAY vdelay	Adjust video delay. The higher the value, the earlier the video is played. In milliseconds	0〜	0 : Not set
BOX_SET_VIDEO_MUTE vmute	Video mute. Pause the video and display a pause image.	0〜1	0: No video mute 1: Video mute
BOX_SET_ASPECT aspect	Manual setting of the output aspect ratio	-960〜592
BOX_SET_BRI bri	AV-IN luminance brightness	0〜255	–
BOX_SET_CON con	AV-IN luminance contrast	0\〜255	–
BOX_SET_SAT sat	AV-IN chrominance saturation	0〜255	–
BOX_SETH_BRI hbri	HDMI-IN luminance brightness	0〜255	–
BOX_SETH_CON hcon	HDMI-IN luminance contrast	0〜255	–
BOX_SETH_SAT hsat	HDMI-IN chrominance saturation	0〜255	–
BOX_SETH_HUE hhue	HDMI-IN chroma hue	0〜255	–
BOX_SET_SUB sub	Set on screen text or image and position. Nothing is shown when the value is null. To specify the coordinates and URL, separate by commas.	null	–
BOX_SET_STILL still	Specify the pause image. Nothing is shown when the value is null.	null	–
BOX_SET_LINE line	HDMI line-in volume	0〜9	–
BOX_SET_AV lineb	External audio line-in volume	0〜9	–
BOX_SET_MIC mic	Mic volume	0〜9	–
BOX_SET_MASTER master	Master volume	0〜119	–
BOX_MUTE mute	Mute. Output or mute sound regardless of the mixer settings.	0〜1	0 : Normal 1 : mute
BOX_SET_QUALITY quality	Select picture and sound quality preset.	0〜8	0 : custom 1 : 3GLow/St 2 : 3GHigh/St 3 : ADSL/St 4 : FTTH/St 5 : 3GLow/Mv 6 : 3GHigh/Mv 7 : ADSL/Mv 8 : FTTH/Mv
BOX_SET_FPS fps	Maximum frame rate	-1800〜30	–
BOX_SET_IINT iint	IDR frame interval	0〜8191	–
BOX_SET_ARATE arate	Audio sampling rate. Changing the sampling rate while live may cause external video players to pause and reconnect.	0〜2	0 : 11025Hz 1 : 22050Hz 2 : 44100Hz
BOX_SET_VKBPS vkbps	H.264 video bit rate, unit is kbps. If the queue increases the actual bit rate will be lower than the set value.	32〜4000	–
BOX_SET_PROFILE profile	H.264 profile	0〜2	0 : baseline 1 : main 2 : high
BOX_SET_MINQ minq	The minimum value of the video quantizer. Somewhat equivalent to compression rate. A larger value in a video with no motion can result in a lower bit rate without compromising image quality. Recommended to typically be set to 30 or less.	0〜51	–
BOX_SET_HEIGHT height	Specify the output resolution by number of lines. Odd values will be rounded up to an even number.	128〜720	–
BOX_SET_AKBPS akbps	AAC-LC audio bit rate. Unit is kbps	16〜255	–
BOX_SET_QUEUE_LENGTH queue	Queue length coefficient	1〜65535	–
BOX_SET_MIN_RATE minrate	Set minimum H.264 video bit rate for flow control, unit is kbps.	32〜4000	–
BOX_SET_RATECONTROL vfr	Flow control type. Control whether image quality or frame rate will be lowered when queue is full.	0〜1	0: Image quality variable 1: Frame rate variable
BOX_SET_LOCK lock	Device button lock.	0〜1	0 : Unlocked 1 : Locked
BOX_SET_RECORD record	Ustream recording settings. Does not work when not streaming to Ustream.	0〜1	0: Do not record 1: Recording
BOX_SET_MONITOR monitor	Monitor output	0〜1	0 : Output disabled 1 : Output enabled