Player
interface Player : EventEmitter<Event> , RemoteControlApi
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 com.bitmovin.player.PlayerView. The com.bitmovin.player.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 AdvertisingApi.setViewGroup if advertising features are needed.
A note on threading:
The Player instance must be created and accessed on the application's main thread.
Types
| Name | Summary |
|---|---|
| Companion | object Companion |
Properties
| Name | Summary |
|---|---|
| ads | abstract val ads: AdvertisingApi The AdvertisingApi for interactions regarding ads. |
| audio | abstract val The currently selected AudioTrack or null if there is none. |
| audioQuality | abstract val The currently selected AudioQuality. |
| availableAudio | abstract val A list of all available AudioTracks of the active source. SourceEvent.AudioTrackAdded signals when a new AudioTrack becomes available. |
| availableAudioQualities | abstract val A list of the available AudioQualitys of the currently selected AudioTrack of the active source. |
| availableSubtitles | abstract val A list of all available SubtitleTracks of the active source and the "off" subtitle track. |
| availableVideoQualities | abstract val A list of all available VideoQualitys of the active source. |
| buffer | abstract val buffer: BufferApi The BufferApi for interactions regarding the buffer. |
| config | abstract val config: PlayerConfig The player config. |
| currentTime | abstract val currentTime: Double The current playback time of the active source or ad in seconds. |
| currentVideoFrameRate | abstract val currentVideoFrameRate: Float The current video frame rate as frames per second. |
| droppedVideoFrames | abstract val droppedVideoFrames: Int The total number of dropped frames since playback in the active playback session has started. |
| duration | 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. |
| isAd | abstract val isAd: Boolean Returns true while an ad is being played back or when main content playback has been paused for ad playback. |
| isDestroyed | abstract val isDestroyed: Boolean Whether this player instance has been invalidated by calling destroy. |
| isFrameAboutToBeRenderedEventEnabled | abstract var isFrameAboutToBeRenderedEventEnabled: Boolean Enables or disables emitting PlayerEvent.FrameAboutToBeRendered for this player instance. |
| isLive | abstract val isLive: Boolean Whether the active and loaded source is a live stream. |
| isMuted | abstract val isMuted: Boolean Whether the player is muted. |
| isPaused | abstract val isPaused: Boolean Whether the player is paused. |
| isPlaying | abstract val isPlaying: Boolean Whether the player is currently playing (i.e. has started and is not paused). |
| isStalled | abstract val isStalled: Boolean Whether the player is currently stalled due to low buffer conditions. |
| lowLatency | abstract val lowLatency: LowLatencyApi The LowLatencyApi for interactions regarding low latency. |
| maxTimeShift | abstract val maxTimeShift: Double The limit in seconds for time shifting. This value is either negative or 0.0 and it is always 0.0 if the active source is not a live stream or there is no active playback session. |
| playbackAudioData | abstract val playbackAudioData: AudioQuality? 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). |
| playbackSpeed | abstract var playbackSpeed: Float The playback speed of the player. Slow motion can be achieved by setting the speed to values between 0.0 and 1.0, while fast forward is possible with values greater than 1.0. Values that are less than or equal to 0.0 are ignored. |
| playbackTimeOffsetToAbsoluteTime | abstract val playbackTimeOffsetToAbsoluteTime: Double 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. |
| playbackTimeOffsetToRelativeTime | abstract val playbackTimeOffsetToRelativeTime: Double 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. |
| playbackVideoData | abstract val playbackVideoData: VideoQuality? The VideoQuality that is currently being played back or null if no video is currently being played back. |
| playlist | abstract val playlist: PlaylistApi The PlaylistApi for interactions regarding the playlist. |
| source | abstract val source: Source? The currently active Source in the playback session or null if there is no active playback session. |
| subtitle | abstract val The currently selected SubtitleTrack or null if there is none. |
| timeShift | abstract val timeShift: Double The current time shift of the live stream in seconds. This value is always 0.0 if the active source is not a live stream or there is no active playback session. |
| videoQuality | abstract val The currently selected VideoQuality. |
| volume | abstract var volume: Int The player volume in the range of 0 to 100. |
| vr | abstract val vr: VrApi The VrApi for interacting with VR capabilities. |
Functions
| Name | Summary |
|---|---|
| destroy | 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. |
| getThumbnail | abstract fun Returns a Thumbnail for the provided playback time in the currently active source. Supported thumbnail formats are |
| load | 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. |
| mute | abstract fun mute() Mutes the player. |
| onPause | abstract fun onPause() Notifies the player that the host component entered the paused state. |
| onResume | abstract fun onResume() Notifies the player that the host component entered the resumed state. |
| onStart | abstract fun onStart() Notifies the player that the host component entered the started state. |
| onStop | abstract fun onStop() Notifies the player that the host component entered the stopped state. |
| pause | abstract fun pause() Pauses playback. |
| play | abstract fun play() Starts or resumes playback. |
| preload | 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. |
| preloadDrmLicense | abstract fun preloadDrmLicense(drmConfig: NagraConnectConfig) Initiates preloading of a DRM license for the provided NagraConnectConfig. |
| removeSubtitle | abstract fun 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. |
| scheduleAd | abstract fun Schedules the adItem for playback. |
| seek | abstract fun seek(time: Double) Seeks to the given playback time in seconds. Must not be greater than the duration of the active source. |
| setAdViewGroup | abstract fun Sets the ViewGroup in which the ad and the ad UI should be created. |
| setAudio | abstract fun Enables the AudioTrack that corresponds to the trackId. A list of currently available AudioTracks can be retrieved via availableAudio. |
| setAudioQuality | abstract fun 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. |
| setMaxSelectableVideoBitrate | 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. |
| setMaxSelectableVideoQualityForViewportSize | abstract fun setMaxSelectableVideoQualityForViewportSize(width: Int, height: Int) Provides the video viewport size to the player. The player will constrain the automatic quality selection, such that the maximum selectable resolution is close to the viewport size. This might include qualities that have a slightly higher resolution than the viewport. This does not affect the Source.availableVideoQualities nor the Source.setVideoQuality calls i.e. this call has no effect on manual quality selection. |
| setSubtitle | abstract fun 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. |
| setSurface | abstract fun setSurface(surface: Surface?) Sets the Surface onto which video will be rendered. The caller is responsible for tracking the lifecycle of the surface, and must clear the surface by calling setSurface(null) if the surface is destroyed.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. |
| setTextureView | abstract fun setTextureView(textureView: TextureView?) Sets the TextureView onto which video will be rendered. The player will track the lifecycle of the texture automatically. |
| setVideoQuality | abstract fun 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. |
| skipAd | abstract fun Skips the current ad. A successful skip is signaled via PlayerEvent.AdSkipped. |
| timeShift | 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.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. |
| unload | abstract fun unload() Unloads all Sources in the active playback session and stops the active playback session. |
| unmute | abstract fun unmute() Unmutes the player. |