The Player object contains APIs available for the Bitmovin Roku Player. In order to use Bitmovin Player we first need to download the Bitmovin Player component library
m.bitmovinPlayerLibrary = createObject("roSGNode", "ComponentLibrary")
m.bitmovinPlayerLibrary.id = "BitmovinPlayerLibrary"
m.bitmovinPlayerLibrary.uri = "BITMOVIN_PLAYER_LIBRARY_URL"
Adding the Bitmovin Player component library to the scene or a SceneGraph component will start the download of the library
m.top.appendChild(m.bitmovinPlayerLibrary)Once the loadStatus field of the Bitmovin Player component library changes to ready, we can use it to reference the Bitmovin Player component
m.bitmovinPlayer = createObject("roSGNode", "BitmovinPlayerLibrary:BitmovinPlayer")To receive events from the Bitmovin Player, we need to assign the observer to the specific field of the Bitmovin Player that we want to receive the events for
m.bitmovinPlayer.observeFieldScoped(m.bitmovinPlayer.bitmovinFields.IMPRESSION, "onImpression")In order to use the available Bitmovin Player's API functions, we need to utilize Roku's built-in callFunc() API. For example, the line below calls the PLAY function on Bitmovin Player
m.bitmovinPlayer.callFunc(m.bitmovinPlayer.bitmovinFunctions.PLAY, invalid)The Bitmovin Player API is not available anymore after the destroy event is triggered.
Always contains an associative array with the possible observable player fields (to be used with observeField)
Always contains an associative array with values for the possible API functions (to be called with callFunc)
Always contains an associative array with values for the possible states of the player
Indicates that the video is currently playing
Indicates that the video is currently stalling
Indicates that the video is currently paused
Indicates that the video is finished playing
Indicates that the player is currently stopped due to an error
The state of the player at the moment of component creation
Indicates that the player has been successfully setup with the default config or a passed in config
Indicates that the video is ready to be played, but is not currently playing
Signals that an ad break has finished
Information about the adBreak.
Signals that an ad break has started
Information about the adBreak.
Is fired when ad playback fails.
Is fired when the user interacts with an ad
Is fired when the playback of an ad has progressed over a quartile boundary
Is fired when the playback of an ad has been finished
Is fired when the playback of an ad has been started
Is fired when an ad has been skipped
Signals that the currently selected audio track has changed
Deprecated. Use timeChanged instead. Contains the current time of the video. Contains the time elapsed since playback has started in case of a live stream
Contains the most recent download
The time needed to finish the request
The type of the request
The size of the downloaded data
Indicates whether the request was successful (true) or failed (false)
The URL of the request
Contains an associative array with the fields code, name and message. Additionally the data field contains all the error fields from the native Roku video node.
Error code of the thrown error.
Contains all the error fields from the native Roku video node.
Error message containing details about the error.
Name of the error that has been thrown.
Contains the most recent received meta data from the video stream. By default `ID3` and `EMSG` are supported. By enabling the `nativeHlsParsingEnabled` flag in the player config `EXT-X-SCTE35` and `EXT-X-DATERANGE` will be fired as well.
Contains the result of the Demand API QueryAds() result. To trigger this event use the demandApiQueryAds API call.
Contains the result of the Demand API FetchAds() result. To trigger this event use the demandApiFetchAds API call.
Signals the intention to start/resume playback
Contains a string value equal to the current state of the player (such as play or pause)
Always contains the value of true. Will notify the user when seek has been set to true again, to indicate the start of seeking
Contains a float representing the seeked position in the video and notifies the user when the seek operation has finished
Signals that the source has been successfully loaded
Signals that the source has been successfully unloaded
Contains the intended offset to the live edge and notifies that a timeshift is being made.
Contains the actual offset after a timeshift. Notifies that a timeshift has been made.
Contains an associative array with the fields code and message
Contains the warning code.
Warning message containing details about the warning.
Signals that the player has been muted
Signals that the player has been unmuted
Is fired when the player instance is destroyed
Is fired when the downloaded video quality has been changed successfully
Previous quality or invalid if no quality was set before
New quality
Event type
Is fired when the downloaded audio quality has been changed successfully
Previous quality or invalid if no quality was set before
New quality
Event type
Is fired when the impression call was sent successfully
Contains the domain used for the impression request.
Contains the license key used for the impression request.
Contains the platform speficied for the impression request.
Contains the response of the impression request.
Is fired when a licensing call succeeded
Contains the response from the license request.
Contains the response code from the license request.
Contains the current time of the video. Contains the time elapsed since playback has started in case of a live stream
Current timestamp of the video.
Is fired when a new subtitles/captions track was added
Is fired when the current subtitles/captions track was changed
Fired for selected HLS tags when encountered while parsing the playlist.
Event type
The name of the parsed tag (e.g. "EXT-X-KEY")
An associative array containing data from the parsed tag. The keys represent the lowercase attributes within that tag.
Setup function to give configuration object to player.
Required config object.
Determines if videos should play immediately on load
Determines if videos should be initially muted
Determines if, on load, the video should immediately start to buffer
Minimum startup bitrate specified in kbps. Streaming will start with a variant equal to or greater than this value. If this value is not set or if it's set to zero, any minimum start bitrate will be ignored.
Maximum startup bitrate specified in kbps. Streaming will start with a variant less than or equal to this value. If this value is not set, it will default to 2500 kbps.
Bitmovin Player license key
Object containing data pertaining to a specific video source, alternatively, a configured ContentNode could be passed instead.
Title of video source
Url to dash video source
Url to hls video source
Url to smooth video source
Url to progressive video source. Default type is `mp4`. To use a different type pass a ProgressiveSourceConfig object.
Url to progressive video source
Type of progressive video source. Valid values can be found in the official Roku documentation.
Determines if asset is of VOD or LIVE type. If LIVE is not specifially set, VOD type will be used. Can be set to AUTO to automatically detect if the content is live or not (only works for HLS streams)
Array of subtitle tracks to side load
Url to subtitle track
Language for subtitle track
Object containing data relevant to DRM options
Object containing data specific to Widevine DRM
Object containing data specific to Playready DRM
An associative array containing the HTTP headers and values to be included in the HTTP request
Source config options
The position where the stream should be started, the number can be positive or negative depending on the used startOffsetTimelineReference
Timeline reference point to calculate startOffset from, default for live is "end" and for VOD it is "start"
The ad configuration used to schedule one or more ad breaks
Specifies if extended RAF (Roku advertising framework) debug output should be enabled or not. Default is false.
When enabled multiple ads within an ad break will be stitched together. Conversely, when In-Pod-Stitching (IPS) is disabled, each video plays individually and a few seconds are spent in a buffering screen between the ads. Default value is `false`.
Collection of ad breaks
Defines the url and type of the ad manifest
Defines the path to an ad manifest. If the tag is a VMAP manifest, the resulting ad breaks will be scheduled as described in the manifest
Specifies whether the ad tag is a VAST or VMAP tag
Unique identifier of the ad break. Used to be able to identify and discard the ad break dynamically
Defines when the ad break shall be started. Default is 'pre'.
Allowed Values are:
- 'pre': pre-roll ad
- 'post': post-roll ad
- fractional seconds: '10', '12.5' (mid-roll ad)
- percentage of the entire video duration: '25%', '50%' (mid-roll ad)
- timecode [hh:mm:ss.mmm]: '00:10:30.000', '01:00:00.000' (mid-roll ad)
IMA DAI configuration object
Object containing the properties of the asset
Determines if asset is VOD or LIVE. Default is VOD.
Required for on-demand streams. Identifier for the video content source.
Required for on-demand streams. The content source ID comes from the DFP Video Content Source found in the Google DFP (Ad Manager) UI.
Required for live streams. This is used to determine which stream should be played. The live stream request asset key is an identifier which can be found in the Google DFP (Ad Manager) UI.
Specifiies the format of the stream. Can either be DASH or HLS. Default is HLS.
Determines if playback should snap back to seeked over ads. Default is false.
Optional. These keys can be used to authenticate stream requests. DAI authentication keys must be set up in the Google DFP (Ad Manager) UI.
Optional custom metadata represented in string key-value pair
Title of video source
The description of the video source
The video source poster image url
Comma-delimited string. It must be present in order for ad measurements to be enabled
String representation of Boolean value to specify whether content is targeted towards children or not. It must be present in order for ad measurements to be enabled
Value representing content to allow potential ad targeting. It must be present in order for ad measurements to be enabled
String representation of Integer value representing total length of content (in seconds). It must be present in order for ad measurements to be enabled
Used to configure the adaptation logic of the corresponding source.
Minimum startup bitrate specified in kbps. Streaming will start with a variant equal to or greater than this value. If this value is not set or if it's set to zero, any minimum start bitrate will be ignored.
Maximum startup bitrate specified in kbps. Streaming will start with a variant less than or equal to this value. If this value is not set, it will default to 2500 kbps.
Determines if the default ui should be enabled
Thumbnail track
Object containing urls for sd, hd and fhd thumbnail track
Set the url to the standart definition thumbnail track
Set the url to the high definition thumbnail track
Set the url to the full high definition thumbnail track
If enabled, HLS playlists would be parsed and corresponding events carrying segment-specific metadata, e.g. #EXT-X-SCTE35 tag if present in the manifest, are going to be sent.
If enabled, image media playlist parsing will be disabled
Deprecated. Functionality is enabled by default. If enabled additional metadata from the timedMetadata2 field will be surfaced. Only certain streams contain the metadata sufaced by this field, usually streams with ads stitched in.
Enables the thumbnailTiles field to be set and updated in the case of live HLS and DASH streams, which contain thumbnails as the thumbnails become available. Default is false.
Valid HEX color code. Default value: #000000
Defines if the background is visible or not. Default value: true
Valid HEX color code. Default value: #FFCCCCCC
Default value: Your program will begin after this message
Defines if the bufferingMessage is visible or not. Default value: true
Valid HEX color code. Default value: #FFCCCCCC
Default value: Loading...
Defines if the progressBarMessage is visible or not. Default value: true
Valid HEX color code. Default value: #313131
Defines if the progressBarBackground is visible or not. Default value: true
Valid HEX color code. Default value: #19B3FF
Defines if the progressBarIndicator is visible or not. Default value: true
If not set or empty string, "posterImageUrl" value from source config metadata will be used. If "posterImageUrl" value is not set source config poster value will be used
Defines if the posterImage is visible or not. Default value: false
Valid HEX color code. Default value: #FFCCCCCC
If not set or empty string, "title" value from source config metadata will be used. If "title" value of metadata is not set source config title value will be used
Defines if the title is visible or not. Default value: false
Valid HEX color code. Default value: #FFCCCCCC
If not set or empty string, "description" value from source config metadata will be used. If "description" value of metadata is not set source config description will be used
Defines if the description is visible or not. Default value: false
Returns the config object of the current player instance.
invalid param, unused but due to nature, required to be passed in.
Returns the player version.
invalid param, unused but due to nature, required to be passed in.
Function called to play video by setting control on the video node to "play".
invalid param, unused but due to nature, required to be passed in.
Function called to replay the last couple of seconds of video by setting control on the video node to "replay".
invalid param, unused but due to nature, required to be passed in.
Function called to play video by setting control on the video node to "pause".
invalid param, unused but due to nature, required to be passed in.
Function called to play video by setting control on the video node to "prebuffer".
invalid param, unused but due to nature, required to be passed in.
Function called to seek to new time, in seconds, on the video node. Also, handles seeking state.
time to seek to in seconds.
Function called to mute current video.
invalid param, unused but due to nature, required to be passed in.
Function called to unmute current video.
invalid param, unused but due to nature, required to be passed in.
Deprecated. Use setCaptionMode instead.
Function called to set captions mode on the video node. This effects global settings.
ccModes: "On", "Off", "Instant Replay", "When Mute (Roku TV Only)"
String to set captions to.
Function called to set captions mode on the video node. This effects global settings.
ccModes: "On", "Off", "Instant Replay", "When Mute" (Roku TV Only)
String to set captions to.
Function to get current mute value.
invalid param, unused but due to nature, required to be passed in.
Function to get if player is currently playing
invalid param, unused but due to nature, required to be passed in.
Function to get if player is currently paused
invalid param, unused but due to nature, required to be passed in.
Function to get if player is currently buffering, referred to as "stalled" by Bitmovin API.
invalid param, unused but due to nature, required to be passed in.
Function to get the available subtitles on the current video.
invalid param, unused but due to nature, required to be passed in.
Function gets the current subtitle. If subtitleTrack has not been set by setSubtitle an empty string will be returned. If subtitleTrack has been set to an invalid value, an invalid will be returned.
invalid param, unused but due to nature, required to be passed in.
Function to set the subtitle track. trackID must be a valid ID in availableSubtitleTracks.
Track ID as defined in availableSubtitleTracks
Function to set the subtitle styles.
See https://developer.roku.com/docs/references/scenegraph/media-playback-nodes/video.md#closed-caption-fields for possible key names and values
The subtitle styles to be applied
Function to get the current subtitle styles.
See https://developer.roku.com/docs/references/scenegraph/media-playback-nodes/video.md#closed-caption-fields for possible key names and values
invalid param, unused but due to nature, required to be passed in.
Function to get the available audio on the current video.
invalid param, unused but due to nature, required to be passed in.
Function to get the current audio track being played. If there is no audio track and empty string is returned. If the audio track is set to an invalid value, and invalid is returned.
invalid param, unused but due to nature, required to be passed in.
Function to set audioTrack to the first available track with ID
ID of audio track you wish to switch to. Must exist in availableAudioTracks
Function to unload video and stop observing fields.
invalid param, unused but due to nature, required to be passed in.
Function to load a source object into the video node, set up player states, and show video on the scene.
Alternatively, a configured ContentNode could be passed instead.
Source object, formatted to conform to the Bitmovin API.
Title of video source
Url to dash video source
Url to hls video source
Url to smooth video source
Url to progressive video source. Default type is `mp4`. To use a different type pass a ProgressiveSourceConfig object.
Url to progressive video source
Type of progressive video source. Valid values can be found in the official Roku documentation.
Determines if asset is of VOD or LIVE type. If LIVE is not specifially set, VOD type will be used. Can be set to AUTO to automatically detect if the content is live or not (only works for HLS streams)
Array of subtitle tracks to side load
Url to subtitle track
Language for subtitle track
Object containing data relevant to DRM options
Object containing data specific to Widevine DRM
Object containing data specific to Playready DRM
An associative array containing the HTTP headers and values to be included in the HTTP request
Source config options
The position where the stream should be started, the number can be positive or negative depending on the used startOffsetTimelineReference
Timeline reference point to calculate startOffset from, default for live is "end" and for VOD it is "start"
The ad configuration used to schedule one or more ad breaks
Specifies if extended RAF (Roku advertising framework) debug output should be enabled or not. Default is false.
When enabled multiple ads within an ad break will be stitched together. Conversely, when In-Pod-Stitching (IPS) is disabled, each video plays individually and a few seconds are spent in a buffering screen between the ads. Default value is `false`.
Collection of ad breaks
Defines the url and type of the ad manifest
Defines the path to an ad manifest. If the tag is a VMAP manifest, the resulting ad breaks will be scheduled as described in the manifest
Specifies whether the ad tag is a VAST or VMAP tag
Unique identifier of the ad break. Used to be able to identify and discard the ad break dynamically
Defines when the ad break shall be started. Default is 'pre'.
Allowed Values are:
- 'pre': pre-roll ad
- 'post': post-roll ad
- fractional seconds: '10', '12.5' (mid-roll ad)
- percentage of the entire video duration: '25%', '50%' (mid-roll ad)
- timecode [hh:mm:ss.mmm]: '00:10:30.000', '01:00:00.000' (mid-roll ad)
IMA DAI configuration object
Object containing the properties of the asset
Determines if asset is VOD or LIVE. Default is VOD.
Required for on-demand streams. Identifier for the video content source.
Required for on-demand streams. The content source ID comes from the DFP Video Content Source found in the Google DFP (Ad Manager) UI.
Required for live streams. This is used to determine which stream should be played. The live stream request asset key is an identifier which can be found in the Google DFP (Ad Manager) UI.
Specifiies the format of the stream. Can either be DASH or HLS. Default is HLS.
Determines if playback should snap back to seeked over ads. Default is false.
Optional. These keys can be used to authenticate stream requests. DAI authentication keys must be set up in the Google DFP (Ad Manager) UI.
Optional custom metadata represented in string key-value pair
Title of video source
The description of the video source
The video source poster image url
Comma-delimited string. It must be present in order for ad measurements to be enabled
String representation of Boolean value to specify whether content is targeted towards children or not. It must be present in order for ad measurements to be enabled
Value representing content to allow potential ad targeting. It must be present in order for ad measurements to be enabled
String representation of Integer value representing total length of content (in seconds). It must be present in order for ad measurements to be enabled
Used to configure the adaptation logic of the corresponding source.
Minimum startup bitrate specified in kbps. Streaming will start with a variant equal to or greater than this value. If this value is not set or if it's set to zero, any minimum start bitrate will be ignored.
Maximum startup bitrate specified in kbps. Streaming will start with a variant less than or equal to this value. If this value is not set, it will default to 2500 kbps.
Returns the duration of the video node for a VOD. Returns -1 in case of a live stream
The duration of the video being played, specified in seconds. This becomes valid when playback begins and may change if the video is dynamic content, such as a live event.
invalid param, unused but due to nature, required to be passed in.
Function to shift the time to a given offset. Has to be within getMaxTimeShift() (which is a negative value) and 0. Only works with live streams and only after playback has started, otherwise it will result in a no-op.
offset
Returns the current time shift offset to the live edge in seconds. Only applicable to live streams.
invalid param, unused but due to nature, required to be passed in.
Returns the limit in seconds for time shift. Is either negative or 0 and applicable to live streams only.
invalid param, unused but due to nature, required to be passed in.
Return true if the displayed video is a live stream.
invalid param, unused but due to nature, required to be passed in.
Deprecated - use setHttpAgent instead. Function to set http header on the video node.
headers
Returns a thumbnail image for a certain time or invalid if there is no thumbnail available.
Requires a configured thumbnails track in SourceConfig.thumbnailTrack.
the media time in seconds for which the thumbnail should be returned
the maximum dimensions of the thumbnail
the maximum width of the thumbnail
the maximum height of the thumbnail
Schedules resulting ad break(s) of an ad config for playback.
The ad configuration used to schedule one or more ad breaks
Specifies if extended RAF (Roku advertising framework) debug output should be enabled or not. Default is false.
Collection of ad breaks
Defines the url and type of the ad manifest
Defines the path to an ad manifest. If the tag is a VMAP manifest, the resulting ad breaks will be scheduled as described in the manifest
Specifies whether the ad tag is a VAST or VMAP tag
Unique identifier of the ad break. Used to be able to identify and discard the ad break dynamically
Defines when the ad break shall be started. Default is 'pre'.
Allowed Values are:
- 'pre': pre-roll ad
- 'post': post-roll ad
- fractional seconds: '10', '12.5' (mid-roll ad)
- percentage of the entire video duration: '25%', '50%' (mid-roll ad)
- timecode [hh:mm:ss.mmm]: '00:10:30.000', '01:00:00.000' (mid-roll ad)
Returns all scheduled ad breaks.
invalid param, unused but due to nature, required to be passed in.
Returns the currently active ad break. If no ad is active returns invalid.
invalid param, unused but due to nature, required to be passed in.
Discards all scheduled ad breaks with the given ID.
The ID of the ad break which shall be removed from the scheduled ad breaks.
Is fired when the player instance is destroyed.
invalid param, unused but due to nature, required to be passed in.
Returns the current playback time of the video in seconds.
invalid param, unused but due to nature, required to be passed in.
Returns true while an ad is played back, false otherwise.
invalid param, unused but due to nature, required to be passed in.
Queries a list of ads based on the given criteria. Given criteria may consist of user, device and content values along with other values specified by the publisher. The resulting list of ads can be retrieved via the `demandApiQueryAdsResult` callback once available.
DemandApi configuration criteria, for more details about each parameter of the criteria object please refer to the Demand API documentation provided by Roku.
Calls the FetchAds function on the Roku Demand API, the result can be found on the field demandApiFetchAdsResults once the request has been made.
The list of ad creative URLs to be parsed and rendered. The list includes the ads selected from the set returned by the demandApiQueryAds method
Updates the roHttpAgent object on the video node.
Type "generic" applies the given roHttpAgent to all requests, while type "drm" only applies (and supersedes) for DRM related requests. Default is "generic".
Object that specifies which and what type of HttpAgent should be set.
The roHttpAgent to be set on the video node.
Determines the type of HTTP Agent. Can be either "generic" or "drm".
Error is unknown. Error can be thrown in cases where Bitmovin Player can’t recognise the error. The most common cause for this error is configuring dash, hls, progressive or smooth properties with the non-corresponding stream format like using dash stream for the hls property. For further troubleshooting please check the data property of the error event.
The license is not valid. The player license server did not grant playback for the given player key as specified in the player config. The most common cause for this error is an incorrect or non-existing player key was specified in the player config.
No valid source was provided. Common causes for this error is that source config object didn't contain dash, hls, progressive or smooth properties.
General playback error. The most common cause for this error is configuring dash, hls, progressive or smooth properties with the stream format not supported by the Roku platform.
Network error while downloading. There was an error in the HTTP response. This could mean malformated HTTP header or error code was returned. The most common causes for this error includes: Malformed URL of dash, hls, progressive or smooth properties and trying to playback the content with the two different instances of the player at the same time.
General DRM error. Error can be thrown in cases where DRM for the stream is not properly configured in the source config or if there are any issues with the DRM on the server side. Please verify that license and/or server certificate URLs are correct, and that the server certificate specified in the DRM config is valid, if one was specified. In order to get more information about the specific DRM error, please check the data property of the error event.
Generated using TypeDoc
Bitmovin-Player-Roku-SDK v1.73.0
Documentation for Bitmovin Player Roku SDK