Documentation Center

Service Host

Version 1.0 | Published November 15, 2017 ©

Channel Recorder Control Commands

The application Viz Send, included in Viz Artist installation, can be used to communicate with Channel Recorder. Connect the tool to the port specified in the configuration file. The following commands are implemented in the service:

ABOUT

Command

Description

ABOUT GET

Print license information of all libraries used in this software.

MAIN

Some of the following commands must be called during initialization. These commands are striked through. To configure these commands, use the configuration web interface and the restart the service. Refer to Channel Recorder Configuration for more information.

Command

Description

MAIN VERSION

Return application version.

GET VERSION

Same as MAIN VERSION. Return application version.

MAIN HOSTNAME

List all available boards.

MAIN SVCNAME

Select a board. The board is identified by the serial number. If the board with the given number is not found, the first board will be selected.

MAIN BOARD LIST

List all available boards.

MAIN BOARD SELECT

[serial number]

Select a board. The board is identified by the serial number. If the board with the given number is not found, the first board will be selected.

MAIN BOARD GET

Return the selected boards.

MAIN CONNECTOR SELECT

[connector number]

([address] [port])

Select a connector. Connectors are labeled consecutively from A to H. The [address] and [port] parameters are required for IP boards only, and defines which IP address and UDP port the Channel Recorder will listen to for the input stream.

MAIN CONNECTOR GET

Return the selected connector.

MAIN CLOCKTYPE

[type]

Select the type of clock. [type] can be one of:

INPUT: Use the clock on the input signal. With this mode the record can start without any input or genlock signal being connected. If there is no input signal black will be recorded.

GENLOCK: Use the genlock signal. This is the default type and what was being used in 1.0.

MAIN CRASH

[type]

Crash the service. [type] can either be omitted or be one of:

MAIN: Crash the service (same as when omitted).

RECORD: Crash the recording thread.

OUTPUT

One output target can be initialized during startup. During execution more than one output can be enabled. For instance you can have VideoOut A and Coder enabled. Please refer to Channel Recorder Configuration to initialize an output during startup.

Command

Description

OUTPUT GET

List the active targets.

OUTPUT LIST

List available targets.

OUTPUT START

[target]

Start an output handler for the specified [target]. Several output handlers can be started in parallel, but only one is allowed for each target. Valid targets are:
VideoOut: This target requires one additional parameter: [connector]. The [connector] parameter specifies the video output connector of the Matrox board.

Example:
OUTPUT START VideoOut A

Coder: This target requires three additional parameters, [SHM name], [address] and [port].
[SHM name] is the name of the shared memory area the fields will be written to. The name cannot contain whitespace characters.
[address] denotes the IP address or host name of the proxy service, and [port] is used to specify which port the service is listening to.

Example:
OUTPUT START Coder SHMCoder1 localhost 12345

OUTPUT STOP

[target]

Stop the output handler for the specified target.

RECORD

Crash recording / one-time scheduling

These are specific commands used only for crash and one-time scheduling of recording. These command are available from version 1.0. For scheduling it is recommended to use RECORD SET introduced from version 1.1.

Command

Description

RECORD CLIP

[clip name]

Set the clip name and initialize the recorder. This command does not start recording (see RECORD START).

RECORD START

[duration]

[start time]

[end mode]

Start or continue recording. The [duration], [start time], and [end mode] parameters are optional. However, the parameters are interdependent as follows:

If the parameter [start time] is provided, [duration] is also required.
If the parameter [end mode] is provided, [duration] is also required.

The format for both is Timecode (see Data Types).
[duration] and [start time] can be zero timecode, which will then be ignored.

[end mode] can either be STOP, which finalizes and closes the clip, or PAUSE (default behavior), where the clip stays open and can be used for further recording.

RECORD PAUSE

Pause recording.

RECORD STOP

[end time]

Stop recording and flush the recorder. A new clip needs to be set afterwards (see RECORD CLIP).
The end time is optional and specifies the timecode when the recording should end.

Example crash recording:

RECORD CLIP crashRecording.mxf

RECORD START

RECORD STOP

Example one-time scheduling recording:

RECORD CLIP crashRecording.mxf

RECORD START 600 15:00:00:00

Loop recording

These are specific commands used only for loop recording. It allows setup, start or stop loop recording. These are introduced from version 1.1.

Command

Description

RECORD LOOP

[key=value]

...

[key=value]

[operation]

Start, stop or configure the settings for loop recording. Any number of properties can be applied in the form of key-value-pairs. If no property is supplied, and the entry does not yet exist, it is added with the default values. Available keys are:

  • PREFIX Prefix to the filename. It will be appended with the timestamp of the start time.

  • POSTFIX Postfix to the filename. Will be appended after the timestamp.

  • LENGTH Length of the loop in frames or timecode. At least this amount of frames will reside on the disk. The minimum length value is 00:02:00:00 or the equivalent number of fields / frames.

  • CHUNK The size of one chunk in frames or timecode. The chunk size influences the loop length. The minimum chunk value is 00:00:30:00 or the equivalent number of fields / frames.

  • DISKSIZE The size of the loop is defined by the size of the clips on the disk. The oldest clips are deleted until the disk size drops below the specified value.

  • DISKFREE The size of the loop is defined by the space left on the disk. If it drops below the value, the oldest clips are deleted until at least the specified amount is free again.

[operation] can be START or STOP. When no [operation] is specified then only the settings are set for the specified key-value-pairs. It is possible to specify [key=value] [operation] at the same time but only when [operation] is START.

Example:

RECORD LOOP LENGTH=00:05:00:00 CHUNK=00:00:30:00 PREFIX=Loopy START

RECORD LOOP STOP

Scheduled recording

These are specific commands used only for scheduled recording. It allows setup, start or stop scheduled recording.

Command

Description

RECORD SET

[name]

[key=value]

...

[key=value]

Add a new clip to the timeline, or change a property of an entry defined by [name]. Any number of properties can be applied in the form of key-value-pairs. If no property is supplied, and the entry does not yet exist, it is added with the default values. Available keys are:

  • CODEC Set the codec type of the recorded file. By setting the codec type, default values for bitrate and audio will also be set.

  • CONTAINER Set the container type of the recorded file. With the container type, a default codec is also set. By setting the container type, a valid recording can be started.

  • BITRATE Set the bitrate for the video encoding. The value can either be applied as bits per second or as Megabits per second. Not all codecs allow changes to the bitrate. In such cases, BITRATE will be ignored.

  • IN Set the timecode when the recording should start.

  • OUT Set the timecode when the recording should stop.

  • DURATION Set the default value for the recording duration. The initial value is 0.

  • VBR Enable or disable VBI

  • TDIRENABLE Set the default behavior of Time Delayed Instant Replay (TDIR).

  • AUDIOCHANNELS Set the number of audio channels to record. How many channels are actually recorded depends on the codec and the input signal.

  • STARTTC Defines which start timecode to use for the recording.

For more information regarding these settings possible values and default values check the section CONFIG SET below.

RECORD REMOVE

[name]

...

[name]

Remove the entry [name]. Multiple [name] arguments can be provided.

RECORD GET

[name] | [key]

...

[name] | [key]

List all entries or show the properties of an entry. If no parameter is applied, a list of all scheduled clips is returned. Any number of [name] and [key] can be applied. The values of all keys will be returned for all values. If no [key] is provided, all values of the applied keys will be returned and vice versa. This means that if you call RECORD GET with clip names only, the command returns all properties of these clips. When called with properties only, it will return this property for all clips. A special [key] is TIMELINE, which returns all entries in the timeline.

Common record commands

Some of these commands are only used for loop and crash recording, while others are used for all three modes.

Command

Description

RECORD DURATION

If no duration parameter is applied to the command, it returns the timecode relative to the start timecode. If a duration parameter is applied, the duration of an ongoing recording is changed. The duration parameter can be specified as either a number of frames or a timecode (see Data Types). In the case of loop and schedule recording the value used to set using this command is ignored.

RECORD RESOLUTION GET

Returns the resolution the Channel Recorder is running at.

RECORD STATE

Returns the state the Record Channel service is in. By default state is idle. State is only invalid when the clip was configured incorrectly (e.g. container / codec combination is wrong).

State flow:
 

 Idle -- Start() --> Recording -- Stop() --> Paused
   ^                     |                      |
   `-- Flush() ----------+---------------------´

RECORD STARTTC [starttc]

Defines which start timecode to use for the recording. If the command is not called before the recording starts, the current timecode is written to the clip. If no value is given, the command returns the current value. This is only used for loop and schedule recording.

CONFIG

Command

Description

CONFIG GET

Get the current settings.

CONFIG LIST [argument]

List all available variables. The optional [argument] flag provides information specific to the applied argument. Known arguments are:

  • CONTAINER - displays all known container types.

  • CODEC - displays all known codec types.

  • DUMP - displays the current dump file setting.

  • PRIORITY - displays the current process priority setting.

CONFIG SET [variable] [value]

Set the [variable] to [value]. To get all available variables, call CONFIG LIST. Refer also to variables and values for CONFIG SET below.

CONFIG SET

Variabled and values for CONFIG SET command. The CONFIG SET command is used to set the configuration globally, this means that all the recording mode will use these settings by default unless specified otherwise. Only schedule recording can specify different settings for each schedule by specifiying them via RECORD SET command.

Variable

Value

AUDIOCHANNELS [channels]

Set the number of audio channels to record. How many channels are actually recorded depends on the codec and the input signal.

BITRATE [rate]

Set the bitrate for the video encoding. The value can either be applied as bits per second or as Megabits per second. Not all codecs allow changes to the bitrate. In such cases, BITRATE will be ignored.

CLIP_ROOT [path]

Set the root folder for the captured files. If the filename in command RECORD CLIP does not contain a absolute path name, the CLIP_ROOT is prepended.

CODEC [codec type]

Sets the codec type of the recorded file. By setting the codec type, default values for bitrate and audio will also be set. These values can be changed (see below). Not all codec types are available with all container types.
Available codec types are:

  • Default

  • DvCam

  • DvCPro

  • Dv50

  • IFrame

  • XDCam (See note regarding bitrates specification)

  • XDCamEX (See note regarding bitrates specification)

  • XDCamHD (See note regarding bitrates specification)

  • AVCIntra50

  • AVCIntra100ProRes

Note 1: To utilize the TDIR capabilities of the ProRes codec with a .mov container in Viz Engine, you must use the .Ref-file

Note 2: When container is XDCAMMXF the default codec will be XDCam which is HD422. The default bitrate for XDCam, XDCamEX and XDCamHD are 50, 35 and 35 or 25 repectively. XDCamEX will output 1920x1080 clip at 35 Mbps and XDCamHD will output 1440x1080 clip at 35 Mbps (VBR) or 25 Mbps (CBR) depending on the bitrate chosen.

CONTAINER [container type]

Sets the container type of the recorded file. With the container type, a default codec is also set. By setting the container type, a valid recording can be started.
Known container types are:
DefaultAVCINTRAMXF - see note regarding audio and timecode support
AVI
DVCPROMXF - see note regarding audio and timecode support
MOV
MXF - see note regarding audio and timecode support
XAVCMXF - Requires a Matrox M264 card in order to work. Also, see note regarding audio and timecode support.
XDCAMMXF- see note regarding audio and timecode support

Note: The MXF container type uses the OP-Atom format and does not include audio or timecode information. However, the AVCINTRAMXF, DVCPROMXF, XAVCMXF and XDCAMMXF container types all use the OP1a format, which features audio and timecode support. Refer to the Supported Codecs for further details.

DISKACCESSSIZE [size]

Set the size of data blocks written to the disk in byte. Postfixes like KiB, Kb, k, etc., are allowed, but must not be separated from the value with a blank space (see example).
The default value is 4 MiB (4194304 bytes).
The minimum value is 32 KiB (32768 bytes).
KiB and k multiplies the value by 1024.kb multiplies the value by 1000.
The same works with m for mega and g for giga.

Example:
CONFIG SET DISKACCESSSIZE 1024KiB- sets the data block size to 1048576 bytes (one mebibyte).

DUMP [NORMAL | PRIVATE | FULL]

Set the dump file content to the specified value:
NORMAL: Include just the information necessary to capture stack traces for all existing threads in a process.
PRIVATE: Includes the contents of every readable and writable private memory page.
FULL: Include all accessible memory in the process. 

DURATION [frames|timecode]

Set the default value for the recording duration. The initial value is 0.
When applying a duration to the RECORD START command, the default value is ignored but not changed.
Refer to Data Types for information on time code formatting.

FILEEXTENSION [boolean]

Enables or disables automatically adding a file extension to the file name. If this feature is turned off, the client application has full control over the file name. The default value is ON.Please refer to Data Types for details on accepted boolean values.

PERSINTERVAL [seconds]

Set the interval, at which the data is written to the disk. The value is in seconds and fractions of seconds, meaning both 0.1 and 1.0 are considered valid values. A value of 0 means that every change is written.
The default value is 0.

PERSISTENCE [bool]

Turn on persistence for operational data like the config and the timeline.
The default value is ON.

PRIORITY [priority]

Sets the process priority class. The values correspond to the Windows process priority. Valid values for [priority] are:
DefaultIDLEBELOW_NORMALNORMAL = DefaultABOVE_NORMALHIGHREALTIME

RINGBUFFERSIZE [size]

Set the size of the capture ring buffer. The default value is 60. 

RESOLUTION [resolution]

Set the default resolution. Format of [resolution] is:
WxHs@F, WxHs@FM, Hs@F, Hs@FM, NTSC, PAL
With W = Width, H = Height, s = Scanmode, F = Framerate, and M = Drop Frame Flag.
Possible values for s are:

  • i or I: Interlaced

  • p or P: Progressive

  • psf or PSF: Progressive segmented

M is optional, and as an alternative, you can use framerate with two decimal points (e.g. 30M = 29.97).
Examples: NTSC, PAL, 1280x720p@50, 1920X1080P@50, 1280x720p@60M, [email protected], 720p50, 720P60M, 1080P50.
This flag must be set before selecting a connector using MAIN CONNECTOR SELECT.

The default value is NTSC.

STOPATEND [boolean]

Set the default behavior at the end of the recording.
The default setting is NO/FALSE/OFF.
Refer to Data Types for details on accepted boolean values.

TCLOGINTERVAL [frames|timecode]

Specify the interval at which the current timecode is logged. The value can either be a number of frames or a timecode-based relative value. The default value is 0, which means that every full second is logged.

TDIRENABLE [boolean]

Set the default behavior of Time Delayed Instant Replay (TDIR).
The default setting is ON.

TDIRINTERVAL [time]

Set the interval of file header updates in TDIR recordings. The value is in seconds and fractions of seconds, meaning both 0.1 and 1.0 are considered valid values. Minimum allowed value is 0.001, which is interpreted by Channel Recorder as every frame. A typical value would be 10.0, the default value is 3.0.

IMPORTANT! In order to secure proper operation with Viz Engine, this value must not exceed 10.0.

TIMECODE [source]

Specify the timecode source. Valid values for [source] are:
DefaultZERO_BASED: The timecode written to the file starts at 00:00:00:00.
VITC = Default: Write the ATC/VITC from the input signal to the file.
LTC: Write the ATC/LTC from the input signal to the file.
TIME_OF_DAY: Write the current system time to the file. In order to get a proper time from the system, the system time must be synchronized using a time server.

Note: From version 1.1 Channel Recorder is able to read SMPTE 12M-1 VITC timecode from PAL and NTSC signals

TIMEOUT [timecode]

Set the timeout for the capture operation in milliseconds. If the recorder reports timeout errors, increasing the timeout could help.
Refer to Data Types for information on time code formatting.

TRIGGERTHRESHOLD [frames|timecode]

If a timed command misses the execution time, but is still within the trigger threshold, it will be executed (late). Outside of this window, the command is ignored until the next time the timecode is received. The value can either be a number of frames or a timecode-based relative value.

The default value is 5 frames.

UHD [bool]

Enable detection of UHDTV signals. When set to ON, the Channel Recorder scans the signal resolution on the four corresponding input connectors. If four 3G signals are detected, they are interpreted as one UHDTV signal. When set to OFF, the four connectors are treated as separate 3G signals.
This flag must be set before selecting a connector using MAIN CONNECTOR SELECT.

The default value is OFF.

VBI [bool]

Turn off VBI recording. The default value is ON.
This flag must be set before selecting a connector using MAIN CONNECTOR SELECT.

V210 [bool]

Use the 10-bit surface format V210. This is needed to record XAVC. It also increases performance when for example recording ProRes. This surface format is not supported on the Matrox X.mio2+.
This flag must be set before selecting a connector using MAIN CONNECTOR SELECT.

The default value is OFF. 

WRITERS [number]

Set the number of writers to initialize. More writers increases memory consumption.
This flag must be set before selecting a connector using MAIN CONNECTOR SELECT.

The default value is 2.

COMMUNICATION

Command

Description

COMMAND_HANDLER PORT SET [port]

Set the port of the command interface. A port can only be set once.

COMMAND_HANDLER DUMP

Prints this list of available commands.

MVCP PORT [port]

Set the port for the MVCP communication. This command is required to initialize MVCP.

EXIT

Command

Description

exit, EXIT

Stop all channels, clean up the hardware and stop the service.