---
title: roVideoPlayer
slug: develop/rovideoplayer
docTags: 
createdAt: 2025-03-11T07:07:18.733Z
---

This object is used to play back video files (using the generic *ifMediaTransport* interface). If the message port is set, the object will send events of the type *roVideoEvent*. All object calls are asynchronous. That is, video playback is handled in a different thread from the script, and the script will continue to run while video is playing. Decoded video will be scaled to the output resolution specified by *roVideoMode*. The JavaScript equivalent is to use \<video> elements with [BrightSign properties](docId\:e6uJleH69Q0JmMv8kyTrp).

To display video in a zone/window, you must call `SetRectangle()`. In firmware versions 6.0.x and later, zone support is enabled by default.

## ifVideoControl

**PlayStaticImage(filename As String) As Boolean**

Uses the video decoder to display an image. On 4Kx42, XT3, XD3, HD4, XD4, XT4, XC5, XT5, XD5, HD5, and LS445 models, you can use the video decoder to display 4K images.

**PlayStaticImage(parameters As roAssociativeArray) As Boolean**

Uses the video decoder to display an image. The passed associative array can contain the following parameters:

- `Filename`: The name of the image file
- `EncryptionAlgorithm`: The file-encryption algorithm. Currently the options are "AesCtr" and "AesCtrHmac".
- `EncryptionKey`: The key to decrypt the image file. This is a byte array consisting of 128 bits of key, followed by 128 bits of IV.

See [this page](docId:0UMXqYvruY7DRNLuUZAFp) for details on displaying encrypted images.

:::hint{type="warning"}
The video player no longer accepts "\{A|A}" AES encryption keys (i.e. where the top and bottom 64 bits of the key are identical).
:::

**SetViewMode(mode As String) As Boolean**

Sets the scaling of the video in relation to the video window. The passed string can be one of the following values:

- `"ScaleToFit"`: Scales the video to fill the window. The aspect ratio of the source video is ignored, so the video may appear stretched/squashed.
- `"LetterboxedAndCentered"`: Letterboxes and centers the window. The aspect ratio of the source window is maintained.
- `"FillScreenAndCentered"`: Scales the video to fill the window. The aspect ratio is maintained, so the video may appear cropped. This is the default behavior.
- `"Centered"`: Centers the window.

:::hint{type="info"}
View modes rely on correct aspect-ratio marking from video files, and some files may be marked incorrectly.
:::

**SetRectangle(r As roRectangle) As Void**

Specifies the placement and dimensions of the video window using a passed *roRectangle&#x20;*&#x69;nstance.

**Hide() As Boolean**

Hides the video window.

**Show() As Boolean**

Shows the video window.

**EnableSafeRegionTrimming(enable As Boolean) As Boolean**

**AdjustVideoColor(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.

**SetKeyingValue(keying\_settings As roAssociativeArray) As Boolean&#xA0;**

Applies a mask to each pixel in the video window. If the pixel value falls within the specified range of chroma and luma key values, the pixel will appear transparent, allowing video and graphics behind it to show through. If the pixel value does not fall within the specified range, the pixel is unaltered. The chroma and luma key values are set using integers contained in the passed associative array:

- `luma`
- `cr`
- `cb`

Each integer value is arranged as follows:` [8 bits of mask][8 bits of high-end range][8 bits of low-end range]`. For example, an 0xff8040 value for luma would mask luma at 0xff (no change) and then apply a range from 0x40 to 0x80 for changing to transparent alpha. Note that chroma and luma keying work well with simple shapes and patterns, while complex patterns like hair or grass will not be masked effectively.

**SetTransform(transform As String) As Boolean**

Applies one of eight transforms to the video plane. This method works equally well with all video sources (files, streams, HDMI® input) and can be called separately on multiple *roVideoPlayer&#x20;*&#x69;nstances. Calls to this method only take effect when the next file/source is played, and transitions to a transformed video do not take place seamlessly.

- `"identity"`: No transformation (default behavior)
- `"rot90"`: 90 degree anticlockwise rotation
- `"rot180"`: 180 degree anticlockwise rotation
- `"rot270"`: 270 degree anticlockwise rotation
- `"mirror"`: Horizontal mirror transformation
- `"mirror_rot90"`: Mirrored 90 degree clockwise rotation
- `"mirror_rot180"`: Mirrored 180 degree clockwise rotation
- `"mirror_rot270"`: Mirrored 270 degree clockwise rotation

:::hint{type="info"}
The coordinates and dimensions of the *roRectangle&#x20;*&#x69;nstance containing the video are not affected by rotation.
:::

**GetFilePlayability(filename As String) As roAssociativeArray**

Returns an associative array indicating the playability of the video file. For the following keys, a `"playable"` value indicates that the component is playable, while a `"no media"` value indicates that there is no media—any other value indicates that the media is unplayable.

- `audio`: The audio file associated with the video
- `video`: The video file associated with the video
- `file`: The video container file

**GetProbePlayability(probe\_string As String) As roAssociativeArray**

Returns an associative array indicating the playability of the probe string. For the following keys, a `"playable"` value indicates that the component is playable, while a `"no media"` value indicates that there is no media—any other value indicates that the media is unplayable.

- `audio`: The audio file associated with the video
- `video`: The video file associated with the video
- `file`: The video container file

**GetStreamInfo() As roAssociativeArray**

Returns an associative array containing information about the current video. To retrieve metadata about a video file that is not currently playing, use the `ProbeFile()`method instead. The associative array can contain the following parameters:

- `Source` <font color="#704ae0">string</font>: The URI of the video file
- `SrcAddress` <font color="#704ae0">string</font>: The source IP address of the video stream
- `DstAddress` <font color="#704ae0">string</font>: The multicast address on which the IP stream is being transmitted. This value may be absent if the RTSP service has not redirected the stream (in this case, the IP address of the player may be displayed instead).
- `Encapsulation` <font color="#704ae0">string</font>: The encapsulation of the video. This value can be "ES" (elementary stream), "TS" (transport stream), or "UNKNOWN" for streaming video.
- `AudioFormat` <font color="#704ae0">string</font>: The format of the audio file
- `AudioSampleRate` <font color="#704ae0">int</font>: The audio sample rate (in hertz)
- `AudioChannelCount` <font color="#704ae0">int</font>: The number of audio channels
- `AudioDuration` <font color="#704ae0">int</font>: The duration of the audio track (in milliseconds)
- `VideoFormat` <font color="#704ae0">string</font>: The format of the video file
- `VideoFramerate` <font color="#704ae0">int</font>: The video frame rate (in frames per second)
- `VideoColorDepth` <font color="#704ae0">int</font>: The color depth of the video (in bits)
- `VideoWidth` <font color="#704ae0">int</font>: The width of the video (in pixels)
- `VideoHeight` <font color="#704ae0">int</font>: The height of the video (in pixels)
- `VideoAspectRatio` <font color="#704ae0">float</font>: The aspect ratio of the video
- `VideoDuration` <font color="#704ae0">int</font>: The duration of the video (in milliseconds)
- `PreferredVideo` <font color="#704ae0">int</font>: The current preferred video track, as determined by the SetPreferredVideo() method
- `PreferredAudio` <font color="#704ae0">int</font>: The current preferred audio track, as determined by the SetPreferredAudio() method
- `PreferredSubtitle` <font color="#704ae0">int</font>: The current preferred subtitle track, as determend by the SetPreferredCaptions() method
- `Programs` <font color="#704ae0">roArray</font>: A list of programs that are part of the video. Each entry contains the program ID, along with indicies of video, audio, and subtitle tracks that are part of the program. These track lists can be used–along with the `Video`, `Audio`, and `Subtitle` parameters and the `SetPreferred<>()` methods to scan and select tracks. Each entry can contain the following parameters:
  - `ProgramId` <font color="#704ae0">int</font>: The program ID
  - `Video`  <font color="#704ae0">roArray</font>: An index of integers corresponding to video tracks that are part of the program
  - `Audio`  <font color="#704ae0">roArray</font>: An index of integers corresponding to audio tracks that are part of the program
  - `Subtitle`  <font color="#704ae0">roArray</font>: An index of integers corresponding to subtitle tracks that are part of the program. To retrieve more information about an individual video/audio/subtitle track, use the integer value to look up the associated `Video`/`Audio`/`Subtitle` index (e.g. `print streaminfo.subtitle[streaminfo.programs[0].subtitle[1]]`)
- `Video` <font color="#704ae0">roArray</font>: A list of video tracks that are part of the video. Each entry in the list is an associative array with the following parameters:
  - `AspectRatio` <font color="#704ae0">float</font>: The aspect ratio of the video track
  - `Name` <font color="#704ae0">string</font>: The name of the video track
  - `Width` <font color="#704ae0">int</font>: The video width (in pixels)
  - `Height` <font color="#704ae0">int</font>: The video height (in pixels)
  - `ColorDepth` <font color="#704ae0">int</font>: The aspect ratio of the video track
  - `Duration` <font color="#704ae0">int</font>: The duration of the video track (in milliseconds)
  - `Program` <font color="#704ae0">int</font>: The ID of the program to which the video track belongs
  - `FrameRate` <font color="#704ae0">float</font>: The framerate of the video track
  - `Pid` <font color="#704ae0">int</font>: The packet identifier (PID) of the video track
  - `Format` <font color="#704ae0">string</font>: The format of the video track
- `Audio` <font color="#704ae0">roArray</font>: A list of audio tracks that are part of the video. Each entry in the list is an assocative array with the following parameters:
  - `Name` <font color="#704ae0">string</font>: The name of the audio track
  - `ChannelCount` <font color="#704ae0">int</font>: The number of audio channels
  - `Format` <font color="#704ae0">string</font>: The format of the audio track
  - `Pid` <font color="#704ae0">int</font>: The packet identifier (PID) of the audio track
  - `Program` <font color="#704ae0">int</font>: The ID of the program to which the audio track belongs
  - `Duration` <font color="#704ae0">int</font>: The duration of the audio track (in milliseconds)
  - `SampleRate` <font color="#704ae0">int</font>: The audio sample rate (in hertz)
  - `Language` <font color="#704ae0">string</font>:  A code specifying the language of the audio track (e.g. "eng", "spa"). The language codes are specified in the ISO 639-2 standard.
- `Subtitle` <font color="#704ae0">roArray</font>:  A list of subtitle tracks that are part of the video. Each entry in the list is an assocative array with the following parameters:
  - `Language` <font color="#704ae0">string</font>: A code specifying the language of the subtitle track (e.g. "eng", "spa"). The language codes are specified in the ISO 639-2 standard.
  - `Program` <font color="#704ae0">int</font>: The ID of the program to which the subtitle track belongs
  - `Pid` <font color="#704ae0">int</font>: The packet identifier (PID) of the subtitle track
  - `Type` <font color="#704ae0">string</font>: The encoding standard of the subtitles (e.g. "CEA708", "DVB")

**GetStreamStatistics() As roAssociativeArray**

Returns an associative array containing statistics associated with the IP stream. The associative array contains the following parameters:

:::hint{type="info"}
All counters are reset every time PlayFile() is called. The audio keys will not be included in the associative array if there is no audio in the stream.
:::

- `Bitrate` <font color="#704ae0">int</font>: The video bitrate
- `NumDisplayed` <font color="#704ae0">int</font>: The number of video frames displayed. This is based on the refresh rate of the monitor.
- `NumUnderflowed` <font color="#704ae0">int</font>: The number of times the video FIFO has under-flowed. This usually indicates that the [buffer size](docId:0Tioy9PJdGG4G25yGBnib) needs to be increased.
- `NumDecodeErrors` <font color="#704ae0">int</font>: The number of video frames with decode errors
- `NumDecoded` <font color="#704ae0">int</font>: The total number of video frames decoded
- `NumAudioDecoded` <font color="#704ae0">int</font>: The total number of audio frames decoded
- `NumAudioDecodeErrors` <font color="#704ae0">int</font>: The number of audio frames with decode errors
- `NumAudioDummy` <font color="#704ae0">int</font>: The total number of missing audio frames. This value will increment when an audio frame goes missing or a timestamp is incorrect. A couple of frames will often be registered when streaming begins.
- `NumAudioUnderflows` <font color="#704ae0">int</font>: The number of times the audio FIFO has under-flowed. This usually indicates that the [buffer size](docId:0Tioy9PJdGG4G25yGBnib) needs to be increased.
- `VideoFramesPerSecond` <font color="#704ae0">int</font>: The video frame rate (in frames per second)
- `VideoInterlaced` <font color="#704ae0">int</font>: Indicates whether the video frames are interlaced or progressive
- `HardwareDecode` <font color="#704ae0">bool</font>:  Indicates whether or not the player is using hardware acceleration. This is always true for Series 4 players, but Series 5 players may report false if the player can’t use hardware acceleration for the media. Software decode is not recommended and is only used when the player can’t use hardware acceleration for a media file.

:::hint{type="info"}
Note that GetStreamStatistics() only returns valid data after the PLAYING event has been sent to a script.
:::

**GetCrc() As Integer**

Returns the CRC of the Y and Cb signals as a single integer. This method allows the script to compare two moments in the video-window output: If the return values differ, then the output is not identical.

**SetPreferredVideo(description As String) As Boolean**

Chooses a video stream from the video input based on the parameters in the passed string.

**SetPreferredAudio(description As String) As Boolean**

Chooses an audio stream from the video input based on the parameters in the passed string.

**SetPreferredCaptions(description As String) As Boolean**

Chooses a data stream from the video input based on the parameters in the passed string.

**SetOpacity(opacity As Integer) As Boolean**

The range of opacities from 0 to 255 (fully transparent to fully opaque).

## ifMediaTransport

**PlayFile(source As Object) As Boolean**

Plays a video file or HDMI Input. To play a file, pass a string specifying the file name and path. To play HDMI Input, pass an *roVideoInput&#x20;*&#x69;nstance.

**PlayFile(parameters As roAssociativeArray) As Boolean**

Plays video using the parameters passed as an associative array. All settings specified with this method are transient: They will only last for the duration of the file/stream playback. To specify persistent settings, use the `SetProperties()` method or the equivalent "Set" methods (`SetTransform()`, `SetViewMode()`, etc.).

- `AudioDelay`: A user-controllable delay for audio in milliseconds.
- `Decoder`: The decoder\_hint used by mosaic mode to suggest which [decoder](docId\:QQ734nQz0hCwNI0uNSdMP)  to use.
- `EncryptionAlgorithm`: The encryption algorithm to use for [encrypted playback](docId\:zTUZ0LdazCmL2kQmdBKCn) &#x20;
- `EncryptionKey`: The encryption key to use for [encrypted playback](docId\:zTUZ0LdazCmL2kQmdBKCn) &#x20;
- `FadeInLength`: The length (in milliseconds) of fade-in at the beginning of the media
- `FadeOutLength`: The length (in milliseconds) of fade-out at the end of the media
- `Filename`: The name/path of a file to be used for playback
- `LoopMode`: The looping mode for media playback. See the `SetLoopMode()` entry for a list of applicable values.
- `NoForceCapture`: A boolean value. If true, video capture to DRAM is bypassed when frame-rate conversion is not required. This reduces decode-to-display latency but introduces the following limitations:
  - Transform values other than "identity" will not work.
  - Screenshots may not be correct.
- `NoReordering`: Improves latency but disables playback of B-slices
- `Preload`: Start playback paused at the start.
- `ProbeString`: Used by BrightSign Author to supply a probe hint which may accelerate stream startup in some cases.
- `StreamFadeIn`: The length (in milliseconds) of audio/video fade-in for streams. This operates independently of [HWZ "fade"](docId\:e6uJleH69Q0JmMv8kyTrp).
- `Transform`: The rotation of the video. See the `SetTransform()` entry for a list of applicable values.
- `VideoDelay`: A user-controllable delay for video in milliseconds.
- `ViewMode`: The view mode of the video window. See the `SetViewMode()` entry for a list of applicable values.
- `ZIndex`: Control the z-index of the video layers.

These parameters are specifically used for streaming:

- `AudioFifoSize`: Set the audio FIFO size (ACDB).
- `StreamBufferSize`: Demux input buffer size (in bytes).
- `StreamJitter`: The jitter threshold for the stream in milliseconds. If the timing of incoming packets exceeds this value then the stream STC will be re-centered so as to remain in sync.
- `StreamLatency`: The amount of deviation (in milliseconds) from the default latency value: For example, a value of -500 will reduce the latency by half a second; a 500 value will increase the latency by half a second; and a 0 value will specify the default latency. Specifying a negative value will not change the buffer size; instead, it will give the buffer less time to fill up before playback begins. Usable values extend to approximately -750, though this value may differ depending on the network environment. Reducing the latency too much will result in obvious playback stutter.
- `StreamLowLatency`: Low-latency mode for RTSP streams. Setting this parameter to True will achieve the lowest possible latency for a stream, but at a reduced maximum bitrate.
- `StreamMaxBitrate`: Sets the maximum allowed bitrate (in bytes) for adaptive (HLS) playback.
- `StreamPollInterval`: Gives fine control of how often streams are polled (checked for freezing)
- `StreamProbe`: The stream probe type. This parameter can be set to "deep" (to include video dimensions, audio sample rate, etc.) or "shallow".
- `StreamTimeout`: Stop searching for the stream after this amount of time (in milliseconds).
- `StreamTrace`: Turns on stream debugging
- `StreamUsePcrClock`: Use recovered PCR as timebase for unrecognized stream protocols. This should be selected when using an external GStreamer component where the PCRs arrive at the correct time similar to RTP or UDP.
- `Url`: The URL of the video stream to be used for playback
- `VideoFifoSize`: Set the video FIFO size (VCDB).

These parameters are for MJPEG only:

- `Greyscale`: Boolean. Sets MJPEG stream to greyscale.
- `Rotate`: 0, 90, 180, or 270 degrees. If possible, use `Transform` instead.

These parameters are used to set they keying value of the video (see the [SetKeyingValue()](docId\:zTUZ0LdazCmL2kQmdBKCn) entry for more details)

- `CbKey`
- `CrKey`
- `LumaKey`

These parameters are used to [play encrypted video](docId\:zTUZ0LdazCmL2kQmdBKCn):

- `EncryptionAlgorithm`
- `EncryptionKey`

These parameters are used to parse [preferred streams](docId\:zTUZ0LdazCmL2kQmdBKCn):

- `PreferredAudio`
- `PreferredCaptions`
- `PreferredVideo`

These parameters are used in conjunction with th&#x65;*&#xA0;*[roSyncManager](docId\:Wwc22ZsPhu1e689xe7en6)*&#xA0;*&#x6F;bject to synchronize playback:

- `SyncDomain`
- `SyncId`
- `SyncIsoTimestamp`

These parameters are used for [multiscreen](docId\:zTUZ0LdazCmL2kQmdBKCn) playback:

- `MultiscreenHeight`
- `MultiscreenWidth`
- `MultiscreenX`
- `MultiscreenY`
- `SourceHeight`
- `SourceWidth`
- `SourceX`
- `SourceY`

**DropErrorFrames() As Boolean**

Configure whether to show frames with errors or drop them (which can cause pauses). By default, these errors are shown on Series 4 and earlier players. On Series 5 and later players, errors are hidden by default. Error concealment (extrapolating between good frames) performance varies between platforms. This method is available as of BOS 9.1.137.

**SetProperties(parameters As roAssociativeArray) As Boolean&#xA0;**

Sets persistent properties for video playback. These properties can be temporarily overridden by the parameters in a `PlayFile()`  call. See the [PlayFile()](docId\:zTUZ0LdazCmL2kQmdBKCn) entry for a list of available parameters.

**GetProperties() As roAssociativeArray**

Returns the current video-playback properties as an associative array. See the [PlayFile()](docId\:zTUZ0LdazCmL2kQmdBKCn) entry for a description of parameters.

**SetPropertiesString(parameters As String) As Boolean**

Sets persistent properties for video playback using a comma-separated list. These properties can be temporarily overridden by the parameters in a `PlayFile()` call. See the [PlayFile()](docId\:zTUZ0LdazCmL2kQmdBKCn) entry for a list of available parameters.

**Example**

:::BlockQuote
vp = CreateObject("roVideoPlayer")
vp.SetPropertiesString("Transform=rot90,StreamLowLatency=true") 
:::

**GetPropertiesString() As String**

Returns the current video-playback properties as a string (e.g. `"<key>=<value>, <key>=<value>"`). See the [PlayFile()](docId\:zTUZ0LdazCmL2kQmdBKCn) entry for a description of parameters.

**SetPlaybackSpeed(speed as Float) As Boolean**

Modulates the playback speed of the video, using the float 1.0 as the value for standard playback speed. To fast-forward the video, pass a value greater than 1.0; to rewind the video, pass a negative value. A value between 0 and 1.0 will the play the video in slow motion.

**PreloadFile(parameters As roAssociativeArray) As Boolean**

See the [PlayFile()](docId\:zTUZ0LdazCmL2kQmdBKCn) entry for a description of parameters.

**Play() As Boolean**

Plays the currently loaded file or stream.

**Stop() As Boolean**

Stops playback of the currently loaded file or stream.

**StopClear() As Boolean**

Stops video playback and clears the currently loaded file or stream.

**Pause(parameters As roAssociativeArray) As Boolean**

Pauses the video file or stream. This method accepts an optional associative array containing the following parameter:

- `SyncIsoTimeStamp`: The time stamp for pausing synchronized video. This value is provided by the `roSyncManager.Synchronize()`*&#xA0;*&#x6D;ethod on the leader unit and the `roSyncManagerEvent.GetIsoTimeStamp()`*&#xA0;*&#x6D;ethod on follower unit(s).

**Resume(parameters As roAssociativeArray) As Boolean**

Resumes a paused video file or stream. This method accepts an optional associative array containing the following parameter:

- SyncIsoTimeStamp: The time stamp for resuming synchronized video. This value is provided by the `roSyncManager.Synchronize()`*&#xA0;*&#x6D;ethod on the leader unit and the `roSyncManagerEvent.GetIsoTimeStamp()`*&#xA0;*&#x6D;ethod on follower unit(s). 

**SetLoopMode(mode As Dynamic) As Boolean&#xA0;**

Specifies the looping mode for media playback. This method can also accept one of the following strings:

- `"NoLoop"`: Looping is disabled in all cases. This is the default behavior, allowing for playback of multiple files in a playlist—with noticeable gaps between the end and beginning of the file.
- `"AlwaysLoop"`: The video is looped seamlessly if possible; otherwise, it is looped with seams.
- `"SeamlessLoopOrNotAtAll"`: The video is looped seamlessly if possible; otherwise, it is not looped at all.
- `"LoopButNotSeamless"`: The video is looped with seams.

Alternatively, this method can accept a Boolean argument: 

- `true`: A single media file will loop seamlessly if possible. If the video file cannot be looped seamlessly, then the video will loop with seams. 
- `false`: Looping is disabled in all cases. This is the default behavior, allowing for playback of multiple files in a playlist—with noticeable gaps between the end and beginning of the file.

:::hint{type="info"}
Media End events are only sent if seamless looping is disabled, or if the mode is set to `"SeamlessLoopOrNotAtAll"` and the file cannot be looped seamlessly.
:::

**AddEvent(user\_data As Integer, time\_in\_ms As Integer) As Boolean**

Adds a trigger that will generate an `roVideoEvent` when it reaches the specified time. The user data will be passed with the event and can be retrieved using the `roVideoEvent.GetData()` method. See the [Video Timecode Events](docId\:zTUZ0LdazCmL2kQmdBKCn) section below for more details.

**ClearEvents() As Boolean**

Removes all timecode events that have been added using the `AddEvent()`method.

**GetEvents() As roArray**

Returns an array of timecode events added to the *roVideoPlayer&#x20;*&#x69;nstance using the `AddEvent()` method. Each entry in the array consists of an associative array with the following values:

- `id`: The `user_data` of the event (as an Integer)
- `timestamp`: The timestamp (in milliseconds)

**PlayEx(a As Object) As Boolean**

This object has been deprecated. We suggest using the `PlayFile()`method for video playback instead.

**GetPlaybackPosition() As Integer**

Returns the amount of time the current file or IP stream has been playing (in milliseconds). If `SetLoopMode()` is set to true, the value will not reset when playback loops. If looping playback or IP streaming continues uninterrupted for approximately 25 days, the value will wrap around and become negative.

**GetDuration() As Integer**

Returns the total playback duration (in milliseconds) of the current file.

**Seek(position As Integer) As Boolean**

Seeks to the specified position in the audio/video file(measured in milliseconds). If the file is currently playing, then it will continue to play; otherwise, it will remain paused after seeking. This method only supports the MP4/MOV video container; all standard audio formats are supported.

**SetFade(parameters As roAssociativeArray) As Boolean**

Fades out both the video and audio when the method is called. When the fade completes, an `roVideoEvent` object with the `18 – FadeOut` value will be posted to the message port. This method accepts an associative array, which can currently contain only one parameter:

- `FadeOutLength`: The length of time (in milliseconds) over which the audio/video fades out.

**ProbeFile(filename As String) As roAssociativeArray**

Returns an associative array containing metadata about the specified video file. To retrieve metadata about a file that is currently playing, use the `GetStreamInfo()` method instead. The returned associative array can contain the following parameters:

- `Source`: The URI of the file
- `Encapsulation`: The encapsulation of the video
- `AudioFormat`: The format of the audio file
- `AudioSampleRate`: The audio sample rate (in hertz)
- `AudioChannelCount`: The number of audio channels
- `AudioDuration`: The duration of the audio track (in milliseconds)
- `VideoFormat`: The format of the video file
- `VideoColorDepth`: The color depth of the video (in bits)
- `VideoWidth`: The width of the video (in pixels)
- `VideoHeight`: The height of the video (in pixels)
- `VideoAspectRatio`: The aspect ratio of the video
- `VideoDuration`: The duration of the video (in milliseconds)

## ifZorderControl

**ToFront() As Boolean**

Places the video layer of the *roVideoPlayer&#x20;*&#x69;nstance in front of the other video player.

**ToBack() As Boolean**

Places the video layer of the *roVideoPlayer &#x20;*&#x69;nstance behind the other video player.

:::hint{type="info"}
This feature is not available on HD/LS players, which only support a single video player. For more information on ordering video layers relative to the graphics layer, refer to the *roVideoMode.SetGraphicsZOrder()&#x20;*&#x65;ntry.
:::

## ifAudioControl

Se&#x65;*&#xA0;*[roAudioPlayer](docId\:KcsshYUYYNrAhPNNFnB-9) for documentation of *ifAudioControl*.

## ifAudioAuxControl

**MapStereoOutputAux(mapping As Integer) As Boolean**

**SetVolumeAux(a As Integer) As Boolean**

**SetChannelVolumesAux(channel\_mask As Integer, b As Integer) As Boolean&#xA0;**

**SetAudioOutputAux(audio\_output As Integer) As Boolean&#xA0;**

**SetAudioModeAux(audio\_mode As Integer) As Boolean**

**SetAudioStreamAux(stream\_index As Integer) As Boolean**

**SetUsbAudioPortAux(a As Integer) As Boolean**

## ifUserData

**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.

## ifIdentity

**GetIdentity() As Integer**

:::hint{type="info"}
The *ifIdentity&#x20;*&#x69;nterface has been deprecated. We recommend using the *ifUserData &#x20;*&#x69;nterface instead.
:::

## ifMessagePort

**SetPort(port As roMessagePort)**

Posts messages of type *roVideoEvent&#x20;*&#x74;o the attached message port.

## Timecode Events 

You can use the `AddEvent()` method to add triggers for *roVideoEvent* events, which will generate the `12 – Timecode Hit` value at the specified millisecond times in a video file. Use the *roVideoEvent.GetData()&#x20;*&#x6D;ethod to retrieve the user data passed with `AddEvent()`.

The following example script uses timecode events. The script prints 2, 5, and 10 at 2 seconds, 5 seconds, and 10 seconds into the video, respectively. The "msg" is approaching frame accurate.

:::CodeblockTabs
Example

```typescript
v = CreateObject("roVideoPlayer")
p = CreateObject("roMessagePort")
v.SetPort(p)
 
ok = v.AddEvent(2, 2000) ' Add timed events to video
ok = v.AddEvent(5, 5000)
ok = v.AddEvent(10, 10000)
ok = v.AddEvent(100, 100000)
ok = v.PlayFile("SD:/C5_d5_phil.vob")
 
waitloop:
msg = Wait(0,p) ' Wait for all events
if msg.GetInt() = 8 then stop ' End of file
if msg.GetInt() <> 12 goto waitloop      ' I only care about time events
print msg.GetData() ' Print out index when the time event happens
goto waitloop
```
:::

## Multiscreen Video Playback 

The `PreloadFile()` and `PlayFile()` methods can be used in conjunction with *roSyncManager&#x20;*&#x20; to stretch an image across multiple screens in an array or display windowed portions of a video.

The following example script uses the `PreloadFile()` method for multiscreen display:

:::CodeblockTabs
Example

```typescript
v=CreateObject("roVideoPlayer")
a=CreateObject("roAssociativeArray")
a["Filename"] = "test.ts"
a["MultiscreenWidth"] = 3
a["MultiscreenHeight"] = 2
a["MultiscreenX"] = 0
a["MultiscreenY"] = 0
v.PreloadFile(a)
...
...
v.Play()
```
:::

The `MultiscreenWidth` and `MultiscreenHeight` values specify the width and height of the multiple-screen matrix. For example, 3x2 would be 3 screens wide and 2 high. `MultiscreenX` and `MultiscreenY` specify the position of the current screen within that matrix. In the case above, on average only 1/6th of the video is drawn on each screen (though the view mode still applies), so depending on the shape of the video, it may have black bars on the side screens. In this way, it is relatively simple for a video player to display part of an image based on its position in the multiscreen array.

`PreloadFile()` does all of the preliminary work to get ready to play the specified video clip, including stopping the playback of the previous video file. The call to "Play" starts the playback. This is good for synchronizing video across multiple players as they can all be prepared ready to play and then will immediately start playing when the "Play" command is issued. This reduces synchronization latencies.

The following are the default values for the parameters:

- `MultiscreenWidth`= 1
- `MultiscreenHeight`= 1
- `MultiscreenX`= 0
- `MultiscreenY`= 0

This script uses `PlayFile()`to display a portion of a video. This displays a windowed portion of the *test.ts* video file starting at coordinates SourceX, SourceY, and SourceWidth by SourceHeight in size. The `SetViewMode()`setting is still honored as if displaying the whole file.

:::CodeblockTabs
Example

```typescript
v=CreateObject("roVideoPlayer")
a=CreateObject("roAssociativeArray")
a["Filename"] = "test.ts"
a["SourceX"] = 100
a["SourceY"] = 100
a["SourceWidth"] = 1000
a["SourceHeight"] = 500
v.PlayFile(a)
```
:::

### Multiscreen with Portrait Mode

To create a multiple-screen matrix in portrait mode, call `SetTransform("rot90")` or `SetTransform("rot270")` before calling `PlayFile()`.

This script creates a 2x1 portrait-mode multiscreen display:

:::CodeblockTabs
Example

```typescript
v1=CreateObject("roVideoPlayer")
v1.SetViewMode("LetterboxedAndCentered")
r=CreateObject("roRectangle", 0, 0, 1920, 1080)
v1.SetRectangle(r)
v1.SetTransform("rot90")

aa1=CreateObject("roAssociativeArray")
aa1.MultiscreenWidth = 2
aa1.MultiscreenHeight = 1
aa1.MultiscreenX = 1
aa1.MultiscreenY = 0
aa1.Filename = "example.mp4"
v1.PlayFile(aa1)
```
:::

## RF Channel Scanning

The `PlayFile()` method can be used for channel scanning and handling functionality similar to *roChannelManager*. To use `PlayFile()` for channel scanning, pass an *roAssociativeArray&#x20;*&#x77;ith the following possible parameters:

- VirtualChannel
- RfChannel
- SpectralInversion
  - INVERSION\_ON
  - INVERSION\_OFF
  - INVERSION\_AUTO
- ModulationType
  - QAM\_64
  - QAM\_256
  - QAM\_AUTO
  - 8VSB
- VideoCodec
  - MPEG1-Video
  - MPEG2-Video
  - MPEG4Part2-Video
  - H264
  - H264-SVC
  - H264-MVCAVSC
- AudioCodec
  - MPEG-Audio
  - AAC
  - AAC+
  - AC3AC3+DTS
- VideoPid
- AudioPid
- PcrPid

The `VirtualChannel` and `RfChannel` parameters must be present for `PlayFile()` to scan correctly. If you specify only these parameters, the player will scan the RF channel for a QAM/ATSC signal and attempt to retrieve the specified virtual channel from the results. The results from this action are cached so that subsequent calls to `PlayFile()` will take much less time. Providing the `SpectralInversion` and/or `ModulationType` parameters will further speed up the scanning process.

If all parameters are supplied, then no scanning is required and the player can tune to the channel immediately. If one or more of the optional parameters is missing, then the player must parse the transport stream metadata to find the appropriate values for the supplied `VirtualChannel` and `RfChannel`.

## Video Decryption 

The *roVideoPlayer&#xA0;*&#x6F;bject can be used to play audio/video files or streams that have been encrypted using AES. 

:::hint{type="info"}
Streaming decryption requires firmware version 6.2.x and is currently only supported with the UDP protocol and the HTTP protocol (when HTTP is paired with an MPEG2 transport stream). If using a UDP multicast MPEG2 transport stream, one of the elemental streams should provide the PCR to the player.
:::

The associative array passed to the `PlayFile()` method can accept two parameters for file decryption:

- `EncryptionAlgorithm`: The file-encryption algorithm. The following are the current options:
  - "AesCtr": The AES algorithm in CTR mode
  - "AesCtrHmac": The AES algorithm in CTR mode with HMAC
  - "TsAesEcb": The AES algorithm in ECB mode (e.g. with a Harmonic Prostream) with front residual termination. This algorithm is used for streaming encryption/decryption.
  - "TsAesEcbRrt": The AES algorithm in ECB mode (e.g. with a Harmonic Prostream) with rear residual termination. This algorithm is used for streaming encryption/decryption. Available from 9.1.164 on all players except LS3, HD3, HS3, HO3, XD3, XT3, LS4, HS4 and HD4.
  - "TsAesCbcRbt": The AES algorithm in CBC mode with residual block termination. This algorithm is used for streaming encryption/decryption.
  - "TsAesCbcCbt": The AES algorithm in CBC mode with clear block termination. This algorithm is used for streaming encryption/decryption.
- `EncryptionKey`: A byte array consisting of 128 bits of key. If the encryption algorithm is AES-CTR or AES-CTR-HMAC, this is followed by 128 bits of IV.

:::hint{type="info"}
Contact *support\@brightsign.biz* to learn more about generating a key for obfuscation and storing it on the player.
:::

:::hint{type="warning"}
The video player no longer accepts "\{A|A}" AES encryption keys (i.e. where the top and bottom 64 bits of the key are identical).
:::

:::CodeblockTabs
Example

```typescript
v = CreateObject("roVideoPlayer")
aa=CreateObject("roAssociativeArray")
aa.filename = "wall-sync2.mp4"
aa.encryptionalgorithm = "AesCtr"
aa.encryptionkey = CreateObject("roByteArray")
aa.encryptionkey.fromhexstring("01030507090b0d0f00020406080a0c0e00000000000000000000000000000000")


v.PlayFile(aa)
```
:::

## Preferred Streams

If multiple video, audio, or data streams are encapsulated in the video input, you can use the `SetPreferredVideo()`, `SetPreferredAudio()`, and `SetPreferredCaptions()` methods to determine which stream to use. For example, if a video may contain English and Spanish audio tracks, you can call `SetPreferredAudio()` to specify that the Spanish track should be played if it exists, with the video defaulting to English otherwise.

Preferred streams are chosen by matching the patterns in the passed string(s) against the textual description of the stream:

1. The passed string is a semicolon-separated list of templates.
2. Each template is a comma-separated list of patterns.
3. Each pattern is a `[field_name]=[field_value]` pair that is matched directly against the stream description.

**SetPreferredVideo(description As String) As Boolean**

Each template in the passed video description string can contain the following patterns:

- `pid=[integer]`: The packet identifier (PID) of the video stream you wish to display
- `program=[integer]`: The program number of the video stream
- `codec=[video_codec]`: The preferred video codec, which can be any of the following:
  - `MPEG1`
  - `MPEG2`
  - `MPEG4Part2`
  - `H263`
  - `H264`
  - `VC1`
  - `H265`
- `width=[integer]`: The preferred video width
- `height=[integer]`: The preferred video height
- `aspect=[float(x.yy)]`: The preferred aspect ratio of the video stream as a floating-point number with two fractional digits.
- `colordepth=[integer]`: The preferred color depth of the video.

Example:

:::BlockQuote
"pid=7680, codec=H264, width=1280, height=720, aspect=1.78, colordepth=8;"
:::

**SetPreferredAudio(description As String) As Boolean**

Each template in the passed description string can contain the following patterns:

- `pid=[integer]`: The packet identifier (PID) of the audio stream you wish to play
- `program=[integer]`: The program number of the audio stream
- `codec=[audio_codec]`: The preferred audio codec, which can be any of the following:
  - `MPEG`
  - `MP3`
  - `AAC`
  - `AAC-PLUS`
  - `AC3`
  - `AC3-PLUS`
  - `DTS`
  - `PCM`
  - `FLAC`
  - `Vorbis`
- `channels=[integer]`: The preferred number of audio channels (from 1 to 8)
- `freq=[frequency]`: The preferred sample frequency of the audio track, which can be any of the following:
  - `32000`
  - `44100`&#x20;
  - `48000`
- `lang=[language]`: A code that determines the preferred language of the audio track (e.g. eng, spa). The language codes are specified in the ISO 639-2 standard.
- `type=[audio_type]`: The preferred audio type, which can be one of the following:
  - `Main audio`
  - `Clean effects`
  - `Hearing impaired`
  - `Visual impaired commentary`

Example:

:::BlockQuote
"pid=4192, codec=AC3, channels=5, freq=48000, lang=eng, type=Main audio;"
:::

**SetPreferredCaptions(description As String) As Boolean**

Each template in the passed description string can contain the following patterns:

- `pid=[integer]`: The packet identifier (PID) of the caption stream you wish to play
- `type=[subtitle_type]`: The encoding standard of the subtitles. This value can be one of the following:
  - `CEA708`: If the CEA-708 standard is not present, the subtitle\_type will default to CEA-608 (if it is present).
  - `CEA608`
  - `DVB`
- `lang=[language]`: A code that determines the preferred language of the subtitles (e.g. eng, spa). The language codes are specified in the ISO 639-2 standard.
- `service=[integer]`: The preferred service number of the caption stream

Example:

:::BlockQuote
"pid=0, type=Cea708, lang=eng service=1;"
:::

### Pattern Matching Rules

Note the following rules when matching templates to video, audio, or caption stream descriptions:

- For a template to match a stream description, every pattern within the template must match.
- The first listed template to match the stream description (if any) will be used.
- An empty template string will match any stream description.
- All value comparisons are case-insensitive.
- Numerical values must match the stream description exactly (without leading zeroes). For example, the pattern `pid=016` will never match the stream PID value of 16.
- To indicate logical negation, apply the "!" exclamation mark to the beginning of a pattern. For example, specifying `SetPreferredVideo("!codec=H265"`) will match only streams that are not encoded using H.265.
- Apply the ">" greater-than symbol before an integer to indicate that, for a successful match, the value in the stream description must be *greater than&#x20;*&#x74;he value following the symbol. For example, specifying `SetPreferredVideo("width=<1921,height=<1081"`) will match only videos that are no larger than full-HD.
- Apply the "\<" less-than symbol before an integer to indicate that, for a successful match, the value in the stream description must be *less than&#x20;*&#x74;he value following the symbol.

### Pattern Matching Examples

The following examples illustrate some of the pattern matching behavior described above:

- The following template list contains three patterns: `lang=eng`, `lang=spa`, and an empty template. The first pattern specifies an English language channel; if the English channel does not exist, the second pattern specifies a Spanish language channel. The third pattern specifies any other channel if the first two don't exist (the empty template matches anything).

:::BlockQuote
SetPreferredAudio("lang=eng;lang=spa;;")
:::

- Since the following template list is empty, no captions are specified. This can be used to disable captions altogether.

:::BlockQuote
SetPreferredCaptions("")
:::

- The following template list contains an empty template. Since an empty template matches anything, the first video stream encountered will be played. This is the default behavior of all attributes.

:::BlockQuote
SetPreferredVideo(";")
:::

- The following template list specifies a 48KHz audio stream if there is one; otherwise, no audio stream will be played. Observe that the list is not correctly terminated with a semicolon; in this case, the semi-colon is implicitly supplied.

:::BlockQuote
SetPreferredAudio("freq=48000")
:::

- The following template list contains two templates. Note that all patterns within a template must match the stream description for the entire template to match. In this example, an AAC-encoded English track is preferred; an MP3-encoded English track is designated as the second option; and any track will be chosen if neither template is matched.

:::BlockQuote
SetPreferredAudio("codec=aac,lang=eng;codec=mp3,lang=eng;;")
:::

## Examples

The following script selects a program from a video and sets preferred video and audio tracks for playback: 

:::CodeblockTabs
Example

```typescript
v1 = CreateObject("roVideoPlayer")
v1.PlayFile("example.ts")
si = v1.GetStreamInfo()


' Pick the program
prog = si.Programs[2].ProgramId
v1 = CreateObject("roVideoPlayer")

' Select the program
v1.SetPreferredVideo("prog=" + prog.ToStr() + ";")
v1.SetPreferredAudio("prog=" + prog.ToStr() + ";")

' Play the stream/file
v1.PlayFile("example.ts")
```
:::

This script enables only HDMI-4 at 3840x2160x60p:

:::CodeblockTabs
Example

```typescript
mode=CreateObject("roVideoMode")
sm = CreateObject("roArray", 1, 1)
sm[0] = CreateObject("roAssociativeArray")
sm[0].name = "HDMI-4"
sm[0].video_mode="3840x2160x60p"
sm[0].transform="normal"
sm[0].display_x=0
sm[0].display_y=0
sm[0].enabled=true
mode.SetScreenModes(sm)

' Play full screen video with audio going to HDMI-4
rect = createobject("roRectangle",0,0,3840,2160)
output = createObject("roAudioOutput", "hdmi:4")
vplayer = createobject("roVideoPlayer")
vplayer.setrectangle(rect)
vplayer.setcompressedaudiooutputs(output)
vplayer.playfile("Example.mp4")
```
:::