Options
All
  • Public
  • Public/Protected
  • All
Menu

Interface PlayerAPI

Bitmovin Player instance members.

Hierarchy

  • PlayerAPI

Index

Properties

ads

The advertising API namespace.

buffer

The buffer API namespace.

drm

drm: DrmAPI

The DRM API namespace.

exports

exports: PlayerExports

Exports from the player core as a convenience fallback for non-modular code. It is recommended to use ES6 imports instead.

Usage:

import { Player } from 'bitmovin-player';
const player = new Player(...);
player.on(player.exports.Event.Loaded, () => ...);

Recommended approach:

import { Player, Event } from 'bitmovin-player';
const player = new Player(...);
player.on(Event.Loaded, () => ...);
deprecated

It is recommended to use ES6 imports instead

lowlatency

lowlatency: LowLatencyAPI

The low latency API namespace.

manifest

The manifest API namespace.

subtitles

The subtitles API namespace.

version

version: string

The version number of the player.

vr

The VR API namespace.

Methods

addMetadata

  • addMetadata(metadataType: CAST, metadata: any): boolean
  • Sends custom metadata to a remote receiver app (e.g. Chromecast).

    since

    v4.0

    Parameters

    • metadataType: CAST

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

    • metadata: any

      The custom data to send to the receiver.

    Returns boolean

    True if it was successful.

castStop

  • castStop(): void
  • Stops a running Cast session (i.e. isCasting returns true). Has no effect if isCasting returns false.

    since

    v4.0

    Returns void

castVideo

  • castVideo(): void
  • Initiates casting the current video to a Cast-compatible device. The user has to choose the target device.

    since

    v4.0

    Returns void

clearQueryParameters

  • clearQueryParameters(): void

destroy

  • destroy(): Promise<void>
  • Unloads the player and removes all inserted HTML elements and event handlers.

    since

    v8.0

    Returns Promise<void>

    Promise resolves when the player has cleaned up all its event handlers & resources

getAudio

  • Returns the currently used audio track.

    since

    v4.0

    Returns AudioTrack

getAudioBufferLength

  • getAudioBufferLength(): number | null
  • Returns the seconds of already buffered audio data or null if no audio source is loaded.

    deprecated

    Use PlayerBufferAPI.getLevel instead.

    Returns number | null

getAudioQuality

getAvailableAudio

  • Returns an array of all available audio tracks.

    since

    v4.0

    Returns AudioTrack[]

getAvailableAudioQualities

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

    since

    v4.0

    Returns AudioQuality[]

getAvailableSegments

  • Returns infos for segments that can be requested by the player

    since

    v7.2

    Returns SegmentMap

getAvailableVideoQualities

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

    since

    v4.0

    Returns VideoQuality[]

getBufferedRanges

  • Returns the currently buffered time ranges of the video element.

    since

    v6.1

    Returns TimeRange[]

getConfig

  • getConfig(mergedConfig?: undefined | false | true): PlayerConfig
  • Returns the config object of the current player instance.

    since

    v4.0

    Parameters

    • Optional mergedConfig: undefined | false | true

      true to return the config expanded with all default values, false to return the user config passed to the player's constructor.

    Returns PlayerConfig

    The current user or merged player config.

getContainer

  • getContainer(): HTMLElement
  • Returns the html element that the player is embedded in, which has been provided in the player constructor.

    since

    v8.0

    Returns HTMLElement

getCurrentTime

  • getCurrentTime(mode?: TimeMode): number
  • Returns the current playback time in seconds of the video.

    since

    v4.0

    Parameters

    • Optional mode: TimeMode

      The mode to decide if the returned time should be absolute or relative, see TimeMode. Default mode is absolute.

    Returns number

getDownloadedAudioData

getDownloadedVideoData

getDroppedVideoFrames

  • getDroppedVideoFrames(): number
  • Returns the total number of dropped video frames since playback started.

    since

    v8.0

    Returns number

getDuration

  • getDuration(): number
  • Returns the total duration in seconds of the current video or {@code Infinity} if it’s a live stream.

    since

    v4.0

    Returns number

getManifest

  • getManifest(): string
  • Returns the used DASH or HLS manifest file.

    Previous player versions (v4.2-v7.0) returned an object for DASH and a string for HLS, this has been corrected in v7.1.

    since

    v7.1

    Returns string

getMaxTimeShift

  • getMaxTimeShift(): number
  • Returns the limit in seconds for time shift. Is either negative or 0 and applicable to live streams only.

    since

    v4.0

    Returns number

getPlaybackAudioData

  • Returns data about the currently playing audio segment.

    since

    v4.0

    Returns AudioQuality

getPlaybackSpeed

  • getPlaybackSpeed(): number
  • 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. Values less or equal zero are ignored.

    since

    v4.0

    Returns number

getPlaybackVideoData

  • Returns data about the currently playing video segment.

    since

    v4.0

    Returns VideoQuality

getPlayerType

  • Returns the currently used rendering mode. See PlayerType for details of the valid values.

    since

    v4.0

    Returns PlayerType

getSeekableRange

  • Returns the time range that is currently valid for seeking.

    since

    v7.1

    Returns TimeRange

getSnapshot

  • getSnapshot(type?: undefined | string, quality?: undefined | number): Snapshot
  • Creates a snapshot of the current video frame. Snapshots cannot be taken from DRM protected content.

    since

    v4.0

    Parameters

    • Optional type: undefined | string

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

    • Optional quality: undefined | number

      A number between 0 and 1 indicating the image quality.

    Returns Snapshot

getSource

  • Gets the source that was loaded via a successfully finished load call or null if no source is loaded or a load is in progress.

    Returns SourceConfig | null

    the loaded source or null if no source is loaded

getStreamType

  • Returns the currently used streaming technology. See StreamType for details of the valid values.

    since

    v4.0

    Returns StreamType

getSupportedDRM

  • getSupportedDRM(): Promise<string[]>
  • Tests and retrieves a list of all supported DRM systems in the current user agent.

    since

    v4.1

    Returns Promise<string[]>

    A Promise that resolves to an array of strings with the supported DRM systems after fulfillment. Should never be rejected.

getSupportedTech

  • Returns an array of objects denoting a player and streaming technology combination. By default, this returns the combinations supported on the current platform (SupportedTechnologyMode.Platform), ordered by descending priority which will be used to play a stream.

    since

    v4.0

    Parameters

    Returns Technology[]

getThumbnail

  • Returns a thumbnail image for a certain time or null if there is no thumbnail available. Requires a configured thumbnails track in SourceConfig.thumbnailTrack.

    since

    v8.0

    Parameters

    • time: number

      the media time for which the thumbnail should be returned

    Returns Thumbnail

    A thumbnail if a thumbnails track is configured and a thumbnail exists for the specified time, else null

getTimeShift

  • getTimeShift(): number
  • Returns the current time shift offset to the live edge in seconds. Only applicable to live streams.

    since

    v4.0

    Returns number

getTotalStalledTime

  • getTotalStalledTime(): number
  • Returns the stalled time in seconds since playback started.

    since

    v4.0

    Returns number

getVideoBufferLength

  • getVideoBufferLength(): number | null
  • Returns the seconds of already buffered video data or null if no video source is loaded.

    deprecated

    Use PlayerBufferAPI.getLevel instead.

    Returns number | null

getVideoElement

  • getVideoElement(): HTMLVideoElement
  • Returns the used HTML5 video element.

    Returns HTMLVideoElement

    The HTML5 video element which is used by the player

getVideoQuality

  • Returns the currently selected video quality, if the user manually selected one. In this case it returns one of the elements of getAvailableVideoQualities.

    In case the user did not select a video quality it returns auto.

    since

    v7.3.1

    Returns VideoQuality

getViewMode

  • Gets the active ViewMode.

    since

    v8.0

    Returns ViewMode

    the view mode that is currently active

getVolume

  • getVolume(): number
  • Returns the player’s volume between 0 (silent) and 100 (max volume).

    since

    v4.0

    Returns number

hasEnded

  • hasEnded(): boolean
  • Returns true if the video has ended.

    since

    v4.0

    Returns boolean

isAirplayActive

  • isAirplayActive(): boolean
  • Checks if Apple Airplay is enabled.

    since

    v7.8.4

    Returns boolean

isAirplayAvailable

  • isAirplayAvailable(): boolean
  • Checks if Apple AirPlay support is available.

    since

    v7.1

    Returns boolean

isCastAvailable

  • isCastAvailable(): boolean
  • 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 PlayerEvent.CastAvailable event has fired.

    since

    v5.2

    Returns boolean

isCasting

  • isCasting(): boolean
  • 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 boolean

isDRMSupported

  • isDRMSupported(drmSystem: string): Promise<string>
  • Checks if a DRM system is supported in the current user agent.

    since

    v4.1

    Parameters

    • drmSystem: string

      A KeySystem string to test against

    Returns Promise<string>

    Resolves with the DRM system string if it is supported, or rejects with an error message if not

isLive

  • isLive(): boolean
  • Return true if the displayed video is a live stream.

    since

    v4.0

    Returns boolean

isMuted

  • isMuted(): boolean
  • Returns true if the player has been muted.

    since

    v4.0

    Returns boolean

isPaused

  • isPaused(): boolean
  • Returns true if the player has started playback but is currently paused.

    since

    v4.0

    Returns boolean

isPlaying

  • isPlaying(): boolean
  • Returns true if the player is currently playing, i.e. has started and is not paused.

    since

    v4.0

    Returns boolean

isStalled

  • isStalled(): boolean
  • Returns true if the player is currently stalling due to an empty buffer.

    since

    v4.0

    Returns boolean

isViewModeAvailable

  • isViewModeAvailable(viewMode: ViewMode): boolean
  • Tests if a particular ViewMode is available for selection with setViewMode.

    since

    v8.0

    Parameters

    • viewMode: ViewMode

      the view mode to test

    Returns boolean

    true if the tested view mode is available, else false

load

  • load(source: SourceConfig, forceTechnology?: undefined | string, disableSeeking?: undefined | false | true): Promise<void>
  • Sets a new video source and returns a promise which resolves to the player.

    since

    v4.0

    Parameters

    • source: SourceConfig

      The source the player should load.

    • Optional forceTechnology: undefined | string

      Forces the player to use the specified playback and streaming technology. The specified technologies have to be separated by a period (e.g. 'html5.hls'). A list of valid combinations can retrieved by calling getSupportedTech.

    • Optional disableSeeking: undefined | false | true

      If set, seeking will be disabled

    Returns Promise<void>

mute

  • mute(issuer?: undefined | string): void
  • Mutes the player if an audio track is available. Has no effect if the player is already muted.

    since

    v4.0

    Parameters

    • Optional issuer: undefined | string

      The issuer of the API call that will be passed to events triggered by this call

    Returns void

off

  • Removes a handler for a player event. This method was called removeEventHandler in previous player versions.

    since

    v7.8

    Parameters

    Returns void

on

  • Subscribes an event handler to a player event. This method was called addEventHandler in previous player versions.

    since

    v7.8

    Parameters

    • eventType: PlayerEvent

      The type of event to subscribe to.

    • callback: PlayerEventCallback

      The event callback handler that will be called when the event fires.

    Returns void

pause

  • pause(issuer?: undefined | string): void
  • Pauses the video if it is playing. Has no effect if the player is already paused.

    since

    v4.0

    Parameters

    • Optional issuer: undefined | string

      The issuer of the API call that will be passed to events triggered by this call

    Returns void

play

  • play(issuer?: undefined | string): Promise<void>
  • Starts playback or resumes after being paused. No need to call it if the player is setup with autoplay attribute (PlaybackConfig.autoplay). Has no effect if the player is already playing.

    since

    v4.0

    Parameters

    • Optional issuer: undefined | string

      The issuer of the API call that will be passed to events triggered by this call

    Returns Promise<void>

    a Promise which resolves as soon as playback has actually started. This promise can reject if play is prohibited by the browser (a missing user interaction for example)

preload

  • preload(): void
  • Starts preloading the content of the currently loaded source.

    since

    v6.1

    Returns void

seek

  • seek(time: number, issuer?: undefined | string): boolean
  • 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.

    since

    v4.0

    Parameters

    • time: number

      The time to seek to

    • Optional issuer: undefined | string

      The issuer of the API call that will be passed to events triggered by this call

    Returns boolean

setAudio

  • setAudio(trackID: string): void
  • Sets the audio track to the ID specified by trackID. Available tracks can be retrieved with getAvailableAudio.

    since

    v4.0

    Parameters

    • trackID: string

      The ID of the audio track to activate

    Returns void

setAudioQuality

  • setAudioQuality(audioQualityID: string): void
  • 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.

    since

    v4.0

    Parameters

    • audioQualityID: string

      The ID of the desired audio quality or 'auto' for dynamic switching

    Returns void

setAuthentication

  • setAuthentication(customData: any): void
  • Sets authentication data which is sent along with the licensing call. Can be used to add more information for a 3rd party licensing backend. The data be any type or object as needed by the 3rd party licensing backend.

    since

    v4.2

    Parameters

    • customData: any

      Data which should be sent with the licensing call

    Returns void

setLogLevel

  • Sets the level of player log outputs.

    since

    v6.1

    Parameters

    • level: LogLevel

      Log level, allowed values are "debug", "log", "warn", "error" and "off"

    Returns void

setPlaybackSpeed

  • setPlaybackSpeed(speed: number): void
  • [HTML5 only] Sets the playback speed of the player. Fast forward as well as slow motion is supported. Slow motion is used by values between 0 and 1, fast forward by values greater than 1.

    see

    getPlaybackSpeed

    since

    v4.0

    Parameters

    • speed: number

      A playback speed factor greater than 0

    Returns void

setPosterImage

  • setPosterImage(url: string, keepPersistent: boolean): void
  • Sets a poster image. Will be displayed immediately, even if a video stream is playing.

    since

    v4.3

    Parameters

    • url: string

      The URL to the poster image

    • keepPersistent: boolean

      Flag to set the poster image persistent so it is also displayed during playback (useful for audio-only playback)

    Returns void

setQueryParameters

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

    since

    v4.1

    Parameters

    • queryParameters: QueryParameters

      The list of query parameter key/value pairs

    Returns void

setVideoElement

  • setVideoElement(videoElement: HTMLElement): void
  • Passes an HTML video element to the player, which should be used in case of Html5 or Native playback. Needs to be called before load.

    since

    v5.1

    Parameters

    • videoElement: HTMLElement

      The HTML video element to use

    Returns void

setVideoQuality

  • setVideoQuality(videoQualityID: string): void
  • 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.

    since

    v4.0

    Parameters

    • videoQualityID: string

      ID defined in the MPD or 'auto'

    Returns void

setViewMode

  • Sets the player to a particular ViewMode. Will only work if the selected view mode is available and isViewModeAvailable returns true, else this call will be ignored. If successful, a PlayerEvent.ViewModeChanged will be fired.

    since

    v8.0

    Parameters

    • viewMode: ViewMode

      the view mode to switch the player into

    • Optional options: ViewModeOptions

      additional optional parameters for view modes

    Returns void

setVolume

  • setVolume(volume: number, issuer?: undefined | string): void
  • Sets the player’s volume in the range of 0 (silent) to 100 (max volume). Unmutes a muted player.

    since

    v4.0

    Parameters

    • volume: number

      The volume to set between 0 and 100

    • Optional issuer: undefined | string

      The issuer of the API call that will be passed to events triggered by this call

    Returns void

showAirplayTargetPicker

  • showAirplayTargetPicker(): void
  • Shows the airplay playback target picker.

    since

    v7.1

    Returns void

timeShift

  • timeShift(offset: number, issuer?: undefined | string): void
  • 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.

    since

    v4.0

    Parameters

    • offset: number

      The offset to timeshift to

    • Optional issuer: undefined | string

      The issuer of the API call that will be passed to events triggered by this call

    Returns void

unload

  • unload(): Promise<void>
  • Unloads the current video source.

    since

    v4.0

    Returns Promise<void>

unmute

  • unmute(issuer?: undefined | string): void
  • Unmutes the player if muted.

    since

    v4.0

    Parameters

    • Optional issuer: undefined | string

      The issuer of the API call that will be passed to events triggered by this call

    Returns void

Generated using TypeDoc