Standalone VGA Grid User Guide

You are here: Maintenance > Third party integration > Configuration keys for third party APIs

Configuration keys for third party APIs

Using HTTP or RS-232, you can send commands to the system to query or configure the system. For the RS-232 and HTTP syntax see Control with RS-232 / serial port and Control with HTTP commands.

Using a "SET" command in RS-232 must always follow with the "SAVECFG" command for the new configuration setting(s) to take effect.

When setting keys to values with spaces use the following syntax.

For RS-232:

Enclose in quotes: SET.2.framesize="640 x 480"

For HTTP:

Encode each space as %20: set_params.cgi?framesize=640%20x%20480

The following sections describe the API keys supported by the system in each of these categories:

System-level settings keys (read-only)
System-level settings keys (read/write)
System-level custom layout keys (read/write)
Recording configuration keys
Configuration keys for third party APIs
IP-based access control configuration keys
UPnP configuration keys
Frame grabber configuration keys
Broadcast configuration keys
Channel encoder configuration keys
Channel layout configuration keys
Audio configuration keys
Stream publishing configuration keys
RTSP Announce configuration keys (Publish type 2)
RTP/UDP configuration keys (Publish type 3)
MPEG-TS configuration keys (Publish types 4 and 5)
RTMP push configuration keys (Publish type 6 and 7)
Livestream configuration keys (Publish type 8)
Content metadata configuration keys

The list of supported keys is also available for viewing from your system. Browse to the following URL (where <address> is the IP address of the system):

http://<address>/admin/http_api.cgi

System-level settings keys (read-only)

The following read-only system-level setting keys are supported. The channel number can be omitted from the command when requesting the value for these keys.

Supported Read-Only System-level Settings configuration keys

Key	Values	Description
firmware_version	String, including the text FIRMWARE_VERSION=.	The system’s firmware version. The value is read-only.
mac_address	String	The system’s mac address. Useful for debugging. The value is read-only.
product_name	String	The product’s name. Useful to confirm you are communicating with the right product or for debugging purposes. The value is read-only.
vendor	Epiphan Video	Name of the vendor. The value is always “Epiphan Video”. The value is read-only.

System-level settings keys (read/write)

The following read/write system-level setting keys are supported. The channel number can be omitted from the command when requesting the value for these keys.

Supported Read/Write System-level Settings configuration keys

Key	Values	Description
frmcheck_enabled	on empty string ("")	Enables or disables automatic firmware update checking. To enable firmware update checking, set to on. To disable firmware update checking, set to an empty string ("").
description	string	To give this system a name in the Epiphan discovery utility, specify a description string.

System-level custom layout keys (read/write)

The following read/write system-level custom layout keys are supported.

Supported read/write system-level custom layout keys

Key	Values	Description
name	Any combination of letters, digits and underscore characters [A-Za-z_0-9]{0,32} to a limit of 32 total characters	Each unique name key contains a variable value. Used for dynamic overlay text in custom layouts (see Control with HTTP commands and Add a text overlay (custom channel))

Recording configuration keys

The following recording settings are supported. When using,, specify the channel or recorder you wish to configure.

Supported Recording configuration keys

Key	Values	Description
rec_enabled	on empty string ("")	Enables or disables recording. To enable recording, set to on. To disable recording, set to an empty string ("").
rec_format	avi mov mp4 mp4f ts	Specifies the format of the saved file. (mp4 is used for the progressive mp4 file format, mp4f for fragmented)
rec_prefix	string	Specifies a prefix for the recorded filenames.
rec_sizelimit	integer	Specifies the file size limit, in kilobytes (kB).
rec_timelimit	string (no quotes) hh:mm:ss	Specifies the time limit before a new recording file is created. For example, for 3 hour recordings, use 3:00:00
rec_upnp	on off	Specifies whether or not recordings should be available over UPnP.

HTTP server configuration keys

The following settings are supported for configuration of the HTTP server run by the system.

Supported HTTP Server configuration keys

Key	Values	Description
http_port	integer	Specifies the HTTP server port.
http_sport	integer	Specifies the HTTP server SSL port (HTTPS port).
http_usessl	on empty string ("")	Enables or disables HTTPS (SSL Server) To enable SSL, set to on. To disable SSL, set to an empty string ("").

IP-based access control configuration keys

The following settings are supported for configuring allowed and denied IP addresses for the system ONLY, not for individual channels. See Restrict viewers by IP address for more information on Allow and Deny lists.

Supported IP-Based Access configuration keys

Key	Values	Description
allowips	string: comma-separated list of IP addresses and/or ranges. empty string("")	Specifies the IP addresses to permit access. To restrict access, provide a list of permitted IP addresses. To clear allowed IP restriction, set to an empty string ("").
denyips	string: comma-separated list of IP addresses and/or ranges. empty string("")	Specifies the IP addresses to deny access. To restrict access, provide a list of denied IP addresses. To clear denied IP restriction, set to an empty string ("").

UPnP configuration keys

The following settings are supported for UPnP streaming.

Supported UPnP Streaming configuration keys

Key	Values	Description
share_archive	on empty string ("")	Enables sharing of recorded files via UPnP. To enable sharing files over UPnP, set to on. To disable sharing files over UPnP, set to an empty string ("").
share_livestreams	on empty string ("")	Enables sharing of the live stream via UPnP. To enable stream sharing over UPnP, set to on. To disable stream sharing over UPnP, set to an empty string ("").
server_name	string	Specifies the UPnP server name. To use the system name, set to an empty string ("").

Frame grabber configuration keys

These configuration keys are not supported for use with Standalone VGA Grid. Please perform tweaks to the frame grabber using the Admin panel. See Configure a source.

Key	Values	Description
gain	0...255	Specifies ADC gain adjustments. 0 is brightest, 255 is darkest.
hshift	-999...999	Specifies horizontal shift. For shifts to the left, use positive values. For shifts to the right, use negative values.
offset	0...63	Specifies ADC offset. 0 is brightest, 63 is darkest.
phase	0...31	Specifies phase adjustments for VGA signals. Generally not used unless value is provided by Epiphan support.
pll	-999...999	Specifies PLL adjustment. Changes the number of pixels in the line.
tune_interval	0...9999	Specifies the number of seconds between auto-adjustments. To disable auto-adjustments, set to 0.
vshift	-20...20	Specifies vertical shift. For shifts up, use positive values. For shifts down, use negative values.

Broadcast configuration keys

The following settings for streaming to viewers (broadcasting) are supported, including stream access control settings.

Supported Broadcast configuration keys

Key	Values	Description
bcast_disabled	on empty string ("")	Enables or disables the broadcast. To disable broadcast, set to on. To enable broadcast, set to empty string ("").
rtsp_port	1000...65535, but not 5557	Specifies the port for RTSP streaming. Note port 5557 is used for network discovery and cannot be used for streaming.
streamport	1000...65535, but not 5557	Specifies the port used for streaming. Note port 5557 is used for network discovery and cannot be used for streaming.
ac_override	on empty string ("")	Overrides the global stream access settings or uses global stream access settings. To use global stream access settings, set to empty string (""). To override global stream access settings and use local viewer access permtions, set to on.
ac_viewerpwd	string	Specifies the password for Viewers.
ac_allowips	integer	Displays a list of the allowed IP addresses for live streams
ac_denyips	integer	Displays a list of the denied IP addresses for live streams

Channel encoder configuration keys

The following encoder settings are supported for each channel. For more information on individual items listed, see Configure encoding .

Supported channel encoder configuration keys

Key	Values	Description
autoframesize	on empty string ("")	Enables or disables use of the current signal’s resolution as the frame size. Is switched to off if a frame size is manually specified. To use current signal’s frame size, set to on. To specify frame size directly, set to empty string ("").
codec	h.264 mpeg4 mjpeg	Specifies the stream codec.
fpslimit	1-60	Specifies the frame per second limit. Set to your desired limit.
framesize	wxh for example: 640x480, 720x400, 1024x768, 1920x1080	Specifies the frame (width by height) size in pixels. Set to desired size. Choose from the list in the UI or set a custom value of your choosing up to the maximum output resoultion supported by Standalone VGA Grid
slicemode	on empty string ("")	Enables or disables H.264 slicing for RTP. To enable slicing, set to on. To disable slicing, set to empty string ("").
vbitrate	Integer	Gets or changes the video bit rate in kbit/s.
vbufmode	1 (low delay) 2 (storage)	Specifies the broadcast compression level. For low delay when streaming, specify 1. For best results or recording, set to 2.
vencpreset	0 (Software) 5 (Hardware Accelerated)	Specifies a video encoding preset. For software, set to 0. For hardware acceleration (recommended), set to 5
vkeyframeinterval	integer	Interval time in seconds between key frames in the encoded stream.
vprofile	66 77 100	Specifies the h.264 video profiles. For Baseline profile, select 66. For Main profile, select 77. For High profile, select 100.
qvalue	0...100	Specifies quality for M-JPEG videos.

Channel layout configuration keys

The following settings are channel layout configuration.

To work with layouts, you need to know the integer identifier for the layout. To find your layout's identifier, select the layout from the Admin panel and look for the identifier in the browser's url bar.

Supported channel layout configuration keys

Key	Values	Description
active_layout	integer	Specifies which layout is currently active for the specified channel.

Audio configuration keys

The following audio configuration keys are supported. For more information on individual items listed, see Configure Encoding (Multi-source).

Supported Audio configuration keys

Key	Values	Description
audio	on empty string ("")	Enables or disables audio for the stream. To enable audio, set to on. To disable audio, set to an empty string ("").
audiobitrate	32 64 96 112 128 160 192	Specifies the audio bitrate for the stream. Not applicable for PCM audio codecs.
audiochannels	1 (mono) 2 (stereo)	Specifies the number of audio channels. For mono, set to 1. For stereo, set to 2.
audiopreset	CODECS: pcm_s161e (PCM) libmp3lame (MP3) libfacc (AAC) RATES: 16000 (AAC only) 22050 44100 48000	Specifies an audio code preset in the format CODEC;RATE. i.e. libfaac;22050

Stream publishing configuration keys

The system supports the following stream publishing settings. For more information on publishing the stream, see What is streaming?.

Supported Stream Publishing configuration keys

Key	Values	Description
publish_enabled	on off / any other value	Starts or stops streaming to CDN servers (RTSP, RTMP type streaming including Original Livestream and Wowza Cloud). See Stream to a CDN. To turn streaming on, set to on. To turn streaming off, set to off or to any other value.
publish_type	0 (do not publish) 2 (RTSP Announce) 3 (multicast RTP/UDP) 4 (multicast MPEG-TS over UDP) 5 (multicast MPEG-TS over RTP/UDP) 6 (RTMP push) 7 (Wowza Streaming Cloud) 8 (Original Livestream)	Specifies the type of stream publishing, if any.

Key

Values

Description

publish_enabled

on
off / any other value

Starts or stops streaming to CDN servers (RTSP, RTMP type streaming including Original Livestream and Wowza Cloud). See Stream to a CDN.

To turn streaming on, set to on.
To turn streaming off, set to off or to any other value.

publish_type

0 (do not publish)
2 (RTSP Announce)
3 (multicast RTP/UDP)
4 (multicast MPEG-TS over UDP)
5 (multicast MPEG-TS over RTP/UDP)
6 (RTMP push)
7 (Wowza Streaming Cloud)
8 (Original Livestream)

Specifies the type of stream publishing, if any.

RTSP Announce configuration keys (Publish type 2)

The following settings are supported when the publish type is set to RTSP Announce. For more information on RTSP and these settings, seeTo stream content to a CDN using RTSP announce What is streaming?.

Supported RTSP Annouce configuration keys

Key	Values	Description
rtsp_url	string	Specifies the RTSP server announce URL.
rtsp_transport	tcp udp or empty string ("")	Specifies the RTSP transport, either tcp or udp. Use udp or "" for udp transport Use tcp for tcp transport.
rtmp_username	string	Specifies the username for the RTSP server.
rtmp_password	string	Specifies the password for the RTSP server.

RTP/UDP configuration keys (Publish type 3)

The following settings are supported when the publish type is set to RTP/UDP. For more information on RTP/UDP and these settings, see What is streaming?.

Supported RTP/UDP configuration keys

Key	Values	Description
unicast_address	string (IP address)	Specifies the unicast/multicast address.
unicast_aport	1000...65535, but not 5557	Specifies the UDP port for RTP/UDP audio streaming. Note port 5557 is used for network discovery and cannot be used for streaming.
unicast_vport	1000...65535, but not 5557	Specifies the UDP port for RTP/UDP video streaming. Note port 5557 is used for network discovery and cannot be used for streaming.

MPEG-TS configuration keys (Publish types 4 and 5)

The following settings are supported when the publish type is set to MPEG-TS and for associated SAP distribution. For more information on MPEG-TS and these settings, see What is streaming?Viewing with Session Announcement Protocol (SAP).

Supported MPEG-TS and SAP configuration keys

Key	Values	Description
unicast_address	string (IP address)	Specifies the unicast/multicast address.
unicast_mport	1000...65535, but not 5557	Specifies the UDP port for MPEG-TS streaming. Note port 5557 is used for network discovery and cannot be used for streaming.
sap	on empty string ("")	Enables sharing of recorded files via SAP. To enable sharing files over SAP, set to on. To disable sharing files over SAP, set to an empty string ("").
sap_channel_no	integer	Specifies the SAP channel number.
sap_group	string	Specifies the SAP group name.
sap_ip	string	Specify the SAP annoucement IP.

RTMP push configuration keys (Publish type 6 and 7)

The following settings are supported when the publish type is set to RTMP Push. For more information on RTMP and these settings, see To stream content to a CDN using RTMP push and What is streaming?.

Supported RTMP Push Configuration Keys

Key	Values	Description
rtmp_url	string	Specifies the RTMP server URL.
rtmp_stream	string	Specifies the RTMP stream name, as configured with the CDN.
rtmp_username	string	Specifies the username for the RTMP server.
rtmp_password	string	Specifies the password for the RTMP server.

Livestream configuration keys (Publish type 8)

The following settings are supported when the publish type is set to Original Livestream. For more information on these settings, see Stream to Original Livestream What is streaming?.

Supported Livestream configuration Keys

Key	Values	Description
livestream_channel	string	The channel name, configured at the Livestream server.
rtmp_username	string	Specifies the username for the Livestream server.
rtmp_password	string	Specifies the password for the Livestream server.

Content metadata configuration keys

The following keys are available for configuration of the content's metadata.

Supported Content Metadata Configuration Keys

Key	Values	Description
author	string	Specifies the name of the author for the stream/recording. Refer to description above on handling white space (spaces) in the string.
comment	string	Specifies a comment for the stream/recording. Refer to description above on handling white space (spaces) in the string.
copyright	string	Specifies the copyright for the streaming/recording. Refer to description above on handling white space (spaces) in the string.
title	string	Specifies the title for the stream/recording. Refer to description above on handling white space (spaces) in the string. (This string can be displayed by certain viewing applications by looking at the stream's metadata information.)