Package 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 LOLLIPOP, Android 5.0.

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.

  • Constructor Details

  • Method Details

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

    • setMP4Enabled

      public void setMP4Enabled(boolean enabled)
      Set MP4 as the preferred playback format for archive video.

      MP4 video is always loaded at full quality, no adaptive lower resolution variants. This should only be used for broadcasts that are short and where the MP4 format is expected to be available, i.e. VOD content. This property can only be set before the first call to load().

      Parameters:
      enabled - True to request fixed-quality MP4 as the preferred format, false for default adaptive formats.

    • 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