Roku SDK Developer Guide

Load

Asynchronously loads Playback API contents (a video or a playlist) into the bcPlayer and starts the playback. Usually the data entered in the load function comes from the bcAPI component available in the Brightcove SDK which retrieves videos data from the Playback API, but it’s also used internally by the getVideo, getVideos, getPlaylist and getRelated functions.

The load function may trigger two bcPlayer.on.load events:

• A start event when the load process begins.
• an error event when an error occurs during the load process.
• An end event when the load process is completed and the new Video content is set.

Parameters:

• data DYNAMIC REQUIRED Brightcove videos data to load into the bcPlayer for playback. This data can represent a single video or multiple videos. The possible values are:

  • A single video object ASSOCIATIVE ARRAY Video by ID/Reference

    • Expected metadata object structure:

                                              {
                                                  account_id: "<papi-video-account_id>"
                                                  sources: [<papi-video-sources>],
                                                  <...>
                                                },
                                              

    • Any other properties in this object (besides account_id and sources) are automatically set as fields of the bcPlayer.content ContentNode, taking into account the following custom specifications:

      • If the title property isn't provided and a name property is, title is set to name. title is a native field of a ContentNode and it defines the title text shown in the top left corner of the player when using Roku's OOTB UI/UX.

      • If the length property isn’t provided and a duration property is, length is set to duration / 1000. length is a native field of a ContentNode and it specifies the length of a video in seconds. The duration property should contain the length of the video in milliseconds, if provided.

      • If the SDPosterUrl, HDPosterUrl and FHDPosterUrl properties aren’t provided and a poster property is, these three properties are set to the poster property value. poster should provide the video poster image URL. SDPosterUrl, HDPosterUrl and FHDPosterUrl are native fields of a ContentNode and, although not required in the bcPlayer node, they might be useful in a MarkupGrid, RowList or similar Roku components.

      • If the live property isn't provided, live is set based on the value of the duration property. live is a native field of a ContentNode and it identifies a live video, which may impact the behavior of Roku’s OOTB UI/UX.

        • If duration is not provided or its value is 0 or below: live is set to true.

        • If duration value is above 0: live is set to false.

      • If the video is considered a live stream (live = true) and the playstart property isn't provided, playstart is set to 2147483647. This forces the player to start playback from the live stream position.

  • A playlist object ASSOCIATIVE ARRAY Playlist by ID/Reference

    • Expected metadata object structure:

                                              {
                                                  videos: [
                                                    {
                                                      account_id: "<papi-video-account_id>"
                                                      sources: [<papi-video-sources>],
                                                      <...<
                                                    },
                                                    <...<
                                                  ],
                                                  <...<
                                                }
                                              

    • This metadata is loaded into a Video playlist ContentNode structure.

    • Any other properties in this object (besides videos) are automatically set as fields of the parent ContentNode in the bcPlayer.content field.

  • An array containing a set of videos ARRAY Related Videos or Video Search

    • Expected metadata object structure:

                                              
                                                  [
                                                    {
                                                      account_id: "<papi-video-account_id>"
                                                      sources: [<papi-video-sources>],
                                                      <...<
                                                    },
                                                    <...<
                                                  ]
                                              

    • This metadata is loaded into a Video playlist ContentNode structure.

• options ASSOCIATIVE ARRAY OPTIONAL

  Additional options that allow some behavior to be customized. The following properties can be set in this object:

  • autoplay INTEGER OPTIONAL [To be implemented] Specifies the index of the video that should start playing when the load process ends (in case of a playlist). A value of -1 will prevent the video from auto playing when the load process ends. By default autoplay is set to 0.

  • position STRING OPTIONAL [To be implemented] Specifies where the new data should be loaded if bcPlayer already has content. Ie, should the data replace the old content, should it be added to the end or start of the current content. Possible values:

    • replace DEFAULT

      Replace previous contents with the new content. If position isn't specified, replace is used by default. If the current content is a single video, the new content will always replace it.

    • append

      Add the new content at the end of the current content. Only applicable if the current content is a playlist.

    • prepend

      Add the new content at the start of the current content. Only applicable if the current content is a playlist.

Return Value

BOOLEAN Indicates if the load process was properly initiated.

Code snippet

                    sub init()
                        m.bcPlayer = createObject("roSGNode", "bcLib:bcPlayer")
                
                        ' load video data returned by the Playback API
                        m.bcPlayer.callFunc("load", videoMetadata)
                
                        ' OR
                
                        ' [To be implemented] Set some options to customize the playlist loading behavior
                        m.bcPlayer.callFunc("load", playlistMetadata, {
                          autoplay: 3 ' start playing the video in the index 3 of the playlist
                          position: "end" ' append the playlist to the current contents
                          })
                
                        ' OR
                
                        ' it's also possible to manually customize Playback API metadata before loading it into bcPlayer
                        ' start by requesting a specific video metadata from the Playback API, specifying the "autoload" config property as false so it returns back a response node
                        rNode = m.bcPlayer.callFunc("getVideo", videoID, { autoload: false })
                
                        ' make sure the response Node is available so it can be used to retrieve the response metadata
                        if rNode <> invalid then
                
                          ' set up a listener function for the "response" field
                          rNode.observeField("response", "onVideoResponse")
                
                        end if
                
                      end sub
                
                      sub onVideoResponse(ev)
                
                        ' ev.getData() returns the Playback API response properties
                        response = ev.getData()
                
                        ' if the request failed for any reason, handle the error
                        if response.code <> 200 then
                          ' handle the failed request here
                          return
                        end if
                
                        ' the "body" property contains the Video metadata
                        videoMetadata = response.body
                
                        ' if needed, "videoMetadata" can be customized here before feeding it into the "load" function (keep in mind some properties shouldn't be changed)
                
                        ' load the customized video metadata into bcPlayer for playback
                        m.bcPlayer.callFunc("load", videoMetadata)
                
                      end sub
                    

loadCustom

Asynchronously loads custom metadata (a video or set of videos) into the bcPlayer. This function should be used to load non-Brightcove videos metadata.

Developers should provide the required playback properties as specified by Roku in their documentation page.

The loadCustom function triggers a bcPlayer.on.load event reporting on the success or failure of the load process.

Parameters:

• metadata ASSOCIATIVE ARRAY REQUIRED

  The video or playlist metadata to load into the bcPlayer for playback. All data is loaded as is into a ContentNode. The possible values are:

  • A single video ASSOCIATIVE ARRAY

    If an Associative Array object is provided, a single ContentNode is created and all key-value pairs are set as its fields.

  • A single video ARRAY

    If an Array of Associative Arrays is provided, the ContentNode is structured as a playlist where the videos ContentNodes are added into the parent playlist ContentNode.

• options ASSOCIATIVE ARRAY OPTIONAL

  Additional options allow some behaviors to be customized. The following properties can be set in this object:

  • autoplay ASSOCIATIVE ARRAY OPTIONAL

    Specifies the index of the video that should start playing when the load process ends (in case of a playlist).

    • 0DEFAULT

      Plays the first video in the playlist or the loaded video if not a playlist.

    • -1

      Disables auto playback. This might be useful to preload / prebuffer the video.

  • [To be Implemented] position STRING OPTIONAL

    Specify the position the new metadata should be load into if bcPlayer already contains previous contents. The possible string values are:

    • replaceDEFAULT

      Replace previous contents with the new content. If position isn't specified, replace is used by default. If the current content is a single video, the new content will always replace it.

    • [To be Implemented] append

      Add the new content at the end of the current content. Only applicable if the current content is a playlist.

    • [To be Implemented] prepend

      Add the new content at the start of the current content. Only applicable if the current content is a playlist.

Return value

BOOLEAN Indicates if the load process was properly initiated.

Code snippet

                        sub init()
                          m.bcPlayer = createObject("roSGNode", "bcLib:bcPlayer")
                    
                          ' load custom video metadata
                          m.bcPlayer.callFunc("loadCustom", {
                            Url: "https://my.video.url",  ' make sure the required playback fields are set, like Url, Streams or StreamUrls
                            StreamFormat: "hls",          ' specify the StreamFormat when using the Url field
                            PlayStart: 40,                ' start playback at 40 seconds
                            myCustomField: "hello world"  ' custom fields can also be set, all properties are added as is
                          })
                    
                        end sub
                        

getVideo

Retrieves a specific Brightcove video through Playback API, loads its metadata into bcPlayer, and starts playback.

Playback API reference.

Parameters:

• id STRING REQUIRED

  Brightcove video ID or video reference ID to be retrieved. To get a video using a video reference ID, id must be formatted like so: ref: <reference_id>.

• options ASSOCIATIVE ARRAY OPTIONAL

  Additional options to allow for some behaviors to be customized. The following properties can be set in this object:

  • params ASSOCIATIVE ARRAY OPTIONAL

    Playback API request parameters as specified in the Playback API Reference. The following properties are supported:

    • ad_config_id STRING OPTIONAL

      Include server-side ad insertion.

    • config_id STRING OPTIONAL

      Include and set equal to the delivery rules id in order to have the delivery rules applied.

  • autoload BOOLEAN OPTIONAL

    Specifies if the video metadata should be loaded into bcPlayer once the request response is available.

    • true DEFAULT

      Video metadata will automatically be loaded into bcPlayer. The load behavior can be customized through the autoplay and position options [To be implemented].

    • false

      When autoload is disabled, getVideo will only retrieve Brightcove video metadata. In this case, getVideo immediately returns a Node object which contains a response field that can be used to setup an observer function to capture the request response details.

  • autoplay INTEGER OPTIONAL

    [To be implemented] Specifies the index of the video that should start playing when the load process ends (in case of a playlist). A value of -1 will prevent auto playback when the load process ends. By default autoplay is set to 0. this property is passed along to the load function, which is responsible for the metadata load process. Ignored if autoload is disabled.

  • position STRING OPTIONAL

    [To be implemented] Specify the position the new metadata should be load into if bcPlayer already contains previous contents. Internally. this property is passed along to the load function, which is responsible for the metadata load process. Ignored if autoload is disabled. The possible string values are:

    • replace DEFAULT

      Replace previous contents with the new content. If position isn't specified, replace is used by default.

    • append

      Add the new content at the end of the current content.

    • prepend

      Add the new content at the start of the current content.

Return Value

• invalid

  Returns invalid if autoload is enabled.

• Node

  Returns a Node object if autoload is disabled. This Node contains a response field which can be used to setup an observer function where the request response can be captured.

Code Snippet

                        sub init()
                            ' autoload enabled
                            m.bcPlayer.callFunc("getVideo", videoID, {
                              params: {ad_config_id: adConfigID},
                              autoplay: -1 ' To be implemented feature
                            })
                    
                            ' OR
                    
                            ' autoload disabled
                            responseNode = m.bcPlayer.callFunc("getVideo", videoID, {
                              params: {ad_config_id: adConfigID},
                              autoload: false
                            })
                    
                            ' make sure the response Node is available so it can be used to retrieve the response metadata
                            if responseNode <> invalid then
                    
                              ' set up an observer function for the "response" field
                              responseNode.observeField("response", "onVideoResponse")
                    
                            end if
                    
                          end sub
                    
                          sub onVideoResponse(ev)
                    
                            ' ev.getData() returns the Playback API response properties
                            response = ev.getData()
                    
                            ' if the request failed for any reason, handle the error
                            if response.code <> 200 then
                              ' handle the failed request here
                              return
                            end if
                    
                            ' the "body" property contains the Video metadata
                            videoMetadata = response.body
                    
                            ' if needed, "videoMetadata" can be customized here before feeding it into the "load" function (keep in mind some properties shouldn't be changed)
                    
                            ' load the customized video metadata into bcPlayer for playback
                            m.bcPlayer.callFunc("load", videoMetadata, {
                              autoplay: -1 ' To be implemented feature
                            })
                    
                          end sub
                        

getVideos

Retrieves a set of Brightcove videos through Playback API and, if configured to do so, loads its metadata into bcPlayer and starts playback.

This option is commonly used to programmatically search for Brightcove videos.

Playback API reference.

Parameters:

• query STRING REQUIRED

  Search query used to retrieved a set of Brightcove videos. More details about the search query format, CMS/Playback API.

• options ASSOCIATIVE ARRAY OPTIONAL

  Additional options to allow for some behaviors to be customized. The following properties can be set in this object:

  • params ASSOCIATIVE ARRAY OPTIONAL

    Playback API request parameters as specified in the Playback API Reference. The following properties are supported:

    • limit INTEGER OPTIONAL

      The number of videos to return.

    • offset INTEGER OPTIONAL

      The number of videos to skip - used to page multiple sets of videos.

    • sort STRING OPTIONAL

      Field to sort results by. Check the Playback API Reference for all the possible values.

    • ad_config_id STRING OPTIONAL

      Include server-side ad insertion.

    • config_id STRING OPTIONAL

      Include and set equal to the delivery rules id in order to have the delivery rules applied.

  • autoload BOOLEAN OPTIONAL

    Specifies if the videos metadata should be loaded into bcPlayer once the request response is available.

    • true DEFAULT

      Videos metadata will automatically be loaded into bcPlayer. The load behavior can be customized through the autoplay and position options [To be implemented].

    • false

      When autoload is disabled, getVideos immediately returns a Node object which contains a response field that can be used to setup an observer function to capture the request response details.

  • autoplay INTEGER OPTIONAL

    [To be implemented] Specifies the index of the video that should start playing when the load process ends (in case of a playlist). A value of -1 will prevent auto playback when the load process ends. By default autoplay is set to 0. this property is passed along to the load function, which is responsible for the metadata load process. Ignored if autoload is disabled.

  • position STRING OPTIONAL

    [To be implemented] Specify the position the new metadata should be load into if bcPlayer already contains previous contents. Internally. this property is passed along to the load function, which is responsible for the metadata load process. Ignored if autoload is disabled. The possible string values are:

    • replace DEFAULT

      Replace previous contents with the new content. If position isn't specified, replace is used by default.

    • append

      Add the new content at the end of the current content.

    • prepend

      Add the new content at the start of the current content.

Return Value

• invalid

  Returns invalid if autoload is enabled.

• Node

  Returns a Node object if autoload is disabled. This Node contains a response field which can be used to setup an observer function where the request response can be captured.

Code Snippet

                        sub init()
                            ' autoload enabled
                            m.bcPlayer.callFunc("getVideos", "name:wildlife", {
                              params: {limit: 10, offset: 20},
                              autoplay: -1 ' To be implemented feature
                            })
                    
                            ' OR
                    
                            ' autoload disabled
                            responseNode = m.bcPlayer.callFunc("getVideos", "name:wildlife", {
                              params: {limit: 10, offset: 20},
                              autoload: false
                            })
                    
                            ' make sure the response Node is available so it can be used to retrieve the response metadata
                            if responseNode <> invalid then
                    
                              ' set up an observer function for the "response" field
                              responseNode.observeField("response", "onVideosResponse")
                    
                            end if
                    
                          end sub
                    
                          sub onVideosResponse(ev)
                    
                            ' ev.getData() returns the Playback API response properties
                            response = ev.getData()
                    
                            ' if the request failed for any reason, handle the error
                            if response.code <> 200 then
                              ' handle the failed request here
                              return
                            end if
                    
                            ' the "body" property contains videos metadata
                            videosMetadata = response.body
                    
                            ' if needed, "videosMetadata" can be customized here before feeding it into the "load" function (keep in mind some properties shouldn't be changed)
                    
                            ' load the customized videos metadata into bcPlayer for playback
                            m.bcPlayer.callFunc("load", videosMetadata, {
                              autoplay: -1 ' To be implemented feature
                            })
                    
                          end sub
                        

getPlaylist

Retrieves a Brightcove playlist through Playback API and, if configured to do so, loads its metadata into bcPlayer and starts playback.

Playback API reference.

Parameters:

• id STRING REQUIRED

  Brightcove playlist ID or reference ID to be retrieved. To get a playlist using a playlist reference ID, id must be formatted like so: ref:<reference_id>.

• options ASSOCIATIVE ARRAY OPTIONAL

  Additional options to allow for some behaviors to be customized. The following properties can be set in this object:

  • params ASSOCIATIVE ARRAY OPTIONAL

    Playback API request parameters as specified in the Playback API Reference. The following properties are supported:

    • limit INTEGER OPTIONAL

      The number of videos to return.

    • offset INTEGER OPTIONAL

      The number of videos to skip - used to page multiple sets of videos.

    • ad_config_id STRING OPTIONAL

      Include server-side ad insertion.

    • config_id STRING OPTIONAL

      Include and set equal to the delivery rules id in order to have the delivery rules applied.

  • autoload BOOLEAN OPTIONAL

    Specifies if the playlist metadata should be loaded into bcPlayer once the request response is available.

    • true DEFAULT

      Playlist metadata will automatically be loaded into bcPlayer. The load behavior can be customized through the autoplay and position options [To be implemented].

    • false

      When autoload is disabled, getPlaylist only retrieve Brightcove videos metadata. In this case, getPlaylist returns a Node object which contains a response field that can be used to setup an observer function to capture the request response details.

  • autoplay INTEGER OPTIONAL

    [To be implemented] Specifies the index of the video that should start playing when the load process ends. A value of -1 will prevent auto playback when the load process ends. By default autoplay is set to 0. this property is passed along to the load function, which is responsible for the metadata load process. Ignored if autoload is disabled.

  • position STRING OPTIONAL

    [To be implemented] Specify the position the new metadata should be load into if bcPlayer already contains previous contents. Internally. this property is passed along to the load function, which is responsible for the metadata load process. Ignored if autoload is disabled. The possible string values are:

    • replace DEFAULT

      Replace previous contents with the new content. If position isn't specified, replace is used by default.

    • append

      Add the new content at the end of the current content.

    • prepend

      Add the new content at the start of the current content.

Return Value

• invalid

  Returns invalid if autoload is enabled.

• Node

  Returns a Node object if autoload is disabled. This Node contains a response field which can be used to setup an observer function where the request response can be captured.

Code Snippet

                        sub init()
                            ' autoload enabled
                            m.bcPlayer.callFunc("getPlaylist", playlistID, {
                              params: {limit: 10, offset: 20},
                              autoplay: 3 ' To be implemented feature
                            })
                    
                            ' OR
                    
                            ' autoload disabled
                            responseNode = m.bcPlayer.callFunc("getPlaylist", playlistID, {
                              params: {limit: 10, offset: 20},
                              autoload: false
                            })
                    
                            ' make sure the response Node is available so it can be used to retrieve the response metadata
                            if responseNode <> invalid then
                    
                              ' set up an observer function for the "response" field
                              responseNode.observeField("response", "onPlaylistResponse")
                    
                            end if
                    
                          end sub
                    
                          sub onPlaylistResponse(ev)
                    
                            ' ev.getData() returns the Playback API response properties
                            response = ev.getData()
                    
                            ' if the request failed for any reason, handle the error
                            if response.code <> 200 then
                              ' handle the failed request here
                              return
                            end if
                    
                            ' the "body" property contains the playlist metadata
                            playlistMetadata = response.body
                    
                            ' if needed, "playlistMetadata" can be customized here before feeding it into the "load" function (keep in mind some properties shouldn't be changed)
                    
                            ' load the customized playlist metadata into bcPlayer for playback
                            m.bcPlayer.callFunc("load", playlistMetadata, {
                              autoplay: 3 ' To be implemented feature
                            })
                    
                          end sub
                    
                        

getRelated

Retrieves a set of Brightcove videos that are related to the specified video through Playback API and, if configured to do so, loads its metadata into bcPlayer and starts playback.

Using the name and short description of the specified video, the Playback API searches for videos with any partial matches in the following fields: name, short description, long_description, tags.

Playback API reference.

Parameters:

• id STRING REQUIRED

  Brightcove playlist ID or reference ID to be retrieved. To get a playlist using a playlist reference ID, id must be formatted like so: ref:<reference_id>.

• options ASSOCIATIVE ARRAY OPTIONAL

  Additional options to allow for some behaviors to be customized. The following properties can be set in this object:

  • params ASSOCIATIVE ARRAY OPTIONAL

    Playback API request parameters as specified in the Playback API Reference. The following properties are supported:

    • limit INTEGER OPTIONAL

      The number of videos to return.

    • offset INTEGER OPTIONAL

      The number of videos to skip - used to page multiple sets of videos.

    • ad_config_id STRING OPTIONAL

      Include server-side ad insertion.

    • config_id STRING OPTIONAL

      Include and set equal to the delivery rules id in order to have the delivery rules applied.

  • autoload BOOLEAN OPTIONAL

    Specifies if the playlist metadata should be loaded into bcPlayer once the request response is available.

    • true DEFAULT

      Videos metadata will automatically be loaded into bcPlayer. The load behavior can be customized through the autoplay and position options [To be implemented].

    • false

      When autoload is disabled, getRelated only retrieve Brightcove videos metadata. In this case, getRelated returns a Node object which contains a response field that can be used to setup an observer function to capture the request response details.

  • autoplay INTEGER OPTIONAL

    [To be implemented] Specifies the index of the video that should start playing when the load process ends. A value of -1 will prevent auto playback when the load process ends. By default autoplay is set to 0. this property is passed along to the load function, which is responsible for the metadata load process. Ignored if autoload is disabled.

  • position STRING OPTIONAL

    [To be implemented] Specify the position the new metadata should be load into if bcPlayer already contains previous contents. Internally. this property is passed along to the load function, which is responsible for the metadata load process. Ignored if autoload is disabled. The possible string values are:

    • replace DEFAULT

      Replace previous contents with the new content. If position isn't specified, replace is used by default.

    • append

      Add the new content at the end of the current content.

    • prepend

      Add the new content at the start of the current content.

Return Value

• invalid

  Returns invalid if autoload is enabled.

• Node

  Returns a Node object if autoload is disabled. This Node contains a response field which can be used to setup an observer function where the request response can be captured.

Code Snippet

                        sub init()
                            ' autoload enabled
                            m.bcPlayer.callFunc("getRelated", videoID, {
                              params: {limit: 10, offset: 20},
                              autoplay: 3 ' To be implemented feature
                            })
                    
                            ' OR
                    
                            ' autoload disabled
                            responseNode = m.bcPlayer.callFunc("getRelated", videoID, {
                              params: {limit: 10, offset: 20},
                              autoload: false
                            })
                    
                            ' make sure the response Node is available so it can be used to retrieve the response metadata
                            if responseNode <> invalid then
                    
                              ' set up an observer function for the "response" field
                              responseNode.observeField("response", "onRelatedResponse")
                    
                            end if
                    
                          end sub
                    
                          sub onRelatedResponse(ev)
                    
                            ' ev.getData() returns the Playback API response properties
                            response = ev.getData()
                    
                            ' if the request failed for any reason, handle the error
                            if response.code <> 200 then
                              ' handle the failed request here
                              return
                            end if
                    
                            ' the "body" property contains the related videos metadata
                            relatedMetadata = response.body
                    
                            ' if needed, "relatedMetadata" can be customized here before feeding it into the "load" function (keep in mind some properties shouldn't be changed)
                    
                            ' load the customized related videos metadata into bcPlayer for playback
                            m.bcPlayer.callFunc("load", relatedMetadata, {
                              autoplay: 3 ' To be implemented feature
                            })
                    
                          end sub
                        

playback

Allows control of bcPlayer playback. It provides the same playback actions as the native Video control field plus some other custom actions introduced by bcPlayer.

Parameters:

• action STRING REQUIRED

  Specifies the playback action. The supported values are:

  • All values supported by the native control field:

    • play

      • To play a specific video in the playlist, the index can be provided through the data parameter.

      • By default it plays the first video in the playlist if an index is not specified.

      • If play is requested over the same video that is currently playing, it will behave as pause (if the the video is currently playing) or resume (if the video is currently paused).

    • pause

    • resume

    • stop

    • replay

    • prebuffer

    • skipcontent

  • next

    If current content is a playlist, skips to the next video, if available. Otherwise does nothing. Before skipping, the next video source TTL is validated and if expired the sources will first be refreshed and only then the skip action gets triggered. SSAI or CSAI is also setup, if enabled and applicable, while loading the next video.

  • previous

    If current content is a playlist, skips to the previous video, if available. Otherwise does nothing. Before skipping, the previous video source TTL is validated and if expired the sources will first be refreshed and only then the skip action gets triggered. SSAI or CSAI are also setup, if enabled and applicable, while loading the previous video.

  • seek

    Allows to seek to a specific playback position. This is specially useful during CSAI video playback, where the active Video node isn’t easily accessible. The position value should be specified through the data parameter.

• data DYNAMIC OPTIONAL

  Allows extra data to be provided to execute the applicable actions. Valid for the following actions:

  • play INTEGER OPTIONAL

    • data can specify the video index for playback.

  • seek INTEGER

    • data should specify the seek position.

Return Value

• boolean

  Returns true if the parameters provided are valid. Be aware that it might still return true and the next or previous actions are not applicable (i.e., next won't work if it's playing the last video in a playlist).

Code Snippet

                        sub init()
                      ' play the video index 3 in the playlist
                      m.bcPlayer.callFunc("playback", "play", 3)
                    
                      ' seek to the position 54 in the stream
                      m.bcPlayer.callFunc("playback", "seek", 54)
                    
                      ' skip to the next video, if available and if content is a playlist
                      m.bcPlayer.callFunc("playback", "next")
                    
                      ' the same can be accomplish with:
                      m.bcPlayer.callFunc("playlist", "next")
                    
                    end sub
                        

playlist

Provides playlist specific features. Allows for a better control over items in a playlist. If bcPlayer content is not a playlist, this function will do nothing.

Parameters:

• action STRING REQUIRED

  Specifies the action to be executed. The following values are supported:

  • contains

    [To be implemented] Checks if a video exists in the playlist through the video URL provided.

  • currentIndex

    Get the index of the video that is currently playing in the playlist.

  • currentItem

    Get the ContentNode of the currently playing video in the playlist.

  • item

    Get the ContentNode of the specified video index in the playlist.

  • first

    Get the ContentNode of the first video in the playlist.

  • indexOf

    [To be implemented] Get the index of a video through the video URL provided.

  • last

    Get the ContentNode of the last video in the playlist.

  • lastIndex

    Get the index of the last video in the playlist.

  • next

    Skips to the next video, if available. Otherwise does nothing. Before skipping, the next video source TTL is validated and if expired the sources will first be refreshed and only then the skip action gets triggered.

  • nextIndex

    Get the index of the next video in the playlist.

  • previous

    Skips to the previous video, if available. Otherwise does nothing. Before skipping, the previous video source TTL is validated and if expired the sources will first be refreshed and only then the skip action gets triggered.

  • previousIndex

    Get the index of the previous video in the playlist.

  • sort

    [To be implemented] Sorts the videos in the playlist

  • shuffle

    [To be implemented] Shuffles the videos in the playlist.

  • remove

    Removes the specified video index from the playlist.

• data DYNAMIC OPTIONAL

  Parameters for some of the supported actions. Required for the following actions:

  • item

    INTEGER Specifies the video index.

  • [To be implemented] contains

    STRING Specifies the searched video URL.

  • [To be implemented] indexOf

    STRING Specifies the searched video URL.

  • [To be implemented] sort

    Specifies the sort options.

  • [To be implemented] remove

    STRING Specifies the video index.

Return Value

DYNAMIC The return value depends on the action executed. If content is not a playlist the return value is invalid for all actions. Otherwise, the return value per action is the following:

• contains BOOLEAN

• currentIndex INTEGER

• currentItem NODE

• item NODE

• first NODE

• indexOf INTEGER

• last NODE

• lastIndex INTEGER

• next INVALID

• nextIndex INTEGER

• previous INVALID

• previousIndex INTEGER

• sort INVALID

• shuffle INVALID

Code Snippet

                        sub init()
                            ' get the index of the next video in the playlist, if content is a playlist
                            nextVideoIndex = m.bcPlayer.callFunc("playlist", "nextIndex")
                            if nextVideoIndex = invalid then
                    
                              ' current content is not a playlist. Handle that situation here if required.
                    
                            end if
                    
                          end sub
                        

close

Closes bcPlayer and terminates all ongoing tasks and playback in the bcPlayer. The closing procedure is asynchronous so that any pending task doesn’t get abruptly interrupted. The closed confirmation can be obtained from the bcPlayer.on.close event.

Parameters:

• This function has no parameters

Return Value

• VOID

Code Snippet

                        sub init()
                            ' listen for the "close" event, in case some action needs to be taken only after the complete termination of the bcPlayer
                            m.bcPlayer.on.observeField("close", "onClose")
                    
                            ' trigger the close action
                            m.bcPlayer.callFunc("close")
                    
                          end sub
                    
                          sub onClose(ev)
                    
                            ' m.bcPlayer is now completely terminated
                    
                          end sub
                        

validate

Validates passed values according to the rules provided.

Parameters:

• value DYNAMIC REQUIRED

  The value meant to be validated.

• map ASSOCIATIVE ARRAY REQUIRED

  A map of rules used to validate the provided value against. This Associative Array object contains the following properties:

  • type STRING REQUIRED

    Specifies the expected value type. The following types are supported:

    • string Value must be a String.

    • number Value must be a number (Integer, Float, Double or LongInteger).

    • boolean Value must be a Boolean.

    • array Value must be an Array.

    • node Value must be a roSGNode.

    • aa Value must be an Associative Array.

    • <type> If none of the previous values is recognized, it uses <type> to support other Roku types. Please be aware that type() can return different values for the “same” type, ie: “String” vs “roString”.

  • required BOOLEAN OPTIONAL

    Specifies that the value cannot be invalid if true. Default to true if not provided. Applicable to all types.

  • empty BOOLEAN OPTIONAL

    Specifies that the value can be an empty String (““), Associative Array ({}) or Array ([]) if true.

    Defaults to true if not provided. Only applicable to string, aa and array types.

  • minLength INTEGER OPTIONAL

    Specifies the minimum length of a String (number of chars), Associative Array (number of keys) or Array (number of entries). Only applicable to string, aa and array types.

  • maxLength INTEGER OPTIONAL

    Specifies the maximum length of a String (number of chars), Associative Array (number of keys) or Array (number of entries). Only applicable to string, aa and array types.

  • enum STRING ARRAY OPTIONAL

    Specifies a list of possible values value can take. The contains function is used to verify if the value is present in enum. Only applicable to string and number types.

  • min INTEGER OPTIONAL

    Specifies the minimum value of value. Only applicable to the number type.

  • max INTEGER OPTIONAL

    Specifies the maximum value of value. Only applicable to the number type.

  • null BOOLEAN OPTIONAL

    Specifies if value can be 0. Only applicable to the number type.

  • properties ASSOCIATIVE ARRAY OPTIONAL

    Specifies a map of rules to be applied to a specific Associative Array property. This allows for a recursion execution of validate. All the properties listed in the map section are supported. Only applicable to the aa type.

  • subtype STRING OPTIONAL

    Specifies the subtype (as indicated by value.subtype()) that value should reflect. Only applicable to the node type.

  • fields ARRAY OPTIONAL

    Specifies a list of fields that the value node must have (as indicated by value.hasField("field")). An Array of Strings must be provided where each entry represents the name of a field. Only applicable to the node type.

  • interface STRING OPTIONAL

    Specifies the interface (as indicated by getInterface()) that value should reflect. Only applicable to the node type.

Return Value

BOOLEAN

Returns a Boolean value that indicates if value respects all the rules provided in the map parameter. A failed validation of a single rule will invalidate the whole validation and return false.

Code Snippet

                        m.bcUtils = createObject("roSGNode", "bcLib:Utils")
                            test1 = "A random string"
                            validTest1 = m.bcUtils.callFunc("validate", test1, {type: "string", maxLength: 4})
                            ? validTest1 ' false because test1 fails the maxLength validation rule
                    
                            test2 = "hello-world"
                            ' keep in mind that when specifying "enum" as a string, the inStr() function
                            ' is used to search for the value
                            validTest2 = m.bcUtils.callFunc("validate", test2, {
                              type: "string",
                              enum: "hello-world/hello-planet/hello-pluto"
                            })
                            ' OR
                            validTest2 = m.bcUtils.callFunc("validate", test2, {
                              type: "string",
                              enum: ["hello-world","hello-planet","hello-pluto"]
                            })
                            ? validTest2 ' true because "hello-world" is a string and
                            ' it's specified in the enum validation rule
                    
                            test4 = invalid
                            validTest3 = m.bcUtils.callFunc("validate", test3, {type: "string", empty: false})
                            ? validTest3 ' false because, by default, the "required" validation rule is true
                    
                            test4 = createObject("roSGNode", "Node")
                            test4.addFields({hello: "world"})
                            validTest4 = m.bcUtils.callFunc("validate", test4, {
                                type: "node",
                                interface: "ifSGNodeChildren",
                                subtype: "Node",
                                fields: ["hello"]
                            })
                            ? validTest4 ' true because all validation rules are valid
                    
                            test5 = {hello: {world: []}}
                            validTest5 = m.bcUtils.callFunc("validate", test5, {
                                type: "aa",
                                properties: {
                                    hello: {
                                        type: "aa",
                                        properties: {
                                            world: {
                                                type: "array",
                                                empty: false
                                            }
                                        }
                                    }
                                }
                            })
                            ? validTest5 ' false because, as specified by the validation rules,
                            ' "test5.hello.world" cannot be an empty array
                    
                            test6 = [1, 2, 4, 8, "testing"]
                            validTest6 = m.bcUtils.callFunc("validate", test6, {type: "array", maxLength: 5})
                            ? validTest6 ' true because test6 respects the array and maxLength validation rule
                        

contains

Allows to search for a needle in a haystack. Internally the indexOf function is used to run the search.

Parameters:

• haystack STRING ARRAY REQUIRED

  A String or Array where to search for the needle. Have in mind the following details:

  • If haystack is a string, the needle should also be a string.

  • If haystack is an array:

    • If needle is a string, it'll be lower-cased before the search process. Haystack string items are also lower-cased for a proper comparison with needle.

    • If needle is not a string, the comparison is made with needle = haystack[i]..

• needle STRING NUMBER REQUIRED

  The value to find in the haystack. When comparing strings, both needle and haystack are lower-cased.

Return Value

INTEGER

Returns true if needle is found in haystack or false otherwise.

Code Snippet

                        m.bcUtils = createObject("roSGNode", "bcLib:Utils")
                            test = m.bcUtils.callFunc("contains", "This is A tEst string", "a test")
                            ' test = true
                    
                            test = m.bcUtils.callFunc("contains", [2, "a", 5], "5")
                            ' test = false
                        

indexOf

Just like contains, searches for a needle in a haystack, but returns the index of the needle in the haystack if found instead.

Parameters:

• haystack STRING ARRAY REQUIRED

  A String or Array where to search for the needle. Have in mind the following details:

  • If haystack is a string, the needle should also be a string.

  • If haystack is an array:

    • If needle is a string, it'll be lower-cased before the search process. Haystack string items are also lower-cased for a proper comparison with needle.

    • If needle is not a string, the comparison is made with needle = haystack[i]..

• needle STRING NUMBER REQUIRED

  The value to find in the haystack. When comparing strings, both needle and haystack are lower-cased.

Return Value

• -1 if needle isn't found.

• Index of needle in haystack. Either the haystack array index where needle was found or the inStr() result if needle and haystack are strings.

Code Snippet

                    m.bcUtils = createObject("roSGNode", "bcLib:Utils")
                        test = m.bcUtils.callFunc("indexOf", "This is A tEst string", "a test")
                        ' test = 8
                
                        test = m.bcUtils.callFunc("indexOf", [2, "a", 5], "5")
                        ' test = -1
                    

isBool

Checks if value is a Boolean.

• value DYNAMIC REQUIRED

Return Value

BOOLEAN

• true if value is Boolean, false otherwise.

Code Snippet

                    m.bcUtils = createObject("roSGNode", "bcLib:Utils")
                        test = m.bcUtils.callFunc("isBool", "Def not a boolean")
                        ' test = false
                    

isFunction

Checks if value is a Function.

Parameters

• value DYNAMIC REQUIRED

Return Value

BOOLEAN

• true if value is Function, false otherwise.

Code Snippet

                    m.bcUtils = createObject("roSGNode", "bcLib:Utils")
                sub myTestFnc()
                  ? "hello world"
                end sub
                
                test = m.bcUtils.callFunc("isFunction", myTestFnc)
                ' test = true
                    

isAA

Checks if value is an Associative Array object.

Parameters:

• value DYNAMIC REQUIRED

Return Value

BOOLEAN

• true if value is an Associative Array object, false otherwise.

Code Snippet

                    m.bcUtils = createObject("roSGNode", "bcLib:Utils")
                        test = m.bcUtils.callFunc("isAA", {})
                        ' test = true
                    

isArray

Checks if value is an Array object.

Parameters:

• value DYNAMIC REQUIRED

Return Value

BOOLEAN

• true if value is an Array object, false otherwise.

Code Snippet

                    m.bcUtils = createObject("roSGNode", "bcLib:Utils")
                        test = m.bcUtils.callFunc("isArray", ["this", "is", "an", "array"])
                        ' test = true
                    

isInt

Checks if value is an Integer number.

Parameters:

• value DYNAMIC REQUIRED

Return Value

BOOLEAN

• true if value is an Integer number, false otherwise.

Code Snippet

                    m.bcUtils = createObject("roSGNode", "bcLib:Utils")
                        test = m.bcUtils.callFunc("isInt", "123")
                        ' test = false
                    

isFloat

Checks if value is an Float number.

Parameters:

• value DYNAMIC REQUIRED

Return Value

BOOLEAN

• true if value is an Float number, false otherwise.

Code Snippet

                    m.bcUtils = createObject("roSGNode", "bcLib:Utils")
                        test = m.bcUtils.callFunc("isFloat", 1.23)
                        ' test = true
                    

isNumber

Checks if value is an Integer, Float, Double or LongInteger number.

Parameters:

• value DYNAMIC REQUIRED

Return Value

BOOLEAN

• true if value is an Integer, Float, Double or LongInteger number, false otherwise.

Code Snippet

                    m.bcUtils = createObject("roSGNode", "bcLib:Utils")
                        test = m.bcUtils.callFunc("isNumber", 323)
                        ' test = true
                    

isString

Checks if value is a String.

Parameters:

• value DYNAMIC REQUIRED

Return Value

BOOLEAN

• true if value is a String, false otherwise.

Code Snippet

                    m.bcUtils = createObject("roSGNode", "bcLib:Utils")
                        test = m.bcUtils.callFunc("isString", "323")
                        ' test = true
                    

charAt

Get the character positioned at a specific index of a string.

Parameters:

• string STRING REQUIRED

  The string to get the character from.

• index INTEGER REQUIRED

  The index of the character.

Return Value

STRING

• The character at the position specified by index.

Code Snippet

                    m.bcUtils = createObject("roSGNode", "bcLib:Utils")
                test = m.bcUtils.callFunc("charAt", "My String", 3)
                ' test = "S"
                    

toString

Converts any type to a string.

Parameters:

• value DYNAMIC REQUIRED

  The value to be converted into a string.

• maxDepth INDEX OPTIONAL

  Specifies the max depth of a roSGNode, Array or Associative Array that should be converted to string. If not specified, the default value is 3. The minimum maxDepth value is 1. Keep in mind that increasing the maxDepth will exponentially increase the performance hit as well.

Return Value

STRING

Returns a string representation of value. The supported types include:

• <uninitialized>

  Returns “UNINITIALIZED“.

• invalid

  Returns “INVALID“.

• string

  Returns value.

• integer

  Returns the number string representation.

• float

  Returns the number string representation.

• double

  Returns the number string representation.

• roSGNode

  Converts the Node fields to an AssociativeArray object, converts it to string and returns it in the following format: “<Component: NodeType {NodeFields}>". If maxDepth has been reached, the following format is returned: “<Component: NodeType>".

• Array

  Converts the Array to a string by converting each individual Array entry to a String in a recursive execution of this function. If maxDepth is reached, the following format is returned: “[ArrayLength]".

• List

  Just like Array, converts the List to a string by converting each individual List entry to a String in a recursive execution of this function. If maxDepth is reached, the following format is returned: “[ListLength]".

• Associative Array

  Converts the Associative Array to a string by converting each individual key value to a String in a recursive execution of this function. If maxDepth is reached, the following format is returned: “{[ListOfKeys]}".

• Boolean

  Returns the Boolean string representation.

• roDateTime

  Returns the DateTime ISO string.

• Any other “ro<node-name>“ nodes

  Returns the following format: “<Component: NodeType>".

• Any other value not mention will return an empty String.

Code Snippet

                    m.bcUtils = createObject("roSGNode", "bcLib:Utils")
                        test = m.bcUtils.callFunc("toString", 567)
                        ' test = "567"
                
                        test2 = { one: { two: { three: { four: { five: "Hello World" } } } } }
                        test2 = m.bcUtils.callFunc("toString", test2, 2)
                        ' test2 = "{\"one\":{\"two\":{[\"three\"]}}}"
                    

toDouble

Converts a string to double.

Parameters:

• value STRING REQUIRED

  The string value to be converted into a Double value.

Return Value

DOUBLE

Returns the converted value as a Double number.

Code Snippet

                    m.bcUtils = createObject("roSGNode", "bcLib:Utils")
                ? m.bcUtils.callFunc("toDouble", "3244.34343")        ' => 3244.34343#
                ? m.bcUtils.callFunc("toDouble", "not a number")      ' => 0#
                ? m.bcUtils.callFunc("toDouble", "dfdfd.435454")      ' => 0.435454#
                ? m.bcUtils.callFunc("toDouble", "0.45454454")        ' => 0.45454454#
                ? m.bcUtils.callFunc("toDouble", "-34343.45454454")   ' => -34343.45454454#
                    

setAddFields

Adds or updates a set of properties in the specified Node. It essentially goes through the list of properties provided in the fields parameter and:

• If the field does not exist in the Node provided: adds the new field with the value provided.

• If the field already exists in the Node provided: updates its value with the value provided.

The change and focusedChild properties are removed from the fields object, if present, before applying the fields to the Node.

Parameters:

• node NODE REQUIRED

  The Node reference which will get its fields updated

• fields ASSOCIATIVE ARRAY REQUIRED

  A set of key-value pairs representing the field names and the respective values to be added / updated in the Node provided.

Return Value

VOID

Code Snippet

                        m.bcUtils = createObject("roSGNode", "bcLib:Utils")
                    testNode = createObject("roSGNode", "ContentNode")
                    testNode.id = "hello world"
                    
                    m.bcUtils.callFunc("setAddFields", {
                      id: "hello planet",
                      customField: "my custom field"
                    })
                    
                    ? "testNode id: " testNode.id ' => "hello planet"
                    ? "testNode customField: " testNode.customField ' => "my custom field"
                        

addURLParams

Adds the provided key-value pairs as query parameters into the URL provided.

Be aware that this function does not verify if query parameters already exist, it simply appends all the properties in the params parameter to the url value.

Parameters:

• url STRING REQUIRED

  The URL where query parameter will be added.

• params ASSOCIATIVE ARRAY REQUIRED

  A key-value object specifying the query parameter names and values to be added into url.

Return Value

STRING

Returns url with the added query parameters. If, for any reason, no query parameters were added, url is returned as is.

Code Snippet

                    m.bcUtils = createObject("roSGNode", "bcLib:Utils")
                url = "http://my.fancy.url"
                url = m.bcUtils.callFunc("addURLParams", url, {hello: "world"})
                ? url ' => "http://my.fancy.url?hello=world"
                
                ' running the function again with the same parameters will result in duplicated query parameters
                url = m.bcUtils.callFunc("addURLParams", url, {hello: "world"})
                ? url ' => "http://my.fancy.url?hello=world&hello=world"
                    

match

Search for matching substrings in a String through a regex pattern. If the matching pattern contains N parenthetical substrings, the relevant substrings are returned as an array of length N+1, where array[0] is again the entire match and each additional entry in the array is the match for the corresponding parenthetical expression.

Uses Roku’s roRegex component internally.

Parameters:

• string STRING REQUIRED

  The string to check.

• pattern STRING REQUIRED

  The regex pattern.

• flag STRING OPTIONAL

  Specifies the behavior flags. Empty string if not provided. Any combination of the following flags is supported:

  • i Case insensitive match.

  • m Multiline mode. The start of line ^ and end of line $ constructs match immediately following or before any newline in the subject string as well as the very start and end of the string. Normally, just the start and end of the string would match.

  • s Sets dot-all mode that includes newline in the .* regular expression. This modifier is equivalent to Perl's /s modifier.

  • x Sets extended mode that ignores whitespace characters except when escaped or inside a character class. Characters between an unescaped # outside a character a character class and the next newline character, inclusive, are also ignored. This modifier is equivalent to Perl's /x modifier.

Return Value

ARRAY

Returns an Array of matched substrings from string. If no match was made, an empty array is returned. If a match was made, the entire match is returned in array[0]. If there are no parenthetical substrings this is the only entry in the array.

Code Snippet

                    m.bcUtils = createObject("roSGNode", "bcLib:Utils")
                        test = m.bcUtils.callFunc("match", "abcd", "(a|(z))(bc)", "i")
                        ' test = ["abc", "a", "", "bc"]
                    

replace

Replaces all occurrences of a matching pattern in string with replacement String and returns the result. The replacement may contain numbered back-references to parenthetical substrings.

Keep in mind that the replace function does not use any behavior flags.

Uses Roku’s roRegex component internally.

Parameters:

• string STRING REQUIRED

  The string to check.

• pattern STRING REQUIRED

  The end characters to check.

• replacement STRING REQUIRED

  The string to be used to replace matches in the provided string.

Return Value

STRING

A string with the result of the replace operation.

Code Snippet

                    m.bcUtils = createObject("roSGNode", "bcLib:Utils")
                        test = m.bcUtils.callFunc("replace", "Abracadabra", "a", "x")
                        ' test = "Abrxcxdxbrx"
                    

truncate

Allows to truncate a string by the specific number of chars and set a custom truncate char.

Parameters:

• string STRING REQUIRED

  The string to check.

• length INTEGER REQUIRED

  The end characters to check.

• chars STRING DEFAULT

  Chars that will be added in the truncate position of the string. Defaults to ... if not provided.

Return Value

STRING

Returns the truncated string.

Code Snippet

                    m.bcUtils = createObject("roSGNode", "bcLib:Utils")
                        test = m.bcUtils.callFunc("truncate", "My String", 3)
                        ' test = "My ..."
                
                        test2 = m.bcUtils.callFunc("truncate", "My String", 2, "-")
                        ' test2 = "My-"
                
                        test3 = m.bcUtils.callFunc("truncate", "My String", 2, "")
                        ' test3 = "My"
                    

toMD5

Generates the hash of a string using MD5 algorithm.

Parameters:

• string STRING REQUIRED

  The string to generate the MD5 hash from.

Return Value

STRING

Returns the string MD5 hash.

Code Snippet

                    m.bcUtils = createObject("roSGNode", "bcLib:Utils")
                        test = m.bcUtils.callFunc("toMD5", "My String")
                        ' test = "4545102cc40ea0a85124cf4b31574661"
                    

toSHA1

Generates the hash of a string using SHA1 algorithm.

Parameters:

• string STRING REQUIRED

  The string to generate the SHA1 hash from.

Return Value

STRING

Returns the string SHA1 hash.

Code Snippet

                    m.bcUtils = createObject("roSGNode", "bcLib:Utils")
                        test = m.bcUtils.callFunc("toSHA1", "My String")
                        ' test = "c9dacbd8a688c5b310890310e14272ac11be5744"
                    

toSHA256

Generates the hash of a string using SHA256 algorithm.

Parameters:

• string STRING REQUIRED

  The string to generate the SHA256 hash from.

Return Value

STRING

Returns the string SHA256 hash.

Code Snippet

                    m.bcUtils = createObject("roSGNode", "bcLib:Utils")
                        test = m.bcUtils.callFunc("toSHA256", "My String")
                        ' test = "3f9a07d83c604dba400d13df4d34566b78338804f0b3181d4e02089fe4daa7b0"
                    

toSHA512

Generates the hash of a string using SHA512 algorithm.

Parameters:

• string STRING REQUIRED

  The string to generate the SHA512 hash from.

Return Value

STRING

Returns the string SHA512 hash.

Code Snippet

                    m.bcUtils = createObject("roSGNode", "bcLib:Utils")
                        test = m.bcUtils.callFunc("toSHA512", "My String")
                        ' test = "8c4b4171030e0483f46805abfa1b9..."
                    

is4kReady

Checks if the current Roku device is capable of reproducing 4K content. The following items are verified:

• Connected display resolution (must be 2160p for 4K content playback)

• [Roku STB only] HDCP version (must be 2.2 for 4K content playback)

• Roku device video decoding capabilities (must be able to decode hevc and vp9 video codecs)

The Roku device is considered 4K Ready if all of these items are valid.

Parameters:

This function has no parameters.

Return Value

BOOLEAN

Returns true if the device is able to reproduce 4K content, false otherwise.

Code Snippet

                    m.bcUtils = createObject("roSGNode", "bcLib:Utils")
                        test = m.bcUtils.callFunc("is4kReady")
                        ' test = true
                    

isHDRReady

Checks if the current Roku device is capable of reproducing the specified HDR type. Uses getDisplayProperties for this purpose.

Parameters:

• hdr STRING OPTIONAL

  The HDR type to check for support. The following values are supported:

  • "" DEFAULT

    Checks if any HDR type is supported. This is the default behavior if hdr is not provided.

  • hdr10

    Checks if HDR10 is supported.

  • hdr10plus

    Checks if HDR10+ is supported.

  • hlg

    Checks if HLG is supported.

  • dolbyvision

    Checks if Dolby Vision is supported.

Return Value

BOOLEAN

Returns true if the specified HDR type is supported, false otherwise.

Code Snippet

                    m.bcUtils = createObject("roSGNode", "bcLib:Utils")
                        test = m.bcUtils.callFunc("isHDRReady", "hdr10plus")
                        ' test = false
                    

canPlayAudio

Checks if the current Roku device is capable of reproducing the specified audio codec. Essentially this function provides an interface for CanDecodeAudio.

Parameters:

• params ASSOCIATIVE ARRAY REQUIRED

  Specifies the audio codec to check for support. Supports the same properties as the CanDecodeAudio audio_format parameter.

Return Value

BOOLEAN

Returns true if the device is able to reproduce the specified audio codec, false otherwise. Essentially returns the value of the CanDecodeAudio return result property.

Code Snippet

                    m.bcUtils = createObject("roSGNode", "bcLib:Utils")
                        test = m.bcUtils.callFunc("canPlayAudio", {codec: "eac3", Atmos: 1})
                        ' test = false
                
                    

error

Triggers an error log message (level 0).

Parameters:

• message STRING REQUIRED

  Specifies the log message.

• params DYNAMIC OPTIONAL

  Specifies the log message.

Code Snippet

                            m.bcLogger = createObject("roSGNode", "bcLib:Logger")
                                m.bcLogger.callFunc("error", "my error message", <optional-data>)
                            

warn

Triggers a warning log message (level 1).

Parameters:

• message STRING REQUIRED

  Specifies the log message.

• params DYNAMIC OPTIONAL

  Specifies any useful data to be logged.

Code Snippet

                            m.bcLogger = createObject("roSGNode", "bcLib:Logger")
                                m.bcLogger.callFunc("warn", "my warning message", <optional-data>)
                                
                            

info

Triggers an info log message (level 2).

Parameters:

• message STRING REQUIRED

  Specifies the log message.

• params DYNAMIC OPTIONAL

  Specifies any useful data to be logged.

Code Snippet

                            m.bcLogger = createObject("roSGNode", "bcLib:Logger")
                                m.bcLogger.callFunc("info", "my informational message", <optional-data>)
                            

verbose

Triggers a verbose log message (level 3).

Parameters:

• message STRING REQUIRED

  Specifies the log message.

• params DYNAMIC OPTIONAL

  Specifies any useful data to be logged.

Code Snippet

                            m.bcLogger = createObject("roSGNode", "bcLib:Logger")
                                m.bcLogger.callFunc("verbose", "my verbose message", <optional-data>)
                            

debug

Triggers a debug log message (level 4).

Parameters:

• message STRING REQUIRED

  Specifies the log message.

• params DYNAMIC OPTIONAL

  Specifies any useful data to be logged.

Code Snippet

                            m.bcLogger = createObject("roSGNode", "bcLib:Logger")
                                m.bcLogger.callFunc("debug", "my debug message", <optional-data>)
                            

theme

ASSOCIATIVE ARRAY OPTIONAL

Allows to set up the Dialog theme colors. The properties provided in theme are reflected in the StandardDialog palette field.

Possible values

• Supports all StandardDialog palette field properties. If not provided, Roku default colors are used.

Code Sinippet

                            m.dialog = createObject("roSGNode", "bcLib:Dialog")
                                m.dialog.theme = {
                                  DialogBackgroundColor: "#29292900",
                                  DialogTextColor: "#D1D1D100",
                                  DialogFocusColor: "#B9323200"
                                }
                        
                                m.top.getScene().dialog = m.dialog
                            

titleConfig

ASSOCIATIVE ARRAY OPTIONAL

Allows to customize the Dialog title area.

Possible values:

Supports all StdDlgTitleArea fields plus the following custom properties:

• fontSize INTEGER OPTIONAL

  Specifies the Dialog title font size. If not provided, the default StdDlgTitleArea font size is used.

• fontUrl STRING OPTIONAL

  Specifies the Dialog title font URL. If not provided, the default StdDlgTitleArea font URL is used.

• align STRING OPTIONAL

  Specifies the Dialog title text horizontal alignment. The following values are supported:

  • left DEFAULT

  • right

  • center

Code Sinippet

                        m.dialog = createObject("roSGNode", "bcLib:Dialog")
                            m.dialog.titleConfig = {
                              primaryTitle: "My Dialog",
                              primaryIcon: "pkg:/my/dialog/icon.png",
                              align: "center"
                            }
                        

content

ARRAY OPTIONAL

Allows to customize the Dialog content area.

Possible values:

Supports an Array where each entry represents a component in the Dialog content area. Any combination of the following items is supported:

• STRING

  Adds a StdDlgTextItem node to the Dialog content area. The provided string specifies its text field.

• ASSOCIATIVE ARRAY

  Adds the specified component to the Dialog content area. The type property value defines what type of component will be added as well as the other properties specific to that component. The following sets of properties are supported, per component type:

  • Text component

    • type STRING REQUIRED

      Specifies the type of the component, text for a StdDlgTextItem component.

    • text STRING OPTIONAL

      Specifies the StdDlgTextItem text field value.

    • style STRING OPTIONAL

      Specifies the StdDlgTextItem namedTextStyle field value. If not provided, normal is used.

    • align STRING OPTIONAL

      Specifies the text horizontal alignment. The following values are supported:

      • left DEFAULT

      • right

      • center

  • Progress component

    • type STRING REQUIRED

      Specifies the type of the component, progress for a StdDlgProgressItem component.

    • text STRING OPTIONAL

      Specifies the StdDlgProgressItem text field value.

    • interval INTEGER OPTIONAL

      Specifies the internal BusySpinner node spinInterval field value.

    • counterclockwise BOOLEAN OPTIONAL

      Specifies if the internal BusySpinner node should rotate in the counter-clockwise direction. Set to false if not specified.

    • size NUMBER OPTIONAL

      Specifies the width and height values of the internal BusySpinner node.

    • url STRING OPTIONAL

      Specifies the Poster node url of the internal BusySpinner node. The size property is required for the url value to be properly applied.

  • MultiStyle component

    • type STRING REQUIRED

      Specifies the type of the component, multistyle for a StdDlgMultiStyleTextItem component.

    • text STRING OPTIONAL

      Specifies the StdDlgMultiStyleTextItem text field value.

    • styles ASSOCIATIVE ARRAY OPTIONAL

      Specifies the StdDlgMultiStyleTextItem drawingStyles field value. Keep in mind that the specified styles require all the following properties to be provided:

      • fontSize REQUIRED

      • fontUri REQUIRED

      • color REQUIRED

    • align STRING OPTIONAL

      Specifies the text horizontal alignment. The following values are supported:

      • left DEFAULT

      • right

      • center

  • Graphic component

    • type STRING REQUIRED

      Specifies the type of the component, graphic for a StdDlgGraphicItem component.

    • text STRING OPTIONAL

      Specifies the StdDlgGraphicItem text field value.

    • url STRING OPTIONAL

      Specifies the StdDlgGraphicItem graphicUri field value.

    • width NUMBER OPTIONAL

      Specifies the StdDlgGraphicItem graphicWidth field value.

    • height NUMBER OPTIONAL

      Specifies the StdDlgGraphicItem graphicHeight field value.

    • align STRING OPTIONAL

      Specifies the StdDlgGraphicItem graphicAlign field value. The following values are supported:

      • left DEFAULT

      • right

      • center_above

      • center_below

Code Sinippet

                        m.dialog = createObject("roSGNode", "bcLib:Dialog")

                            m.dialog.content = [
                                "My Pretty Dialog",
                                {
                                    type: "text",
                                    text: "My bold and centered Pretty Dialog"
                                    style: "bold",
                                    align: "center"
                                },
                                {
                                    type: "multistyle",
                                    text: "My 
Pretty
 Dialog"
                                    styles: {
                                        default: {
                                            fontSize: 34
                                            fontUri: "font:SystemFontFile"
                                            color: "#EFEFEFFF"
                                        },
                                        p: {
                                            fontSize: 42
                                            fontUri: "font:SystemFontFile"
                                            color: "#00FF00FF"
                                        }
                                    },
                                    align: "center"
                                }
                            ]
                            
                            m.top.getScene().dialog = m.dialog
                        

The code snippet above produces the following Dialog content:

sidecard

ASSOCIATIVE ARRAY OPTIONAL

Allows to set up the Dialog side card area.

Possible values:

• invalid removes the current side card if present.

• An Associative Array containing any of the StdDlgSideCardArea fields plus the following custom properties:

  • content ASSOCIATIVE ARRAY REQUIRED

    Specifies the Dialog side card contents. Any combination of the following items is supported:

    • ASSOCIATIVE ARRAY

      An Associative Array object specifying the name of a Node and its fields. The following properties are required:

      • node STRING REQUIRED

        Specifies the name of the Node that should be added into the Dialog side card.

      • fields ASSOCIATIVE ARRAY REQUIRED

        Specifies the fields of the Node and its values.

    • NODE

      A Node reference. This Node will be added as is to the side card content area.

Code Sinippet

                        m.dialog = createObject("roSGNode", "bcLib:Dialog")

                            m.dialog.setFields({
                                  titleConfig: { 
                                      primaryTitle : "My Pretty Dialog"
                                  },
                                  content: [
                                      "Once upon a time a pretty Dialog"
                                  ],
                                  sidecard: {
                                      extendToDialogEdge: true,
                                      horizAlign: "left",
                                      width: 300,
                                      content: [
                                          {
                                              node: "Poster",
                                              fields: { 
                                                width: 300, 
                                                height: 300, 
                                                uri: "https://images.unsplash.com/photo-1553095066-5014bc7b7f2d?q=80&w=300&h=300&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxzZWFyY2h8Mnx8d2FsbCUyMGJhY2tncm91bmR8ZW58MHx8MHx8fDA%3D" 
                                              }
                                          },
                                          {
                                              node: "Label",
                                              fields: {
                                                text: "Fancy", 
                                                horizAlign: "center", 
                                                width: 300, 
                                                translation: [0, 180]
                                              }
                                          }
                                      ]
                                  }
                            })
                            
                            m.top.getScene().dialog = m.dialog
                        

The code snippet above produces the following Dialog content:

buttons

ARRAY OPTIONAL

Allows to set up the buttons of the Dialog.

Since Dialog extends a StandardDialog, its buttons selection and focus events can be accessed through the buttonSelected and buttonFocused fields.

Possible values:

An Array where each item is mapped into a StdDlgButton. Any combination of the following items is supported:

• STRING

  Adds a StdDlgButton node with its text field set to the text provided.

• An Associative Array containing any of the StdDlgSideCardArea fields plus the following custom properties:

  • ASSOCIATIVE ARRAY

    Allows for some extra StdDlgButton customization options. The following properties are supported:

    • ASSOCIATIVE ARRAY

      An Associative Array object specifying the name of a Node and its fields. The following properties are required:

      • text STRING OPTIONAL

        Specifies the button text.

      • disabled BOOLEAN OPTIONAL

        Specifies if the button should be disabled. A disabled button cannot be focused or selected. If not provided, the default value is false.

      • align STRING OPTIONAL

        Specifies the button text horizontal alignment. The following values are supported:

        • left DEFAULT

          right

          center

      • closeDialog BOOLEAN OPTIONAL

        Specifies if this button should close the Dialog when selected. If not provided, the default value is false.

Code Sinippet

                        m.dialog = createObject("roSGNode", "bcLib:Dialog")

                            m.dialog.setFields({
                              titleConfig: {
                                primaryTitle: "My Pretty Dialog"
                              },
                              buttons: [
                                "Pretty",
                                {
                                    text: "Test",
                                    disabled: false,
                                    align: "center",
                                    closeDialog: true
                                },
                                {
                                    text: "Dialog",
                                    disabled: true,
                                    align: "right",
                                }
                              ]
                            })
                            
                            m.top.getScene().dialog = m.dialog
                        

The code snippet above produces the following Dialog content: