Player

Loads, controls and renders audio and video content represented through Sources. A player instance can be created via the Player() function and will idle until one or more Sources are loaded. Once load is called, the player starts a playback session and initiates necessary downloads to start playback of the loaded source(s).

In case multiple sources were loaded into the player, Source.isActive identifies which source is currently active in the playback session. Only one source can be active at any time and API calls on the player will act on that source. More information on how to manage multiple sources can be found on the PlaylistApi.

The player emits events during its lifecycle. See EventEmitter on how to subscribe to events. Events are divided into PlayerEvent and SourceEvent, depending on if they are specific to the player and playback session as a whole or a source. While SourceEvents are naturally emitted from a source, they are also emitted from the player for the active source. This allows for all event handling to be done through the player in case only a single source is loaded, enabling the same workflows as on v2 of the Bitmovin Player SDK, where it was not possible to load multiple sources and where each event was a PlayerEvent.

The player implements the RemoteControlApi, which offers the ability to connect to a cast-compatible device, allowing remote playback of the loaded sources.

By default, a player instance does not provide any UI components. To use the default Bitmovin Player Web UI, a player instance can be attached to a PlayerView. The PlayerView already comes with a Surface to render video into, a ViewGroup to display ads, the Bitmovin Player Web UI and handling for standard UI use-cases. If a custom UI is preferred, a Surface must be provided to the player via setSurface and a ViewGroup must be set via setAdViewGroup if advertising features are needed.

Types

Link copied to clipboard
object Companion

Properties

Link copied to clipboard
abstract val audio: AudioTrack?

The currently selected AudioTrack or null if there is none.

Link copied to clipboard
abstract val audioQuality: AudioQuality?

The currently selected AudioQuality.

Link copied to clipboard

A list of all available AudioTracks of the active source. SourceEvent.AudioTrackAdded signals when a new AudioTrack becomes available.

Link copied to clipboard

A list of the available AudioQualitys of the currently selected AudioTrack of the active source.

Link copied to clipboard

A list of all available SubtitleTracks of the active source and the "off" subtitle track.

Link copied to clipboard

A list of all available VideoQualitys of the active source.

Link copied to clipboard
abstract val buffer: BufferApi

The BufferApi for interactions regarding the buffer.

Link copied to clipboard
abstract val config: PlayerConfig

The player config.

Link copied to clipboard
abstract val currentTime: Double

The current playback time of the active source or ad in seconds.

Link copied to clipboard

The current video frame rate as frames per second.

Link copied to clipboard
abstract val droppedVideoFrames: Int

The total number of dropped frames since playback in the active playback session has started.

Link copied to clipboard
abstract val duration: Double

The duration of the active source in seconds if it's a VoD or Double.POSITIVE_INFINITY if it's a live stream. If isAd is true the duration of the current ad is returned.

Link copied to clipboard
abstract val isAd: Boolean

Returns true while an ad is being played back or when main content playback has been paused for ad playback.

Link copied to clipboard
abstract val isLive: Boolean

Whether the active and loaded source is a live stream.

Link copied to clipboard
abstract val isMuted: Boolean

Whether the player is muted.

Link copied to clipboard
abstract val isPaused: Boolean

Whether the player is paused.

Link copied to clipboard
abstract val isPlaying: Boolean

Whether the player is currently playing (i.e. has started and is not paused).

Link copied to clipboard
abstract val isStalled: Boolean

Whether the player is currently stalled due to low buffer conditions.

Link copied to clipboard

The LowLatencyApi for interactions regarding low latency.

Link copied to clipboard
abstract val maxTimeShift: Double

The limit in seconds for time shifting. This value is either negative or 0 and it is always 0 if the active source is not a live stream or there is no active playback session.

Link copied to clipboard

The AudioQuality that is currently being played back or null if no audio is currently being played back. The returned quality always represents the actual current audio quality, while audioQuality represents what the player is working towards playing (e.g. a new quality can be selected even though it is not being played yet).

Link copied to clipboard
abstract var playbackSpeed: Float

The playback speed of the player. Slow motion can be achieved by setting the speed to values between 0 and 1, while fast forward is possible with values greater than 1. Values that are less than or equal to zero are ignored.

Link copied to clipboard

The offset between a playback time of the active source and its absolute representation. Adding this value to a playback time provided by the player (e.g. currentTime), will always result in an absolute timestamp.

Link copied to clipboard

The offset between a playback time of the active source and its relative representation. Adding this value to a playback time provided by the player (e.g. currentTime), will always result in a relative timestamp.

Link copied to clipboard

The VideoQuality that is currently being played back or null if no video is currently being played back. The returned quality always represents the actual current video quality, while videoQuality represents what the player is working towards playing (e.g. a new quality can be selected even though it is not being played yet).

Link copied to clipboard
abstract val playlist: PlaylistApi

The PlaylistApi for interactions regarding the playlist.

Link copied to clipboard
abstract val source: Source?

The currently active Source in the playback session or null if there is no active playback session.

Link copied to clipboard
abstract val subtitle: SubtitleTrack?

The currently selected SubtitleTrack or null if there is none.

Link copied to clipboard
abstract val timeShift: Double

The current time shift of the live stream in seconds. This value is always 0 if the active source is not a live stream or there is no active playback session.

Link copied to clipboard
abstract val videoQuality: VideoQuality?

The currently selected VideoQuality.

Link copied to clipboard
abstract var volume: Int

The player volume in the range of 0 to 100.

Link copied to clipboard
abstract val vr: VrApi

The VrApi for interacting with VR capabilities.

Functions

Link copied to clipboard
abstract fun destroy()

Destroys the player and stops the active playback session and most internal work. To release all allocated resources, all references to the player instance must be removed. The player instance must not be used after calling this method.

Link copied to clipboard
abstract fun getThumbnail(time: Double): Thumbnail?

Returns a Thumbnail for the provided playback time in the currently active source. Supported thumbnail formats are

Link copied to clipboard
abstract fun load(playlistConfig: PlaylistConfig)

Starts a new playback session consisting of PlaylistConfig.sources. The first source in the playlistConfig becomes active immediately.

abstract fun load(source: Source)

Starts a new playback session consisting of the source.

abstract fun load(sourceConfig: SourceConfig)

Starts a new playback session consisting of a Source based on the provided sourceConfig.

Link copied to clipboard
abstract fun mute()

Mutes the player.

Link copied to clipboard
abstract fun onPause()
Link copied to clipboard
abstract fun onResume()
Link copied to clipboard
abstract fun onStart()
Link copied to clipboard
abstract fun onStop()
Link copied to clipboard
abstract fun pause()

Pauses playback.

Link copied to clipboard
abstract fun play()

Starts or resumes playback.

Link copied to clipboard
abstract fun preload()

Starts preloading the content of the active Source. This is already done by default when a new playback session is started if not explicitly disabled via AdaptationConfig.preload.

Link copied to clipboard
abstract fun removeSubtitle(trackId: String)

Removes the existing SubtitleTrack with trackId from the list of available subtitle tracks. If the track is currently selected, it will be de-selected and then removed. If no SubtitleTrack with the given trackId exists, the call has no effect. Use setSubtitle to just disable but not remove an active SubtitleTrack.

Link copied to clipboard
abstract fun scheduleAd(adItem: AdItem)

Schedules the adItem for playback.

Link copied to clipboard
abstract fun seek(time: Double)

Seeks to the given playback time in seconds. Must not be greater than the duration of the active source.

Link copied to clipboard
abstract fun setAdViewGroup(adViewGroup: ViewGroup?)

Sets the ViewGroup in which the ad and the ad UI should be created.

Link copied to clipboard
abstract fun setAudio(trackId: String)

Enables the AudioTrack that corresponds to the trackId. A list of currently available AudioTracks can be retrieved via availableAudio.

Link copied to clipboard
abstract fun setAudioQuality(qualityId: String)

Sets a fixed AudioQuality, identified by the qualityId. A list of currently available AudioQualitys can be retrieved via availableAudioQualities. To reset to automatic quality selection, Quality.AUTO_ID can be passed in as the qualityId.

Link copied to clipboard
abstract fun setMaxSelectableVideoBitrate(bitrate: Int)

Sets the upper bitrate boundary for video qualities to bitrate. All qualities with a bitrate that is higher than this threshold will not be eligible for automatic quality selection, although they are still available for manual quality selection.

Link copied to clipboard
abstract fun setSubtitle(trackId: String?)

Enables the SubtitleTrack that corresponds to the trackId. A list of currently available SubtitleTracks can be retrieved via availableSubtitles. Providing null as the trackId disables subtitles.

Link copied to clipboard
abstract fun setSurface(surface: Surface?)

Sets the Surface onto which video will be rendered. The player tracks the life cycle of the surface automatically.

abstract fun setSurface(surfaceHolder: SurfaceHolder?)

Sets the SurfaceHolder that holds the Surface onto which video will be rendered. The player tracks the life cycle of the surface automatically.

Link copied to clipboard
abstract fun setVideoQuality(qualityId: String)

Sets a fixed VideoQuality identified by the qualityId. A list of currently available VideoQualitys can be retrieved via availableVideoQualities. To reset to automatic quality selection, Quality.AUTO_ID can be passed in as the qualityId.

Link copied to clipboard
abstract fun skipAd()

Skips the current ad. A successful skip is signaled via PlayerEvent.AdSkipped.

Link copied to clipboard
abstract fun timeShift(offset: Double)

Shifts the time to the given offset in seconds from the live edge. The resulting offset has to be within the timeShift window as specified by maxTimeShift (which is a negative value) and 0. When the provided offset is positive, it will be interpreted as a UNIX timestamp in seconds and converted to fit into the timeShift window. When the provided offset is negative, but lower than maxTimeShift, then it will be clamped to maxTimeShift. Has no effect for VoD.

Link copied to clipboard
abstract fun unload()

Unloads all Sources in the active playback session and stops the active playback session.

Link copied to clipboard
abstract fun unmute()

Unmutes the player.