MediaSession

public class MediaSession
extends Object implements Closeable

java.lang.Object
   ↳ androidx.media2.session.MediaSession


Allows a media app to expose its transport controls and playback information in a process to other processes including the Android framework and other apps. Common use cases are as follows.

  • Bluetooth/wired headset key events support
  • Android Auto/Wearable support
  • Separating UI process and playback process

A MediaSession should be created when an app wants to publish media playback information or handle media keys. In general an app only needs one session for all playback, though multiple sessions can be created to provide finer grain controls of media. See Supporting Multiple Sessions for detail.

If you want to support background playback, MediaSessionService is preferred instead. With it, your playback can be revived even after playback is finished. See MediaSessionService for details.

Topics covered here:

  1. Session Lifecycle
  2. Thread
  3. Media key events mapping
  4. Supporting Multiple Sessions
  5. Backward compatibility with legacy session APIs
  6. Backward compatibility with legacy controller APIs

Session Lifecycle

A session can be obtained by MediaSession.Builder. The owner of the session may pass its session token to other processes to allow them to create a MediaController to interact with the session.

When a session receive transport control commands, the session sends the commands directly to the underlying media player set by MediaSession.Builder or updatePlayer(SessionPlayer).

When an app is finished performing playback it must call close() to clean up the session and notify any controllers. The app is responsible for closing the underlying player after closing the session. is closed.

Thread

MediaSession objects are thread safe, but should be used on the thread on the looper.

Media key events mapping

Here's the table of per key event.

Key codeMediaSession API
KeyEvent.KEYCODE_MEDIA_PLAY SessionPlayer.play()
KeyEvent.KEYCODE_MEDIA_PAUSE SessionPlayer.pause()
KeyEvent.KEYCODE_MEDIA_NEXT SessionPlayer.skipToNextPlaylistItem()
KeyEvent.KEYCODE_MEDIA_PREVIOUS SessionPlayer.skipToPreviousPlaylistItem()
KeyEvent.KEYCODE_MEDIA_STOP SessionPlayer.pause() and then SessionPlayer.seekTo(long) with 0
KeyEvent.KEYCODE_MEDIA_FAST_FORWARD MediaSession.SessionCallback.onFastForward(MediaSession, MediaSession.ControllerInfo)
KeyEvent.KEYCODE_MEDIA_REWIND MediaSession.SessionCallback.onRewind(MediaSession, MediaSession.ControllerInfo)

Supporting Multiple Sessions

Generally speaking, multiple sessions aren't necessary for most media apps. One exception is if your app can play multiple media content at the same time, but only for the playback of video-only media or remote playback, since audio focus policy recommends not playing multiple audio content at the same time. Also keep in mind that multiple media sessions would make Android Auto and Bluetooth device with display to show your apps multiple times, because they list up media sessions, not media apps.

Backward compatibility with legacy session APIs

An active MediaSessionCompat is internally created with the MediaSession for the backward compatibility. It's used to handle incoming connection and command from MediaControllerCompat. And helps to utilize existing APIs that are built with legacy media session APIs. Use getSessionCompatToken() for getting the token for the underlying MediaSessionCompat.

Backward compatibility with legacy controller APIs

In addition to the media2 controller API, session also supports connection from the legacy controller API - framework controller and AndroidX controller compat. However, MediaSession.ControllerInfo may not be precise for legacy controller. See MediaSession.ControllerInfo for the details.

Unknown package name nor UID doesn't mean that you should disallow connection nor commands. For SDK levels where such issue happen, session tokens could only be obtained by trusted apps (e.g. Bluetooth, Auto, ...), so it may be better for you to allow them as you did with legacy session.

Summary

Nested classes

class MediaSession.Builder

Builder for MediaSession

class MediaSession.CommandButton

Button for a SessionCommand that will be shown by the controller. 

class MediaSession.ControllerInfo

Information of a controller. 

class MediaSession.SessionCallback

Callback to be called for all incoming commands from MediaControllers. 

Public methods

void broadcastCustomCommand(SessionCommand command, Bundle args)

Broadcasts a custom command to all connected controllers.

void close()
List<MediaSession.ControllerInfo> getConnectedControllers()

Returns the list of connected controller.

String getId()

Gets the session ID

SessionPlayer getPlayer()

Gets the underlying SessionPlayer.

MediaSessionCompat.Token getSessionCompatToken()

Gets the MediaSessionCompat.Token for the MediaSessionCompat created internally by this session.

SessionToken getToken()

Returns the SessionToken for creating MediaController.

ListenableFuture<SessionResult> sendCustomCommand(MediaSession.ControllerInfo controller,