Module: API

Methods


addEventHandler(eventType, callback)

Adds a handler for a player event.

Parameters:
Name Type Description
eventType String

The eventType to add a handler for.

callback function

The callback function.

Since:
  • v4.0
Returns:
  • The player object.
Type
Object

addMetadata(metadataType, metadata)

Sends custom metadata to the chromecast receiver app.

Parameters:
Name Type Description
metadataType String

The type of the metadata. Currently only "CAST" is supported.

metadata Object

Custom data.

Since:
  • v4.0

addSubtitle(url, subtitleTrackID, kind, lang [, label])

Adds a new external subtitle file. The subtitle/caption track is only added to the available tracks, but is not set active. Use setSubtitle(trackID) to active it.

Parameters:
Name Type Argument Description
url String

specifies the URL to load the file from.

subtitleTrackID String

Specifies a unique ID for the subtitle track. If the ID already exists, the existing subtitle/caption track is overwritten with the new one.

kind String

Should be either “caption” or “subtitle”. Tracks with other values are ignored.

lang String

Specifies the language of the new subtitle/caption track.

label String <optional>

Specifies the text used to display the new track in the player’s settings window.

Since:
  • v4.0
Returns:
  • The player object.
Type
Object

castStop()

Stops casting the current video if it is casting at the moment (i.e. isCasting() returns true). Has no effect if isCasting() returns false.

Since:
  • v4.0
Returns:
  • The player object.
Type
Object

castVideo()

Initiates casting the current video to a cast-compatible device. The user has to choose to which device it should be sent.

Since:
  • v4.0
Returns:
  • The player object.
Type
Object

castVideo()

Initiates casting the current video to a cast-compatible device. The user has to choose to which device it should be sent.

Since:
  • v4.0
Returns:
  • The player object.
Type
Object

clearQueryParameters()

Removes all existing query parameters as specified in setQueryParameters or conf.tweaks.query_parameters.

Since:
  • v4.0
Returns:
  • The player object.
Type
Object

destroy()

Unloads the player, removes all inserted HTML elements and event handlers.

Since:
  • v4.0

enterFullscreen()

The player enters fullscreen mode. Has no effect if already in fullscreen.

Since:
  • v4.0

exitFullscreen()

The player exits fullscreen mode. Has no effect if not in fullscreen.

Since:
  • v4.0

getAudioBufferLength()

Returns the seconds of already buffered audio data.

Since:
  • v4.0
Returns:
  • The seconds of already buffered audio data.
Type
Number

getAvailableAudio()

Returns an array containing objects of all available audio tracks.

Since:
  • v4.0
Returns:
  • The array containing objects of all available audio tracks.
Type
Array.<AudioTrack>

getAvailableAudioQualities()

Returns an array containing all available audio qualities the player can adapt between.

Since:
  • v4.0
Returns:
  • The array containing all available audio qualities.
Type
Array.<AudioQuality>

getAvailableImpressionServers()

Returns a list of available impression servers.

Since:
  • v4.0
Returns:
  • The available impression servers.
Type
Array.<String>

getAvailableLicenseServers()

Returns a list of available license servers.

Since:
  • v4.0
Returns:
  • The available license servers.
Type
Array.<String>

getAvailableSubtitles()

Returns an array containing objects of all available subtitle/caption tracks.

Since:
  • v4.0
Returns:
  • The array containing objects of all available subtitle/caption tracks.
Type
Array.<Subtitle>

getAvailableVideoQualities()

Returns an array containing all available video qualities the player can adapt between.

Since:
  • v4.0
Returns:
  • The array containing all available video qualities.
Type
Array.<VideoQuality>

getConfig( [getMergedConfig])

Returns the config object of the current player instance.

Parameters:
Name Type Argument Description
getMergedConfig Boolean <optional>

Returns the merger player config instead of the user specified config, if set.

Since:
  • v4.0
Returns:
  • The current user or merged player config.
Type
Object

getCurrentTime()

Returns the current playback time in seconds of the video.

Since:
  • v4.0
Returns:
  • The current playback time in seconds.
Type
Number

getDownloadedAudioData()

Returns a JSON object with data about the last downloaded audio segment.

Since:
  • v4.0
Returns:
  • The object containing data about the last downloaded audio segment.
Type
DownloadedAudioData

getDownloadedVideoData()

Returns a JSON object with data about the last downloaded video segment.

Since:
  • v4.0
Returns:
  • The object containing data about the last downloaded video segment.
Type
DownloadedVideoData

getDroppedFrames()

Returns the number of dropped frames until now.

Since:
  • v4.0
Returns:
  • The number of dropped frames until now.
Type
Number

getDuration()

Returns the total duration in seconds of the current video or Infinity if it’s a live stream.

Since:
  • v4.0
Returns:
  • The total duration in seconds of the current video or Infinity.
Type
Number

getFigure()

Returns the figure element that the player is embedded in, if the player is set up, or null otherwise.

Since:
  • v4.0
Returns:
  • The figure element.
Type
Object

getManifest()

Returns the manifest file.

Since:
  • v4.2
Returns:
  • The manifest file.
Type
Object

getMaxTimeShift()

Returns the limit in seconds for time shift. Is either negative or 0. Is applicable for live streams only.

Since:
  • v4.0
Returns:
  • The limit in seconds for time shift.
Type
Number

getPlaybackAudioData()

Returns a JSON object with data about the currently played audio segment..

Since:
  • v4.0
Returns:
  • The object containing data about the currently played audio segment.
Type
AudioQuality

getPlaybackSpeed()

Returns the current playback speed of the player. 1 is the default playback speed, values between 0 and 1 refer to slow motion and values greater than 1 refer to fast forward.

Since:
  • v4.0
Returns:
  • The current playback speed.
Type
Number

getPlaybackVideoData()

Returns a JSON object with data about the currently played video segment.

Since:
  • v4.0
Returns:
  • The object containing data about the currently played video segment.
Type
VideoQuality

getPlayerType()

Returns the currently used rendering mode. Possible values are html5, flash, and native.

Since:
  • v4.0
Returns:
  • The current rendering mode.
Type
String

getSnapshot( [type] [, quality])

Creates a snapshot of the current video frame.

Parameters:
Name Type Argument Description
type String <optional>

The type of image snapshot to capture. Allowed values are "image/jpeg" and "image/webp".

quality Number <optional>

A Number between 0 and 1 indicating image quality.

Since:
  • v4.0
Returns:

snapshot - An object containing the snapshot.

Type
Snapshot

getStreamType()

Returns the currently used streaming technology. Possible values are currently dash, hls, and progressive.

Since:
  • v4.0
Returns:
  • The current streaming technology.
Type
String

getSubtitle()

Returns the currently used subtitle/caption track.

Since:
  • v4.0
Returns:
  • The currently used subtitle/caption track.
Type
Subtitle

getSupportedDRM()

Tests and retrieves a list of all supported DRM systems in the current user agent.

Since:
  • v4.1
Returns:
  • An array of strings with the supported DRM systems after fulfillment. Should never be rejected.
Type
Promise

getSupportedTech()

Returns an array of objects. An object determines a player and streaming technology combination supported on the current platform. The order in the array is the order which will be used to play a stream.

Since:
  • v4.0
Returns:
  • The array containing all supported technology combinations.
Type
Array.<SupportedTech>

getThumb(time)

Returns a thumbnail image.

Parameters:
Name Type Description
time Number

The time for which to get the thumbnail.

Since:
  • v4.0
Returns:
  • The thumbnail.
Type
Thumbnail

getTimeShift()

Returns the current time shift offset to the live edge in seconds. Is applicable for live streams only.

Since:
  • v4.0
Returns:
  • The current time shift offset to the live edge in seconds.
Type
Number

getTotalStalledTime()

Returns the stalled time in seconds since playback started.

Since:
  • v4.0
Returns:
  • The stalled time in seconds.
Type
Number

getVersion()

Returns the version number of the player. This can be used without calling setup (i.e. without setting up the player) first.

Since:
  • v4.0
Returns:
  • The version number of the player.
Type
String

getVideoBufferLength()

Returns the seconds of already buffered video data.

Since:
  • v4.0
Returns:
  • The seconds of already buffered video data.
Type
Number

getVolume()

Returns the player’s volume in the range zero to 100 including, respectively.

Since:
  • v4.0
Returns:
  • The player’s volume.
Type
Number

getVRMode()

Returns the current VR mode. If no VR source is played back, this returns "off".

Since:
  • v4.0
Returns:
  • The current VR mode.
Type
String

hasEnded()

Returns true if the video has ended.

Since:
  • v4.0
Returns:
  • True if the video has ended.
Type
Boolean

isAd()

Returns true when an ad is played back, false otherwise.

Since:
  • v4.0
Returns:
  • True if an ad is played back.
Type
boolean

isCastAvailable()

Returns true if casting to another device (such as a ChromeCast) is available, otherwise false. Please note that this function only returns true after the onCastAvailable event has fired.

Since:
  • v5.2
Returns:
  • True if casting to another device is available.
Type
Boolean

isCasting()

Returns true if the video is currently casted to a device and not played in the browser, or false if the video is played locally.

Since:
  • v4.0
Returns:
  • True if the video is currently casted to a device.
Type
Boolean

isDRMSupported(drmSystem)

Checks if a DRM system is supported in the current user agent.

Parameters:
Name Type Description
drmSystem String

A KeySystem string to test against

Since:
  • v4.1
Returns:
  • Resolves with the DRM system string if it is supported, or rejects with an error message if not.
Type
Promise

isFullscreen()

Returns true if the player is currently in fullscreen mode.

Since:
  • v4.0
Returns:
  • True if the player is in fullscreen.
Type
Boolean

isLive()

Return true if the displayed video is a live stream.

Since:
  • v4.0
Returns:
  • True if the displayed video is a live stream.
Type
Boolean

isMuted()

Returns true if the player has been muted.

Since:
  • v4.0
Returns:
  • True if the player is muted.
Type
Boolean

isPaused()

Returns true if the player has started playback but is currently paused.

Since:
  • v4.0
Returns:
  • True if the player is currently paused.
Type
Boolean

isPlaying()

Returns true if the player is currently playing, i.e. has started and is not paused.

Since:
  • v4.0
Returns:
  • True if the player is currently playing.
Type
Boolean

isReady()

Returns true if the player has finished initialization and is ready to use and to handle other API calls.

Since:
  • v4.0
Returns:
  • True if the player has finished initialization.
Type
Boolean

isSetup()

Returns true if the setup call has already been successfully called.

Since:
  • v4.0
Returns:
  • True if the setup call has been successfully called.
Type
Boolean

isStalled()

Returns true if the player is currently stalling due to an empty buffer.

Since:
  • v4.0
Returns:
  • True if the player is stalling.
Type
Boolean

load(source [, forceTechnology] [, disableSeeking])

Sets a new video source.

Parameters:
Name Type Argument Description
source Object

A source object, as specified in Player Configuration.

forceTechnology String <optional>

Forces the player to use the specified playback and streaming technology.

disableSeeking Boolean <optional>

If set, seeking will be disabled.

Since:
  • v4.0

mute()

Mutes the player if an audio track is available. Has no effect if the player is already muted.

Since:
  • v4.0
Returns:
  • The player object.
Type
Object

pause()

Pauses the video if it is playing. Has no effect if the player is already paused.

Since:
  • v4.0
Returns:
  • The player object.
Type
Object

play()

Starts playback or resumes after being paused. No need to call it if the player is setup with autoplay attribute (see player configuration documentation for more details). Has no effect if the player is already playing.

Since:
  • v4.0
Returns:
  • The player object.
Type
Object

removeEventHandler(eventType, callback)

Removes a handler for a player event.

Parameters:
Name Type Description
eventType String

The eventType to add a handler for.

callback function

The callback function.

Since:
  • v4.0
Returns:
  • The player object.
Type
Object

removeSubtitle(subtitleTrackID)

Removes the existing subtitle/caption track with the track ID specified by trackID. If the track is currently active, it will be deactivated and then removed. If no track with the given ID exists, the call will be ignored. The subtitle/caption track is removed from the available tracks, use setSubtitle(null) to disable an active subtitle/caption track.

Parameters:
Name Type Description
subtitleTrackID String

The ID of the subtitle to remove.

Since:
  • v4.0
Returns:
  • The player object.
Type
Object

scheduleAd(adManifestUrl, adType [, timeOffset] [, persistent] [, adMessage] [, skipMessage] [, style] [, skin])

Schedules an ad for playback

Parameters:
Name Type Argument Description
adManifestUrl String

URL to the ad manifest.

adType String

Always 'vast' (for now).

timeOffset * <optional>

The offset for the ad, may be 'pre', 'post', seconds, percent, or a string in the format hh:mm:ss

persistent Boolean <optional>

[new in v5.1] If set, the ad will be rescheduled automatically when a new source is loaded.

adMessage String <optional>

[new in v5.1] The message that is displayed to the user instead of the progress bar with the placeholder 'xx', which is replaced by the remaining ad duration.

skipMessage SkipMessage <optional>

[new in v5.1] The message that is displayed on the "skip ad" button.

style Object <optional>

[new in v5.1] A full styling object that is applied only during ad playback. Supports all styling options but the player sizing.

skin Object | JSON <optional>

[new in v5.1] A skin that is applied only during ad playback.

Since:
  • v4.2

seek(time)

Seeks to the given playback time specified by the parameter time in seconds. Must not be greater than the total duration of the video. Has no effect when watching a live stream as seeking is not possible.

Parameters:
Name Type Description
time Number

The time to seek to.

Since:
  • v4.0
Returns:
  • True if seeking is possible.
Type
Boolean

setAudio(trackID)

Sets the audio track to the ID specified by trackID. A list can be retrieved by calling getAvailableAudio().

Parameters:
Name Type Description
trackID String

The id of the audio track.

Since:
  • v4.0
Returns:
  • The player object.
Type
Object

setAudioQuality(audioQualityID)

Manually sets the audio stream to a fixed quality, identified by id. Has to be an ID defined in the MPD or the keyword auto. Auto resets to dynamic switching. A list with valid IDs can be retrieved by calling getAvailableAudioQualities().

Parameters:
Name Type Description
audioQualityID String

The ID defined in the MPD or the keyword auto.

Since:
  • v4.0
Returns:
  • The player object.
Type
Object

setAuthentication(customData)

Sets authentication data which is sent along with the licensing call. Can be used to add more information for a 3rd party licensing backend.

Parameters:
Name Type Description
customData *

Data which should be sent with the licensing call. Can be any type or object, as needed by a 3rd party licensing backend.

Since:
  • v4.2

setLastSegment(lastSegmentNum)

Sets the number of the last segment that the player is allowed to request. Only working with Segment Template manifests.

Parameters:
Name Type Description
lastSegmentNum Number

Number of the last segment.

Since:
  • v4.0
Returns:
  • The player object.
Type
Object

setPlaybackSpeed(speed)

[HTML5 only] Sets the playback speed of the player. Fast forward as well as slow motion is supported.

Parameters:
Name Type Description
speed Number

The desired playback speed. Slow motion is used by values between 0 and 1, fast forward by values greater than 1.

Since:
  • v4.0

setPosterImage(url, keepPersistent)

Sets a poster image. Will be displayed immediately, even if a video stream is playing.

Parameters:
Name Type Description
url String

The URL to the poster image

keepPersistent Boolean

Flag to set the poster image persistent so it is also displayed during playback.

Since:
  • v4.3

setQueryParameters(queryParameters)

Adds GET parameters to all request URLs (e.g. manifest, media segments, subtitle files, …). The queryParameters should be an object with key value pairs, where the keys are used as parameter name and the values as parameter values.

Parameters:
Name Type Description
queryParameters Object

The query parameters to set.

Since:
  • v4.1
Returns:
  • The player object.
Type
Object

setSkin(param)

Applies a new skin during run-time. See the https://bitmovin.com/tutorials/html5-player-skin-tutorial/ in the player configuration for more details about the parameter.

Parameters:
Name Type Description
param String | Object

Either the URL to a skin JSON file or a skin object.

Since:
  • v4.0
Returns:
  • A promise that resolves once the skin was successfully loaded.
Type
Promise

setSubtitle(trackID)

Sets the subtitle track to the ID specified by trackID. A list can be retrieved by calling getAvailableSubtitles(). Using null as ID disables subtitles.

Parameters:
Name Type Description
trackID String

The id of the subtitle track.

Since:
  • v4.0
Returns:
  • The player object.
Type
Object

setup(userConfig [, forceTechnology])

Sets up a new player instance with the given configuration, as specified in player configuration documentation.

Parameters:
Name Type Argument Description
userConfig Object

The user config.

forceTechnology String <optional>

Forces the player to use the specified playback and streaming technology.

Since:
  • v4.0

setVideoElement(videoElement)

Passes an HTML video element to the player, which should be used in case of non-Flash playback. Needs to be called before the setup(...) Has no effect if the Flash fallback is selected.

Parameters:
Name Type Description
videoElement Object

The video element.

Since:
  • v5.1

setVideoQuality(videoQualityID)

Manually sets the video stream to a fixed quality, identified by id. Has to be an ID defined in the MPD or the keyword auto. Auto resets to dynamic switching. A list with valid IDs can be retrieved by calling getAvailableVideoQualities().

Parameters:
Name Type Description
videoQualityID String

ID defined in the MPD or the keyword auto.

Since:
  • v4.0
Returns:
  • The player object.
Type
Object

setVolume(volume)

Sets the player’s volume to the value specified by volume which is an integer in the range zero to 100 including, respectively. If the player is muted when calling this, the player is unmuted.

Parameters:
Name Type Description
volume Number

The volume to set.

Since:
  • v4.0
Returns:
  • The player object.
Type
Object

setVRMode(mode)

Sets the current VR mode of the player. Has no effect if no VR source is played back.

Parameters:
Name Type Description
mode String

The VR mode the enter. Allowed values are "off", "2d", "3d", "stereo-2d" and "stereo-3d". [new in v5.2] Startup modes also accessible via the bitdash.VR.STARTUP_MODE.OFF, bitdash.VR.STARTUP_MODE.MONO_2D, bitdash.VR.STARTUP_MODE.MONO_3D, bitdash.VR.STARTUP_MODE.STEREO_2D and bitdash.VR.STARTUP_MODE.STEREO_3D constants.

Since:
  • v4.2

skipAd()

Skips the current ad. Has no effect if ad is not skippable or if no ad is played back.

Since:
  • v4.0

timeShift(offset)

Shifts the time to the given offset in seconds from the live edge. Has to be within getMaxTimeShift (which is a negative value) and 0. Only works in live streams. [new in v4.3]: The offset can be positive and is then interpreted as a UNIX timestamp in seconds. The value has to be within the timeShift window, as specified by getMaxTimeShift.

Parameters:
Name Type Description
offset Number

The amount to shift.

Since:
  • v4.0
Returns:
  • The player object.
Type
Object

unload()

Unloads the current video source.

Since:
  • v4.0
Returns:
  • The player object.
Type
Object

unmute()

The player will unmute if muted.

Since:
  • v4.0
Returns:
  • The player object.
Type
Object