SessionPlayer
public
abstract
class
SessionPlayer
extends Object
implements
Closeable
java.lang.Object | |
↳ | 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
SessionPlayer.PlayerCallback
invocations instead ofSessionPlayer.PlayerResult
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 callclose()
. 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(long)
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,
SessionPlayer.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 SessionPlayer.PlayerResult
with
SessionPlayer.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 | |
---|---|
class |
SessionPlayer.PlayerCallback
A callback class to receive notifications for events on the session player. |
class |
SessionPlayer.PlayerResult
Result class of the asynchronous APIs. |
class |
SessionPlayer.TrackInfo
Class for the player to return each audio/video/subtitle track's metadata. |
Constants | |
---|---|
int |
BUFFERING_STATE_BUFFERING_AND_PLAYABLE
Buffering state indicating the player is buffering but enough has been buffered for this player to be able to play the content. |
int |
BUFFERING_STATE_BUFFERING_AND_STARVED
Buffering state indicating the player is buffering, but the player is currently starved for data, and cannot play. |
int |
BUFFERING_STATE_COMPLETE
Buffering state indicating the player is done buffering, and the remainder of the content is available for playback. |
int |
BUFFERING_STATE_UNKNOWN
Buffering state is unknown. |
int |
INVALID_ITEM_INDEX
Media item index is invalid. |
int |
PLAYER_STATE_ERROR
State when the player is in error state and cannot be recovered self. |
int |
PLAYER_STATE_IDLE
State when the player is idle, and needs configuration to start playback. |
int |
PLAYER_STATE_PAUSED
State when the player's playback is paused |
int |
PLAYER_STATE_PLAYING
State when the player's playback is ongoing |
int |
REPEAT_MODE_ALL
Playing media list will be repeated. |
int |
REPEAT_MODE_GROUP
Playback of the playing media group will be repeated. |
int |
REPEAT_MODE_NONE
Playback will be stopped at the end of the playing media list. |
int |
REPEAT_MODE_ONE
Playback of the current playing media item will be repeated. |
int |
SHUFFLE_MODE_ALL
Media list will be played in shuffled order. |
int |
SHUFFLE_MODE_GROUP
Media group will be played in shuffled order. |
int |
SHUFFLE_MODE_NONE
Media list will be played in order. |
long |
UNKNOWN_TIME
Value indicating the time is unknown |
Public constructors | |
---|---|
SessionPlayer()
|
Public methods | |
---|---|
abstract
ListenableFuture<SessionPlayer.PlayerResult>
|
addPlaylistItem(int index, MediaItem item)
Adds the media item to the playlist at the index. |
void
|
close()
Removes all existing references to callbacks and executors. |
ListenableFuture<SessionPlayer.PlayerResult>
|
deselectTrack(SessionPlayer.TrackInfo trackInfo)
Deselects the |
abstract
AudioAttributesCompat
|
getAudioAttributes()
Gets the |
abstract
long
|
getBufferedPosition()
Gets the position for how much has been buffered, or |
abstract
int
|
getBufferingState()
Returns the current buffering state of the player. |
abstract
MediaItem
|
getCurrentMediaItem()
Gets the current media item, which is currently playing or would be played with later
|
abstract
int
|
getCurrentMediaItemIndex()
Gets the index of current media item in playlist. |
abstract
long
|
getCurrentPosition()
Gets the current playback position. |
abstract
long
|
getDuration()
Gets the duration of the current media item, or |
abstract
int
|
getNextMediaItemIndex()
Gets the next item index in the playlist. |
abstract
float
|
getPlaybackSpeed()
Gets the actual playback speed to be used by the player when playing. |
abstract
int
|
getPlayerState()
Gets the current player state. |
abstract
List<MediaItem>
|
getPlaylist()
Gets the playlist. |
abstract
MediaMetadata
|
getPlaylistMetadata()
Gets the playlist metadata. |
abstract
int
|
getPreviousMediaItemIndex()
Gets the previous item index in the playlist. |
abstract
int
|
getRepeatMode()
Gets the repeat mode. |
SessionPlayer.TrackInfo
|
getSelectedTrack(int trackType)
Gets currently selected track's |
abstract
int
|
getShuffleMode()
Gets the shuffle mode. |
List<SessionPlayer.TrackInfo>
|
getTracks()
Gets the full list of selected and unselected tracks that the media contains. |
VideoSize
|
getVideoSize()
Gets the size of the video. |
ListenableFuture<SessionPlayer.PlayerResult>
|
movePlaylistItem(int fromIndex, int toIndex)
Moves the media item at |
abstract
ListenableFuture<SessionPlayer.PlayerResult>
|
pause()
Pauses playback. |
abstract
ListenableFuture<SessionPlayer.PlayerResult>
|
play()
Starts or resumes playback. |
abstract
ListenableFuture<SessionPlayer.PlayerResult>
|
prepare()
Prepares the media items for playback. |
final
void
|
registerPlayerCallback(Executor executor, SessionPlayer.PlayerCallback callback)
Register |
abstract
ListenableFuture<SessionPlayer.PlayerResult>
|
removePlaylistItem(int index)
Removes the media item from the playlist
The implementation must notify registered callbacks with
|
abstract
ListenableFuture<SessionPlayer.PlayerResult>
|
replacePlaylistItem(int index, MediaItem item)
Replaces the media item at index in the playlist. |
abstract
ListenableFuture<SessionPlayer.PlayerResult>
|
seekTo(long position)
Seeks to the specified position. |
ListenableFuture<SessionPlayer.PlayerResult>
|
selectTrack(SessionPlayer.TrackInfo trackInfo)
Selects the |
abstract
ListenableFuture<SessionPlayer.PlayerResult>
|
setAudioAttributes(AudioAttributesCompat attributes)
Sets the |
abstract
ListenableFuture<SessionPlayer.PlayerResult>
|
setMediaItem(MediaItem item)
Sets a |
abstract
ListenableFuture<SessionPlayer.PlayerResult>
|
setPlaybackSpeed(float playbackSpeed)
Sets the playback speed. |
abstract
ListenableFuture<SessionPlayer.PlayerResult>
|
setPlaylist(List<MediaItem> list, MediaMetadata metadata)
Sets a list of |
abstract
ListenableFuture<SessionPlayer.PlayerResult>
|
setRepeatMode(int repeatMode)
Sets the repeat mode. |
abstract
ListenableFuture<SessionPlayer.PlayerResult>
|
setShuffleMode(int shuffleMode)
Sets the shuffle mode. |
ListenableFuture<SessionPlayer.PlayerResult>
|
setSurface(Surface surface)
Sets the |
abstract
ListenableFuture<SessionPlayer.PlayerResult>
|
skipToNextPlaylistItem()
Skips to the next item in the playlist. |
abstract
ListenableFuture<SessionPlayer.PlayerResult>
|
skipToPlaylistItem(int index)
Skips to the item in the playlist at the index. |
abstract
ListenableFuture<SessionPlayer.PlayerResult>
|
skipToPreviousPlaylistItem()
Skips to the previous item in the playlist. |
final
void
|
unregisterPlayerCallback(SessionPlayer.PlayerCallback callback)
Unregister the previously registered |
abstract
ListenableFuture<SessionPlayer.PlayerResult>
|
updatePlaylistMetadata(MediaMetadata metadata)
Updates the playlist metadata while keeping the playlist as-is. |
Protected methods | |
---|---|
final
List<Pair<SessionPlayer.PlayerCallback, Executor>>
|
getCallbacks()
Gets the callbacks with executors for subclasses to notify player events. |
Inherited methods | |
---|---|
Constants
BUFFERING_STATE_BUFFERING_AND_PLAYABLE
public static final int BUFFERING_STATE_BUFFERING_AND_PLAYABLE
Buffering state indicating the player is buffering but enough has been buffered
for this player to be able to play the content.
See getBufferedPosition()
for how far is buffered already.
Constant Value: 1 (0x00000001)
BUFFERING_STATE_BUFFERING_AND_STARVED
public static final int BUFFERING_STATE_BUFFERING_AND_STARVED
Buffering state indicating the player is buffering, but the player is currently starved for data, and cannot play.
Constant Value: 2 (0x00000002)
BUFFERING_STATE_COMPLETE
public static final int BUFFERING_STATE_COMPLETE
Buffering state indicating the player is done buffering, and the remainder of the content is available for playback.
Constant Value: 3 (0x00000003)
BUFFERING_STATE_UNKNOWN
public static final int BUFFERING_STATE_UNKNOWN
Buffering state is unknown.
Constant Value: 0 (0x00000000)
INVALID_ITEM_INDEX
public static final int INVALID_ITEM_INDEX
Media item index is invalid. This value will be returned when the corresponding media item does not exist.
Constant Value: -1 (0xffffffff)
PLAYER_STATE_ERROR
public static final int PLAYER_STATE_ERROR
State when the player is in error state and cannot be recovered self.
Constant Value: 3 (0x00000003)
PLAYER_STATE_IDLE
public static final int PLAYER_STATE_IDLE
State when the player is idle, and needs configuration to start playback.
Constant Value: 0 (0x00000000)
PLAYER_STATE_PAUSED
public static final int PLAYER_STATE_PAUSED
State when the player's playback is paused
Constant Value: 1 (0x00000001)
PLAYER_STATE_PLAYING
public static final int PLAYER_STATE_PLAYING
State when the player's playback is ongoing
Constant Value: 2 (0x00000002)
REPEAT_MODE_ALL
public static final int REPEAT_MODE_ALL
Playing media list will be repeated.
Constant Value: 2 (0x00000002)
REPEAT_MODE_GROUP
public static final int REPEAT_MODE_GROUP
Playback of the playing media group will be repeated. A group is a logical block of media items which is specified in the section 5.7 of the Bluetooth AVRCP 1.6. An example of a group is the playlist.
Constant Value: 3 (0x00000003)
REPEAT_MODE_NONE
public static final int REPEAT_MODE_NONE
Playback will be stopped at the end of the playing media list.
Constant Value: 0 (0x00000000)
REPEAT_MODE_ONE
public static final int REPEAT_MODE_ONE
Playback of the current playing media item will be repeated.
Constant Value: 1 (0x00000001)
SHUFFLE_MODE_ALL
public static final int SHUFFLE_MODE_ALL
Media list will be played in shuffled order.
Constant Value: 1 (0x00000001)
SHUFFLE_MODE_GROUP
public static final int SHUFFLE_MODE_GROUP
Media group will be played in shuffled order. A group is a logical block of media items which is specified in the section 5.7 of the Bluetooth AVRCP 1.6. An example of a group is the playlist.
Constant Value: 2 (0x00000002)
SHUFFLE_MODE_NONE
public static final int SHUFFLE_MODE_NONE
Media list will be played in order.
Constant Value: 0 (0x00000000)
UNKNOWN_TIME
public static final long UNKNOWN_TIME
Value indicating the time is unknown
Constant Value: -9223372036854775808 (0x8000000000000000)
Public constructors
SessionPlayer
public SessionPlayer ()
Public methods
addPlaylistItem
public abstract ListenableFuture<SessionPlayer.PlayerResult> addPlaylistItem (int index, MediaItem item)
Adds the media item to the playlist at the index. Index equals to or greater than
the current playlist size (e.g. Integer.MAX_VALUE
) will add the item at the end of
the playlist.
If index is less than or equal to the current index of the playlist, the current index of the playlist should be increased correspondingly.
The implementation must notify registered callbacks with
SessionPlayer.PlayerCallback.onPlaylistChanged(SessionPlayer, List, MediaMetadata)
when it's
completed.
The implementation must close the ParcelFileDescriptor
in the FileMediaItem
if the given media item is a FileMediaItem
.
On success, a SessionPlayer.PlayerResult
should be returned with item
added.
Parameters | |
---|---|
index |
int : the index of the item you want to add in the playlist |
item |
MediaItem : the media item you want to add |
Returns | |
---|---|
ListenableFuture<SessionPlayer.PlayerResult> |
close
public void close ()
Removes all existing references to callbacks and executors.
Note: Sub classes of SessionPlayer
that override this API should call this super
method.
deselectTrack
public ListenableFuture<SessionPlayer.PlayerResult> deselectTrack (SessionPlayer.TrackInfo trackInfo)
Deselects the SessionPlayer.TrackInfo
for the current media item.
Generally, a track should already be selected in order to be deselected, and audio and video tracks should not be deselected.
The types of tracks supported may vary based on player implementation.
Note: getSelectedTrack(int)
returns the currently selected track per track type that
can be deselected, but the list may be invalidated when
SessionPlayer.PlayerCallback.onTracksChanged(SessionPlayer, List)
is called.
Parameters | |
---|---|
trackInfo |
SessionPlayer.TrackInfo : track to be deselected |
Returns | |
---|---|
ListenableFuture<SessionPlayer.PlayerResult> |
a ListenableFuture which represents the pending completion of the command |
getAudioAttributes
public abstract AudioAttributesCompat getAudioAttributes ()
Gets the AudioAttributesCompat
that media player has.
Returns | |
---|---|
AudioAttributesCompat |
getBufferedPosition
public abstract long getBufferedPosition ()
Gets the position for how much has been buffered, or UNKNOWN_TIME
if unknown.
The position is the relative position based on the MediaItem.getStartPosition()
.
So the position 0
means the start position of the MediaItem
.
Returns | |
---|---|
long |
the buffered position in ms, or UNKNOWN_TIME if unknown
|
getBufferingState
public abstract int getBufferingState ()
Returns the current buffering state of the player.
During the buffering, see getBufferedPosition()
for the quantifying the amount
already buffered.
Returns | |
---|---|
int |
the buffering state, or BUFFERING_STATE_UNKNOWN if unknown |
See also:
getCurrentMediaItem
public abstract MediaItem getCurrentMediaItem ()
Gets the current media item, which is currently playing or would be played with later
play()
. This value may be updated when
SessionPlayer.PlayerCallback.onCurrentMediaItemChanged(SessionPlayer, MediaItem)
or
SessionPlayer.PlayerCallback.onPlaylistChanged(SessionPlayer, List, MediaMetadata)
is
called.
Returns | |
---|---|
MediaItem |
the current media item. Can be null only when the player is in
PLAYER_STATE_IDLE and a media item or playlist hasn't been set. |
getCurrentMediaItemIndex
public abstract int getCurrentMediaItemIndex ()
Gets the index of current media item in playlist. This value should be updated when
SessionPlayer.PlayerCallback.onCurrentMediaItemChanged(SessionPlayer, MediaItem)
or
SessionPlayer.PlayerCallback.onPlaylistChanged(SessionPlayer, List, MediaMetadata)
is called.
Returns | |
---|---|
int |
the index of current media item. Can be INVALID_ITEM_INDEX when current
media item is null or not in the playlist, and when the playlist hasn't been set.
Value is -1 or greater. |
getCurrentPosition
public abstract long getCurrentPosition ()
Gets the current playback position.
The position is the relative position based on the MediaItem.getStartPosition()
.
So the position 0
means the start position of the MediaItem
.
Returns | |
---|---|
long |
the current playback position in ms, or UNKNOWN_TIME if unknown
|
getDuration
public abstract long getDuration ()
Gets the duration of the current media item, or UNKNOWN_TIME
if unknown. If the
current MediaItem
has either start or end position, then duration would be adjusted
accordingly instead of returning the whole size of the MediaItem
.
Returns | |
---|---|
long |
the duration in ms, or UNKNOWN_TIME if unknown
|
getNextMediaItemIndex
public abstract int getNextMediaItemIndex ()
Gets the next item index in the playlist. This value should be updated when
SessionPlayer.PlayerCallback.onCurrentMediaItemChanged(SessionPlayer, MediaItem)
or
SessionPlayer.PlayerCallback.onPlaylistChanged(SessionPlayer, List, MediaMetadata)
is called.
Returns | |
---|---|
int |
the index of next media item. Can be INVALID_ITEM_INDEX only when next media
item does not exist or playlist hasn't been set.
Value is -1 or greater. |
getPlaybackSpeed
public abstract float getPlaybackSpeed ()
Gets the actual playback speed to be used by the player when playing. A value of 1.0f
is the default playback value, and a negative value indicates reverse playback.
Note that it may differ from the speed set in setPlaybackSpeed(float)
.
Returns | |
---|---|
float |
the actual playback speed |
getPlayerState
public abstract int getPlayerState ()
Gets the current player state.
Returns | |
---|---|
int |
the current player state |
getPlaylist
public abstract List<MediaItem> getPlaylist ()
Gets the playlist. It can be null
if the playlist hasn't been set or it's reset by
setMediaItem(MediaItem)
.
Returns | |
---|---|
List<MediaItem> |
playlist, or null |
getPlaylistMetadata
public abstract MediaMetadata getPlaylistMetadata ()
Gets the playlist metadata.
Returns | |
---|---|
MediaMetadata |
metadata metadata of the playlist, or null if none is set |
getPreviousMediaItemIndex
public abstract int getPreviousMediaItemIndex ()
Gets the previous item index in the playlist. This value should be updated when
SessionPlayer.PlayerCallback.onCurrentMediaItemChanged(SessionPlayer, MediaItem)
or
SessionPlayer.PlayerCallback.onPlaylistChanged(SessionPlayer, List, MediaMetadata)
is called.
Returns | |
---|---|
int |
the index of previous media item. Can be INVALID_ITEM_INDEX only when
previous media item does not exist or playlist hasn't been set.
Value is -1 or greater. |
getRepeatMode
public abstract int getRepeatMode ()
Gets the repeat mode.
Returns | |
---|---|
int |
repeat mode |
getSelectedTrack
public SessionPlayer.TrackInfo getSelectedTrack (int trackType)
Gets currently selected track's SessionPlayer.TrackInfo
for the given track type.
The returned value can be outdated after
SessionPlayer.PlayerCallback.onTracksChanged(SessionPlayer, List)
,
SessionPlayer.PlayerCallback.onTrackSelected(SessionPlayer, TrackInfo)
,
or SessionPlayer.PlayerCallback.onTrackDeselected(SessionPlayer, TrackInfo)
is called.
Parameters | |
---|---|
trackType |
int : type of selected track |
Returns | |
---|---|
SessionPlayer.TrackInfo |
selected track info |
getShuffleMode
public abstract int getShuffleMode ()
Gets the shuffle mode.
Returns | |
---|---|
int |
the shuffle mode |
getTracks
public List<SessionPlayer.TrackInfo> getTracks ()
Gets the full list of selected and unselected tracks that the media contains. The order of the list is irrelevant as different players expose tracks in different ways, but the tracks will generally be ordered based on track type.
The types of tracks supported may vary based on player implementation.
Returns | |
---|---|
List<SessionPlayer.TrackInfo> |
list of tracks. The total number of tracks is the size of the list. If empty,
the implementation should return an empty list instead of null . |
getVideoSize
public VideoSize getVideoSize ()
Gets the size of the video.
Returns | |
---|---|
VideoSize |
the size of the video. The width and height of size could be 0 if there is no video or the size has not been determined yet. |
movePlaylistItem
public ListenableFuture<SessionPlayer.PlayerResult> movePlaylistItem (int fromIndex, int toIndex)
Moves the media item at fromIdx
to toIdx
in the playlist.
The implementation must notify registered callbacks with
SessionPlayer.PlayerCallback.onPlaylistChanged(SessionPlayer, List, MediaMetadata)
when it's
completed.
On success, a SessionPlayer.PlayerResult
should be returned with item
set.
Parameters | |
---|---|
fromIndex |
int : the media item's initial index in the playlist |
toIndex |
int : the media item's target index in the playlist |
Returns | |
---|---|
ListenableFuture<SessionPlayer.PlayerResult> |
pause
public abstract ListenableFuture<SessionPlayer.PlayerResult> pause ()
Pauses playback.
On success, this transfers the player state to PLAYER_STATE_PAUSED
and
a SessionPlayer.PlayerResult
should be returned with the current media item when the command
was completed. If it is called in PLAYER_STATE_IDLE
or PLAYER_STATE_ERROR
,
it should be ignored and a SessionPlayer.PlayerResult
should be returned with
SessionPlayer.PlayerResult.RESULT_ERROR_INVALID_STATE
.
Returns | |
---|---|
ListenableFuture<SessionPlayer.PlayerResult> |
a ListenableFuture representing the pending completion of the command
|
play
public abstract ListenableFuture<SessionPlayer.PlayerResult> play ()
Starts or resumes playback.
On success, this transfers the player state to PLAYER_STATE_PLAYING
and
a SessionPlayer.PlayerResult
should be returned with the current media item when the command
was completed. If it is called in PLAYER_STATE_IDLE
or PLAYER_STATE_ERROR
,
it should be ignored and a SessionPlayer.PlayerResult
should be returned with
SessionPlayer.PlayerResult.RESULT_ERROR_INVALID_STATE
.
Returns | |
---|---|
ListenableFuture<SessionPlayer.PlayerResult> |
a ListenableFuture representing the pending completion of the command
|
prepare
public abstract ListenableFuture<SessionPlayer.PlayerResult> prepare ()
Prepares the media items for playback. During this time, the player may allocate resources
required to play, such as audio and video decoders. Before calling this API, set media
item(s) through either setMediaItem(MediaItem)
or setPlaylist(List
.
On success, this transfers the player state from PLAYER_STATE_IDLE
to
PLAYER_STATE_PAUSED
and a SessionPlayer.PlayerResult
should be returned with the prepared
media item when the command completed. If it's not called in PLAYER_STATE_IDLE
,
it should be ignored and SessionPlayer.PlayerResult
should be returned with
SessionPlayer.PlayerResult.RESULT_ERROR_INVALID_STATE
.
Returns | |
---|---|
ListenableFuture<SessionPlayer.PlayerResult> |
a ListenableFuture representing the pending completion of the command
|
registerPlayerCallback
public final void registerPlayerCallback (Executor executor, SessionPlayer.PlayerCallback callback)
Register SessionPlayer.PlayerCallback
to listen changes.
Parameters | |
---|---|
executor |
Executor : a callback Executor |
callback |
SessionPlayer.PlayerCallback : a PlayerCallback |
Throws | |
---|---|
IllegalArgumentException |
if executor or callback is null .
|
removePlaylistItem
public abstract ListenableFuture<SessionPlayer.PlayerResult> removePlaylistItem (int index)
Removes the media item from the playlist
The implementation must notify registered callbacks with
SessionPlayer.PlayerCallback.onPlaylistChanged(SessionPlayer, List, MediaMetadata)
when it's
completed.
On success, a SessionPlayer.PlayerResult
should be returned with item
removed.
If the last item is removed, the player should be moved to PLAYER_STATE_IDLE
.
Parameters | |
---|---|
index |
int : the index of the item you want to remove in the playlist |
Returns | |
---|---|
ListenableFuture<SessionPlayer.PlayerResult> |
replacePlaylistItem
public abstract ListenableFuture<SessionPlayer.PlayerResult> replacePlaylistItem (int index, MediaItem item)
Replaces the media item at index in the playlist. This can be also used to update metadata of an item.
The implementation must notify registered callbacks with
SessionPlayer.PlayerCallback.onPlaylistChanged(SessionPlayer, List, MediaMetadata)
when it's
completed.
The implementation must close the ParcelFileDescriptor
in the FileMediaItem
if the given media item is a FileMediaItem
.
On success, a SessionPlayer.PlayerResult
should be returned with item
set.
Parameters | |
---|---|
index |
int : the index of the item to replace in the playlist |
item |
MediaItem : the new item |
Returns | |
---|---|
ListenableFuture<SessionPlayer.PlayerResult> |
seekTo
public abstract ListenableFuture<SessionPlayer.PlayerResult> seekTo (long position)
Seeks to the specified position.
The position is the relative position based on the MediaItem.getStartPosition()
. So
calling seekTo(long)
with 0
means the seek to the start position.
On success, a SessionPlayer.PlayerResult
should be returned with the current media item when the
command completed. If it's called in PLAYER_STATE_IDLE
, it is ignored and
a SessionPlayer.PlayerResult
should be returned with
SessionPlayer.PlayerResult.RESULT_ERROR_INVALID_STATE
.
Parameters | |
---|---|
position |
long : the new playback position in ms. The value should be in the range of start
and end positions defined in MediaItem .
|
Returns | |
---|---|
ListenableFuture<SessionPlayer.PlayerResult> |
a ListenableFuture representing the pending completion of the command |
selectTrack
public ListenableFuture<SessionPlayer.PlayerResult> selectTrack (SessionPlayer.TrackInfo trackInfo)
Selects the SessionPlayer.TrackInfo
for the current media item.
Generally one track will be selected for each track type.
The types of tracks supported may vary based on player implementation.
Note: getTracks()
returns the list of tracks that can be selected, but the
list may be invalidated when SessionPlayer.PlayerCallback.onTracksChanged(SessionPlayer, List)
is called.
Parameters | |
---|---|
trackInfo |
SessionPlayer.TrackInfo : track to be selected |
Returns | |
---|---|
ListenableFuture<SessionPlayer.PlayerResult> |
a ListenableFuture representing the pending completion of the command |
setAudioAttributes
public abstract ListenableFuture<SessionPlayer.PlayerResult> setAudioAttributes (AudioAttributesCompat attributes)
Sets the AudioAttributesCompat
to be used during the playback of the media.
You must call this method in PLAYER_STATE_IDLE
in order for the audio attributes to
become effective thereafter. Otherwise, the call would be ignored and SessionPlayer.PlayerResult
should be returned with SessionPlayer.PlayerResult.RESULT_ERROR_INVALID_STATE
.
On success, a SessionPlayer.PlayerResult
should be returned with the current media item when the
command completed.
Parameters | |
---|---|
attributes |
AudioAttributesCompat : non-null AudioAttributes .
|
Returns | |
---|---|
ListenableFuture<SessionPlayer.PlayerResult> |
setMediaItem
public abstract ListenableFuture<SessionPlayer.PlayerResult> setMediaItem (MediaItem item)
Sets a MediaItem
for playback. Use this or setPlaylist(List
to specify which
items to play. If you want to change current item in the playlist, use one of
skipToPlaylistItem(int)
, skipToNextPlaylistItem()
, or
skipToPreviousPlaylistItem()
instead of this method.
This can be called multiple times in any states other than PLAYER_STATE_ERROR
. This
would override previous setMediaItem(MediaItem)
or setPlaylist(List
calls.
It's recommended to fill MediaMetadata
in MediaItem
especially for the
duration information with the key MediaMetadata.METADATA_KEY_DURATION
. Without the
duration information in the metadata, session will do extra work to get the duration and send
it to the controller.
The implementation must notify registered callbacks with
SessionPlayer.PlayerCallback.onPlaylistChanged(SessionPlayer, List
and SessionPlayer.PlayerCallback.onCurrentMediaItemChanged(SessionPlayer, MediaItem)
when it's completed. The current item would be the item given here.
The implementation must close the ParcelFileDescriptor
in the FileMediaItem
if the given media item is a FileMediaItem
.
On success, a SessionPlayer.PlayerResult
should be returned with item
set.
Parameters | |
---|---|
item |
MediaItem : the descriptor of media item you want to play |
Returns | |
---|---|
ListenableFuture<SessionPlayer.PlayerResult> |
a ListenableFuture which represents the pending completion of the command |
Throws | |
---|---|
IllegalArgumentException |
if the given item is null .
|
setPlaybackSpeed
public abstract ListenableFuture<SessionPlayer.PlayerResult> setPlaybackSpeed (float playbackSpeed)
Sets the playback speed. The default playback speed is 1.0f
, and negative values
indicate reverse playback and 0.0f
is not allowed.
The supported playback speed range depends on the underlying player implementation, so it is
recommended to query the actual speed of the player via getPlaybackSpeed()
after the
operation completes. In particular, please note that player implementations may not support
reverse playback.
On success, a SessionPlayer.PlayerResult
should be returned with the current media item when the
command completed.
Parameters | |
---|---|
playbackSpeed |
float : the requested playback speed |
Returns | |
---|---|
ListenableFuture<SessionPlayer.PlayerResult> |
a ListenableFuture representing the pending completion of the command |
setPlaylist
public abstract ListenableFuture<SessionPlayer.PlayerResult> setPlaylist (List<MediaItem> list, MediaMetadata metadata)
Sets a list of MediaItem
with metadata. Use this or setMediaItem(MediaItem)
to specify
which items to play.
This can be called multiple times in any states other than PLAYER_STATE_ERROR
. This
would override previous setMediaItem(MediaItem)
or setPlaylist(List
calls.
Ensure uniqueness of each MediaItem
in the playlist so the session can uniquely
identity individual items. All MediaItem
s shouldn't be null
as well.
It's recommended to fill MediaMetadata
in each MediaItem
especially for the
duration information with the key MediaMetadata.METADATA_KEY_DURATION
. Without the
duration information in the metadata, session will do extra work to get the duration and send
it to the controller.
The implementation must notify registered callbacks with
SessionPlayer.PlayerCallback.onPlaylistChanged(SessionPlayer, List
and SessionPlayer.PlayerCallback.onCurrentMediaItemChanged(SessionPlayer, MediaItem)
when it's completed. The current media item would be the first item in the playlist.
The implementation must close the ParcelFileDescriptor
in the FileMediaItem
when a media item in the playlist is a FileMediaItem
.
On success, a SessionPlayer.PlayerResult
should be returned with the first media item of the
playlist when the command completed.
Parameters | |
---|---|
list |
List : a list of MediaItem objects to set as a play list |
metadata |
MediaMetadata |
Returns | |
---|---|
ListenableFuture<SessionPlayer.PlayerResult> |
a ListenableFuture which represents the pending completion of the command |
Throws | |
---|---|
IllegalArgumentException |
if the given list is null or empty, or has
duplicated media items. |
setRepeatMode
public abstract ListenableFuture<SessionPlayer.PlayerResult> setRepeatMode (int repeatMode)
Sets the repeat mode.
The implementation must notify registered callbacks with
SessionPlayer.PlayerCallback.onRepeatModeChanged(SessionPlayer, int)
when it's completed.
On success, a SessionPlayer.PlayerResult
should be returned with the current media item when the
command completed.
Parameters | |
---|---|
repeatMode |
int : repeat mode |
Returns | |
---|---|
ListenableFuture<SessionPlayer.PlayerResult> |
setShuffleMode
public abstract ListenableFuture<SessionPlayer.PlayerResult> setShuffleMode (int shuffleMode)
Sets the shuffle mode.
The implementation must notify registered callbacks with
SessionPlayer.PlayerCallback.onShuffleModeChanged(SessionPlayer, int)
when it's completed.
On success, a SessionPlayer.PlayerResult
should be returned with the current media item when the
command completed.
Parameters | |
---|---|
shuffleMode |
int : the shuffle mode |
Returns | |
---|---|
ListenableFuture<SessionPlayer.PlayerResult> |
a ListenableFuture representing the pending completion of the command |
setSurface
public ListenableFuture<SessionPlayer.PlayerResult> setSurface (Surface surface)
Sets the Surface
to be used as the sink for the video portion of the media.
A null surface will reset any Surface and result in only the audio track being played.
On success, a SessionPlayer.PlayerResult
is returned with
the current media item when the command completed.
Parameters | |
---|---|
surface |
Surface : the Surface to be used for the video portion of the media |
Returns | |
---|---|
ListenableFuture<SessionPlayer.PlayerResult> |
a ListenableFuture which represents the pending completion of the command
|
skipToNextPlaylistItem
public abstract ListenableFuture<SessionPlayer.PlayerResult> skipToNextPlaylistItem ()
Skips to the next item in the playlist.
The implementation must notify registered callbacks with
SessionPlayer.PlayerCallback.onCurrentMediaItemChanged(SessionPlayer, MediaItem)
when it's
completed.
On success, a SessionPlayer.PlayerResult
should be returned with the current media item when the
command completed.
Returns | |
---|---|
ListenableFuture<SessionPlayer.PlayerResult> |
a ListenableFuture representing the pending completion of the command |
skipToPlaylistItem
public abstract ListenableFuture<SessionPlayer.PlayerResult> skipToPlaylistItem (int index)
Skips to the item in the playlist at the index.
The implementation must notify registered callbacks with
SessionPlayer.PlayerCallback.onCurrentMediaItemChanged(SessionPlayer, MediaItem)
when it's
completed.
On success, a SessionPlayer.PlayerResult
should be returned with the current media item when the
command completed.
Parameters | |
---|---|
index |
int : the index of the item you want to play in the playlist |
Returns | |
---|---|
ListenableFuture<SessionPlayer.PlayerResult> |
skipToPreviousPlaylistItem
public abstract ListenableFuture<SessionPlayer.PlayerResult> skipToPreviousPlaylistItem ()
Skips to the previous item in the playlist.
The implementation must notify registered callbacks with
SessionPlayer.PlayerCallback.onCurrentMediaItemChanged(SessionPlayer, MediaItem)
when it's
completed.
On success, a SessionPlayer.PlayerResult
should be returned with the current media item when the
command completed.
Returns | |
---|---|
ListenableFuture<SessionPlayer.PlayerResult> |
a ListenableFuture representing the pending completion of the command |
unregisterPlayerCallback
public final void unregisterPlayerCallback (SessionPlayer.PlayerCallback callback)
Unregister the previously registered SessionPlayer.PlayerCallback
.
Parameters | |
---|---|
callback |
SessionPlayer.PlayerCallback : the callback to be removed |
Throws | |
---|---|
IllegalArgumentException |
if the callback is null .
|
updatePlaylistMetadata
public abstract ListenableFuture<SessionPlayer.PlayerResult> updatePlaylistMetadata (MediaMetadata metadata)
Updates the playlist metadata while keeping the playlist as-is.
The implementation must notify registered callbacks with
SessionPlayer.PlayerCallback.onPlaylistMetadataChanged(SessionPlayer, MediaMetadata)
when it's
completed.
On success, a SessionPlayer.PlayerResult
should be returned with the current media item when the
command completed.
Parameters | |
---|---|
metadata |
MediaMetadata : metadata of the playlist |
Returns | |
---|---|
ListenableFuture<SessionPlayer.PlayerResult> |
Protected methods
getCallbacks
protected final List<Pair<SessionPlayer.PlayerCallback, Executor>> getCallbacks ()
Gets the callbacks with executors for subclasses to notify player events.
Returns | |
---|---|
List<Pair<SessionPlayer.PlayerCallback, Executor>> |
map of callbacks and its executors |
Content and code samples on this page are subject to the licenses described in the Content License. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2021-04-21 UTC.