com.bambuser.broadcaster

Class BroadcastPlayer

java.lang.Object

com.bambuser.broadcaster.BroadcastPlayer

All Implemented Interfaces:

MediaController.MediaPlayerControl

public final class BroadcastPlayer
extends Object
implements MediaController.MediaPlayerControl

Class for integrating playback of Bambuser broadcasts in an app. Automatically handles various streaming formats required for live / archived video and low latency / high scalability. The lowest supported API level is KITKAT, Android 4.4.

BroadcastPlayer implements the MediaController.MediaPlayerControl interface and can thereby be passed to a standard MediaController widget for pause/resume/seek in an archived broadcast. Pause/resume/seek is disabled during normal low-latency playback of a live broadcast, but can be enabled by switching to high-latency timeshift mode through setTimeshiftMode(true). The onBroadcastLoaded(live, width, height) callback is suitable for showing relevant UI components.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	BroadcastPlayer.AcceptType
static class	BroadcastPlayer.LatencyMode
static interface	BroadcastPlayer.Observer
static interface	BroadcastPlayer.ViewerCountObserver An interface that should be passed to setViewerCountObserver(ViewerCountObserver) to receive callbacks about the current and total number of viewers of the broadcast.

Constructor Summary

Constructors

Constructor and Description
BroadcastPlayer(Context context, String resourceUri, String applicationId, BroadcastPlayer.Observer observer) Creates a BroadcastPlayer instance in the PlayerState.CONSTRUCTION state.

Method Summary

Modifier and Type	Method and Description
boolean	canPause() Implementation for the MediaController.MediaPlayerControl interface, determining whether the broadcast can be paused/resumed.
boolean	canSeekBackward() Implementation for the MediaController.MediaPlayerControl interface, determining whether the BroadcastPlayer currently supports seeking.
boolean	canSeekForward() Implementation for the MediaController.MediaPlayerControl interface, determining whether the BroadcastPlayer currently supports seeking.
void	close() Immediately stops any playback and frees all related system resources.
int	getAudioSessionId() Returns the current audio session id if a broadcast has been loaded.
String	getBroadcastId() Returns the id of the loaded broadcast.
int	getBufferPercentage() Implementation for the MediaController.MediaPlayerControl interface, returning a current buffer percentage for an archived broadcast.
int	getCurrentPosition() Get the current play position in a video.
int	getDuration() Get the duration of the currently playing video.
LatencyMeasurement	getEndToEndLatency() Get the current measured end-to-end latency when playing a live broadcast.
PlayerState	getState() Get the current state
boolean	isPlaying() Implementation for the MediaController.MediaPlayerControl interface, determining whether the MediaController should show a pause or play button.
boolean	isTypeLive() Returns the type of the broadcast.
void	load() Starts loading the requested Bambuser broadcast for playback.
void	pause() Pause any currently PLAYING/BUFFERING archived broadcast (or a live broadcast in timeshift mode).
void	seekTo(int position) Seek to desired position.
void	setAcceptType(BroadcastPlayer.AcceptType acceptedBroadcastType) Set the type accepted when loading the broadcast.
void	setAudioVolume(float volume) Set the desired audio volume for this BroadcastPlayer instance.
void	setLatencyMode(BroadcastPlayer.LatencyMode mode) Set whether the player should prioritize low latency or playback with less interruptions.
void	setSurface(Surface surface) Set the Surface where video should be shown.
void	setSurfaceView(SurfaceView surfaceView) Set the SurfaceView where video will be shown.
void	setTextureView(TextureView textureView) Set the TextureView where video will be shown.
void	setTimeshiftMode(boolean enabled) Set whether the player should be configured for timeshift mode.
void	setViewerCountObserver(BroadcastPlayer.ViewerCountObserver observer) Get the number of viewers into your app by implementing a BroadcastPlayer.ViewerCountObserver.
void	start() Resume playback of a PAUSED broadcast, or restart playback of a COMPLETED archived broadcast.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BroadcastPlayer

public BroadcastPlayer(Context context,
                       String resourceUri,
                       String applicationId,
                       BroadcastPlayer.Observer observer)

Creates a BroadcastPlayer instance in the PlayerState.CONSTRUCTION state. After this, you should use setSurfaceView(SurfaceView), setTextureView(TextureView) or setSurface(Surface). Then you may set optional features, such as setAcceptType(AcceptType) and setAudioVolume(float), and call load().

Always call close() when the instance is no longer needed, to stop playback and free allocated resources.

Parameters:

context - Context providing system information needed for playback.

resourceUri - A signed resource URI for a Bambuser broadcast, for example received from the Bambuser Metadata API.

applicationId - Customer app specific secret ID, ensuring access to the customer's content.

observer - Implement the BroadcastPlayer.Observer interface to receive callbacks about state changes in the BroadcastPlayer.

Method Detail

setAcceptType

public void setAcceptType(BroadcastPlayer.AcceptType acceptedBroadcastType)

Set the type accepted when loading the broadcast. For example, this can be used to ensure that the player will only play the provided broadcast while its status is still live, prohibiting playback of an archived file, or vice versa. This can only be set before the first call to load().

Parameters:

acceptedBroadcastType - Use BroadcastPlayer.AcceptType.LIVE or BroadcastPlayer.AcceptType.ARCHIVED to allow playback of only the specified broadcast type. The default is BroadcastPlayer.AcceptType.ANY.

setTimeshiftMode

public void setTimeshiftMode(boolean enabled)

Set whether the player should be configured for timeshift mode. Timeshift mode should be enabled only if seeking in a live broadcast is necessary. Timeshift mode allows playback of any part of the broadcast, but involves much higher latency on a live broadcast, and playback performance may suffer on very long broadcasts. In timeshift mode, the player will not repeatedly seek to the live edge. This can only be set before the first call to load().

Parameters:

enabled - True to configure the player for timeshift mode, false otherwise.

setLatencyMode

public void setLatencyMode(BroadcastPlayer.LatencyMode mode)

Set whether the player should prioritize low latency or playback with less interruptions. In LOW latency mode, the player prioritizes low latency and is quick to start initial playback. In HIGH latency mode, the player uses larger buffers and will buffer slightly more initially, to minimize the risk of playback interruptions due to network fluctuations.

This option currently only affects live broadcasts. This method can only be used before the first call to load().

Parameters:

mode - A BroadcastPlayer.LatencyMode. Default is BroadcastPlayer.LatencyMode.LOW.

setSurfaceView

public void setSurfaceView(SurfaceView surfaceView)

Set the SurfaceView where video will be shown. When a SurfaceView is provided, the BroadcastPlayer will attempt to keep the screen on while video is playing. If the provided SurfaceView is a SurfaceViewWithAutoAR and is allowed to set its own dimensions, the BroadcastPlayer will automatically set its aspect ratio.

Parameters:

surfaceView - A SurfaceView (preferably a SurfaceViewWithAutoAR) where the video will be shown.

setTextureView

public void setTextureView(TextureView textureView)

Set the TextureView where video will be shown. When a TextureView is provided, the BroadcastPlayer will attempt to keep the screen on while video is playing. The BroadcastPlayer will use TextureView.setSurfaceTextureListener(TextureView.SurfaceTextureListener), overriding any existing listener.

Parameters:

textureView - A TextureView where the video will be shown.

setSurface

public void setSurface(Surface surface)

Set the Surface where video should be shown. NOTE: when using this method, you are fully responsible for setting a fully created Surface and clearing it before the Surface is destroyed. You must also keep the screen awake. For most use cases setSurfaceView(SurfaceView) or setTextureView(TextureView) are better.

Parameters:

surface - Surface where the video will be shown.

load

public void load()

Starts loading the requested Bambuser broadcast for playback. This method is only valid when the player is in the PlayerState.CONSTRUCTION state.

close

public void close()

Immediately stops any playback and frees all related system resources. Make sure to call this when the player instance is no longer needed, or you may experience background playback. Starting new players without closing old ones will eventually deplete all available system resources. After this call, this BroadcastPlayer instance can not be used.

isTypeLive

public boolean isTypeLive()

Returns the type of the broadcast. Available after the BroadcastPlayer has loaded the initial data (state changed from LOADING to BUFFERING/PLAYING). The value is not updated later.

Returns:

true if the loaded broadcast is a live broadcast, false otherwise.

getBroadcastId

public String getBroadcastId()

Returns the id of the loaded broadcast. Available after the BroadcastPlayer has loaded the initial data (state changed from LOADING to BUFFERING/PLAYING).

For example when a player is initiated with a virtual resource uri, this method can be used to determine which broadcast the player loaded.

Returns:

A broadcast id string when the player has loaded a broadcast. Empty string otherwise.

getState

public PlayerState getState()

Get the current state

Returns:

One of the values defined in PlayerState.

getDuration

public int getDuration()

Get the duration of the currently playing video. Returns -1 when duration is unknown, for example for live broadcasts without timeshift mode. Duration is always available for archived broadcasts and for live broadcasts viewed in timeshift mode.

Specified by:

getDuration in interface MediaController.MediaPlayerControl

Returns:

Current video length in milliseconds. -1 if duration is unavailable.

getCurrentPosition

public int getCurrentPosition()

Get the current play position in a video. The current position is always available for archived broadcasts and for live broadcasts viewed in timeshift mode. It may also be available for live broadcasts, depending on video format.

Specified by:

getCurrentPosition in interface MediaController.MediaPlayerControl

Returns:

Current position in milliseconds. 0 if position is unavailable.

seekTo

public void seekTo(int position)

Seek to desired position. If the player has not loaded an archived seekable video (or a live video in timeshift mode), this method does nothing.

Specified by:

seekTo in interface MediaController.MediaPlayerControl

Parameters:

position - Desired playback position in milliseconds.

getEndToEndLatency

public LatencyMeasurement getEndToEndLatency()

Get the current measured end-to-end latency when playing a live broadcast. During a live broadcast, the Broadcaster and BroadcastPlayer can synchronize their clocks with the servers and the player can determine the current end-to-end latency.

End-to-end latency measurements may take a while before appearing and may not be available for all broadcasts, as it requires successful clock synchronization and needs to be supported by the broadcast source too.

Returns:

A LatencyMeasurement object containing the current end-to-end latency and the total uncertainty of the broadcaster and player. null if end-to-end latency measurement is currently unavailable.

isPlaying

public boolean isPlaying()

Implementation for the MediaController.MediaPlayerControl interface, determining whether the MediaController should show a pause or play button.

Specified by:

isPlaying in interface MediaController.MediaPlayerControl

Returns:

True while the BroadcastPlayer state is PLAYING or BUFFERING, false otherwise.

getBufferPercentage

public int getBufferPercentage()

Implementation for the MediaController.MediaPlayerControl interface, returning a current buffer percentage for an archived broadcast.

Specified by:

getBufferPercentage in interface MediaController.MediaPlayerControl

Returns:

0-100 percent during playback of an archived broadcast. 0 for a live broadcast.

canPause

public boolean canPause()

Implementation for the MediaController.MediaPlayerControl interface, determining whether the broadcast can be paused/resumed.

Specified by:

canPause in interface MediaController.MediaPlayerControl

Returns:

True if the BroadcastPlayer has loaded an archived broadcast (or a live broadcast in timeshift mode) and is in a state that supports pause/play/seeking, false otherwise.

canSeekBackward

public boolean canSeekBackward()

Implementation for the MediaController.MediaPlayerControl interface, determining whether the BroadcastPlayer currently supports seeking.

Specified by:

canSeekBackward in interface MediaController.MediaPlayerControl

Returns:

True if the BroadcastPlayer has loaded an archived broadcast (or a live broadcast in timeshift mode) and is in a state that supports pause/play/seeking, false otherwise.

canSeekForward

public boolean canSeekForward()

Implementation for the MediaController.MediaPlayerControl interface, determining whether the BroadcastPlayer currently supports seeking.

Specified by:

canSeekForward in interface MediaController.MediaPlayerControl

Returns:

True if the BroadcastPlayer has loaded an archived broadcast (or a live broadcast in timeshift mode) and is in a state that supports pause/play/seeking, false otherwise.

getAudioSessionId

public int getAudioSessionId()

Returns the current audio session id if a broadcast has been loaded.

Specified by:

getAudioSessionId in interface MediaController.MediaPlayerControl

Returns:

The current audio session id. 0 if no broadcast has been loaded or playback has failed.

setViewerCountObserver

public void setViewerCountObserver(BroadcastPlayer.ViewerCountObserver observer)

Get the number of viewers into your app by implementing a BroadcastPlayer.ViewerCountObserver.

Parameters:

observer - An observer object enabling viewer count functionality.

setAudioVolume

public void setAudioVolume(float volume)

Set the desired audio volume for this BroadcastPlayer instance. The gain is linear from 0.0 to 1.0. UI controls should be scaled logarithmically.

This method can be used at any time, and is suitable for silencing individual player instances, as it does not affect the global audio stream volume.

Parameters:

volume - float value between 0.0 and 1.0. The default is 1.0.

pause

public void pause()

Pause any currently PLAYING/BUFFERING archived broadcast (or a live broadcast in timeshift mode).

Specified by:

pause in interface MediaController.MediaPlayerControl

start

public void start()

Resume playback of a PAUSED broadcast, or restart playback of a COMPLETED archived broadcast. This method is only applicable when an archived broadcast (or a live broadcast in timeshift mode) has been loaded.

Specified by:

start in interface MediaController.MediaPlayerControl