mtv

The mtv command creates, edits, and routes MultiView configurations.

Command Type	DisplayNet
Minimum Version	3.x.x

Usage

mtv list
mtv create <config_name> [<assignment>...]
mtv assign <config_name> <assignment>...
mtv connect <config_name> <target>[,<target>...] [stopstreams | preservestreams]
mtv rename <config_name> <new_name>
mtv delete <config_name>

Subcommands

Subcommand	Description
list (alias refresh)	Returns the existing multiview configurations
create	Creates a configuration; accepts the same assignments as assign
assign	Assigns a layout, sources, and settings to a configuration. See Assignments
connect (alias join)	Routes a configuration to receiver(s). See Connecting
rename	Renames a configuration
delete	Deletes a configuration

Configuration names are case-insensitive; replace spaces with underscores.

Assignments

Assignments can be stacked in a single create or assign command:

mtv create NewConfig layout TwoByTwoLayout surface 12 6cdffb00387f 0 0 surface 13 341b22f00183 0 0

Assignment	Syntax	Description
layout	layout <layout_name>	Sets the configuration's layout
surface	surface <target_surface> <mac> <width> <height>	Assigns a source to a surface. See Surface assignment
frc (alias framerateconverter)	frc <window_number> <true | false>	Enables the frame rate converter for a window. The receiver halves the frame rate of the secondary scaler stream to save bandwidth
controllable	controllable <true | false>	Marks the configuration's surfaces as controllable by KVM cursor routing
ovl.*	ovl.<property> <value>	Per-configuration overlay settings: ovl.state, ovl.fontname, ovl.fontsize, ovl.color, ovl.backgroundcolor, ovl.transparency, ovl.backgroundtransparency, ovl.scaling, ovl.position, ovl.timeout, ovl.positionrotation, ovl.overlaytext

Surface assignment

mtv assign MyConfig layout MyLayout surface 12 6cdffb00387f 0 0

Several surfaces may be assigned in one command:

mtv assign MyConfig layout MyLayout surface 12 6cdffb011b0f 0 0 surface 13 341b22f00183 0 0 surface 14 6cdffb016d55 0 0

Surface assignment rules

• The surface number is the target_surface value from the layout's window definitions, not the window index. Use layout descriptions to find the correct numbers.
• Devices must be referenced by MAC address; device names are not supported here.
• The layout <name> argument is required when assigning surfaces.
• Each source can appear in only one window per configuration.
• The <width> <height> parameters are typically 0 0.

Connecting

mtv connect TwoByTwo MainMonitor

target is the hostname or MAC address of the receiving device. An optional trailing keyword controls what happens to the source streams of the previous route:

Option	Behavior
stopstreams (alias stophdmistreams)	Force-stops the previous HDMI streams
preservestreams (alias preservehdmistreams)	Leaves the previous HDMI streams running

Return value

mtv list

mtv list
{
  "status": "SUCCESS",
  "request_id": null,
  "result": {
    "multiviewconfigs": [
      {
        "MtvConfigurationId": 42,
        "name": "New_Config",
        "layout": "LONE",
        "resolution": "3840x2160@60",
        "surfaces": [
          {
            "MtvConfigurationSurvateId": 95,
            "surface": 2,
            "id": "d88039e5c614",
            "height": 0,
            "width": 0,
            "useFramerateConverter": true
          },
          {
            "MtvConfigurationSurvateId": 96,
            "surface": 1,
            "id": "341b2280dadd",
            "height": 0,
            "width": 0,
            "useFramerateConverter": true
          }
        ],
        "overlays": [
          {
            "MtvConfigurationOverlayId": 35,
            "Scope": "config",
            "surface": -1,
            "State": "off",
            "Fontname": "DejaVu Sans",
            "Fontsize": "30",
            "Color": "ffffff",
            "BackgroundColor": "000000",
            "Transparency": "25",
            "BackgroundTransparency": "80",
            "Scaling": "NORMAL",
            "Position": "BOTTOM_CENTER",
            "Timeout": "0",
            "PositionRotation": "false",
            "OverlayText": "DEVICE_NAME"
          }
        ],
        "connectedDevices": []
      }
    ]
  },
  "error": null
}

Other subcommands

mtv delete MyMultiViewConfig
{
  "status": "SUCCESS",
  "request_id": null,
  "result": null,
  "error": null
}

State and side effects

• DisplayNet allocates the surfaces and tracks window state. The layout, which source occupies which window, and the z-order are DisplayNet's records. Driving the receiver's layout with a raw SDVoE set changes the picture without updating those records, so the configuration can no longer be restored or reproduced.
• Sources join through their scaled stream, so a source needs a SCALER node to appear in a MultiView.
• The composed output runs at a fixed 60 fps. The frame rate of a MultiView is not currently configurable.

Notifications

In async mode, a DN_NOTIFICATION is sent whenever a configuration is added, updated, deleted, or renamed:

Result object	Contains
mtvconfig_update	The changed configuration descriptions
mtvconfig_delete	The deleted configuration names
mtvconfig_rename	Objects with oldname and newname

Update

mtv create New_Config_1 layout MyLayout
{
  "status": "DN_NOTIFICATION",
  "request_id": null,
  "result": {
    "mtvconfig_update": [
      {
        "MtvConfigurationId": 43,
        "name": "New_Config_1",
        "layout": "MyLayout",
        "resolution": "3840x2160@60",
        "surfaces": [],
        "overlays": [
          {
            "MtvConfigurationOverlayId": 36,
            "Scope": "config",
            "surface": -1,
            "State": "off",
            "Fontname": "DejaVu Sans",
            "Fontsize": "30",
            "Color": "ffffff",
            "BackgroundColor": "000000",
            "Transparency": "25",
            "BackgroundTransparency": "80",
            "Scaling": "NORMAL",
            "Position": "BOTTOM_CENTER",
            "Timeout": "0",
            "PositionRotation": "false",
            "OverlayText": "DEVICE_NAME"
          }
        ],
        "connectedDevices": []
      }
    ]
  },
  "error": null
}

Delete

mtv delete MyMTVConfig
{
  "status": "DN_NOTIFICATION",
  "request_id": null,
  "result": {
    "mtvconfig_delete": [
      {
        "mtvConfigurationId": 43,
        "name": "MyMTVConfig"
      }
    ]
  },
  "error": null
}

Rename

mtv rename New_Config_1 MyMTVConfig
{
  "status": "DN_NOTIFICATION",
  "request_id": null,
  "result": {
    "mtvconfig_rename": [
      {
        "mtvConfigurationId": 43,
        "oldname": "New_Config_1",
        "newname": "MyMTVConfig"
      }
    ]
  },
  "error": null
}

REST API

Endpoint type	DisplayNet API command
Address	POST /api/displaynet/<operation>, or name the operation in the body of a POST /api/displaynet. See Sending commands.
Role	User

Subcommand	Operation	Parameters
assign	mtv_assign	config [assignments]*
connect	mtv_connect	config targets [option]
create	mtv_create	name [settings]*
delete	mtv_delete	name
list	mtv_list	—
rename	mtv_rename	name new_name

A parameter in brackets is optional. A parameter marked * takes the remainder of the command line as one string. Pass the text exactly as you would type it on the TCI interface.

See also

• layout: define the layouts configurations are built on
• disconnect: disconnect mtv <receiver> exits a multiview
• set scaler: the scaled-stream resolution used by multiview sources