Matrox Monarch HD User manual

Y11308-301-0219
Matrox Monarch HD
Dev Tools Reference Guide
May 16, 2017

Copyright © 2017 Matrox Electronic Systems Ltd. All rights reserved.
Disclaimer Matrox Electronic Systems Ltd. reserves the right to make changes in specifications at any time and without notice. The
information provided by this document is believed to be accurate and reliable. However, no responsibility is assumed by Matrox Electronic
Systems Ltd. for its use; nor for any infringements of patents or other rights of third parties resulting from its use. No license is granted
under any patents or patent rights of Matrox Electronic Systems Ltd.
Unauthorized recording or use of broadcast television programming, video tape, or other copyrighted material may violate copyright laws.
Matrox Electronic Systems Ltd. assumes no responsibility for the illegal duplication, use, or other acts that infringe on the rights of
copyright owners.
Matrox Electronic Systems Ltd.
1055 St. Regis Blvd., Dorval, Quebec, Canada H9P 2T4
Tel: [phone] Fax: [phone] World Wide Web: www.matrox.com
Trademarks
Matrox Electronic Systems Ltd. ...........................................................................Matrox
®
, Monarch
™
All other nationally and internationally recognized trademarks and tradenames are hereby acknowledged.

Chapter 1
Using the Monarch HD Control API
Monarch HD Control API Overview ........................................................... 2
Commands ................................................................................................ 2
GetStatus ......................................................................................................... 3
StartStreaming.................................................................................................. 3
StartRecording ................................................................................................. 4
StartStreamingAndRecording ........................................................................... 4
StopStreaming.................................................................................................. 4
StopRecording.................................................................................................. 5
StopStreamingAndRecording ........................................................................... 5
GetInputStatus.................................................................................................. 5
SetStreamingVideoDataRate ............................................................................ 6
GetStreamingVideoDataRate............................................................................ 6
SetRTSP............................................................................................................ 6
GetRTSP ........................................................................................................... 7
SetRTMP .......................................................................................................... 7
GetRTMP .......................................................................................................... 8
SetRecordFileName.......................................................................................... 8
GetRecordFileName ......................................................................................... 8
Example third-party tools .......................................................................... 8
GNU Wget ........................................................................................................ 9
cURL................................................................................................................. 9
PHP (cURL) ...................................................................................................... 9
C#..................................................................................................................... 9
Chapter 2
Configuring the Monarch HD XML File
Monarch HD XML configuration overview ................................................ 12
How it works ...................................................................................................12
Generating an XML file ....................................................................................12
Guidelines for working with the XML file ..........................................................12
Sample XML and parameter descriptions ................................................ 13
<MatroxMonarch> ...........................................................................................15
<deviceName>.................................................................................................15
<monarchSettingsVersion> ..............................................................................15
Contents

iv
Contents
<configuration>................................................................................................ 16
<audio>............................................................................................................ 16
<encoder1> and <encoder2> ........................................................................... 16
<encoderParam> ................................................................................................................ 16
<recordParam> ...................................................................................................................18
<streamParam> .................................................................................................................. 18
<useEncoder2Param> ....................................................................................................... 20
Additional XML configuration ...................................................................20
Dynamic bit rate ............................................................................................. 20
Call home ....................................................................................................... 20
Periodic call home ........................................................................................... 21
Stop and Start control ..................................................................................... 21
Processing order of the XML tags ...........................................................22
XML configuration sample scenarios.......................................................22
Streaming to a CDN using RTMP only (no recording enabled) ....................... 22
Changing encoding parameters for recording................................................ 23
Start streaming............................................................................................... 23
Change bit rate while streaming..................................................................... 24
Chapter 3
Using the Monarch HD Command Line Utility
Updating or rebooting the Monarch HD using the command line ...........26
Update/reboot command line syntax examples..............................................27
Update on a different subnet ..............................................................................................27
Reboot on the same subnet ...............................................................................................27

1
Using the Monarch HD Control API
This chapter describes how to use
the Monarch HD HTTP-based
Control API to control the
streaming and recording functions
for a Monarch device.

2
Chapter 1, Using the Monarch HD Control API
Monarch HD Control API Overview
The Monarch HD Control API is an HTTP-based API that allows you to control the
streaming, recording, and other related functions for a Monarch HD device using
third-party applications and scripting languages.
Users and system integrators can create their own software to control the various
functions of a Monarch device, such as starting or stopping streaming/recording,
getting the device status, and more.
Commands
Commands can be sent to Monarch HD using the following URL syntax (HTTP):
http://<username>:<password>@<ipAddress>/Monarch/syncconnect/sdk.aspx?com
mand=<command>.
Where:
• <username> is the username that is set in the Monarch device (default: admin).
• <password> is the password that is set in the Monarch device (default: admin).
• <ipAddress> is the network IP address of the Monarch device.
• <command> is one of the following commands:
For examples of how to use the command line in third-party applications, see
“Example third-party tools” on page 8.
API commands
GetStatus SetStreamingVideoDataRate
StartStreaming GetStreamingVideoDataRate
StartRecording SetRTSP
StartStreamingAndRecording GetRTSP
StopStreaming SetRTMP
StopRecording GetRTMP
StopStreamingAndRecording SetRecordFileName
GetInputStatus GetRecordFileName

3
Commands
GetStatus
This command is used to acquire the current status of a Monarch HD device.
Returns:
• RECORD: <state>, STREAM:<mode>,<state>, NAME:<devicename>
Where:
$<state> is ON, READY or DISABLED
$<mode> is RTSP, RTMP or DISABLED
$<devicename> is the name of the Monarch HD device as set by the client in
the Monarch HD Command Center
• RETRY, if two or more commands are sent to the Monarch at the same time, or if
the Monarch is executing a command while receiving another. The first
command received will execute, and the others will return RETRY.
The following table shows example returns based on the device name, encoding
mode, and stream/record status:
StartStreaming
This command is used to start the stream function on a Monarch HD device that is set
to RTMP mode.
Returns:
• SUCCESS, if streaming is enabled on the device (Stream-only or
Stream-and-record mode) and the stream was started successfully. If the device is
in RTSP mode, this command will return “SUCCESS”.
• FAILED, if streaming is not enabled on the device (Record-only mode), or the
RTMP stream could not be started.
Device name Operating mode Stream status Record status
Example 1 Device1 Stream-and-record RTMP - Not streaming Not recording
RECORD: READY, STREAM:RTMP,READY, NAME:DEVICE1
Example 2 Device2 Stream-and-record RTSP - Client not connected Recording
RECORD: ON, STREAM:RTSP,READY, NAME:DEVICE2
Example 3 Device3 Stream-and-record RTSP - Client connected Recording
RECORD: ON, STREAM:RTSP,ON, NAME:DEVICE3
Example 4 Device4 Record-only N/A Not recording
RECORD: READY, STREAM:DISABLED,DISABLED, NAME:DEVICE4
Example 5 Device5 Stream-only RTMP - Streaming N/A
RECORD: DISABLED, STREAM:RTMP,ON, NAME:DEVICE5

4
Chapter 1, Using the Monarch HD Control API
• RETRY, if two or more commands are sent to the Monarch at the same time, or if
the Monarch is executing a command while receiving another. The first
command received will execute, and the others will return RETRY.
StartRecording
This command is used to start the record function on a Monarch HD device.
Returns:
• SUCCESS, if recording is enabled on the device (Record-only or
Stream-and-record mode) and the recording was started successfully.
• FAILED, if recording is not enabled on the device (Stream-only mode), or the
recording could not be started.
• RETRY, if two or more commands are sent to the Monarch at the same time, or if
the Monarch is executing a command while receiving another. The first
command received will execute, and the others will return RETRY.
StartStreamingAndRecording
This command is used to start the stream (RTMP mode) and record functions
simultaneously on a Monarch HD device.
¦NoteIn RTSP mode, the Monarch is always in an active streaming state that cannot
be stopped or started. Therefore, we do not recommend using this command when in
RTSP mode. Use the commands StartRecording and StopRecording instead.
Returns:
• SUCCESS, if both streaming and recording are enabled on the device
(Stream-and-record mode) and the stream and recording was started successfully.
• FAILED, if either streaming or recording is not enabled on the device
(Stream-only or Record-only mode), or the RTMP stream or recording could not
be started.
• RETRY, if two or more commands are sent to the Monarch at the same time, or if
the Monarch is executing a command while receiving another. The first
command received will execute, and the others will return RETRY.
StopStreaming
This command is used to stop the stream function on a Monarch HD device that is set
to RTMP mode.
Returns:
• SUCCESS, if streaming is enabled on the device (Stream-only or
Stream-and-record mode) and the stream was stopped successfully.
• FAILED, if streaming is not enabled on the device (Record-only mode). If the
device is in RTSP mode, this command will return “FAILED”.

5
Commands
• RETRY, if two or more commands are sent to the Monarch at the same time, or if
the Monarch is executing a command while receiving another. The first
command received will execute, and the others will return RETRY.
StopRecording
This command is used to stop the record function on a Monarch HD device.
Returns:
• SUCCESS, if recording is enabled on the device (Record-only or
Stream-and-record mode) and the recording was stopped successfully.
• FAILED, if recording is not enabled on the device (Stream-only mode).
• RETRY, if two or more commands are sent to the Monarch at the same time, or if
the Monarch is executing a command while receiving another. The first
command received will execute, and the others will return RETRY.
StopStreamingAndRecording
This command is used to stop the stream (RTMP mode) and record functions
simultaneously on a Monarch HD device.
¦NoteIn RTSP mode, the Monarch is always in an active streaming state that cannot
be stopped or started. Therefore, we do not recommend using this command when in
RTSP mode. Use the commands StartRecording and StopRecording instead.
Returns:
• SUCCESS, if both streaming and recording are enabled on the device
(Stream-and-record mode), and the stream and recording was stopped
successfully.
• FAILED, if either streaming or recording is not enabled on the device
(Stream-only or Record-only mode).
• RETRY, if two or more commands are sent to the Monarch at the same time, or if
the Monarch is executing a command while receiving another. The first
command received will execute, and the others will return RETRY.
GetInputStatus
This command is used to acquire the input resolution of a Monarch.
Returns:
• This command will return the HDMI video input resolution and framerate.
Example: HDMI: 1920x1080i, 29.97 fps
• If the input does not have an HDMI cable connected to it, this command will
return “No video input”.

6
Chapter 1, Using the Monarch HD Control API
• RETRY, if two or more commands are sent to the Monarch at the same time, or if
the Monarch is executing a command while receiving another. The first
command received will execute, and the others will return RETRY.
SetStreamingVideoDataRate
This command is used to set the data rate (in kb/s) dynamically without stopping a
current streaming operation. For this command to work, the device must be in
Stream-only mode. The minimum data rate will be set to 90% of the average, and the
maximum data rate will be set to 110% of the average data rate.
Format:
• SetStreamingVideoDataRate,<average bit rate>
• Average bit rate value must be between 50 and 20000.
Returns:
• SUCCESS, if the bit rate is set.
• FAILED, if the value is outside the 50 to 20000 range.
• RETRY, if two or more commands are sent to the Monarch at the same time, or if
the Monarch is executing a command while receiving another. The first
command received will execute, and the others will return RETRY.
GetStreamingVideoDataRate
This command is used to acquire the average video data rate in kb/s (bit rate) that is
currently programmed on the device. The device must be in Stream-only mode for
this call to succeed.
Returns:
• BITRATE: <average bit rate>
• FAILED, if Stream-only mode is not enabled on the device.
• RETRY, if two or more commands are sent to the Monarch at the same time, or if
the Monarch is executing a command while receiving another. The first
command received will execute, and the others will return RETRY.
SetRTSP
This command is used to set the RTSP URL and port, as well as switch the streaming
mode to RTSP on the device. This command will always fail unless the Monarch is
idle (not streaming or recording).
Format:
• SetRTSP,<url name>,<port>.
• <url name> is the path to connect to and <port> is either 554 or 8554.
Returns: