---
title: Multiscreen VideoMode
slug: technical/multiscreen-videomode
docTags: 
createdAt: 2025-03-11T07:10:25.852Z
---

The XC2055, XC4055 and XT2145 BrightSign players have multiple independent video outputs. This page describes how to configure these outputs with BrightSign APIs.

# Relevant APIs

For multiple outputs the relevant API is `roVideoMode` `SetScreenModes` and the corresponding `GetScreenModes` (for single output players the main API is `roVideoMode` `SetMode`).

`GetScreenModes` returns an `roArray` of `roAssociativeArray` which describe each available output on the platform and how they are configured. The members of the `roAssociativeArray` are:

- *name*: On the XC platform, the possible values are `HDMI-1`, `HDMI-2`, `HDMI-3`, or `HDMI-4`.  The number of array items depend on the number of outputs:
  - The XC2055 has two outputs, HDMI-1 and HDMI-2
  - The XC4055 has four outputs, HDMI-1, HDMI-2, HDMI-3, and HDMI-4
  - The name tells the system which output is associated with the rest of the settings in that entry within the `roAssociativeArray` (the order of the HDMI outputs is not important).
- *video\_mode*: The videomode can be either
  - A known BrightSign format videomode (for example, *1920x1080x60p)*
  - A full modeline as described [here](docId:58VplQM4sGH_VgqVs4Frs).
  - *auto* which differs slightly from previous platforms. *auto* isn’t recommended when using multiple outputs because the canvas positions are fixed and so if a screen uses an unexpected resolution then it won’t be positioned correctly in the canvas.
- *display\_x* and *display\_y*: The position of the screen within the overall canvas. The origin 0,0 is the top left corner, and each screen can be positioned relative to that. This allows for bezel compensation as gaps can be left on the canvas between screens.
- *transform*: `normal`, `90`, `180` or `270`. Each screen can be rotated independently. When a screen is rotated, it rotates all of the content including video. If a single screen is set to *1920x1080x60p* and `90` then the screen is running in portrait mode and all of the firmware will run as if the screen is set to *1080x1920x60p* with video and graphics all rotated.
- *enabled*: Whether the screen is enabled for output. To turn an output to off, set `enabled = false`. No other fields need to be set.

If you do not want to change the existing screen settings, do not enter a value for those settings.

:::hint{type="danger"}
The frame rates on all screens must be an exact match to ensure precise synchronization.
:::

# Videomode Plugins

Videomode plugins allow you to set custom multi-screen video modes. This feature has been updated to support multi-screens in BrightSign Author version 1.13.0 and later and BrightAuthor Classic version 5.0.1.1 and later. You must match the graphics mode that you set when authoring the presentation. See [here](docId:58VplQM4sGH_VgqVs4Frs) for more info.

## Example

`SetScreenModes` takes the argument that `GetScreenModes` returns. To configure a 1x2 video wall with bezel compensation:

```text
vm=CreateObject("roVideoMode")
sm = vm.GetScreenModes()

sm[0].video_mode="1920x1080x60p"
sm[0].transform = "normal"
sm[0].display_x=0
sm[0].display_y=0
sm[0].enabled=true

sm[1].video_mode="1920x1080x60p"
sm[1].transform = "normal"
sm[1].display_x=0
sm[1].display_y=1100    ' Bezel compensation of 20 pixels
sm[1].enabled=true

sm[2].enabled=false
sm[3].enabled=false

vm.SetScreenModes(sm)
```

In this case the resulting canvas will be 1920x2180, and full screen video and graphics will display across the whole canvas.

If a screen is `enabled`, but isn't plugged in, then the correct size is used for the missing screen so that the canvas size and shape remains constant. Obviously, this isn’t possible with `auto` mode as the screen size is unknown and so again *auto* mode is dis-recommended for use with multiple outputs.

Note that if a script calls `SetMode` on a player capable of multiple screen outputs, then it effectively calls `SetScreenModes` with just the first screen `enabled` and a transform of `normal`.

For internal debugging, the registry entry `.bs/vms` is where the screen configuration is stored as a JSON string. For the above example it looks like this:

```text
{"HDMI-1":{"mode":"1920x1080x60p","transform":"normal","x":0,"y":0},"HDMI-2":{"mode":"1920x1080x60p","transform":"normal","x":0,"y":1100}}
```

That is turned into an initialization file which is stored in memory. Currently, that format looks like this:

```text
[core]
require-input=false
idle-time=0

[shell]
panel-location=""
panel-position=none
background-color=0xff000000
animation=none
close-animation=none

[output]
name=HDMI-A-1
mode=148.5 1920 2008 2052 2200 1080 1084 1089 1125 +hsync +vsync
force-on=true
transform=normal
x_position=0
y_position=0

[output]
name=HDMI-A-2
mode=148.5 1920 2008 2052 2200 1080 1084 1089 1125 +hsync +vsync
force-on=true
transform=normal
x_position=0
y_position=1100

[output]
name=HDMI-A-3
mode=off
force-on=false
transform=normal
x_position=0
y_position=0

[output]
name=HDMI-A-4
mode=off
force-on=false
transform=normal
x_position=0
y_position=0
```

Note that the BrightSign style mode is passed to our compositor as a complete modeline.