com.google.android.exoplayer2.ext.mediasession

Class MediaSessionConnector

java.lang.Object

com.google.android.exoplayer2.ext.mediasession.MediaSessionConnector

public final class MediaSessionConnector
extends java.lang.Object

Connects a MediaSessionCompat to a Player.

The connector listens for actions sent by the media session's controller and implements these actions by calling appropriate player methods. The playback state of the media session is automatically synced with the player. The connector can also be optionally extended by providing various collaborators:

• Actions to initiate media playback (PlaybackStateCompat#ACTION_PREPARE_* and PlaybackStateCompat#ACTION_PLAY_*) can be handled by a MediaSessionConnector.PlaybackPreparer passed when calling setPlayer(Player, PlaybackPreparer, CustomActionProvider...). Custom actions can be handled by passing one or more MediaSessionConnector.CustomActionProviders in a similar way.
• To enable a media queue and navigation within it, you can set a MediaSessionConnector.QueueNavigator by calling setQueueNavigator(QueueNavigator). Use of TimelineQueueNavigator is recommended for most use cases.
• To enable editing of the media queue, you can set a MediaSessionConnector.QueueEditor by calling setQueueEditor(QueueEditor).
• An ErrorMessageProvider for providing human readable error messages and corresponding error codes can be set by calling setErrorMessageProvider(ErrorMessageProvider).

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	MediaSessionConnector.CommandReceiver Receiver of media commands sent by a media controller.
static interface	MediaSessionConnector.CustomActionProvider Provides a PlaybackStateCompat.CustomAction to be published and handles the action when sent by a media controller.
static class	MediaSessionConnector.DefaultMediaMetadataProvider Provides a default MediaMetadataCompat with properties and extras propagated from the active queue item to the session metadata.
static interface	MediaSessionConnector.MediaMetadataProvider Provides a MediaMetadataCompat for a given player state.
static interface	MediaSessionConnector.PlaybackController Interface to which playback actions are delegated.
static interface	MediaSessionConnector.PlaybackPreparer Interface to which playback preparation actions are delegated.
static interface	MediaSessionConnector.QueueEditor Handles media session queue edits.
static interface	MediaSessionConnector.QueueNavigator Handles queue navigation actions, and updates the media session queue by calling MediaSessionCompat.setQueue().
static interface	MediaSessionConnector.RatingCallback Callback receiving a user rating for the active media item.

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_REPEAT_TOGGLE_MODES The default repeat toggle modes which is the bitmask of RepeatModeUtil.REPEAT_TOGGLE_MODE_ONE and RepeatModeUtil.REPEAT_TOGGLE_MODE_ALL.
static java.lang.String	EXTRAS_PITCH
android.support.v4.media.session.MediaSessionCompat	mediaSession The wrapped MediaSessionCompat.

Constructor Summary

Constructors

Constructor and Description
MediaSessionConnector(android.support.v4.media.session.MediaSessionCompat mediaSession) Creates an instance.
MediaSessionConnector(android.support.v4.media.session.MediaSessionCompat mediaSession, MediaSessionConnector.PlaybackController playbackController) Creates an instance.
MediaSessionConnector(android.support.v4.media.session.MediaSessionCompat mediaSession, MediaSessionConnector.PlaybackController playbackController, boolean doMaintainMetadata, java.lang.String metadataExtrasPrefix) Deprecated. Use MediaSessionConnector(MediaSessionCompat, PlaybackController, MediaMetadataProvider).
MediaSessionConnector(android.support.v4.media.session.MediaSessionCompat mediaSession, MediaSessionConnector.PlaybackController playbackController, MediaSessionConnector.MediaMetadataProvider mediaMetadataProvider) Creates an instance.

Method Summary

Modifier and Type	Method and Description
void	invalidateMediaSessionMetadata() Updates the metadata of the media session.
void	invalidateMediaSessionPlaybackState() Updates the playback state of the media session.
void	invalidateMediaSessionQueue() Updates the queue of the media session by calling MediaSessionConnector.QueueNavigator.onTimelineChanged(Player).
void	setCustomErrorMessage(java.lang.CharSequence message) Sets a custom error on the session.
void	setCustomErrorMessage(java.lang.CharSequence message, int code) Sets a custom error on the session.
void	setErrorMessageProvider(com.google.android.exoplayer2.util.ErrorMessageProvider<? super com.google.android.exoplayer2.ExoPlaybackException> errorMessageProvider) Sets the optional ErrorMessageProvider.
void	setPlayer(com.google.android.exoplayer2.Player player, MediaSessionConnector.PlaybackPreparer playbackPreparer, MediaSessionConnector.CustomActionProvider... customActionProviders) Sets the player to be connected to the media session.
void	setQueueEditor(MediaSessionConnector.QueueEditor queueEditor) Sets the MediaSessionConnector.QueueEditor to handle queue edits sent by the media controller.
void	setQueueNavigator(MediaSessionConnector.QueueNavigator queueNavigator) Sets the MediaSessionConnector.QueueNavigator to handle queue navigation actions ACTION_SKIP_TO_NEXT, ACTION_SKIP_TO_PREVIOUS and ACTION_SKIP_TO_QUEUE_ITEM.
void	setRatingCallback(MediaSessionConnector.RatingCallback ratingCallback) Sets the MediaSessionConnector.RatingCallback to handle user ratings.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_REPEAT_TOGGLE_MODES

@RepeatModeUtil.RepeatToggleModes
public static final int DEFAULT_REPEAT_TOGGLE_MODES

The default repeat toggle modes which is the bitmask of RepeatModeUtil.REPEAT_TOGGLE_MODE_ONE and RepeatModeUtil.REPEAT_TOGGLE_MODE_ALL.

See Also:

Constant Field Values

EXTRAS_PITCH

public static final java.lang.String EXTRAS_PITCH

See Also:

Constant Field Values

mediaSession

public final android.support.v4.media.session.MediaSessionCompat mediaSession

The wrapped MediaSessionCompat.

Constructor Detail

MediaSessionConnector

public MediaSessionConnector(android.support.v4.media.session.MediaSessionCompat mediaSession)

Creates an instance.

Equivalent to MediaSessionConnector(mediaSession, new DefaultPlaybackController()).

Parameters:

mediaSession - The MediaSessionCompat to connect to.

MediaSessionConnector

public MediaSessionConnector(android.support.v4.media.session.MediaSessionCompat mediaSession,
                             MediaSessionConnector.PlaybackController playbackController)

Creates an instance.

Equivalent to MediaSessionConnector(mediaSession, playbackController, new DefaultMediaMetadataProvider(mediaSession.getController(), null)).

Parameters:

mediaSession - The MediaSessionCompat to connect to.

playbackController - A MediaSessionConnector.PlaybackController for handling playback actions.

MediaSessionConnector

@Deprecated
public MediaSessionConnector(android.support.v4.media.session.MediaSessionCompat mediaSession,
                                         @Nullable
                                         MediaSessionConnector.PlaybackController playbackController,
                                         boolean doMaintainMetadata,
                                         @Nullable
                                         java.lang.String metadataExtrasPrefix)

Deprecated. Use MediaSessionConnector(MediaSessionCompat, PlaybackController, MediaMetadataProvider).

Creates an instance.

Parameters:

mediaSession - The MediaSessionCompat to connect to.

playbackController - A MediaSessionConnector.PlaybackController for handling playback actions, or null if the connector should handle playback actions directly.

doMaintainMetadata - Whether the connector should maintain the metadata of the session.

metadataExtrasPrefix - A string to prefix extra keys which are propagated from the active queue item to the session metadata.

MediaSessionConnector

public MediaSessionConnector(android.support.v4.media.session.MediaSessionCompat mediaSession,
                             @Nullable
                             MediaSessionConnector.PlaybackController playbackController,
                             @Nullable
                             MediaSessionConnector.MediaMetadataProvider mediaMetadataProvider)

Creates an instance.

Parameters:

mediaSession - The MediaSessionCompat to connect to.

playbackController - A MediaSessionConnector.PlaybackController for handling playback actions, or null if the connector should handle playback actions directly.

mediaMetadataProvider - A MediaSessionConnector.MediaMetadataProvider for providing a custom metadata object to be published to the media session, or null if metadata shouldn't be published.

Method Detail

setPlayer

public void setPlayer(@Nullable
                      com.google.android.exoplayer2.Player player,
                      @Nullable
                      MediaSessionConnector.PlaybackPreparer playbackPreparer,
                      MediaSessionConnector.CustomActionProvider... customActionProviders)

Sets the player to be connected to the media session. Must be called on the same thread that is used to access the player.

The order in which any MediaSessionConnector.CustomActionProviders are passed determines the order of the actions published with the playback state of the session.

Parameters:

player - The player to be connected to the MediaSession, or null to disconnect the current player.

playbackPreparer - An optional MediaSessionConnector.PlaybackPreparer for preparing the player.

customActionProviders - Optional MediaSessionConnector.CustomActionProviders to publish and handle custom actions.

setErrorMessageProvider

public void setErrorMessageProvider(@Nullable
                                    com.google.android.exoplayer2.util.ErrorMessageProvider<? super com.google.android.exoplayer2.ExoPlaybackException> errorMessageProvider)

Sets the optional ErrorMessageProvider.

Parameters:

errorMessageProvider - The error message provider.

setQueueNavigator

public void setQueueNavigator(MediaSessionConnector.QueueNavigator queueNavigator)

Sets the MediaSessionConnector.QueueNavigator to handle queue navigation actions ACTION_SKIP_TO_NEXT, ACTION_SKIP_TO_PREVIOUS and ACTION_SKIP_TO_QUEUE_ITEM.

Parameters:

queueNavigator - The queue navigator.

setQueueEditor

public void setQueueEditor(MediaSessionConnector.QueueEditor queueEditor)

Sets the MediaSessionConnector.QueueEditor to handle queue edits sent by the media controller.

Parameters:

queueEditor - The queue editor.

setRatingCallback

public void setRatingCallback(MediaSessionConnector.RatingCallback ratingCallback)

Sets the MediaSessionConnector.RatingCallback to handle user ratings.

Parameters:

ratingCallback - The rating callback.

setCustomErrorMessage

public void setCustomErrorMessage(@Nullable
                                  java.lang.CharSequence message)

Sets a custom error on the session.

This sets the error code via PlaybackStateCompat.Builder#setErrorMessage(int, CharSequence). By default, the error code will be set to PlaybackStateCompat.ERROR_CODE_APP_ERROR.

Parameters:

message - The error string to report or null to clear the error.

setCustomErrorMessage

public void setCustomErrorMessage(@Nullable
                                  java.lang.CharSequence message,
                                  int code)

Sets a custom error on the session.

Parameters:

message - The error string to report or null to clear the error.

code - The error code to report. Ignored when message is null.

invalidateMediaSessionMetadata

public final void invalidateMediaSessionMetadata()

Updates the metadata of the media session.

Apps normally only need to call this method when the backing data for a given media item has changed and the metadata should be updated immediately.

invalidateMediaSessionPlaybackState

public final void invalidateMediaSessionPlaybackState()

Updates the playback state of the media session.

Apps normally only need to call this method when the custom actions provided by a MediaSessionConnector.CustomActionProvider changed and the playback state needs to be updated immediately.

invalidateMediaSessionQueue

public final void invalidateMediaSessionQueue()

Updates the queue of the media session by calling MediaSessionConnector.QueueNavigator.onTimelineChanged(Player).

Apps normally only need to call this method when the backing data for a given queue item has changed and the queue should be updated immediately.