Object Creation: The roVideoMode object is created with no parameters.
The roVideoMode object generates roHdmiInputChanged and roHdmiOutputChanged event objects whenever the hotplug status of the HDMI input or output changes.
SetMode(mode As String) As Boolean
Sets the video output mode. If the specified video mode is different from the current video mode of the object, the unit will reboot and change the video mode to the new setting during system initialization. See here for a list of supported video modes. This method also accepts "auto" as a mode parameter. The following optional parameters can be appended to the string
<resolution>:<color_space>:<depth>bit: The video profile for HDMI output. For example, to output 4Kp60 at the 4:2:0 color space with 10 bits of depth, you would pass the following string: "
<resolution>:preferred: A preferred video-mode flag. This instructs the player to only use the video mode if the display EDID indicates that it is supported. Otherwise, the output will default to "auto" mode. If no EDID is detected at bootup, the player will output the preferred video mode. If an HDMI hotplug event occurs afterward, then the player will perform the preferred video-mode check again. The
:preferredflag currently ignores video profile settings (i.e. color space and bit depth).
<resolution>:rgb:<range>: The RGB range setting for the video mode. The
<range>parameter can be either "fullrange" for RGB Full (0-255) or "limitedrange" for RGB Limited (16-235). For example, to output 1080p60 at RGB Full, you would pass the following string:
BrightSign hardware has a video anti-aliasing low-pass filter that is set automatically.
SetModeForNextBoot(video_mode As String) As Boolean
Specifies the target video mode of the device the next time it reboots. Once a video mode is specified using
SetMode(), it can only be changed by a device reboot.
GetModeForNextBoot() As String
Returns the target video mode of the device the next time it reboots. The return value is specified with the
GetBestMode(connector As String) As String
Returns the highest supported video mode, as reported by the display via EDID. The video connector can be specified as
"vga" (these values are case sensitive). If the display does not return a resolution value over EDID (or if no display is connected), this method returns a blank string.
GetMode() As String
Returns the current video mode of the device, which is specified using the
GetAvailableModes() As Array
Returns all video modes supported by the player as an array of of entries. Each entry is an associative array with the following values:
videomode:(string) A description of the video mode (a full list of modes can be found here)
width:(integer) The width of the video output
height:(integer) The height of the video output
graphicsPlaneWidth:(integer) The width of the graphics plane
graphicsPlaneHeight:(integer) The height of the graphics plane
In 4K modes, the graphics plane may be smaller than the video plane and output. In these cases, the graphics plane is upscaled to match the video plane/output.
framerate:(integer) The frame rate of the video output
interlaced:(Boolean) A flag indicating whether the video output is interlaced (
true) or progressive (
overscan:(Boolean) A flag indicating whether the video output is using an overscan setting or not
colorspace:(string) The color space of the video signal ("8bit", "10bit", or "12bit")
colordepth:(string) The color depth of the video signal ("rgb", "yuv420", or "yuv422")
dropframe:(Boolean) A flag indicating whether the video timecode utilizes drop frames
preferred:(Boolean) A flag indicating whether the video mode is the preferred mode, which is configured using the
GetActiveMode() As AssociativeArray
Returns information about the current video mode as an associative array. All values in the roAssociativeArray are strings:
videomode: The current video mode (e.g. "3840x2160x60p")
colordepth: The current color depth ("8bit", "10bit", or "12bit")
colorspace: The current color space ("rgb", "yuv420", or "yuv422")
preferred: A "true" or "false" string indicating whether the current video mode is the preferred mode, which is set using the
GetConfiguredMode() As AssociativeArray
Returns information about the video mode configured using the
SetMode() method. This method returns an roAssociativeArray; see the
entry for more details about returned values. If the video mode is set to "auto", this method will return Invalid.
GetFPS() As Integer
Returns the current framerate of the video output.
SetDecoderMode(decoder As String, timeslice_mode As String, z_order As Integer, friendly_name As String, enable_mosaic_deinterlacer As Boolean) As Boolean
Configures a video decoder for either standard mode or Mosaic mode. In standard mode, a single decoder is used to play a single video; in Mosaic mode, the decoder can be used to decode multiple videos from different local or remote sources. See the Selecting Decoders section below for more information on assigning video players to decoders in HTML or BrightScript.
decoder: The video decoder to be used (decoder availability differs by model).
- "4K": The 4K decoder (on XTx43, 4Kx42, and XDx33 models only)
- "HD1": The first HD decoder
- "HD2": The second HD decoder
timeslice_mode: The maximum resolution that the decoder will accept (at framerates up to 60p). If this resolution is the same as the decoder's maximum resolution limit, the decoder will use standard mode, not Mosaic mode.
- "4K": 4096x2160
- "HD": 1920x1080
- "SD": 720x576
- "CIF": 352x288
- "QCIF": 176x144
Upscaling videos in Mosaic mode currently causes severe performance degradation.
z_order: The z-order of the video window (in standard mode) or group of video windows (in Mosaic mode) relative to the graphics plane:
- 1: The video window (or group of windows) is positioned in front of the graphics plane.
-1: The video window (or group of windows) is positioned behind the graphics plane.
This configuration can be modified using the
friendly_name: A human-readable name for referencing the decoder in HTML and scripts
enable_mosaic_deinterlacer: A Boolean value indicating whether Mosaic-mode videos can be interlaced or not. Enabling the deinterlacer will allow playback of interlaced videos in Mosaic mode, but will reduce the number of Mosaic-mode videos that can be decoded simultaneously as well.
GetDecoderModes() As roArray
Returns an array of associative arrays, each one corresponding to a single decoder. Each associative array contains the following entries:
decoder_name: The system name of the decoder
friendly_name: The name of the decoder as specified when calling
max_decode_size: The maximum resolution of the decoder, as set by system software. This value can be either "4K" or "HD"
configured_decode_size: The maximum resolution of the decoder that is specified when calling
mode: The current mode of the decoder, which can be either "Regular" or "Mosaic"
usage_count: The number of videos currently being decoded by the decoder
max_usage: The maximum number of videos that can be decoded simultaneously by the decoder. The optimum
max_usagelimits are described below; the limit may be lower depending on a number of factors, including interlacing and frame rate.
- 4K decoder:
- 1 4K video
- 2 HD videos
- 4 SD videos
- 8 CIF videos
- 10 QCIF videos
- HD decoder:
- 0 4K videos
- 1 HD video
- 3 SD videos
- 4 CIF videos
- 5 QCIF videos
- 4K decoder:
mosaic_mode_interlace: The current deinterlacing mode of the decoder, which can be either "Enabled" or "Disabled". This value is specified when calling
Set3dMode(mode As Integer) As Boolean
Sets the 3D video output mode, which is specified by passing one the following parameters:
- 0: Standard mono video (default)
- 1: Side-by-side stereo video
- 2: Top-and-bottom stereo video
Screenshot(parameters As roAssociativeArray) As Boolean
Captures a screenshot of the video and graphics layer as a .jpeg or .bmp file. The screenshot is configured by passing an associative array of parameters to the method:
filename: A string specifying the name and path of the image file that will be saved (e.g. "SD:/myscreenshots/screen.jpg"). If the specified directory does not exist, the screenshot will fail.
width: An integer specifying the width of the image file.
height: An integer specifying the height of the image file.
The default dimensions of the image file is 640x480.
filetype: A string determining whether the image is a "JPEG" or "BMP" file type. Note that the file extension (".jpg" or ".bmp") is not appended to the filename by default and, if needed, should be included in the
quality: An integer value (between 0 and 100) that determines the image quality of the screenshot. This parameter is set to 50 by default.
async: An integer value that determines whether the screenshot should be taken synchronously or asynchronously. If set to 0, the function returns True after the image file has successfully finished writing. If set to 1, the function will return True prior to saving the file, then return an roScreenShotComplete event once the file has finished writing.
rotation: The rotation of the screenshot image (in degrees). The default value is 0. Accepted values are 0, 90, 180, and 270.
GetResX() As Integer
Returns the current width of the graphics plane.
GetResY() As Integer
Returns the current height of the graphics plane.
GetVideoResX() As Integer
Returns the current width of the video plane.
GetVideoResY() As Integer
Returns the current height of the video plane.
GetOutputResX() As Integer
Returns the width of the display for the current video mode.
GetOutputResY() As Integer
Returns the height of the display for the current video mode.
In most cases, the values returned by
GetOutputResY() will be identical. The "GetRes" and "GetVideoRes" values will sometimes differ when using 4K modes if the graphics plane (i.e. "GetRes") remains at 1920x1080, while the video plane (i.e. "VideoRes") expands (e.g. to 3840x2160). The "OutputRes" value will differ from the other two values when the video output is upscaled: For example, when upscaling from HD to 4K, the "GetRes" and "GetVideoRes" values will remain at 1920x1080, while the "OutputRes" values will indicate 3840x2160.
GetSafeX() As Integer
Returns the horizontal coordinate for the upper-left corner of the "safe area". For modes that are generally displayed with no overscan, this will be zero.
GetSafeY() As Integer
Returns the vertical coordinate for the upper-left corner of the "safe area". For modes that are generally displayed with no overscan, this will be zero.
GetSafeWidth() As Integer
Returns the width of the "safe area." For modes that are generally displayed with no overscan, this will return the same as GetResX.
GetSafeHeight() As Integer
Returns the height of the "safe area." For modes that are generally displayed with no overscan, this will return the same as GetResY.
SetGraphicsZOrder(order As String) As Boolean
Specifies the order of the graphics plane (which includes all graphical elements) in relation to the video plane(s). This method accepts three parameters:
"front": Places the graphics plane in front of the video plane(s).
"middle": Places the graphics plane between two video planes. This option is only applicable for models that have two video decoders (e.g. XTx43, XDx33, 4Kx42).
"back": Places the graphics plane behind the video plane(s).
If the player is rendering two videos, the
back options will always place the graphics plane in front of or behind both video planes. To determine the z-order of video planes in relation to one another, use the
ToBack() methods provided by the roVideoPlayer object. The following table shows all possible video and graphics z-order arraignments that can be specified using the
SetGraphicsZOrder() method and calling the
ToBack() methods on a "Video1" roVideoPlayer instance.
PauseGraphics(timeout_in_ms As Integer) As Boolean
Suspends graphics compositor updates for the specified number of milliseconds (or until the
ResumeGraphics() method is called), up to a maximum interval of 10 seconds. While the graphics compositor is paused, no visual elements will be updated (except for HWZ video, scrolling tickers, and off-screen Chromium textures). Use this method to combine
SetRectangle() operations into a single v-sync update.
ResumeGraphics() As Boolean
Resumes the graphics compositor if it has been paused with the
SetImageSizeThreshold(parameters As roAssociativeArray) As Boolean
Changes the maximum allowed resolution for images. The default image resolution limit is 2048x1280x32bpp (or 4096x2160x32bpp for XTx43, XDx33, 4Kx42 players). Displaying images larger than the default value may deplete the graphics memory and cause a crash, so we recommend testing a script that uses this method thoroughly before deploying it in a production environment. This method accepts an associative array with the following parameters:
width: Overrides the maximum allowed width with the specified value.
height: Overrides the maximum allowed height with the specified value.
ignore: Disables resolution limits completely if the value is 1.
Without altering the default maximum resolution, you can increase the maximum width of images by sacrificing height (e.g. using a 4096x640x32bpp image on non-4K-capable players is allowed). You can also increase the maximum width/height by reducing the bpp value (e.g. using a 4096x1280x16bpp on non-4K-capable players is allowed).
AdjustGraphicsColor(parameters As roAssociativeArray) As Boolean
Adjusts the video and graphics output of the player using the following parameters, which can be passed to the method as an associative array: "brightness", "hue", "contrast", "saturation". Each parameter has a default value of 0 and can accept a range of values between -1000 and 1000.
ConfigureHdmiInput(parameters As roAssociativeArray) As Boolean
Configures EDID reporting for the HDMI input. By default, the input EDID includes video modes from the display attached to the HDMI output, some video modes supported by the player, and support for PCM audio up to 48kHz; it does not report proprietary media codecs that can be decoded by the device connected to the HDMI output, so you can use this method to announce such support if available at the endpoint. Using this method to change the default configuration will trigger a reboot on the player. The passed associative array can contain the following parameters:
[int] MaxSampleRate: The maximum supported PCM audio sampling rate in Hz (e.g. the default sampling rate is 48000)
[int] MaxChannelCount: The number of PCM channels that are advertised over EDID. The default value is 2, which allows for stereo mixdown. Increasing this value to 6 allows the source to send multichannel PCM.
If AC-3 or E-AC-3 is enabled on the player, multichannel audio is supported regardless of the
[int] EnableAC3: A flag specifying whether AC-3 is not supported (0) or supported (1)
[int] EnableEAC3: A flag specifying whether E-AC-3 is not supported (0) or supported (1)
[int] EnableTrueHDMlp: A flag specifying whether TrueHD MLP is not supported (0) or supported (1)
[int] EnableDTS: A flag specifying whether DTS is not supported (0) or supported (1)
[int] EnableDTSHD: A flag specifying whether DTS-HD is not supported (0) or supported (1)
[int] LockAudioToVideoClock: A flag specifying whether the audio sample rate clock is locked to the audio clock (0) or video clock (1) of the incoming HDMI signal.
GetHdmiOutputStatus() As roAssociativeArray
Returns an associative array of Boolean and integer values if an HDMI output is currently connected to a display device. This method will return Invalid if the HDMI output is currently not connected to a display device. The associative array contains the following parameters:
output_present: Returns True if the HDMI output is connected to a display device or False if no device is present.
output_powered: Returns True if the display device is on (i.e. RX powered) or False if it is off.
EOTF: Returns a string indicating the current electro-optical transfer function (EOTF) used by the display. The following are possible values:
- "HDR (GAMMA)"
- "SDR (GAMMA)"
- "SMPTE 2084 (PQ)"
- "Future (BBC/NHK)"
audio_bits_per_sample: The number of bits per audio sample
audio_format: The format of the audio output. A "PCM" value indicates that the player is sending decoded output.
audio_channel_count: The number of audio channels in the output
audio_sample_rate: The audio sample rate (in hertz)
If an HDR video is playing, the following values will be retrieved from the video file: "max_cll", "max_fall", "red_primary_x", "red_primary_y", "green_primary_x", "green_primary_y", "blue_primary_x", "blue_primary_y", "white_point_x", "white_point_y", "min_mastering_luminance", "max_mastering_luminance".
GetHdmiInputStatus() As roAssociativeArray
Returns an associative array of Boolean and integer values if an HDMI input is currently connected to the device (XT1143, 4K1142, XD1132, XD1230 only). This method will return Invalid if there is currently no HDMI input source. The associative array contains the following parameters:
[Boolean] device_present: A flag indicating whether an HDMI input source is present
[int] width: The width of the source video
[int] height: The height of the source video
[Boolean] interlaced: A flag indicating whether the video source is interlaced
[float] frame_rate: The framerate of the source video
[float] pixelClock: The pixel-clock rate of the source video (in MHz)
[string] colorspace: The color space of the source video
[string] audio_type: The audio encoding of the source video
[int] audio_sampling_rate: The audio sampling rate of the source video (in Hz)
GetCompositorCRC() As Integer
Returns the CRC of the Y and Cb signals as a single integer.
GetTxHDCPStatus() As roAssociativeArray
Returns an associative array indicating the current HDCP status of the HDMI output. The associative array currently contains a single key labeled
state, which can have the following values:
- "not-required": HDCP has not been requested.
- "authenticated": HDCP has been enabled and successfully negotiated.
- "authentication-in-progress": HDCP has been enabled, but authentication has not been completed.
- "authentication-failed": HDCP has been requested but could not be negotiated.
ForceHDCPOn(force As Boolean) As Boolean
Forces HDCP authentication on the HDMI output if passed True. Passing False to this method will prevent forced authentication attempts with subsequent hotplug events. This method will return False if the player does not support HDCP or if
ForceHDCPOn() has already been called with the same value.
DisableHDCPRepeater(disable As Boolean) As Boolean
Prevents HDCP authentication from taking place on the HDMI input if passed True. The HDMI source will treat the player like any other non-HDCP authenticated HDMI sink. This method returns False if the HDCP state could not be changed, indicating that there's no HDMI input on the player or that HDCP has already been disabled.
SetBackgroundColor(color As Integer) As Boolean
Specifies the background color using an
#rrggbb hex value (8 bits for each color).
SetPowerSaveMode(power_save_enable As Boolean) As Boolean
Disables HDMI output, the syncs for VGA output, and the DAC output for component video. The absence of a signal will cause some monitors to go into standby mode.
IsAttached(connector As String) As Boolean
Returns True if the specified video connector is attached to an output device (i.e. the display EDID can be read successfully). This method can be passed the following parameters (note that they are case sensitive):
HdmiAudioDisable(disable As Boolean) As Boolean
Disables audio output if True. This method is set to False by default.
SetMultiscreenBezel(x_pct As Integer, y_pct As Integer) As Boolean
Adjusts the size of the bezel used in calculations for multiscreen displays, allowing for users to compensate for the width of their screen bezels. The calculations for the percentages are as follows:
x_percentage = (width_of_bezel_between_active_screens / width_of_active_screen) * 100
y_percentage = (height_of_bezel_between_active_screens / height_of_active_screen) * 100
The bezel measurement is therefore the total of the top and bottom bezels in the y case, or the left and right bezels in the x case. When this value is set correctly, images spread across multiple screens take account of the bezel widths, leading to better alignment of images.
SaveEdids(filename As String) As Boolean
Saves the EDID information of the display(s) connected via HDMI and/or VGA. The EDID fields are saved sequentially as raw binaries into the specified file. The EDID sets are two 2kb each, resulting in a maximum file size of 4kb. This method returns True upon success and False upon failure.
GetEdidIdentity(video_connector As Boolean) As roAssociativeArray
Returns an associative array with EDID information from a compatible monitor/television. Passing True with this method specifies EDID over HDMI, while passing False specifies EDID over VGA. These are the possible parameters returned in the associative array:
The system will generate an roHdmiEdidChanged event when an HDMI cable is hotplugged and the EDID information changes. Calling
GetEdidIdentity(true) at this point retrieves the new EDID information.
SetMpcdi(enable As Boolean) As Boolean
Enables MPCDI if passed True. This will only happen if all of the resources needed for MPCDI have been allocated and set correctly—otherwise, this method will return False and not enable MPCDI. You can pass False to this method to disable MPCDI after it has been enabled.
See the MPCDI tech note for more information about configuring MPCDI on BrightSign players.
SetMpcdiRegionResRectangle(window As roRectangle) As Boolean
Sets the region viewport. Use the
<YResolution> attributes in the
<region> tag to configure the dimensions of the roRectangle.
SetMpcdiRegionRectangle(x As Float, y As Float, xsize As Float, ysize As Float) As Boolean
Sets the region coordinates. Pass the values contained in the
<ysize> attributes in the
SetMpcdiAlphaMapRectangle(r As roRectangle) As Boolean
Sets the width and height of the Alpha blend map. The x and y coordinates are set to 0.
SetMpcdiAlphaMap(data As roByteArray) As Boolean
Sets the alpha blend map. Pass the decoded .png data in the form of an roByteArray.
SetMpcdiAlphaMapGamma(gamma As Float) As Boolean
Sets the gamma value of the alpha map. Pass the value contained in the
<gammaEmbedded> attribute in the
SetMpcdiWarpMapRectangle(r As roRectangle) As Boolean
Sets the width and height of the warp grid. The x and y coordinates are set to 0.
SetMpcdiWarpMap(data As roArray) As Boolean
Sets the warp geometry grid data extracted from the .pfm file.
SetMpcdiBetaMapRectangle(r As roRectangle) As Boolean
Sets the Beta blend map width and height. The x and y coordinates are set to 0.
SetMpcdiBetaMap(data As roByteArray) As Boolean
Sets the beta blend map. Pass the decoded .png data in the form of an roByteArray.
SetPort(port As Object) As Void
Posts events to the attached message port
SetUserData(user_data As Object)
Sets the user data that will be returned when events are raised.
GetUserData() As Object
Returns the user data that has previously been set via
SetUserData(). It will return Invalid if no data has been set.
"Auto" Video Mode
If the mode is set to "auto," the BrightSign player will use the following algorithm to determine the best video mode to use based on connected hardware:
- Try VGA: If VGA is attached, use the highest-resolution mode (as reported by the monitor) that the player supports.
- Try HDMI: If HDMI is attached, use the highest-resolution mode (as reported by the monitor) that the player supports.
- Default to 640x480x60p.
- If an HDMI hotplug event occurs at any point, recheck the monitor EDID to determine if the highest-resolution mode has changed. If it has changed, reboot the player and use the new video mode.
Selecting Decoders for Playback
The system software selects which video decoder to use based on the resolution probed from the video file. In standard mode, it will attempt to select the decoder that has the closest maximum supported resolution (i.e. 1920x1080 for the HD decoder and 3840x2160 for the 4K decoder), without exceeding that maximum resolution. If a decoder has been configured for Mosaic mode, it will match the video resolution against the specified
timeslice_mode instead. If both decoders support the same maximum resolution, you can select a decoder by matching the z-order of the roVideoPlayer instance (set using the
ToBack() methods) with the z-order of the decoder (set using the roVideoMode.SetDecoderMode() method).
You can also select the decoder manually. First, configure the decoder(s) using the roVideoMode.SetDecoderMode() method. Then, use the
friendly_name specified when calling the method to designate a decoder to use for video playback.
To select a decoder in BrightScript, pass an associative array to the roVideoPlayer.PlayFile() method containing the
To select a decoder for HTML video, include the
decoder:[friendly_name] property with the
max_usage of a decoder determines how many video players can be assigned to the decoder using the system software algorithm described above—video players beyond the
max_usage limit may be assigned to another decoder or not displayed at all. On the other hand, if you manually assign video players using the
friendly_name of the decoder, you can assign more video players to the decoder than the
max_usage limit, but this may cause unpredictable video-display behavior.