Roku SDK Developer Guide

Load

Loads Brightcove Playback API video or playlist metadata into the bcPlayer asynchronously. 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 triggers a bcPlayer.on.load event reporting on the success or failure of the load process.

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

  • prebuffer BOOLEAN OPTIONAL

    Specifies if it should start prebuffering the video stream indicated in the autoplay option.

    • false DEFAULT

      if autoplay is set (ie, >= 0), video playback will start when the loading process finishes

    • true

      if autoplay is set (ie, >= 0), video prebuffering will be initiated when the loading process finishes

  • position STRING OPTIONAL 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
                
                        ' 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 an observer 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 set of videos 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 INTEGER 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.

  • prebuffer BOOLEAN OPTIONAL

    Specifies if it should start prebuffering the video stream indicated in the autoplay option.

    • false DEFAULT

      if autoplay is set (ie, >= 0), video playback will start when the loading process finishes

    • true

      if autoplay is set (ie, >= 0), video prebuffering will be initiated when the loading process finishes

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

    • append

      Add the new content at the end of the current content. If the current content is not a playlist, a new playlist is created and both the current and new content are added to the playlist.

    • prepend

      Add the new content at the start of the current content. If the current content is not a playlist, a new playlist is created and both the current and new content are added to the 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, if configured to do so, 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.

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

  • 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

    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.

  • <custom-prop> DYNAMIC OPTIONAL

    It’s also possible to specify custom properties to be passed along to the response object. These are especially useful when the autoload option is disabled. On the other hand, if the autoload option is enabled, these properties are ignored.

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

 ' OR

 ' autoload disabled
 responseNode = m.bcPlayer.callFunc("getVideo", videoID, {
   params: {ad_config_id: adConfigID},
   autoload: false,
   myCustomOption: "hello world"
 })

 ' 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

 options = response.options 

 ' retrieve the custom properties from the response object
  myCustomOption = options.myCustomOption

 ' 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
 })

 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.

    • 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

    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

    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.

  • <custom-prop> DYNAMIC OPTIONAL

    It’s also possible to specify custom properties to be passed along to the response object. These are especially useful when the autoload option is disabled. On the other hand, if the autoload option is enabled, these properties are ignored.

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
                            })
                    
                            ' OR
                    
                            ' autoload disabled
                            responseNode = m.bcPlayer.callFunc("getVideos", "name:wildlife", {
                              params: {limit: 10, offset: 20},
                              autoload: false,
                              myCustomOption: "hello world"
                            })
                    
                            ' 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

                            options = response.options 
                            
                            ' retrieve the custom properties from the response object
                            myCustomOption = options.myCustomOption

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

    • 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

    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

    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.

  <custom-prop> DYNAMIC OPTIONAL

  It’s also possible to specify custom properties to be passed along to the response object. These are especially useful when the autoload option is disabled. On the other hand, if the autoload option is enabled, these properties are ignored.

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
                            })
                    
                            ' OR
                    
                            ' autoload disabled
                            responseNode = m.bcPlayer.callFunc("getPlaylist", playlistID, {
                              params: {limit: 10, offset: 20},
                              autoload: false,
                              myCustomOption: "hello world"
                            })
                    
                            ' 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

                            options = response.options

                            ' retrieve the custom properties from the response object
                            myCustomOption = options.myCustomOption
                    
                            ' 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 ' TBI feature
                            })
                    
                          end sub
                    
                        

getRelated

ASSOCIATIVE ARRAY

Retrieves a set of Brightcove videos that are related to the specified video id through Playback API.

Using the name and short description of the specified video id, 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

    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

    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.

  <custom-prop> DYNAMIC OPTIONAL

  It’s also possible to specify custom properties to be passed along to the response object. These are especially useful when the autoload option is disabled. On the other hand, if the autoload option is enabled, these properties are ignored.

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 
                            })
                    
                            ' OR
                    
                            ' autoload disabled
                            responseNode = m.bcPlayer.callFunc("getRelated", videoID, {
                              params: {limit: 10, offset: 20},
                              autoload: false,
                              myCustomOption: "hello world"
                            })
                    
                            ' 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
                                
                            options = response.options 

                            ' retrieve the custom properties from the response object
                            myCustomOption = options.myCustomOption
                    
                            ' 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
                        

close

Initiates the close action, which depending on the parameter provided, terminates/kills bcPlayer completely (hard close) or just stops and clears the current playback session (soft close). By default, if no parameter is provided, it executes a hard close.

The hard close is an asynchronous process, at the end of which it triggers a bcPlayer.on.closed event to confirm that the close process is complete.

Once the close action is called, the bcPlayer.on.close event is also triggered specifying the type of close action that was called (soft or hard).

The close process can also be triggered internally by the closeOnBack and closeOnFinished configurations, if configured to do so.

Be aware that a hard close completely kills the bcPlayer node instance and it’s not possible to access/use its functions afterwards.

Parameters

• kill BOOLEAN OPTIONAL

  • true DEFAULT

    Triggers a hard close action, which terminates/kills the bcPlayer instance completely.

  • false

    Triggers a soft close action, which stops the current playback session and clears the content. The bcPlayer node remains on standby waiting for other commands.

Return value

VOID

Code Snippet

                        sub init()

   ...

   ' listen for the "close" event, in case some action needs to be taken when closing bcPlayer
   m.bcPlayer.on.observeField("close", "onClose")

   ' listen for the "closed" event, which is only triggered by a hard close
   m.bcPlayer.on.observeField("closed", "onClosed")

   ' trigger the close action
   m.bcPlayer.callFunc("close")

 end sub

 sub onClose(ev)

   data = ev.getData() ' data => {type: "soft" / "hard"}

   ' bcPlayer close action was triggered, 
   ' data.type specifies what type of close was requested

 end sub

 sub onClosed()

   ' bcPlayer was completely terminated by a hard close action. 
   ' If there's still any bcPlayer reference in the app or fields observers, these
   ' should be removed / unobserved at this point

   m.bcPlayer.on.unobserveField("close")
   m.bcPlayer.on.unobserveField("closed")
   m.bcPlayer = invalid

 end sub
                        

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 (StdTextItem)

    • 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 <p>Pretty</p> 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:

• A String Value STRING

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

• An Associative Array object ASSOCIATIVE ARRAY

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

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