User Tools

Site Tools


http_api |

This is an old revision of the document!


Table of Contents

HTTP API for Z3CAM / HE2K-DCK / HE4K-DCK / FV2K-DCK / FV4K-DCK/ FSDI-DCK / DME-10 / HE1080-RPS / ZCube / ZCube-SDI

For HE4K-01 / HE4K-R4 / MVE-150 / MVE-100R / SME-01 / DME-02/03/04 use Z3-TI-http_api

Configuration API Syntax

Reading Configuration

To read configuration variable, simply perform an HTTP GET to the URL

http://server_address/cgi-bin/control.cgi

with the body as given below.

The reponse will be in JSON format, giving the value of each variable.
To read global configuration variables, GET with this body:

ctrl=sys&chn=null

To read encoder channel configuration variables for channel 1, GET with this body:

ctrl=enc&chn=1

Python example code for reading configuration:

import requests, json, sys

server_url='http://192.168.0.120/cgi-bin/control.cgi'

global_cfg = requests.get(server_url, params='ctrl=sys&chn=null')
print global_cfg.json()

enc_cfg = requests.get(server_url, params='ctrl=enc&chn=1' )
print enc_cfg.json()

Sample output:

>>> print global_cfg.json()
{u'wifi_exists': False, u'processor_id': u'Hi3519', u'default_gw': u'192.168.0.1', u'disp_std': u'auto', u'session_id': u'---', u'timezone': u'CST6CDT,M3.2.0,M11.1.0', u'MODEL': u'Z3CAM-HD', u'pe3': u'', u'board_id': u'0xFF02', u'z3_termsrv': u'enabled', u'local_netmask': u'255.255.0.0', u'ret': u'0', u'z3_wifi': u'enabled', u'opmode': u'encoder', u'syspassword': u'', u'enc_current_preset': u'encoder', u'sysdevicename': u'ENCDEV', u'z3_tslowlat': u'enabled', u'z3_sntp': u'enabled', u'enc_adv_setting': u'off', u'do_autostart': 1, u'enc_channels': u'1', u'pe8': u'', u'local_dnsip': u'8.8.8.8', u'local_ip': u'192.168.0.120', u'pe4': u'', u'pe5': u'', u'pe6': u'', u'pe7': u'', u'pe0': u'encoder', u'pe1': u'', u'pe2': u'', u'opstate': u'RUNNING', u'enable_snmp': u'false', u'local_dnsip2': u'8.8.4.4', u'enable_sntp': u'false', u'use_dhcp': u'1', u'sntp_servers': u'128.138.141.172', u'focus_manual': u'auto', u'optical_zoom_only': u'0', u'visca_present': u'true'}>>> print enc_cfg.json()
{u'zixioverhead': u'15', u'tsrate': u'3000K', u'zixiuser': u'user', u'vprofile': u'high', u'vbitrate': u'2M', u'feconoff': u'off', u'vdelay': 1000, u'vsource': u'hdmi', u'klvsrc': u'/dev/gv7601.0', u'fprefix': u'MOV1_%F_%T_', u'enc_status': u'RUNNING', u'telopenable': u'off', u'auth_passwd': u'password', u'teloplocation': u'top_left', u'pcrinterval': 50, u'aptspcr': 250, u'teloptext': u'ENCDEV', u'zixiauthen': u'off', u'tslowlat': u'on', u'storage': u'', u'vquality': u'balanced', u'ret': u'0', u'asamplerate': u'48000', u'vdest': u'192.168.0.6:8600', u'filesize': u'1024M', u'vgdr': u'on', u'telopcharsize': u'32', u'vratectrl': u'cbr', u'klvbrate': u'1000', u'abitrate': u'128000', u'vpid': 221, u'feccol': 5, u'acodec': u'fdk_aaclc', u'vframeratediv': 1, u'zixisession': u'test', u'vres': u'follow_input', u'pcrpid': 521, u'apid': 120, u'aenable': u'on', u'asource': u'MICL', u'vprotocol': u'rtsp', u'preset': u'actv_preset', u'nfstrength': u'0', u'aport': u'8700', u'klvpid': u'35', u'vgopsize': 60, u'pmtpid': 31, u'authonoff': u'off', u'vcodec': u'h265', u'klvenable': u'off', u'klvmode': u'sdi', u'auxonoff': u'off', u'channel': 1, u'mounts': u'', u'auth_user': u'user', u'fecrow': 1}

Encoder Channel Configuration

codec

Set to h265 and will be auto-detected as h265/h264/mjpeg

Possible values: h264, h265

viewport

Description: Display size, [keep original size, fit to display, keep aspect ratio, scale percentage]

Possible values: =original, fit, keep_aspect, scale

ZIXI URL Parameters

The URL may have parameters passed in as:

base_url?param1=val1&param2=val2

fec

Description:

Possible values: on, off

fecoverhead

Description:

Possible values: overhead_percentage

fecblock

Description:

Possible values: fec block size in milliseconds

latency

Description:

Possible values: latency in milliseconds for retransmissions

decrypt

Description:

Possible values: 0, 1, 2, 3, 4 (0=AES-128, 1=AES-192, 2= AES-256, 3=ChaCha20, 4=None)

pass

Description:

Possible values: <password>

SRT URL Parameters

mode

Description:

Possible values: listener, caller, rendezvous

latency

Description:

Possible values: latency in milliseconds for retransmission

pbkeylen

Description:

Possible values: 16, 24, 32 (16=AES-128, 24=AES-192, 32=AES-256)

passphrase

Description:

Possible values: <password>

feccol

Description: Column count for ProMPEG.

Possible values: integer greater than 1

feconoff

Description: Enable ProMPEG if supported.

Possible values: on, off

fecrow

Description: Row count for ProMPEG.

Possible values: integer greater than 1

filesize

Description: Size of TSFILE or AUX file recording, in bytes.

A “K” suffix indicates kilobytes (thousands of bytes/second).

A “M” suffix indicates megabytes (millions of bytes/second).

fprefix

Description: Relative filename for TSFILE or AUX file recording. Note that “fprefix” does NOT include the absolute media path – the “storage” parameter is the proper place to specify the absolute media path.

storage

Absolute path to mounted media device (e.g. /media/sda1/)

telopcharsize

OSD overlay text character size in pixels

Possible values: 16, 32, or 64

telopenable

Enable or disable telop (i.e. OSD overlay of text).

Possible values: on, off

teloplocation

Where to overlay text in the encoded video

Possible values: top_left top_right top_center bottom_left bottom_right bottom_center

teloptext

Text string for OSD overlay

vgopsize

Description: Distance between I frames (key frames) in GOP sequence

Possible values: 1 through 240

vbitrate

Description: Video bitrate in bits per second.

Possible values: A “K” suffix indicates kilobits (thousands of bits/second).

A “M” suffix indicates megabits (millions of bits/second).

Note: In UDP transport stream case, the tsrate should be set

higher than the vbitrate, with at least 15% margin.

vdelay

Description: Video maximum burst size in milliseconds.

Possible values: 100 to 2000

vdest

Description: Destination URL address for encoded bitstream. May be interpreted differently depending on “vprotocol” setting.

For UDP and RTP transports:

client_ip:client_port

For RTMP transport:

 server_ip[:server_port]/application/streamname

vframeratediv

Description: Divide video input frame rate by this number to get encode frame rate.
The encoder will discard (frameratediv-1) out of (frameratediv) frames.

Possible values: 1, 2, 3, 4, 5, 6

vgdr

Description: Enable or disable Gradual Data Refresh. Reduces I-frame size (reduces latency). At lower bitrates, a horizontal rolling artifact may be visible.

Possible values: on, off

vcodec

Description: Specifiec which codec to encode with.

Possible values: h265, h264, mjpeg

vprofile

Description: H.264 profile (see https://en.wikipedia.org/wiki/H.264/MPEG-4_AVC#Profiles​ for full description)

Possible values: baseline, main, high

vprotocol

Description: Protocol used to transport the encoded bitstream.

Possible values: rtp, rtmp, udp, asi, tsfile, mts, tsrtp

vquality

Description: Set balance between low latency, and higher quality bitrate compliance.

Possible values: lowlat, balanced, high

vratectrl

Description: Rate control mode for encoder.

Possible values: cbr, vbr

vbr mode may be burstier than cbr.

vres

Description: Video resolution

Possible values: follow_input preserve video source resolution, no resize

               WxH           resize to width W and height H

vsource

Description: Video input from which encoder will source its video

Possible values: Board-dependent

pipenable

Description: Enable PIP of channel 2 on channel 1 encode. Only available on FV4K/FV2K/FSDI

Possible values: on, off

piplocaton

Description: Sets the location of the PIP on channel one. Only available on FV4K/FV2K/FSDI

Possible values: top_left, top_right, bottom_left, bottom_right

vinterlacemode

Description: Sets the interlaced mode for the video input

Possible values: combined, separated (H265 only)

vmulticastdest

Description: video multicast destination for RTSP. Used by ONVIF StartMulticast/StopMulticast functions

Possible values: valid multicast addresses

amulticastdest

Description: audio multicast destination for RTSP. Used by ONVIF StartMulticast/StopMulticast functions

Possible values: valid multicast addresses

rtsp_auth_enable

Description: enables/disables rtsp authorization for stream

Possible values: on, off

rtsp_auth_username

Description: username for rtsp authorization

Possible values: alpha numeric string

rtsp_auth_password

Description: password for rtsp authorization

Possible values: *

Transport Stream Parameters

The following parameters only apply to transport stream encoding (transport is set to udp, asi, tsfile, mts, or tsrtp).

vpid

Description: Video PID for transport stream.

Possible values: 32 to 8191 – must not conflict with other PID assignments

apid

Description: Audio PID for transport stream.

Possible values: 32 to 8191 – must not conflict with other PID assignments

pcrpid

Description: PCR PID for transport stream.

Possible values: 32 to 8191 – must not conflict with other PID assignments

pmtpid

Description: PMT PID for transport stream.

Possible values: 16 to 31 – must not conflict with other PID assignments

tsrate

Description: Transport stream total transport rate in bits per second.

Possible values: The 'K' suffix indicates kilobits (thousands of bits/second). The 'M' suffix indicates megabits (millions of bits/second).

Note: In UDP transport stream case, the tsrate should be set higher than the vbitrate, with at least 15% margin.

tslowlat

Description: Low latency transport stream mode (VBR).

Possible values: off, on

auxonoff

Describe: Enable AUXillary file recording in UDP mode – allows simultaneous UDP streaming and TS file recording on the same channel. Only valid if transport is UDP and tslowlat is off

The path to storage is set by the “storage” parameter.

The filename is set by the “fprefix” parameter. The default value is “MOV1_%F_%T”. The “%F” specifier inserts a date stamp, and the “%T” specifier inserts a time stamp.

The recording file size is set by the “filesize” parameter. When the file reaches this size, a new file will be created.

klvbrate

Description: Bitrate to allocate in transport stream for KLV data.

klvenable

Description: Enable KLV capture from SDI, if supported.

Possible values: off, on

klvpid

Description: PID for KLV data in transport stream

klvsrc

Description: Source device for KLV metadata

pcrinterval

Description: Interval between PCR packets in milliseconds.

Possible values: 30 - 100

Global Configuration


Action Syntax

Generic Actions (POST)

Python example code for starting/stopping all channels:

import requests, json
import sys, getopt

actionname='StartChannel'

server_url='http://192.168.0.120'

control_cgi_url = server_url   '/cgi-bin/control.cgi'

payload = 'ctrl=sys&chn=null'
sysctrl = requests.get(control_cgi_url, params=payload)

j = sysctrl.json()
print j

enc_channels_string = j['enc_channels']
opmode       = j['opmode']

enc_channels = enc_channels_string.split( ',' )

print 'enc_channels', enc_channels, 'opmode', opmode

channel_list = enc_channels

for channel in channel_list :
    # Remove leading C
    if channel[0:0] == 'C':
        channel = channel[1:]
    print actionname, ' ', opmode, 'channel', channel
    payload = 'action=' actionname '&'  'chn='  channel '&'   'loadfromdb=true';
    headers={'Content-Type':'application/x-www-form-urlencoded; charset=UTF-8'}
    r = requests.post(control_cgi_url, data=payload, headers=headers)

    print r.text

The “loadfromdb=true” parameter will load the current settings from the database.

If you omit the loadfromdb parameter, *none* of the database settings will be used – any parameters you do not supply, will be set to default values.

For example, this is what a StartChannel request from the web server looks like:

action=StartChannel&chn=1&vsource=&vres=follow_input&vcodec=h265&vgdr=on&vprofile=high&vratectrl=cbr&vbitrate=2M&vframeratediv=1&vgopsize=60&vprotocol=rtsp&vdest=192.168.0.6:8600&storage=&fprefix=MOV1_%F_%T_&vpid=221&vdelay=1000&pcrpid=521&pcrinterval=50&pmtpid=31&tsrate=3000K&tslowlat=on&feconoff=off&fecrow=1&feccol=5&zixioverhead=15&zixiauthen=off&zixisession=test&zixiuser=user&aenable=on&asource=MICL&acodec=fdk_aaclc&abitrate=128000&asamplerate=48000&aport=8700&apid=120&aptspcr=250&klvenable=off&klvmode=sdi&klvsrc=/dev/gv7601.0&klvpid=35&klvbrate=1000&authonoff=off&auth_user=user&auth_passwd=password&auxonoff=off&filesize=1024M&telopenable=off&teloptext=ENCDEV&teloplocation=top_left&telopcharsize=32&vquality=balanced

StartChannel


Transition the encoder channel into the running state.

Once you start the channel, it will not transmit data until the
video input is detected.

StopChannel

Transition the encoder channel into the stopped state.

SaveUser

Save current settings to non-volatile memory, so they will be used on the next startup.

RestartBoard

Reboot the board

PtzContinuousMove

Pan to the left at half speed

  action=PtzContinuousMove&data={"PanTilt":{"x":-0.5,"y":0},"idx":0}

Pan to the right at half speed

  action=PtzContinuousMove&data={"PanTilt":{"x":0.5,"y":0},"idx":0}

Tilt down at max speed

  action=PtzContinuousMove&data={"PanTilt":{"x":0,"y":1},"idx":0}

PtzStop

Stop pan and tilt

  action=PtzStop&data={"mode":1,"idx":0}

CameraControl

Send VISCA commands to camera.

Only one command can be sent at a time; the list below are the only supported VISCA commands through the HTTP API. To use VISCA commands that are not listed, usage of the TCP socket can be used to send those VISCA commands.

API Format:

action=CameraControl&command=visca_command&cam_index=1

example:

Commands without value assignments

action=CameraControl&command=dzoom_off&cam_index=1

Commands with value assignments

action=CameraControl&command=set_monitor_mode 1080p-59.94&cam_index=1

The commands use the same syntax as the serial menu “V” command, as shown below

For the most current list of VISCA commands supported press “V” from the Serial/SSH session of the Serial Menu.

auto_icr_disable
auto_icr_enable
cam_control_inquiry
cam_custom_recall
cam_custom_reset
cam_custom_set
chroma_get_suppress
chroma_suppress      Set Chroma Suppression  (0=none, 1 to 3=chroma supression strength)
clear_if
color_gain           Set Color gain (0=60%, 14=200%)
color_get_gain
color_get_hue
color_hue            Set Color hue (0=-14 degrees, 14= 14 degrees)
debug_rx
dzoom_combine_mode
dzoom_direct         D-Zoom Position (0x00 to 0xeb)
                     * Enabled during Separate mode
dzoom_off
dzoom_on
dzoom_separate_mode
dzoom_stop
dzoom_super_res
dzoom_tele_var       p = 0 (Low) .. 7 (High)
                     * Enabled during Separate Mode
dzoom_wide_var       p = 0 (Low) .. 7 (High)
                     * Enabled during Separate Mode
dzoom_x1_max
eflip_off
eflip_on
ext1_func_inquiry
ext2_func_inquiry
ext3_func_inquiry
focus_auto
focus_direct         focus pos
                     Min. 0x1000 Over Inf
                     0x2000 10m
                     0x3000 5m
                     0x4000 3.3m
                     0x5000 2.5m
                     0x6000 2m
                     0x7000 1.7m
                     0x8000 1.5m
                     0x9000 1m
                     0xa000 50cm
                     0xb000 30cm
                     0xc000 15cm
                     0xd000 6cm
                     0xe000 1cm
focus_get_mode
focus_get_pos
focus_manual
focus_near_limit     focus near limit
                     Min. 0x1000 Over Inf
                     0x2000 10m
                     0x3000 5m
                     0x4000 3.3m
                     0x5000 2.5m
                     0x6000 2m
                     0x7000 1.7m
                     0x8000 1.5m
                     0x9000 1m
                     0xa000 50cm
                     0xb000 30cm
                     0xc000 15cm
                     0xd000 6cm
                     0xe000 1cm
focus_stop
focus_tele_std
focus_tele_var       p = 0 (Low) .. 7 (High)
focus_toggle
focus_wide_std
focus_wide_var       p (0 (Low) .. 7 (High))
get_low_delay_mode   Get low delay mode: 0 - normal, 1 - low delay
get_monitor_mode     get_monitor_mode: Get video mode of camera output
help
high_sensitivity_off
high_sensitivity_on
icr_mode             modes:
                     auto
                     on
                     off
                     threshold [0-255]
lens_control_inquiry
lens_get_temp
lr_reverse_off
lr_reverse_on
other_inquiry
power_inquiry
power_off
power_on
register_read        Read internal register.
register_write       Write internal register.
                     * Note: To make register changes effective, run power_off and power_on
set_address
set_low_delay_mode   Set low delay mode: 0 - normal, 1 - low delay
set_monitor_mode     Set monitor mode.
                     List of modes: 1080p-25
                     720p-50
                     720p-59.94
                     2160p-25
                     2160p-29.97
                     1080p-29.97
                     1080p-59.94
                     1080p-50
slow_shutter         modes:
                     on
                     off
limit [0-255]
trace                enable (0=off, 1=on)
version_inquiry
wb_auto_mode
wb_autotrace_mode
wb_get_bgain
wb_get_mode
wb_get_mode_name
wb_get_rgain
wb_indoor_mode
wb_manual_bgain_direct Set Manual WB BGain (0..255)
                       * Enabled during Manual WB mode
wb_manual_bgain_reset
wb_manual_mode
wb_manual_rgain_direct Set Manual WB RGain (0..255)
                       * Enabled during Manual WB mode
wb_manual_rgain_reset
wb_onepush_mode
wb_onepush_trigger
wb_outdoor_auto_mode
wb_outdoor_mode
wb_sodium_lamp_auto_mode
wb_sodium_lamp_fixed_mode
wb_sodium_lamp_outdoor_mode
zoom_direct          pos
                     Min. 0x0000
                     Max. 0x4000 (In Separate mode)
                     Max. 0x4000 (In Combine mode and DZoom=Off)
                     Max. 0x59C0 (In Combine mode, DZoom=Super Resolution Zoom, and monitoring mode QFHD)
                     Max. 0x6000h (In Combine mode, DZoom=Super Resolution Zoom, and monitoring mode FHD or less)
                     Max. 0x7AC0h (In Combine mode and DZoom=On)
zoom_get_pos
zoom_stop
zoom_tele_std
zoom_tele_var        p = 0 (Low) .. 7 (High)
zoom_wide_std
zoom_wide_var        p (0 (Low) .. 7 (High))

With dual VISCA camera supported added we need to tell the API which camera we want to talk to. this is done with cam_index

The values accepted are either 1 or 2

SaveCamera

Save camera-related settings below.

zoom_direct_value

Description: Set camera zoom

Possible values: 0 (wide) to 0x7ac0 (full zoom)

white_balance_mode

Possible values: auto. indoor, outdoor, onepush, autotrace, manual, outdoor_auto,

               sodium_lamp_auto, sodium_lamp_fixed, sodium_lamp_outdoor

color_gain

Possible values: Range from 0 (60%) to 14 (200%)

color_hue

Possible values: Range from 0 (60%) to 14 (200%)

chroma_suppress

Possible values: 0=none, 1, 2, 3

wb_manual_rgain_direct

Possible values: 0 to 255

wb_manual_bgain_direct

Possible values: 0 to 255

optical_zoom_only

Possible values: 0, 1

focus_direct_value

Description: Set manual camera focus distance Possible values: 0x1000 to 0xf000

manual_focus

Description: Set focus mode

Possible values: auto, manual

SetIp

local_ip

IPv4 adresss

local_netmask

IPv4 netmask

default_gw

IPv4 default gateway

local_dnsip

DNS server primary

local dnsip2

DNS server secondary

do_autostart

Control automatic stream start after bootup

Possible values: 1 = do autostart 0 = do not autostart

enc_adv_setting

Control appearance of advanced settings on WebUI

Possible values: off, on

SetDisplay

Controls composite output (passthru video from camera)

disp_std

Set display standard for composite output

Possible values; auto, ntsc, pal

UpdateTerm

Control serial port terminal server for VISCA

term_mode

Possible values: client, server

term_protocol

Possible values: clearchannel, telnet

term_localport

Local TCP port (for server mode)

term_servaddr

Remote IP address (for client mode only)

term_servport

Remote TCP port (for client mode only)

term_baudrate

Possible values: 9600, 19200, 38400, 57600, 115200

term_devicefile

Overlay

Add/Update overlay

chn

​Encoder channel to add overlay to.

rgn_idx

​Index to map overlay to.

​type

Type of overlay to be used possible values: text or png.

source

In the case of text overlay this would be the source text for png overlay this is the path to the png on the encoder. Images must be uploaded to board to be used.

location

This is the location of the overlay. Possible values: 'top_left', 'top_right', 'top_center', 'bottom_left', 'bottom_right', 'bottom_center', 'x,y' (negative numbers not supported for x or y)

char_size

For text overlay this is the character size. Possible values: 16,32,64

layer

This will set the layer for the overly higher numbers will overlay over lower numbers if overlapping.

alpha

Sets the transparency of the text. Possible values: 0-255

OverlayStop

chn

​Encoder channel to remove overlay from.

rgn_idx

​Index of overly for this channel.

​Dynamic

chn

​Encoder channel to apply dynamic command to.

var

Variable to modify dynamically. Possible values: vratediv, vrate, gop, analog_gain, telop_text, pip_enable, pip_location, startmulticast, stopmulticast

val

Value to set dynamic variable to.

​SetSNTP

enable

Enable/Disable SNTP.

servers

NTP server or list of NTP servers.

timezone

Linux TZ database value for Timezone.

​SetOnvif

enable

Enable/Disable ONVIF.

fixed_profile_max

Maximum ONVIF profiles to allow (1 or 2).

​SetTermSrvEnable

termserve_remote_enable

Enable/Disable remote access to terminal server.

​SetZFinderEnable

zfinder_enable

Enable/Disable zfinder support.

Encoder Actions (POST)

SetEncoder

Write encoder settings to active preset. See Python example code for Seting Configuration below

EncoderStatus

Requests an update to encoder_status_str variable.

To read the result, you need to POST the “stats” control as shown\ in the Python example code below.

StreamStatus

Requests an update to stream_status_str variable.

To read the result, you need to POST the “stats” control as shown\ in the Python example code below.

AStreamStatus

Requests an update to astream_status_str variable.

To read the result, you need to POST the “stats” control as shown\ in the Python example code below.

SourceStatus

Requests an update to source_status_str variable.

To read the result, you need to POST the “stats” control as shown\ in the Python example code below.


Setting Encoder Configuration

To set the encode configuration per channel the SetEncoder action is used with a post. All variables should be present or they will be replaced with a defualt that may not be valid for your application. More than one channel can be set per command. It is recommended you first read the current settings from the encoder then modify them and send the new settings back as in the Python example below:

import requests, json, sys

server_url='http://192.168.0.120/cgi-bin/control.cgi'
channel = 1

enc_cfg = requests.get(server_url, params='ctrl=enc&chn={}'.format(channel))
print enc_cfg.json()

enc_cfg_json=enc_cfg.json()
enc_cfg_json['vframeratediv'] = 2 #set frame rate divider to 2
new_cfg = {}
new_cfg['action'] = 'SetEncoder'
for key, value in enc_cfg_json.iteritems():
   print "key = {} value = {}".format(key,value)
   new_idx = "enc_{}_{}".format(channel,key)
   print "setting {} to {}".format(new_idx,value)
   new_cfg[new_idx] = value

print new_cfg
requests.post(server_url, data=new_cfg)

Reading Statistics

Python example of updating and reading encoder statistics:

import requests, json, sys
server_url='http://192.168.0.120/cgi-bin/control.cgi'

requests.post(server_url, data={'action' : 'EncoderStatus'})
requests.post(server_url, data={'action' : 'StreamStatus'})
requests.post(server_url, data={'action' : 'AStreamStatus'})
requests.post(server_url, data={'action' : 'SourceStatus'})
requests.post(server_url, data={'action' : 'TempStatus'})

print requests.get(server_url, params='ctrl=stats&chn=').json()

Example output:

{u'status': u'OK',
 u'astream_status_str': u'\tChannel 1 Codec fdk_aaclc Frames 8998  OK',
 u'temp_status_str': u' LENS 39  FPGA 42  CPU 42  OK',
 u'ret': u'0',
 u'encoder_status_str': u'   *** Encode Bitstream Received Statistics ***    Elapsed time =    0.0 secs   CH | Bitrate (Kbps) | Actual Bitrate | FPS  | Actual FPS | Key-frame FPS | Width | Height   ------------------------------------------------------------------------------------------------------------   1 |        2000.00 |        2020.17 | 60.0 |     60.0 |           1.0 |  1920 |   1080  |  OK',
 u'source_status_str': u' CAMERA 1920x1080p 60.00 fps  OK',
 u'stream_status_str': u'Channel 1 URL rtsp Frames 11524  OK'}

asamplerate

Description: Audio sample rate

Possible values: 48000, 44100

asource

Description: Select audio input

Possible values: MICL (microphone, line input levels)

               MIC    (unpowered microphone levels)
               HDMI   (microHDMI input, for HE4K-DCK only)
               HD-SDI (SDI input, for DME-10/FSDI-DCK only)

apid

Description: Audio PID for transport stream.

Possible values: 32 to 8191 - must not conflict with other PID assignments.

aport

Description: Destination UDP port for RTP audio

aptspcr

Description: For transport stream modes only – intial PTS to PCR offset for audio, in milliseconds

Possible values: 100 to 2000

auth_passwd

Description: Password for RTMP authentication.

auth_user

Description: Username for RTMP authentication.

authonoff

Description: Enable or disable RTMP authentication. Default: off Possible values: on, off

channel

Description: Encoder channel number

Possible values: 1, 2, 3

feccol

Description: Column count for ProMPEG.

Possible values: integer greater than 1

feconoff

Description: Enable ProMPEG if supported.

Possible values: on, off

fecrow

Description: Row count for ProMPEG.

Possible values: integer greater than 1

filesize

Description: Size of TSFILE or AUX file recording, in bytes.

A “K” suffix indicates kilobytes (thousands of bytes/second).

A “M” suffix indicates megabytes (millions of bytes/second).

fprefix

Description: Relative filename for TSFILE or AUX file recording. Note that “fprefix” does NOT include the absolute media path – the “storage” parameter is the proper place to specify the absolute media path.

storage

Absolute path to mounted media device (e.g. /media/sda1/)

telopcharsize

OSD overlay text character size in pixels

Possible values: 16, 32, or 64

telopenable

Enable or disable telop (i.e. OSD overlay of text).

Possible values: on, off

teloplocation

Where to overlay text in the encoded video

Possible values: top_left top_right top_center bottom_left bottom_right bottom_center

teloptext

Text string for OSD overlay

vgopsize

Description: Distance between I frames (key frames) in GOP sequence

Possible values: 1 through 240

vbitrate

Description: Video bitrate in bits per second.

Possible values: A “K” suffix indicates kilobits (thousands of bits/second).

A “M” suffix indicates megabits (millions of bits/second).

Note: In UDP transport stream case, the tsrate should be set

higher than the vbitrate, with at least 15% margin.

vdelay

Description: Video maximum burst size in milliseconds.

Possible values: 100 to 2000

vdest

Description: Destination URL address for encoded bitstream. May be interpreted differently depending on “vprotocol” setting.

For UDP and RTP transports:

client_ip:client_port

For RTMP transport:

 server_ip[:server_port]/application/streamname

vframeratediv

Description: Divide video input frame rate by this number to get encode frame rate.
The encoder will discard (frameratediv-1) out of (frameratediv) frames.

Possible values: 1, 2, 3, 4, 5, 6

vgdr

Description: Enable or disable Gradual Data Refresh. Reduces I-frame size (reduces latency). At lower bitrates, a horizontal rolling artifact may be visible.

Possible values: on, off

vcodec

Description: Specifiec which codec to encode with.

Possible values: h265, h264, mjpeg

vprofile

Description: H.264 profile (see https://en.wikipedia.org/wiki/H.264/MPEG-4_AVC#Profiles​ for full description)

Possible values: baseline, main, high

vprotocol

Description: Protocol used to transport the encoded bitstream.

Possible values: rtp, rtmp, udp, asi, tsfile, mts, tsrtp

vquality

Description: Set balance between low latency, and higher quality+bitrate compliance.

Possible values: lowlat, balanced, high

vratectrl

Description: Rate control mode for encoder.

Possible values: cbr, vbr

vbr mode may be burstier than cbr.

vres

Description: Video resolution

Possible values: follow_input preserve video source resolution, no resize

               WxH           resize to width W and height H

vsource

Description: Video input from which encoder will source its video

Possible values: Board-dependent

pipenable

Description: Enable PIP of channel 2 on channel 1 encode. Only available on FV4K/FV2K/FSDI

Possible values: on, off

piplocaton

Description: Sets the location of the PIP on channel one. Only available on FV4K/FV2K/FSDI

Possible values: top_left, top_right, bottom_left, bottom_right

vinterlacemode

Description: Sets the interlaced mode for the video input

Possible values: combined, separated (H265 only)

vmulticastdest

Description: video multicast destination for RTSP. Used by ONVIF StartMulticast/StopMulticast functions

Possible values: valid multicast addresses

amulticastdest

Description: audio multicast destination for RTSP. Used by ONVIF StartMulticast/StopMulticast functions

Possible values: valid multicast addresses

rtsp_auth_enable

Description: enables/disables rtsp authorization for stream

Possible values: on, off

rtsp_auth_username

Description: username for rtsp authorization

Possible values: alpha numeric string

rtsp_auth_password

Description: password for rtsp authorization

Possible values: *

Transport Stream Parameters

The following parameters only apply to transport stream encoding (transport is set to udp, asi, tsfile, mts, or tsrtp).

vpid

Description: Video PID for transport stream.

Possible values: 32 to 8191 – must not conflict with other PID assignments

apid

Description: Audio PID for transport stream.

Possible values: 32 to 8191 – must not conflict with other PID assignments

pcrpid

Description: PCR PID for transport stream.

Possible values: 32 to 8191 – must not conflict with other PID assignments

pmtpid

Description: PMT PID for transport stream.

Possible values: 16 to 31 – must not conflict with other PID assignments

tsrate

Description: Transport stream total transport rate in bits per second.

Possible values: The 'K' suffix indicates kilobits (thousands of bits/second). The 'M' suffix indicates megabits (millions of bits/second).

Note: In UDP transport stream case, the tsrate should be set higher than the vbitrate, with at least 15% margin.

tslowlat

Description: Low latency transport stream mode (VBR).

Possible values: off, on

auxonoff

Describe: Enable AUXillary file recording in UDP mode – allows simultaneous UDP streaming and TS file recording on the same channel. Only valid if transport is UDP and tslowlat is off

The path to storage is set by the “storage” parameter.

The filename is set by the “fprefix” parameter. The default value is “MOV1_%F_%T”. The “%F” specifier inserts a date stamp, and the “%T” specifier inserts a time stamp.

The recording file size is set by the “filesize” parameter. When the file reaches this size, a new file will be created.

klvbrate

Description: Bitrate to allocate in transport stream for KLV data.

klvenable

Description: Enable KLV capture from SDI, if supported.

Possible values: off, on

klvpid

Description: PID for KLV data in transport stream

klvsrc

Description: Source device for KLV metadata

pcrinterval

Description: Interval between PCR packets in milliseconds.

Possible values: 30 - 100

Global Configuration


Action Syntax

Generic Actions (POST)

Python example code for starting/stopping all channels:

import requests, json
import sys, getopt

actionname='StartChannel'

server_url='http://192.168.0.120'

control_cgi_url = server_url + '/cgi-bin/control.cgi'

payload = 'ctrl=sys&chn=null'
sysctrl = requests.get(control_cgi_url, params=payload)

j = sysctrl.json()
print j

enc_channels_string = j['enc_channels']
opmode       = j['opmode']

enc_channels = enc_channels_string.split( ',' )

print 'enc_channels', enc_channels, 'opmode', opmode

channel_list = enc_channels

for channel in channel_list :
    # Remove leading C
    if channel[0:0] == 'C':
        channel = channel[1:]
    print actionname, ' ', opmode, 'channel', channel
    payload = 'action='+actionname+'&'+ 'chn=' +channel+'&' + 'loadfromdb=true';
    headers={'Content-Type':'application/x-www-form-urlencoded; charset=UTF-8'}
    r = requests.post(control_cgi_url, data=payload, headers=headers)
    
    print r.text

The “loadfromdb=true” parameter will load the current settings from the database.

If you omit the loadfromdb parameter, *none* of the database settings will be used – any parameters you do not supply, will be set to default values.

For example, this is what a StartChannel request from the web server looks like:

action=StartChannel&chn=1&vsource=&vres=follow_input&vcodec=h265&vgdr=on&vprofile=high&vratectrl=cbr&vbitrate=2M&vframeratediv=1&vgopsize=60&vprotocol=rtsp&vdest=192.168.0.6:8600&storage=&fprefix=MOV1_%F_%T_&vpid=221&vdelay=1000&pcrpid=521&pcrinterval=50&pmtpid=31&tsrate=3000K&tslowlat=on&feconoff=off&fecrow=1&feccol=5&zixioverhead=15&zixiauthen=off&zixisession=test&zixiuser=user&aenable=on&asource=MICL&acodec=fdk_aaclc&abitrate=128000&asamplerate=48000&aport=8700&apid=120&aptspcr=250&klvenable=off&klvmode=sdi&klvsrc=/dev/gv7601.0&klvpid=35&klvbrate=1000&authonoff=off&auth_user=user&auth_passwd=password&auxonoff=off&filesize=1024M&telopenable=off&teloptext=ENCDEV&teloplocation=top_left&telopcharsize=32&vquality=balanced

StartChannel


Transition the encoder channel into the running state.

Once you start the channel, it will not transmit data until the
video input is detected.

StopChannel

Transition the encoder channel into the stopped state.

SaveUser

Save current settings to non-volatile memory, so they will be used on the next startup.

RestartBoard

Reboot the board

PtzContinuousMove

Pan to the left at half speed

  action=PtzContinuousMove&data={"PanTilt":{"x":-0.5,"y":0},"idx":0}

Pan to the right at half speed

  action=PtzContinuousMove&data={"PanTilt":{"x":0.5,"y":0},"idx":0}

Tilt down at max speed

  action=PtzContinuousMove&data={"PanTilt":{"x":0,"y":1},"idx":0}

PtzStop

Stop pan and tilt

  action=PtzStop&data={"mode":1,"idx":0}

CameraControl

Send VISCA commands to camera.

Only one command can be sent at a time; the list below are the only supported VISCA commands through the HTTP API. To use VISCA commands that are not listed, usage of the TCP socket can be used to send those VISCA commands.

API Format:

action=CameraControl&command=visca_command&cam_index=1

example:

Commands without value assignments

action=CameraControl&command=dzoom_off&cam_index=1

Commands with value assignments

action=CameraControl&command=set_monitor_mode 1080p-59.94&cam_index=1

The commands use the same syntax as the serial menu “V” command, as shown below

For the most current list of VISCA commands supported press “V” from the Serial/SSH session of the Serial Menu.

auto_icr_disable
auto_icr_enable
cam_control_inquiry
cam_custom_recall
cam_custom_reset
cam_custom_set
chroma_get_suppress
chroma_suppress      Set Chroma Suppression  (0=none, 1 to 3=chroma supression strength)
clear_if
color_gain           Set Color gain (0=60%, 14=200%)
color_get_gain
color_get_hue
color_hue            Set Color hue (0=-14 degrees, 14=+14 degrees)
debug_rx
dzoom_combine_mode
dzoom_direct         D-Zoom Position (0x00 to 0xeb)
                     * Enabled during Separate mode
dzoom_off
dzoom_on
dzoom_separate_mode
dzoom_stop
dzoom_super_res
dzoom_tele_var       p = 0 (Low) .. 7 (High)
                     * Enabled during Separate Mode
dzoom_wide_var       p = 0 (Low) .. 7 (High)
                     * Enabled during Separate Mode
dzoom_x1_max
eflip_off
eflip_on
ext1_func_inquiry
ext2_func_inquiry
ext3_func_inquiry
focus_auto
focus_direct         focus pos
                     Min. 0x1000 Over Inf
                     0x2000 10m
                     0x3000 5m
                     0x4000 3.3m
                     0x5000 2.5m
                     0x6000 2m
                     0x7000 1.7m
                     0x8000 1.5m
                     0x9000 1m
                     0xa000 50cm
                     0xb000 30cm
                     0xc000 15cm
                     0xd000 6cm
                     0xe000 1cm
focus_get_mode
focus_get_pos
focus_manual
focus_near_limit     focus near limit
                     Min. 0x1000 Over Inf
                     0x2000 10m
                     0x3000 5m
                     0x4000 3.3m
                     0x5000 2.5m
                     0x6000 2m
                     0x7000 1.7m
                     0x8000 1.5m
                     0x9000 1m
                     0xa000 50cm
                     0xb000 30cm
                     0xc000 15cm
                     0xd000 6cm
                     0xe000 1cm
focus_stop
focus_tele_std
focus_tele_var       p = 0 (Low) .. 7 (High)
focus_toggle
focus_wide_std
focus_wide_var       p (0 (Low) .. 7 (High))
get_low_delay_mode   Get low delay mode: 0 - normal, 1 - low delay
get_monitor_mode     get_monitor_mode: Get video mode of camera output
help
high_sensitivity_off
high_sensitivity_on
icr_mode             modes:
                     auto
                     on
                     off
                     threshold [0-255]
lens_control_inquiry
lens_get_temp
lr_reverse_off
lr_reverse_on
other_inquiry
power_inquiry
power_off
power_on
register_read        Read internal register.
register_write       Write internal register.
                     * Note: To make register changes effective, run power_off and power_on
set_address
set_low_delay_mode   Set low delay mode: 0 - normal, 1 - low delay
set_monitor_mode     Set monitor mode.
                     List of modes: 1080p-25
                     720p-50
                     720p-59.94
                     2160p-25
                     2160p-29.97
                     1080p-29.97
                     1080p-59.94
                     1080p-50
slow_shutter         modes:
                     on
                     off
limit [0-255]
trace                enable (0=off, 1=on)
version_inquiry
wb_auto_mode
wb_autotrace_mode
wb_get_bgain
wb_get_mode
wb_get_mode_name
wb_get_rgain
wb_indoor_mode
wb_manual_bgain_direct Set Manual WB BGain (0..255)
                       * Enabled during Manual WB mode
wb_manual_bgain_reset
wb_manual_mode
wb_manual_rgain_direct Set Manual WB RGain (0..255)
                       * Enabled during Manual WB mode
wb_manual_rgain_reset
wb_onepush_mode
wb_onepush_trigger
wb_outdoor_auto_mode
wb_outdoor_mode
wb_sodium_lamp_auto_mode
wb_sodium_lamp_fixed_mode
wb_sodium_lamp_outdoor_mode
zoom_direct          pos
                     Min. 0x0000
                     Max. 0x4000 (In Separate mode)
                     Max. 0x4000 (In Combine mode and DZoom=Off)
                     Max. 0x59C0 (In Combine mode, DZoom=Super Resolution Zoom, and monitoring mode QFHD)
                     Max. 0x6000h (In Combine mode, DZoom=Super Resolution Zoom, and monitoring mode FHD or less)
                     Max. 0x7AC0h (In Combine mode and DZoom=On)
zoom_get_pos
zoom_stop
zoom_tele_std
zoom_tele_var        p = 0 (Low) .. 7 (High)
zoom_wide_std
zoom_wide_var        p (0 (Low) .. 7 (High))

With dual VISCA camera supported added we need to tell the API which camera we want to talk to. this is done with cam_index

The values accepted are either 1 or 2

SaveCamera

Save camera-related settings below.

zoom_direct_value

Description: Set camera zoom

Possible values: 0 (wide) to 0x7ac0 (full zoom)

white_balance_mode

Possible values: auto. indoor, outdoor, onepush, autotrace, manual, outdoor_auto,

               sodium_lamp_auto, sodium_lamp_fixed, sodium_lamp_outdoor

color_gain

Possible values: Range from 0 (60%) to 14 (200%)

color_hue

Possible values: Range from 0 (60%) to 14 (200%)

chroma_suppress

Possible values: 0=none, 1, 2, 3

wb_manual_rgain_direct

Possible values: 0 to 255

wb_manual_bgain_direct

Possible values: 0 to 255

optical_zoom_only

Possible values: 0, 1

focus_direct_value

Description: Set manual camera focus distance Possible values: 0x1000 to 0xf000

manual_focus

Description: Set focus mode

Possible values: auto, manual

SetIp

local_ip

IPv4 adresss

local_netmask

IPv4 netmask

default_gw

IPv4 default gateway

local_dnsip

DNS server primary

local dnsip2

DNS server secondary

do_autostart

Control automatic stream start after bootup

Possible values: 1 = do autostart 0 = do not autostart

enc_adv_setting

Control appearance of advanced settings on WebUI

Possible values: off, on

SetDisplay

Controls composite output (passthru video from camera)

disp_std

Set display standard for composite output

Possible values; auto, ntsc, pal

UpdateTerm

Control serial port terminal server for VISCA

term_mode

Possible values: client, server

term_protocol

Possible values: clearchannel, telnet

term_localport

Local TCP port (for server mode)

term_servaddr

Remote IP address (for client mode only)

term_servport

Remote TCP port (for client mode only)

term_baudrate

Possible values: 9600, 19200, 38400, 57600, 115200

term_devicefile

Overlay

Add/Update overlay

chn

​Encoder channel to add overlay to.

rgn_idx

​Index to map overlay to.

​type

Type of overlay to be used possible values: text or png.

source

In the case of text overlay this would be the source text for png overlay this is the path to the png on the encoder. Images must be uploaded to board to be used.

location

This is the location of the overlay. Possible values: 'top_left', 'top_right', 'top_center', 'bottom_left', 'bottom_right', 'bottom_center', 'x,y' (negative numbers not supported for x or y)

char_size

For text overlay this is the character size. Possible values: 16,32,64

layer

This will set the layer for the overly higher numbers will overlay over lower numbers if overlapping.

alpha

Sets the transparency of the text. Possible values: 0-255

OverlayStop

chn

​Encoder channel to remove overlay from.

rgn_idx

​Index of overly for this channel.

​Dynamic

chn

​Encoder channel to apply dynamic command to.

var

Variable to modify dynamically. Possible values: vratediv, vrate, gop, analog_gain, telop_text, pip_enable, pip_location, startmulticast, stopmulticast

val

Value to set dynamic variable to.

​SetSNTP

enable

Enable/Disable SNTP.

servers

NTP server or list of NTP servers.

timezone

Linux TZ database value for Timezone.

​SetOnvif

enable

Enable/Disable ONVIF.

fixed_profile_max

Maximum ONVIF profiles to allow (1 or 2).

​SetTermSrvEnable

termserve_remote_enable

Enable/Disable remote access to terminal server.

​SetZFinderEnable

zfinder_enable

Enable/Disable zfinder support.

Encoder Actions (POST)

SetEncoder

Write encoder settings to active preset. See Python example code for Seting Configuration below

EncoderStatus

Requests an update to encoder_status_str variable.

To read the result, you need to POST the “stats” control as shown\ in the Python example code below.

StreamStatus

Requests an update to stream_status_str variable.

To read the result, you need to POST the “stats” control as shown\ in the Python example code below.

AStreamStatus

Requests an update to astream_status_str variable.

To read the result, you need to POST the “stats” control as shown\ in the Python example code below.

SourceStatus

Requests an update to source_status_str variable.

To read the result, you need to POST the “stats” control as shown\ in the Python example code below.


Setting Encoder Configuration

To set the encode configuration per channel the SetEncoder action is used with a post. All variables should be present or they will be replaced with a defualt that may not be valid for your application. More than one channel can be set per command. It is recommended you first read the current settings from the encoder then modify them and send the new settings back as in the Python example below:

import requests, json, sys

server_url='http://192.168.0.120/cgi-bin/control.cgi'
channel = 1

enc_cfg = requests.get(server_url, params='ctrl=enc&chn={}'.format(channel))
print enc_cfg.json()

enc_cfg_json=enc_cfg.json()
enc_cfg_json['vframeratediv'] = 2 #set frame rate divider to 2
new_cfg = {}
new_cfg['action'] = 'SetEncoder'
for key, value in enc_cfg_json.iteritems():
   print "key = {} value = {}".format(key,value)
   new_idx = "enc_{}_{}".format(channel,key)
   print "setting {} to {}".format(new_idx,value)
   new_cfg[new_idx] = value

print new_cfg
requests.post(server_url, data=new_cfg)

Reading Statistics

Python example of updating and reading encoder statistics:

import requests, json, sys
server_url='http://192.168.0.120/cgi-bin/control.cgi'

requests.post(server_url, data={'action' : 'EncoderStatus'})
requests.post(server_url, data={'action' : 'StreamStatus'})
requests.post(server_url, data={'action' : 'AStreamStatus'})
requests.post(server_url, data={'action' : 'SourceStatus'})
requests.post(server_url, data={'action' : 'TempStatus'})

print requests.get(server_url, params='ctrl=stats&chn=').json()

Example output:

{u'status': u'OK',
 u'astream_status_str': u'\tChannel 1 Codec fdk_aaclc Frames 8998 +OK',
 u'temp_status_str': u'+LENS 39 +FPGA 42 +CPU 42 +OK',
 u'ret': u'0',
 u'encoder_status_str': u'   *** Encode Bitstream Received Statistics ***    Elapsed time =    0.0 secs   CH | Bitrate (Kbps) | Actual Bitrate | FPS  | Actual FPS | Key-frame FPS | Width | Height   ------------------------------------------------------------------------------------------------------------   1 |        2000.00 |        2020.17 | 60.0 |     60.0 |           1.0 |  1920 |   1080  | +OK',
 u'source_status_str': u'+CAMERA 1920x1080p 60.00 fps +OK',
 u'stream_status_str': u'Channel 1 URL rtsp Frames 11524 +OK'}
http_api.1604083541.txt.gz · Last modified: 2020/10/30 18:45 by rachel