MediaPlayer

const val MEDIA_INFO_AUDIO_NOT_PLAYING = 804: Int

Informs that audio is not playing. Note that playback of the video is not interrupted.

const val MEDIA_INFO_BAD_INTERLEAVING = 800: Int

Bad interleaving means that a media has been improperly interleaved or not interleaved at all, e.g has all the video samples first then all the audio ones. Video is playing but a lot of disk seeks may be happening.

const val MEDIA_INFO_BUFFERING_UPDATE = 704: Int

Update status in buffering a media source received through progressive downloading. The received buffering percentage indicates how much of the content has been buffered or played. For example a buffering update of 80 percent when half the content has already been played indicates that the next 30 percent of the content to play has been buffered.

The extra parameter in onInfo is the percentage (0-100) of the content that has been buffered or played thus far.

const val MEDIA_INFO_METADATA_UPDATE = 802: Int

A new set of metadata is available.

const val MEDIA_INFO_NOT_SEEKABLE = 801: Int

The media cannot be seeked (e.g live stream)

const val MEDIA_INFO_VIDEO_NOT_PLAYING = 805: Int

Informs that video is not playing. Note that playback of the audio is not interrupted.

const val MEDIA_INFO_VIDEO_RENDERING_START = 3: Int

The player just pushed the very first video frame for rendering.

const val MEDIA_INFO_VIDEO_TRACK_LAGGING = 700: Int

The video is too complex for the decoder: it can't decode frames fast enough. Possibly only the audio plays fine at this stage.

const val NO_TRACK_SELECTED = -2147483648: Int

The return value of getSelectedTrack when there is no selected track for the given type.

const val PLAYER_ERROR_IO = -1004: Int

File or network related operation errors.

const val PLAYER_ERROR_MALFORMED = -1007: Int

Bitstream is not conforming to the related coding standard or file spec.

const val PLAYER_ERROR_TIMED_OUT = -110: Int

Some operation takes too long to complete, usually more than 3-5 seconds.

const val PLAYER_ERROR_UNKNOWN = 1: Int

Unspecified player error.

const val PLAYER_ERROR_UNSUPPORTED = -1010: Int

Bitstream is conforming to the related coding standard or file spec, but the media framework does not support the feature.

const val SEEK_CLOSEST = 3: Int

This mode is used with seekTo to move media position to a frame (not necessarily a key frame) associated with a media item that is located closest to or at the given time.

const val SEEK_CLOSEST_SYNC = 2: Int

This mode is used with seekTo to move media position to a sync (or key) frame associated with a media item that is located closest to (in time) or at the given time.

const val SEEK_NEXT_SYNC = 1: Int

This mode is used with seekTo to move media position to a sync (or key) frame associated with a media item that is located right after or at the given time.

const val SEEK_PREVIOUS_SYNC = 0: Int

This mode is used with seekTo to move media position to a sync (or key) frame associated with a media item that is located right before or at the given time.

MediaPlayer(context: Context)

Constructor to create a MediaPlayer instance.

fun addPlaylistItem(index: Int, item: MediaItem): ListenableFuture<SessionPlayer.PlayerResult!>

Adds the media item to the playlist at the index. Index equals to or greater than the current playlist size (e.g. 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 would be increased correspondingly.

On success, a SessionPlayer.PlayerResult would be returned with item added.

fun attachAuxEffect(effectId: Int): ListenableFuture<SessionPlayer.PlayerResult!>

Attaches an auxiliary effect to the player. A typical auxiliary effect is a reverberation effect which can be applied on any sound source that directs a certain amount of its energy to this effect. This amount is defined by setAuxEffectSendLevel(). See setAuxEffectSendLevel.

After creating an auxiliary effect (e.g. android.media.audiofx.EnvironmentalReverb), retrieve its ID with getId and use it when calling this method to attach the player to the effect.

To detach the effect from the player, call this method with a null effect id.

This method must be called before setMediaItem and setPlaylist methods.

fun close(): Unit

Closes the player and relinquish underlying resources.

fun deselectTrack(trackInfo: SessionPlayer.TrackInfo): ListenableFuture<SessionPlayer.PlayerResult!>

Deselects the TrackInfo for the current media item.

The track must be a subtitle track, and no audio or video tracks can be deselected.

Note: getSelectedTrack returns the currently selected track per track type that can be deselected, but the list may be invalidated when onTracksChanged is called.

fun getAudioAttributes(): AudioAttributesCompat?

Gets the AudioAttributesCompat that media player has.

fun getAudioSessionId(): Int

Returns the audio session ID.

fun getBufferedPosition(): Long

Gets the position for how much has been buffered, or UNKNOWN_TIME if unknown.

The position is the relative position based on the getStartPosition. So the position 0 means the start position of the MediaItem.

fun getBufferingState(): Int

Returns the current buffering state of the player.

During the buffering, see getBufferedPosition for the quantifying the amount already buffered.

fun getCurrentMediaItem(): MediaItem?

Gets the current media item, which is currently playing or would be played with later play. This value may be updated when onCurrentMediaItemChanged or onPlaylistChanged is called.

fun getCurrentMediaItemIndex(): Int

Gets the index of current media item in playlist. This value would be updated when onCurrentMediaItemChanged or onPlaylistChanged is called.

fun getCurrentPosition(): Long

Gets the current playback position.

The position is the relative position based on the getStartPosition. So the position 0 means the start position of the MediaItem.

fun getDuration(): Long

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.

fun getNextMediaItemIndex(): Int

Gets the next item index in the playlist. This value would be updated when onCurrentMediaItemChanged or onPlaylistChanged is called.

fun getPlaybackParams(): PlaybackParams

Gets the playback params, containing the current playback rate.

fun getPlaybackSpeed(): @FloatRange(from = 0.0, to = Float.MAX_VALUE, fromInclusive = false) Float

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.

fun getPlayerState(): Int

Gets the current player state.

fun getPlaylist(): (Mutable)List<MediaItem!>?

Gets the playlist. It can be null if the playlist hasn't been set or it's reset by setMediaItem.

fun getPlaylistMetadata(): MediaMetadata?

Gets the playlist metadata.

fun getPreviousMediaItemIndex(): Int

Gets the previous item index in the playlist. This value would be updated when onCurrentMediaItemChanged or onPlaylistChanged is called.

fun getRepeatMode(): Int

Gets the repeat mode.

fun getSelectedTrack(trackType: Int): MediaPlayer.TrackInfo?

Returns the selected track for the given track type. The return value is an element in the list returned by getTracks.

fun getShuffleMode(): Int

Gets the shuffle mode.

fun getTimestamp(): MediaTimestamp?

Gets current playback position as a MediaTimestamp.

The MediaTimestamp represents how the media time correlates to the system time in a linear fashion using an anchor and a clock rate. During regular playback, the media time moves fairly constantly (though the anchor frame may be rebased to a current system time, the linear correlation stays steady). Therefore, this method does not need to be called often.

To help users get current playback position, this method always anchors the timestamp to the current system time, so getAnchorMediaTimeUs can be used as current playback position.

fun getTracks(): (Mutable)List<SessionPlayer.TrackInfo!>

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.

fun getVideoSize(): VideoSize

Returns the size of the video.

fun movePlaylistItem(fromIndex: Int, toIndex: Int): ListenableFuture<SessionPlayer.PlayerResult!>

Moves the media item at fromIdx to toIdx in the playlist.

On success, a SessionPlayer.PlayerResult would be returned with item set.

fun pause(): ListenableFuture<SessionPlayer.PlayerResult!>

Pauses playback.

On success, this transfers the player state to PLAYER_STATE_PAUSED and a SessionPlayer.PlayerResult would 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 would be ignored and a SessionPlayer.PlayerResult would be returned with RESULT_ERROR_INVALID_STATE.

fun play(): ListenableFuture<SessionPlayer.PlayerResult!>

Starts or resumes playback.

On success, this transfers the player state to PLAYER_STATE_PLAYING and a SessionPlayer.PlayerResult would 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 would be ignored and a SessionPlayer.PlayerResult would be returned with RESULT_ERROR_INVALID_STATE.

fun prepare(): ListenableFuture<SessionPlayer.PlayerResult!>

Prepares the media items for playback. Before calling this API, set media item(s) through either setMediaItem or setPlaylist, and set a display surface through setSurface when needed.

On success, this transfers the player state from PLAYER_STATE_IDLE to PLAYER_STATE_PAUSED and a SessionPlayer.PlayerResult would be returned with the prepared media item when the command completed. If it's not called in PLAYER_STATE_IDLE, it would be ignored and SessionPlayer.PlayerResult would be returned with RESULT_ERROR_INVALID_STATE.

fun registerPlayerCallback(
    executor: Executor,
    callback: MediaPlayer.PlayerCallback
): Unit

Register PlayerCallback to listen changes.

fun removePlaylistItem(index: @IntRange(from = 0) Int): ListenableFuture<SessionPlayer.PlayerResult!>

Removes the media item from the playlist

On success, a SessionPlayer.PlayerResult would be returned with item removed.

fun replacePlaylistItem(index: Int, item: MediaItem): ListenableFuture<SessionPlayer.PlayerResult!>

Replaces the media item at index in the playlist. This can be also used to update metadata of an item.

On success, a SessionPlayer.PlayerResult would be returned with item set.

fun reset(): Unit

Resets MediaPlayer to its uninitialized state if not closed. After calling this method, you will have to initialize it again by setting the media item and calling prepare.

Note that if the player is closed, there is no way to reuse the instance.

fun seekTo(position: Long): ListenableFuture<SessionPlayer.PlayerResult!>

Seeks to the specified position.

The position is the relative position based on the getStartPosition. So calling seekTo with 0 means the seek to the start position.

On success, a SessionPlayer.PlayerResult would 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 would be returned with RESULT_ERROR_INVALID_STATE.

fun seekTo(position: Long, mode: Int): ListenableFuture<SessionPlayer.PlayerResult!>

Moves the media to specified time position by considering the given mode.

There is at most one active seekTo processed at any time. If there is a to-be-completed seekTo, new seekTo requests will be queued in such a way that only the last request is kept. When current seekTo is completed, the queued request will be processed if that request is different from just-finished seekTo operation, i.e., the requested position or mode is different.

On success, a SessionPlayer.PlayerResult is returned with the current media item when the command completed.

fun selectTrack(trackInfo: SessionPlayer.TrackInfo): ListenableFuture<SessionPlayer.PlayerResult!>

Selects the TrackInfo for the current media item.

If the player is in invalid state, RESULT_ERROR_INVALID_STATE will be reported with SessionPlayer.PlayerResult. If a player is in Playing state, the selected track is presented immediately. If a player is not in Playing state, it just marks the track to be played.

In any valid state, if it is called multiple times on the same type of track (ie. Video, Audio), the most recent one will be chosen.

The first audio and video tracks are selected by default if available, even though this method is not called.

Currently, tracks that return true for isSelectable can be selected via this method.

fun setAudioAttributes(attributes: AudioAttributesCompat): ListenableFuture<SessionPlayer.PlayerResult!>

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 would be returned with RESULT_ERROR_INVALID_STATE.

On success, a SessionPlayer.PlayerResult would be returned with the current media item when the command completed.

fun setAudioSessionId(sessionId: Int): ListenableFuture<SessionPlayer.PlayerResult!>

Sets the audio session ID.

fun setAuxEffectSendLevel(level: @FloatRange(from = 0, to = 1) Float): ListenableFuture<SessionPlayer.PlayerResult!>

Sets the send level of the player to the attached auxiliary effect. See attachAuxEffect. The level value range is 0 to 1.0.

By default the send level is 0, so even if an effect is attached to the player this method must be called for the effect to be applied.

Note that the passed level value is a raw scalar. UI controls should be scaled logarithmically: the gain applied by audio framework ranges from -72dB to 0dB, so an appropriate conversion from linear UI input x to level is: x == 0 -> level = 0, 0 level = 10^(72*(x-R)/20/R)

On success, a SessionPlayer.PlayerResult is returned with the current media item when the command completed.

fun setMediaItem(item: MediaItem): ListenableFuture<SessionPlayer.PlayerResult!>

Sets a MediaItem for playback. Use this or setPlaylist to specify which items to play. If you want to change current item in the playlist, use one of skipToPlaylistItem, skipToNextPlaylistItem, or skipToPreviousPlaylistItem instead of this method.

When this is called multiple times in any states other than PLAYER_STATE_ERROR, it would override previous setMediaItem or setPlaylist calls.

It's recommended to fill MediaMetadata in MediaItem especially for the duration information with the key 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.

On success, a SessionPlayer.PlayerResult would be returned with item set.

fun setPlaybackParams(params: PlaybackParams): ListenableFuture<SessionPlayer.PlayerResult!>

Sets playback params using PlaybackParams.

On success, a SessionPlayer.PlayerResult is returned with the current media item when the command completed.

fun setPlaybackSpeed(
    playbackSpeed: @FloatRange(from = 0.0, to = Float.MAX_VALUE, fromInclusive = false) Float
): ListenableFuture<SessionPlayer.PlayerResult!>

Sets the playback speed. The default playback speed is 1.0f, and values less than or equals to 0.0f is not allowed.

On success, a SessionPlayer.PlayerResult would be returned with the current media item when the command completed.

fun setPlayerVolume(volume: @FloatRange(from = 0, to = 1) Float): ListenableFuture<SessionPlayer.PlayerResult!>

Sets the volume of the audio of the media to play, expressed as a linear multiplier on the audio samples.

Note that this volume is specific to the player, and is separate from stream volume used across the platform.

A value of 0.0f indicates muting, a value of 1.0f is the nominal unattenuated and unamplified gain. See getMaxPlayerVolume for the volume range supported by this player.

The default player volume is 1.0f.

On success, a SessionPlayer.PlayerResult is returned with the current media item when the command completed.

fun setPlaylist(list: (Mutable)List<MediaItem!>, metadata: MediaMetadata?): ListenableFuture<SessionPlayer.PlayerResult!>

Sets a list of MediaItem with metadata. Use this or setMediaItem 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 or setPlaylist calls.

Ensure uniqueness of each MediaItem in the playlist so the session can uniquely identity individual items. All MediaItems wouldn't be null as well.

It's recommended to fill MediaMetadata in each MediaItem especially for the duration information with the key 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.

On success, a SessionPlayer.PlayerResult would be returned with the first media item of the playlist when the command completed.

fun setRepeatMode(repeatMode: Int): ListenableFuture<SessionPlayer.PlayerResult!>

Sets the repeat mode.

On success, a SessionPlayer.PlayerResult would be returned with the current media item when the command completed.

fun setShuffleMode(shuffleMode: Int): ListenableFuture<SessionPlayer.PlayerResult!>

Sets the shuffle mode.

On success, a SessionPlayer.PlayerResult would be returned with the current media item when the command completed.

fun setSurface(surface: Surface?): ListenableFuture<SessionPlayer.PlayerResult!>

Sets the Surface to be used as the sink for the video portion of the media.

A null surface will result in only the audio track being played.

If the Surface sends frames to a SurfaceTexture, the timestamps returned from getTimestamp will have an unspecified zero point. These timestamps cannot be directly compared between different media sources, different instances of the same media source, or multiple runs of the same program. The timestamp is normally monotonically increasing and is unaffected by time-of-day adjustments, but it is reset when the position is set.

On success, a SessionPlayer.PlayerResult is returned with the current media item when the command completed.

fun skipToNextPlaylistItem(): ListenableFuture<SessionPlayer.PlayerResult!>

Skips to the next item in the playlist.

On success, a SessionPlayer.PlayerResult would be returned with the current media item when the command completed.

fun skipToPlaylistItem(index: @IntRange(from = 0) Int): ListenableFuture<SessionPlayer.PlayerResult!>

Skips to the item in the playlist at the index.

On success, a SessionPlayer.PlayerResult would be returned with the current media item when the command completed.

fun skipToPreviousPlaylistItem(): ListenableFuture<SessionPlayer.PlayerResult!>

Skips to the previous item in the playlist.

On success, a SessionPlayer.PlayerResult would be returned with the current media item when the command completed.

fun unregisterPlayerCallback(callback: MediaPlayer.PlayerCallback): Unit

Unregister the previously registered PlayerCallback.

fun updatePlaylistMetadata(metadata: MediaMetadata?): ListenableFuture<SessionPlayer.PlayerResult!>

Updates the playlist metadata while keeping the playlist as-is.

On success, a SessionPlayer.PlayerResult swuld be returned with the current media item when the command completed.