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 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: Theuser_dataof 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 fileEncapsulation: The encapsulation of the videoAudioFormat: The format of the audio fileAudioSampleRate: The audio sample rate (in hertz)AudioChannelCount: The number of audio channelsAudioDuration: The duration of the audio track (in milliseconds)VideoFormat: The format of the video fileVideoColorDepth: 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 videoVideoDuration: The duration of the video (in milliseconds)
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.
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() entry.
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
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
The ifIdentity interface has been deprecated. We recommend using the ifUserData interface instead.
ifMessagePort
SetPort(port As roMessagePort)
Posts messages of type roVideoEvent to 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() 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.
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 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:
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= 1MultiscreenHeight= 1MultiscreenX= 0MultiscreenY= 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)
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:
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 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.
Video Decryption
The roVideoPlayer object can be used to play audio/video files or streams that have been encrypted using AES.
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). This algorithm is used for streaming encryption/decryption.
"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.
Contact support@brightsign.biz to learn more about generating a key for obfuscation and storing it on the player.
Important
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).
Example
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:
The passed string is a semicolon-separated list of templates.
Each template is a comma-separated list of patterns.
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 displayprogram=[integer]: The program number of the video streamcodec=[video_codec]: The preferred video codec, which can be any of the following:MPEG1MPEG2
MPEG4Part2
H263
H264
VC1
H265
width=[integer]: The preferred video widthheight=[integer]: The preferred video heightaspect=[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
"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 playprogram=[integer]: The program number of the audio streamcodec=[audio_codec]: The preferred audio codec, which can be any of the following:MPEGMP3AACAAC-PLUSAC3AC3-PLUSDTSPCMFLACVorbis
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:320004410048000
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 audioClean effectsHearing impairedVisual impaired commentary
Example
"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 playtype=[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).CEA608DVB
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
"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=016will 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.
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).
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;;")
Examples
The following script selects a program from a video and sets preferred video and audio tracks for playback:
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:
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")