SessionPlayer
abstract class SessionPlayer : Closeable
kotlin.Any | |
↳ | androidx.media2.common.SessionPlayer |
Base interface for all media players that want media session.
APIs that return ListenableFuture
should be the asynchronous calls and shouldn't block the calling thread. This guarantees the APIs are safe to be called on the main thread.
Topics covered here are:
Best practices
Here are best practices when implementing/using SessionPlayer:- When updating UI, you should respond to
PlayerCallback
invocations instead ofPlayerResult
objects since the player can be controlled by others. - When a SessionPlayer object is no longer being used, call #close() as soon as possible to release the resources used by the internal player engine associated with the SessionPlayer. For example, if a player uses hardware decoder, other player instances may fallback to software decoders or fail to play. You cannot use SessionPlayer instance after you call #close(). There is no way to reuse the instance.
- The current playback position can be retrieved with a call to
getCurrentPosition()
, which is helpful for applications such as a music player that need to keep track of the playback progress. - The playback position can be adjusted with a call to
seekTo(long)
. Although the asynchronousseekTo
call returns right away, the actual seek operation may take a while to finish, especially for audio/video being streamed. - You can call
seekTo(long)
from thePLAYER_STATE_PAUSED
. In these cases, if you are playing a video stream and the requested position is valid, one video frame may be displayed.
Player states
The playback control of audio/video files is managed as a state machine. The SessionPlayer defines four states:PLAYER_STATE_IDLE
: Initial state after the instantiation.While in this state, you should call
setMediaItem(MediaItem)
orsetPlaylist(List, MediaMetadata)
. Check returnedListenableFuture
for potential error.Calling
prepare()
transfers this object toPLAYER_STATE_PAUSED
.PLAYER_STATE_PAUSED
: State when the audio/video playback is paused.Call
play()
to resume or start playback from the position where it paused.PLAYER_STATE_PLAYING
: State when the player plays the media item.In this state,
PlayerCallback#onBufferingStateChanged( * SessionPlayer, MediaItem, int)
will be called regularly to tell the buffering status.Playback state would remain
PLAYER_STATE_PLAYING
when the currently playing media item is changed.When the playback reaches the end of stream, the behavior depends on repeat mode, set by
setRepeatMode(int)
. If the repeat mode was set toREPEAT_MODE_NONE
, the player will transfer to thePLAYER_STATE_PAUSED
. Otherwise, the SessionPlayer object remains in thePLAYER_STATE_PLAYING
and playback will be ongoing.PLAYER_STATE_ERROR
: State when the playback failed and player cannot be recovered by itself.In general, playback might fail due to various reasons such as unsupported audio/video format, poorly interleaved audio/video, resolution too high, streaming timeout, and others. In addition, due to programming errors, a playback control operation might be performed from an invalid state. In these cases the player may transition to this state.
PLAYER_STATE_IDLE
from other states. Take a look at documentations of specific subclass that you're interested in.
Invalid method calls
The only method you safely call from thePLAYER_STATE_ERROR
is #close(). Any other methods might return meaningless data.
Subclasses of the SessionPlayer may have extra methods that are safe to be called in the error state and/or provide a method to recover from the error state. Take a look at documentations of specific subclass that you're interested in.
Most methods can be called from any non-Error state. In case they're called in invalid state, the implementation should ignore and would return PlayerResult
with PlayerResult#RESULT_ERROR_INVALID_STATE
. The following table lists the methods that aren't guaranteed to successfully running if they're called from the associated invalid states.
Method Name | Invalid States |
---|---|
setAudioAttributes | {Paused, Playing} |
prepare | {Paused, Playing} |
play | {Idle} |
pause | {Idle} |
seekTo | {Idle} |
Summary
Nested classes | |
---|---|
abstract |
A callback class to receive notifications for events on the session player. |
open |
Result class of the asynchronous APIs. |
open |
Class for the player to return each audio/video/subtitle track's metadata. |
Constants | |
---|---|
static Int |
Buffering state indicating the player is buffering but enough has been buffered for this player to be able to play the content. |
static Int |
Buffering state indicating the player is buffering, but the player is currently starved for data, and cannot play. |
static Int |
Buffering state indicating the player is done buffering, and the remainder of the content is available for playback. |
static Int |
Buffering state is unknown. |
static Int |
Media item index is invalid. |
static Int |
State when the player is in error state and cannot be recovered self. |
static Int |
State when the player is idle, and needs configuration to start playback. |
static Int |
State when the player's playback is paused |
static Int |
State when the player's playback is ongoing |
static Int |
Playing media list will be repeated. |
static Int |
Playback of the playing media group will be repeated. |
static Int |
Playback will be stopped at the end of the playing media list. |
static Int |
Playback of the current playing media item will be repeated. |
static Int |
Media list will be played in shuffled order. |
static Int |
Media group will be played in shuffled order. |
static Int |
Media list will be played in order. |
static Long |
Value indicating the time is unknown |
Public constructors | |
---|---|
<init>() Base interface for all media players that want media session. |
Public methods | |
---|---|
abstract ListenableFuture<SessionPlayer.PlayerResult!> |
addPlaylistItem(index: Int, @NonNull item: MediaItem) Adds the media item to the playlist at the index. |
open Unit |
close() Removes all existing references to callbacks and executors. |
open ListenableFuture<SessionPlayer.PlayerResult!> |
deselectTrack(@NonNull |