Package com.google.android.exoplayer2.ext.mediasession

## Class MediaSessionConnector

- java.lang.Object
- - com.google.android.exoplayer2.ext.mediasession.MediaSessionConnector

-     public final class MediaSessionConnector
      extends Object

  Connects a `MediaSessionCompat` to a `Player`.

  This connector does not call `MediaSessionCompat.setActive(boolean)`, and so application code is responsible for making the session active when desired. A session must be active for transport controls to be displayed (e.g. on the lock screen) and for it to receive media button events.

  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 to `setPlaybackPreparer(PlaybackPreparer)`.
  - Custom actions can be handled by passing one or more `MediaSessionConnector.CustomActionProvider`s to `setCustomActionProviders(CustomActionProvider...)`.
  - 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)`.
  - A `MediaSessionConnector.MediaButtonEventHandler` can be set by calling `setMediaButtonEventHandler(MediaButtonEventHandler)`. By default media button events are handled by `MediaSessionCompat.Callback.onMediaButtonEvent(Intent)`.
  - An `ErrorMessageProvider` for providing human readable error messages and corresponding error codes can be set by calling `setErrorMessageProvider(ErrorMessageProvider)`.
  - A `MediaSessionConnector.MediaMetadataProvider` can be set by calling `setMediaMetadataProvider(MediaMetadataProvider)`. By default the `MediaSessionConnector.DefaultMediaMetadataProvider` is used.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static interface` | `MediaSessionConnector.CaptionCallback` | Handles requests for enabling or disabling captions.
    `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 taken from the `MediaDescriptionCompat` of the `MediaSessionCompat.QueueItem` of the active queue item.
    `static interface` | `MediaSessionConnector.MediaButtonEventHandler` | Handles a media button event.
    `static interface` | `MediaSessionConnector.MediaMetadataProvider` | Provides a `MediaMetadataCompat` for a given player state.
    `static interface` | `MediaSessionConnector.PlaybackActions` | Playback actions supported by the connector.
    `static interface` | `MediaSessionConnector.PlaybackPreparer` | Interface to which playback preparation and play 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 | Description
    --- | --- | ---
    `static long` | `ALL_PLAYBACK_ACTIONS` |
    `static long` | `DEFAULT_PLAYBACK_ACTIONS` | The default playback actions.
    `static String` | `EXTRAS_SPEED` | The name of the `PlaybackStateCompat` float extra with the value of `Player.getPlaybackParameters().speed`.
    `android.support.v4.media.session.MediaSessionCompat` | `mediaSession` | The wrapped `MediaSessionCompat`.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `MediaSessionConnector​(android.support.v4.media.session.MediaSessionCompat mediaSession)` | Creates an instance.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | 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` | `registerCustomCommandReceiver​(MediaSessionConnector.CommandReceiver commandReceiver)` | Registers a custom command receiver for responding to commands delivered via `MediaSessionCompat.Callback.onCommand(String, Bundle, ResultReceiver)`.
    `void` | `setCaptionCallback​(MediaSessionConnector.CaptionCallback captionCallback)` | Sets the `MediaSessionConnector.CaptionCallback` to handle requests to enable or disable captions.
    `void` | `setControlDispatcher​(ControlDispatcher controlDispatcher)` | Deprecated. Use a `ForwardingPlayer` and pass it to `setPlayer(Player)` instead.
    `void` | `setCustomActionProviders​(MediaSessionConnector.CustomActionProvider... customActionProviders)` | Sets custom action providers.
    `void` | `setCustomErrorMessage​(CharSequence message)` | Sets a custom error on the session.
    `void` | `setCustomErrorMessage​(CharSequence message, int code)` | Sets a custom error on the session.
    `void` | `setCustomErrorMessage​(CharSequence message, int code, Bundle extras)` | Sets a custom error on the session.
    `void` | `setDispatchUnsupportedActionsEnabled​(boolean dispatchUnsupportedActionsEnabled)` | Sets whether actions that are not advertised to the `MediaSessionCompat` will be dispatched either way.
    `void` | `setEnabledPlaybackActions​(long enabledPlaybackActions)` | Sets the enabled playback actions.
    `void` | `setErrorMessageProvider​(ErrorMessageProvider<? super PlaybackException> errorMessageProvider)` | Sets the optional `ErrorMessageProvider`.
    `void` | `setMediaButtonEventHandler​(MediaSessionConnector.MediaButtonEventHandler mediaButtonEventHandler)` | Sets the `MediaSessionConnector.MediaButtonEventHandler`.
    `void` | `setMediaMetadataProvider​(MediaSessionConnector.MediaMetadataProvider mediaMetadataProvider)` | Sets a provider of metadata to be published to the media session.
    `void` | `setMetadataDeduplicationEnabled​(boolean metadataDeduplicationEnabled)` | Sets whether `MediaSessionConnector.MediaMetadataProvider.sameAs(MediaMetadataCompat, MediaMetadataCompat)` should be consulted before calling `MediaSessionCompat.setMetadata(MediaMetadataCompat)`.
    `void` | `setPlaybackPreparer​(MediaSessionConnector.PlaybackPreparer playbackPreparer)` | Sets the `MediaSessionConnector.PlaybackPreparer`.
    `void` | `setPlayer​(Player player)` | 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.
    `void` | `unregisterCustomCommandReceiver​(MediaSessionConnector.CommandReceiver commandReceiver)` | Unregisters a previously registered custom command receiver.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### ALL_PLAYBACK_ACTIONS

          public static final long ALL_PLAYBACK_ACTIONS

      See Also:
        Constant Field Values

    - #### DEFAULT_PLAYBACK_ACTIONS

          public static final long DEFAULT_PLAYBACK_ACTIONS

      The default playback actions.
      See Also:
        Constant Field Values

    - #### EXTRAS_SPEED

          public static final String EXTRAS_SPEED

      The name of the `PlaybackStateCompat` float extra with the value of `Player.getPlaybackParameters().speed`.
      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.
      Parameters:
        `mediaSession` - The `MediaSessionCompat` to connect to.

  - ### Method Detail

    - #### setPlayer

          public void setPlayer​(@Nullable
                                Player player)

      Sets the player to be connected to the media session. Must be called on the same thread that is used to access the player.
      Parameters:
        `player` - The player to be connected to the `MediaSession`, or `null` to disconnect the current player.

    - #### setPlaybackPreparer

          public void setPlaybackPreparer​(@Nullable
                                          MediaSessionConnector.PlaybackPreparer playbackPreparer)

      Sets the `MediaSessionConnector.PlaybackPreparer`.
      Parameters:
        `playbackPreparer` - The `MediaSessionConnector.PlaybackPreparer`.

    - #### setControlDispatcher

          @Deprecated
          public void setControlDispatcher​(ControlDispatcher controlDispatcher)

      Deprecated.
      Use a `ForwardingPlayer` and pass it to `setPlayer(Player)` instead. You can also customize some operations when configuring the player (for example by using `SimpleExoPlayer.Builder#setSeekBackIncrementMs(long)`).

    - #### setMediaButtonEventHandler

          public void setMediaButtonEventHandler​(@Nullable
                                                 MediaSessionConnector.MediaButtonEventHandler mediaButtonEventHandler)

      Sets the `MediaSessionConnector.MediaButtonEventHandler`. Pass `null` if the media button event should be handled by `MediaSessionCompat.Callback.onMediaButtonEvent(Intent)`.

      Please note that prior to API 21 MediaButton events are not delivered to the `MediaSessionCompat`. Instead they are delivered as key events (see 'Responding to media buttons'). In an `Activity`, media button events arrive at the `Activity.dispatchKeyEvent(KeyEvent)` method.

      If you are running the player in a foreground service (prior to API 21), you can create an intent filter and handle the `android.intent.action.MEDIA_BUTTON` action yourself. See Service handling ACTION_MEDIA_BUTTON for more information.

      Parameters:
        `mediaButtonEventHandler` - The `MediaSessionConnector.MediaButtonEventHandler`, or null to let the event be handled by `MediaSessionCompat.Callback.onMediaButtonEvent(Intent)`.

    - #### setEnabledPlaybackActions

          public void setEnabledPlaybackActions​(long enabledPlaybackActions)

      Sets the enabled playback actions.
      Parameters:
        `enabledPlaybackActions` - The enabled playback actions.

    - #### setErrorMessageProvider

          public void setErrorMessageProvider​(@Nullable
                                              ErrorMessageProvider<? super PlaybackException> errorMessageProvider)

      Sets the optional `ErrorMessageProvider`.
      Parameters:
        `errorMessageProvider` - The error message provider.

    - #### setQueueNavigator

          public void setQueueNavigator​(@Nullable
                                        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​(@Nullable
                                     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​(@Nullable
                                        MediaSessionConnector.RatingCallback ratingCallback)

      Sets the `MediaSessionConnector.RatingCallback` to handle user ratings.
      Parameters:
        `ratingCallback` - The rating callback.

    - #### setCaptionCallback

          public void setCaptionCallback​(@Nullable
                                         MediaSessionConnector.CaptionCallback captionCallback)

      Sets the `MediaSessionConnector.CaptionCallback` to handle requests to enable or disable captions.
      Parameters:
        `captionCallback` - The caption callback.

    - #### setCustomErrorMessage

          public void setCustomErrorMessage​(@Nullable
                                            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
                                            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`.

    - #### setCustomErrorMessage

          public void setCustomErrorMessage​(@Nullable
                                            CharSequence message,
                                            int code,
                                            @Nullable
                                            Bundle extras)

      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`.
        `extras` - Extras to include in reported `PlaybackStateCompat`.

    - #### setCustomActionProviders

          public void setCustomActionProviders​(@Nullable
                                               MediaSessionConnector.CustomActionProvider... customActionProviders)

      Sets custom action providers. The order of the `MediaSessionConnector.CustomActionProvider`s determines the order in which the actions are published.
      Parameters:
        `customActionProviders` - The custom action providers, or null to remove all existing custom action providers.

    - #### setMediaMetadataProvider

          public void setMediaMetadataProvider​(@Nullable
                                               MediaSessionConnector.MediaMetadataProvider mediaMetadataProvider)

      Sets a provider of metadata to be published to the media session. Pass `null` if no metadata should be published.
      Parameters:
        `mediaMetadataProvider` - The provider of metadata to publish, or `null` if no metadata should be published.

    - #### setDispatchUnsupportedActionsEnabled

          public void setDispatchUnsupportedActionsEnabled​(boolean dispatchUnsupportedActionsEnabled)

      Sets whether actions that are not advertised to the `MediaSessionCompat` will be dispatched either way. Default value is false.

    - #### setMetadataDeduplicationEnabled

          public void setMetadataDeduplicationEnabled​(boolean metadataDeduplicationEnabled)

      Sets whether `MediaSessionConnector.MediaMetadataProvider.sameAs(MediaMetadataCompat, MediaMetadataCompat)` should be consulted before calling `MediaSessionCompat.setMetadata(MediaMetadataCompat)`.

      Note that this comparison is normally only required when you are using media sources that may introduce duplicate updates of the metadata for the same media item (e.g. live streams).

      Parameters:
        `metadataDeduplicationEnabled` - Whether to deduplicate metadata objects on invalidation.

    - #### 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.

      The `MediaMetadataCompat` which is published to the session is obtained by calling `MediaSessionConnector.MediaMetadataProvider.getMetadata(Player)`.

    - #### 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.

    - #### registerCustomCommandReceiver

          public void registerCustomCommandReceiver​(@Nullable
                                                    MediaSessionConnector.CommandReceiver commandReceiver)

      Registers a custom command receiver for responding to commands delivered via `MediaSessionCompat.Callback.onCommand(String, Bundle, ResultReceiver)`.

      Commands are only dispatched to this receiver when a player is connected.

      Parameters:
        `commandReceiver` - The command receiver to register.

    - #### unregisterCustomCommandReceiver

          public void unregisterCustomCommandReceiver​(@Nullable
                                                      MediaSessionConnector.CommandReceiver commandReceiver)

      Unregisters a previously registered custom command receiver.
      Parameters:
        `commandReceiver` - The command receiver to unregister.