Package com.amazonaws.ivs.player

Interface Player

All Superinterfaces:
Releasable
public interface Player extends Releasable
Interface defining a Player.

Player usage

Player state

  • Player.State.IDLE: This is the initial state, the state when the player is not processing any media samples
  • Player.State.READY: The player has prepared the source stream and can start downloading and processing media samples.
  • Player.State.BUFFERING: The player buffer does not have enough media samples to render. The player is filling the buffer while no media samples are rendered.
  • Player.State.PLAYING: The player is actively downloading, processing and rendering media samples from the player buffer.
  • Player.State.ENDED: The player has reached the end of stream and there are no more media samples to render.

Here is a simple example illustrating the state transitions 

   | Time | Action         | State     | Notes
   =============================================================================
   | 0    | create player  | IDLE      |
   | 1    | load           | IDLE      | player starts loading the stream
   | 2    |                | READY     | player finishes loading the stream
   | 3    | play           | BUFFERING | player starts filling the buffer
   | 4    |                | PLAYING   | player starts playing
   | 5    | pause          | IDLE      | user stops watching, playback is paused
   | 6    | release player | --        | player is no longer needed and its
   |      |                |           |     resources are released

  • Method Details

    • release

      void release()
      Releases and destroys the player instance. This method must be called when the Player is no longer being used in order to free network and system resources. This method can be called when the player is in one of these states: Player.State.READY, Player.State.IDLE or Player.State.ENDED. The player instance cannot be used after this method is called.
      Specified by:
      release in interface Releasable

    • getAudioSessionId

      int getAudioSessionId()
      Gets session ID of the audio track. This method returns a valid value only after a stream is loaded and the player is in (Player.State.PLAYING) state.
      Returns:
      session ID of the audio track

    • getState

      @NonNull Player.State getState()
      Gets current player state.
      Returns:
      The state of the player.
      See Also:

    • getPosition

      long getPosition()
      Gets the playback position, in milliseconds. This method returns a valild value only when the player is in Player.State.PLAYING state. Otherwise, this returns the last play position or -1 if playback has not started yet.
      Returns:
      playback position in milliseconds

    • getSyncTime

      long getSyncTime()
      Gets the synchronized time, in milliseconds. The synchronized time is a UTC time that represents a specific time during playback, at a granularity of 1 second. It can be used to sync external events and state to a specific moment during playback. This method returns a valid value only when the player is in Player.State.PLAYING state. Otherwise, this returns the last sync time or 0 if playback has not started yet. Note an event is dispatched when this value changes: See Player.Listener.onSyncTimeChanged(long syncTime)
      Returns:
      synchronized time in milliseconds

    • getDuration

      long getDuration()
      Gets the duration of the loaded stream, in milliseconds. This method returns -1 if no stream was loaded, or if the stream length is infinite or unknown.
      Returns:
      duration of the loaded stream in milliseconds

    • getBufferedPosition

      long getBufferedPosition()
      Gets the buffered position, in milliseconds.
      Returns:
      buffered position in milliseconds or -1 if no data is buffered.

    • getVersion

      @NonNull String getVersion()
      Gets player version.
      Returns:
      version string of the player

    • addListener

      void addListener(@NonNull Player.Listener listener)
      Adds a playback listener that receives information about this player instance.
      Parameters:
      listener - playback listener to add
      See Also:

    • removeListener

      void removeListener(@NonNull Player.Listener listener)
      Removes a playback state listener.
      Parameters:
      listener - playback listener to remove
      See Also:

    • setLooping

      void setLooping(boolean loop)
      Enables the player to loop the source video, for streams that support looping.
      Parameters:
      loop - true to loop video playback, false otherwise

    • isMuted

      boolean isMuted()
      Returns:
      true if the player is muted, false otherwise

    • setMuted

      void setMuted(boolean muted)
      Mutes or unmutes the player audio.
      Parameters:
      muted - true to mute the player, false to unmute the player

    • setSurface

      void setSurface(@Nullable android.view.Surface surface)
      Sets the Surface to use for rendering video. This method can be called at any time. A valid surface must be set to display video. When using a SurfaceView or TextureView, the application must listen for the corresponding lifecycle callbacks in order to set the surface on the player, and clear it by setting it to null, when the surface is being destroyed.
      • For SurfaceView: SurfaceHolder.Callback.surfaceCreated(SurfaceHolder) and SurfaceHolder.Callback.surfaceDestroyed(SurfaceHolder)
      • For TextureView: TextureView.SurfaceTextureListener.onSurfaceTextureAvailable(SurfaceTexture, int, int) and TextureView.SurfaceTextureListener.onSurfaceTextureDestroyed(SurfaceTexture)
      Parameters:
      surface - surface to use for rendering; this value can be null to stop displaying video

    • getPlaybackRate

      float getPlaybackRate()
      Gets the playback rate for the player.
      Returns:
      current playback rate

    • setPlaybackRate

      void setPlaybackRate(float rate)
      Sets the playback rate for the player.

      For live content, setting this value to higher than 1.0 may increase rebuffering.

      For non-live content, most devices support up to 2.0 playback rate, with a few exceptions that only support up to 1.5. It is not recommended to set the playback rate to higher than 2.0.

      Parameters:
      rate - new playback rate

    • setVolume

      void setVolume(float volume)
      Sets the output gain value for the audio track.
      Parameters:
      volume - volume for the audio track between 0.0f and 1.0f

    • getVolume

      float getVolume()
      Gets the output gain value for the audio track.
      Returns:
      current volume for the audio track between 0.0f and 1.0f

    • load

      void load(@NonNull android.net.Uri uri)
      Loads the specified stream. On success, the player state changes to Player.State.READY. On failure, this invokes Player.Listener.onError(com.amazonaws.ivs.player.PlayerException).
      Parameters:
      uri - URI of the stream to load (e.g. a url or file)

    • load

      void load(@NonNull android.net.Uri uri, @NonNull String mediaType)
      Loads the specified stream. On success, the player state changes to Player.State.READY. On failure, this invokes Player.Listener.onError(com.amazonaws.ivs.player.PlayerException).
      Parameters:
      uri - URI of the stream to load (e.g. a url or file)
      mediaType - Media type of the content if known, e.g. "video/mp4" or "application/x-mpegURL"

    • seekTo

      void seekTo(long position)
      Seeks to a specified position in the stream, in milliseconds. Seeks to the given time in the stream and begins playing at that position if play() has been called. If no stream is loaded, the seek will be be deferred until load(android.net.Uri) is called.

      On success, depending on the type of stream the player state will change to Player.State.BUFFERING and then Player.State.PLAYING or remain in Player.State.PLAYING. getPosition() will update to the seek time.

      On failure, this invokes Player.Listener.onError(com.amazonaws.ivs.player.PlayerException)

      Parameters:
      position - to seek to in milliseconds

    • play

      void play()
      Starts or resumes playback of the stream. If no stream is loaded, this indicates an intent to play and the player will automatically play content from a subsequent load call.

      On success, depending on the type of stream, the player state changes to Player.State.BUFFERING and then Player.State.PLAYING, or just Player.State.PLAYING.

      On failure, this invokes Player.Listener.onError(com.amazonaws.ivs.player.PlayerException).

    • pause

      void pause()
      Pauses playback of the stream. This fails if no stream is loaded. On failure, this invokes Player.Listener.onError(com.amazonaws.ivs.player.PlayerException).

      Resuming the stream with play may result in the position being different depending on the type of source being played.

    • getQualities

      @NonNull Set<Quality> getQualities()
      Gets the qualities from the loaded source. The qualities will be available after the Player.State.READY state has been entered. This set contains the qualities that can be used with setQuality(Quality). Note that this set will contain only qualities capable of being played on the current device and not all those present in the source stream.
      Returns:
      Set of Quality from the loaded source, or empty set if none are currently available.

    • getQuality

      @NonNull Quality getQuality()
      Gets the current quality of the stream
      Returns:
      the Quality of the stream

    • setQuality

      void setQuality(@NonNull Quality quality)
      Sets the quality of the stream. If auto quality mode is enabled, calling this method disables it.
      Parameters:
      quality - new quality

    • setQuality

      void setQuality(@NonNull Quality quality, boolean adaptive)
      Sets the quality of the stream. If auto quality mode is enabled, calling this method disables it. When adaptive is set to true, quality changes at the end of the player buffer, otherwise, the buffer is cleared immediately to change quality.
      Parameters:
      quality - new quality
      adaptive - true for an adaptive quality change

    • isAutoQualityMode

      boolean isAutoQualityMode()
      Returns:
      true if auto quality switching is enabled, false otherwise.

    • setAutoQualityMode

      void setAutoQualityMode(boolean enable)
      Enables automatic quality selection (ABR adaptive bitrate mode). The player will choose the quality to play based on the current network and device conditions. The player by default starts in this mode. This mode is implicitly disabled by a call to setQuality(com.amazonaws.ivs.player.Quality).
      Parameters:
      enable - true to enable auto quality selection, false to disable.

    • setAutoInitialBitrate

      void setAutoInitialBitrate(int bitrate)
      Sets the initial starting bitrate when using auto quality mode, in bps. This determines the initial quality for an adaptive stream, when no bandwidth estimate value has been determined. Applied on the next call to the load(Uri) or load(Uri, String) method. This determines the initial quality for an adaptive stream, when no bandwidth estimate value has been determined.
      Parameters:
      bitrate - initial bitrate in bps

    • setAutoMaxBitrate

      void setAutoMaxBitrate(int bitrate)
      Sets the max bitrate when using auto quality mode, in bps. Allows you to control resource usage in the case of multiple players.
      Parameters:
      bitrate - max bitrate in bps

    • setAutoMaxVideoSize

      void setAutoMaxVideoSize(int width, int height)
      Sets the max video display size of the player, in pixels. This prevents switching to qualities above the specified resolution in auto quality mode.
      Parameters:
      width - display width in pixels
      height - display height in pixels

    • setAutoMaxQuality

      void setAutoMaxQuality(@NonNull Quality quality)
      Sets the maximum quality the player is allowed to switch up to in auto quality mode. It uses the input quality's bitrate value to limit the qualities. This allows you to control resource usage. The Quality you provide here is applied to the current stream. If you load a new stream, call this again after Player.State.READY.
      Parameters:
      quality - maximum quality to use

    • isLiveLowLatency

      boolean isLiveLowLatency()
      Returns:
      true if the player is in low-latency mode, false otherwise.

    • setLiveLowLatencyEnabled

      void setLiveLowLatencyEnabled(boolean enabled)
      Enables or disables low-latency playback. Defaults to true for streams that support low-latency. Changing this value during playback restarts the stream.
      Parameters:
      enabled - true to enable, false to disable

    • setRebufferToLive

      void setRebufferToLive(boolean enable)
      Enables or disables skipping to the live edge on a rebuffer. Note that enabling this can cause video content and content associated with it such as timed metadata to be skipped. Defaults to false.
      Parameters:
      enable - true to enable, false otherwise

    • getAverageBitrate

      long getAverageBitrate()
      Gets the average source media stream bitrate, in bps.
      Returns:
      average bitrate of the stream in bps.

    • getBandwidthEstimate

      long getBandwidthEstimate()
      Gets the network bandwidth estimate, in bps. Only available for network streams.
      Returns:
      the ABR bandwidth estimate in bps or 0 if unknown.

    • getLiveLatency

      long getLiveLatency()
      Gets the live latency between server and the player, in milliseconds. For a live stream, this returns the latency from the server to the player. For non-live streams, this value is undefined.
      Returns:
      live latency in milliseconds

    • getStatistics

      @NonNull Statistics getStatistics()
      Gets playback statistics for the current stream.
      Returns:
      statistics for the stream
      See Also:

    • getSessionId

      @NonNull String getSessionId()
      Gets a unique identifier for the current playback session. This session ID can be shared with support or displayed in user interface to help troubleshoot or diagnose playback issues with the stream.
      Returns:
      a unique identifier for the playback session

    • getChannelMetadata

      @NonNull String[] getChannelMetadata()
      Returns an array of string values that represent channel features or capabilities. Refer to IVS Channel documentation for more information about these values.
      Returns:
      an array of strings as metadata for the current channel

    • setLogLevel

      void setLogLevel(@NonNull Player.LogLevel level)
      Sets the log level for the player. Defaults to Player.LogLevel.ERROR.
      Parameters:
      level - new log level
      See Also:

    • setInitialBufferDuration

      void setInitialBufferDuration(long duration)
      Sets the initial (minimum) buffer duration required to start playback, in milliseconds. If a value outside the allowable range is used, the current value is maintained. Defaults to 1 second in low latency mode, 2 seconds otherwise. Lowering this value may increase rebuffering.
      Parameters:
      duration - buffer duration in milliseconds. The allowable range is 100 ms to 5000 ms.

    • setOrigin

      void setOrigin(@NonNull String origin)
      Sets the HTTP 'Origin' header on all outgoing requests.
      Parameters:
      origin - the HTTP 'Origin' header value

    • setNetworkRecoveryMode

      void setNetworkRecoveryMode(Player.NetworkRecoveryMode mode)
      Sets network recovery mode for handling network interruptions. Default mode is Player.NetworkRecoveryMode.RESUME, which means that player will try to resume its previous state before the network interruption occured.
      Parameters:
      mode - NetworkRecoveryMode to use

    • getPath

      String getPath()
      Gets the URL of the loaded media, if any.
      Returns:
      The URL of the loaded media, or an empty string if nothing has been loaded.