Configuration keys for third party APIs

Using HTTP/HTTPS or RS-232, you can send query and configuration commands to your Pearl system. For the RS-232 and HTTP/HTTPS syntax and important considerations, see About RS-232 / serial port commands and About HTTP/HTTPS 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/HTTPS, encode each space:

%20: set_params.cgi?framesize=640%20x%20480

Since Pearl Nano is a single-channel encoder, the channel index number is always 1. Pearl Nano doesn't support multiple channels, multiple layouts, recorders, touch screen, and the Motion JPEG codec. Commands related to these are either ignored (for example, you cannot delete the channel or create a new layout on Pearl Nano), or applied to only a single target item, such as the single channel or layout on Pearl Nano. Commands related to touch screen settings are not supported.

 

The following categories of API keys are supported:

You can also see the list of supported keys when you browse to the following URL, where <address> is the IP address of your Pearl 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 ’s firmware version.
The value is read-only.
mac_address String The ’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 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 About HTTP/HTTPS commands. For details on how to add a text overlay, see the user guide for your Pearl system.

Touch screen settings keys (read/write)

The following configuration keys are supported for modifying the touch screen configuration. The channel number can be omitted from the command when requesting or setting the value for these keys.

Supported Touch Screen Settings configuration keys

Key Values Description
touchscreen_backlight integer( 0...255) Specify the touchscreen backlight level.
touchscreen_enabled

on
empty string ("")

 Enables or disables the touch screen.
To enable the touch screen, set to on.
To disable the touch screen, set to an empty string ("").
touchscreen_info

on
empty string ("")

 Enables or disables system information from the touch screen.
To enable system info from the touch screen, set to on.
To disable system info from the touch screen, set to an empty string ("").
touchscreen_preview

on
empty string ("")

 Enables or disables channel preview on the touch screen.
To enable preview on the touch screen, set to on.
To disable preview on the touch screen, set to an empty string ("").
touchscreen_recordctl

on
empty string ("")

 Enables or disables recording control from the touch screen.
To enable recording from the touch screen, set to on.
To disable recording from the touch screen, set to an empty string ("").
touchscreen_settings on
empty string ("")		 Enables or disables settings changes from the touch screen.
To enable settings changes from the touch screen, set to on.
To disable settings changes from the touch screen, set to an empty string ("").
touchscreen_timeout integer Specify the time in seconds before the touchsreen times out.
For no timeout, use 0.

Recording configuration keys

The following recording settings are supported. Specify the channel or recorder you want 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 local HTTP server on your Pearl 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 Pearl system (not individual channels). For more information about creating Allow and Deny lists to restrict user access, see the user guide for your Pearl system.

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 name, set to an empty string ("").

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 encoding parameters, see the user guide for your Pearl system. For Pearl Nano, the channel index number is always 1.

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
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 resolution supported by the Pearl system.
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 bitrate in kbps.
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

To work with layouts, you need to know the integer identifier of the layout. To find the layout's identifier, select the layout using the and look for the identifier in the browser's url. For Pearl Nano, the layout identifier is always 1.

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 about audio encoding settings, see the user guide for your Pearl system.

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 supports the following stream publishing settings. For more information about streaming, see the user guide for your Pearl system.

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).

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)

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, see the user guide for your Pearl system.

Supported RTSP Announce 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.
rtsp_username string Specifies the username for the RTSP server.
rtsp_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 the user guide for your Pearl system.

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 Session Announcement Protocol (SAP) distribution. For more information on MPEG-TS and these settings, see the user guide for your Pearl system.

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/ RTMPS and these settings, see the user guide for your Pearl system.

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.

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.)