6.1-roVideoPlayer

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

ifIdentity

GetIdentity() As Integer

ifMessagePort

SetPort(port As roMessagePort)

Posts messages of type roVideoEvent to the attached message port.

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.

ifAudioControl

See the roAudioPlayer entry 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
 

SetAudioOutputAux(audio_output As Integer) As Boolean
 

SetAudioModeAux(audio_mode As Integer) As Boolean
 

SetAudioStreamAux(stream_index As Integer) As Boolean
 

SetUsbAudioPortAux(a As Integer) As Boolean

ifVideoControl

PlayStaticImage(filename As String) As Boolean

Uses the video decoder to display an image. On 4Kx42 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 the Image Decryption section in the roImagePlayer entry for details on displaying encrypted images.

SetViewMode(mode As Integer) As Boolean

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

• 0: Scales the video to fill the window. The aspect ratio of the source video is ignored, so the video may appear stretched/squashed.
• 1: Letterboxes and centers the window. The aspect ratio of the source window is maintained.
• 2:(Default) Scales the video to fill the window. The aspect ratio is maintained, so the video may appear cropped.

Note that view modes rely on correct aspect-ratio marking from video files, and not all files may be marked correctly.

SetRectangle(r As roRectangle) As Void

Specifies the placement and dimensions of the video window using a passed roRectangle instance.

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

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 instances. 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 clockwise rotation
• rot180: 180 degree rotation
• rot270: 270 degree clockwise 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

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: The URI of the video file
• SrcAddress: The source IP address of the video stream
• DstAddress: 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: The encapsulation of the video. This value can be "ES" (elementary stream), "TS" (transport stream), or "UNKNOWN" for streaming 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
• VideoFormat: The format of the video file
• VideoFramerate: The video frame rate (in frames per second)
• 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

GetStreamStatistics() As roAssociativeArray

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

• Bitrate: The video bitrate
• NumDisplayed: The number of video frames displayed. This is based on the refresh rate of the monitor.
• NumUnderflowed: The number of times the video FIFO has under-flowed. This usually indicates that the buffer size needs to be increased.
• NumDecodeErrors: The number of video frames with decode errors
• NumDecoded: The total number of video frames decoded
• NumAudioDecoded: The total number of audio frames decoded
• NumAudioDecodeErrors: The number of audio frames with decode errors
• NumAudioDummy: 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: The number of times the audio FIFO has under-flowed. This usually indicates that the buffer size needs to be increased.
• VideoFramesPerSecond: The video frame rate (in frames per second)
• VideoInterlaced: A flag indicating whether the video frames are interlaced or progressive

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.

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

PlayFile(parameters As roAssociativeArray) As Boolean

Plays video using the parameters passed as an associative array. This method has several uses: Playing synchronized (and multiscreen) video using the parameters provided by the roSyncManager object; playing streaming video from a URL; playing encrypted files; or playing RF Input using the associative array provided by the CreateChannelDescriptor() method on the roChannelManager object. The associative array can contain the following parameters for audio/video playback:

• Filename: The name/path of a file to be used for playback
• Url: The URL of a video stream to be used for playback
• FadeInLength: The length (in milliseconds) of fade-in at the beginning of the media
• FadOutLength: The length (in milliseconds) of fade-out at the end of the media

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
 

Stop() As Boolean
 

Play() As Boolean
 

SetLoopMode(mode As Dynamic) As Boolean

Specifies the looping mode for media playback. If this method is passed 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. Setting this method to False, which is the default behavior, allows for playback of multiple files in a playlist—with noticeable gaps between the end and beginning of the file. Alternatively, this method can accept an associative array with three Boolean parameters: enable, enable_if_seamless, allow_seamless. The following table describes how these parameters interact:

*or not specified.

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 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 instance 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)

StopClear() As Boolean
 

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() method on the leader unit and the roSyncManagerEvent.GetIsoTimeStamp() method 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() method on the leader unit and the roSyncManagerEvent.GetIsoTimeStamp() method on follower unit(s).

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
• 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

ifZorderControl

ToFront() As Boolean

Places the video layer of the roVideoPlayer instance in front of the other video player.

ToBack() As Boolean

Places the video layer of the roVideoPlayer instance behind the other video player.

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() method 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.

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

Multiscreen Video Playback 

The roVideoPlayer object features overloaded PreloadFile() and PlayFile() functions. These take an roAssociativeArray, rather than a string, as a parameter. These alternative methods are used in conjunction with roSyncManager to stretch an image across multiple screens in an array or display windowed portions of a video, though they can also be used in place of the original function calls for standard operations.

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

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.

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)

To create a multiple-screen matrix in portrait mode, call SetViewMode(0) and SetTransform("rot90") before calling PlayFile().

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

v=CreateObject("roVideoPlayer")
a=CreateObject("roAssociativeArray")
a["Filename"] = "test.ts"
a["MultiscreenWidth"] = 3
a["MultiscreenHeight"] = 1
a["MultiscreenX"] = 0
a["MultiscreenY"] = 0
v.PreloadFile(a)
v.SetViewMode(0)

v.Play()

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

Playing Encrypted Files

The roVideoPlayer object can be used to play audio/video files that have been encrypted using AES. The associative array passed to the PlayFile() method can accept two parameters for file decryption:

• EncryptionAlgorithm: The file-encryption algorithm. Currently the options are "AesCtr" and "AesCtrHmac".
• EncryptionKey: A byte array consisting of 128 bits of key, followed by 128 bits of IV.

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

"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 packer identifier (PID) of the audio stream you wish to play
• 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
  • 4800
• 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



"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 packer 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
   

"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 the 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 the value following the symbol.

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

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

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

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.

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.

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.

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