MediaSession

Artifact: androidx.media2:media2-session

View Source

Added in 1.0.0

Deprecated in 1.3.0

---

Kotlin |Java

class MediaSession : Closeable

Known direct subclasses

MediaLibraryService.MediaLibrarySession

MediaLibraryService.MediaLibrarySession

This class is deprecated. androidx.media2 is deprecated.

---

This class is deprecated.

androidx.media2 is deprecated. Please migrate to androidx.media3.

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 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 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 Builder or updatePlayer.

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 code	API
KEYCODE_MEDIA_PLAY	play
KEYCODE_MEDIA_PAUSE	pause
KEYCODE_MEDIA_NEXT	skipToNextPlaylistItem
KEYCODE_MEDIA_PREVIOUS	skipToPreviousPlaylistItem
KEYCODE_MEDIA_STOP	pause and then seekTo with 0
KEYCODE_MEDIA_FAST_FORWARD	onFastForward
KEYCODE_MEDIA_REWIND	onRewind
KEYCODE_MEDIA_PLAY_PAUSE KEYCODE_HEADSETHOOK	For a single tap pause if PLAYER_STATE_PLAYING play otherwise For a double tap, skipToNextPlaylistItem

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 . 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, ControllerInfo may not be precise for legacy controller. See 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.

See also
MediaSessionService

Summary

Nested types
class MediaSession.Builder This class is deprecated. androidx.media2 is deprecated.
class MediaSession.CommandButton : VersionedParcelable This class is deprecated. androidx.media2 is deprecated.
class MediaSession.CommandButton.Builder This class is deprecated. androidx.media2 is deprecated.
class MediaSession.ControllerInfo This class is deprecated. androidx.media2 is deprecated.
abstract class MediaSession.SessionCallback This class is deprecated. androidx.media2 is deprecated.

Public functions
Unit	broadcastCustomCommand(command: SessionCommand, args: Bundle?) Broadcasts a custom command to all connected controllers.
Unit	close()
(Mutable)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(     controller: MediaSession.ControllerInfo,     command: SessionCommand,     args: Bundle? ) Sends a custom command to a specific controller.
Unit	setAllowedCommands(     controller: MediaSession.ControllerInfo,     commands: SessionCommandGroup ) Sets the new allowed command group for the controller.
ListenableFuture<SessionResult!>	setCustomLayout(     controller: MediaSession.ControllerInfo,     layout: (Mutable)List<MediaSession.CommandButton!> ) Sets ordered list of CommandButton for controllers to build UI with it.
Unit	updatePlayer(player: SessionPlayer) Updates the underlying SessionPlayer for this session to dispatch incoming event to.

Public functions

broadcastCustomCommand

Added in 1.0.0

Deprecated in 1.3.0

fun broadcastCustomCommand(command: SessionCommand, args: Bundle?): Unit

Broadcasts a custom command to all connected controllers.

This is synchronous call and doesn't wait for result from the controller. Use sendCustomCommand for getting the result.

A command is not accepted if it is not a custom command.

Parameters
command: SessionCommand	a command
args: Bundle?	optional argument

See also
sendCustomCommand

close

Added in 1.0.0

Deprecated in 1.3.0

fun close(): Unit

getConnectedControllers

Added in 1.0.0

Deprecated in 1.3.0

fun getConnectedControllers(): (Mutable)List<MediaSession.ControllerInfo!>

Returns the list of connected controller.

Returns
(Mutable)List<MediaSession.ControllerInfo!>	list of ControllerInfo

getId

Added in 1.0.0

Deprecated in 1.3.0

fun getId(): String

Gets the session ID

Returns
String

getPlayer

Added in 1.0.0

Deprecated in 1.3.0

fun getPlayer(): SessionPlayer

Gets the underlying SessionPlayer.

When the session is closed, it returns the lastly set player.

Returns
SessionPlayer	player.

getSessionCompatToken

Added in 1.1.0

Deprecated in 1.3.0

fun getSessionCompatToken(): MediaSessionCompat.Token

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

Returns
MediaSessionCompat.Token	MediaSessionCompat.Token

getToken

Added in 1.0.0

Deprecated in 1.3.0

fun getToken(): SessionToken

Returns the SessionToken for creating MediaController.

sendCustomCommand

Added in 1.0.0

Deprecated in 1.3.0

fun sendCustomCommand(
    controller: MediaSession.ControllerInfo,
    command: SessionCommand,
    args: Bundle?
): ListenableFuture<SessionResult!>

Sends a custom command to a specific controller.

A command is not accepted if it is not a custom command.

Parameters
command: SessionCommand	a command
args: Bundle?	optional argument

See also
broadcastCustomCommand

setAllowedCommands

Added in 1.0.0

Deprecated in 1.3.0

fun setAllowedCommands(
    controller: MediaSession.ControllerInfo,
    commands: SessionCommandGroup
): Unit

Sets the new allowed command group for the controller.

This is synchronous call. Changes in the allowed commands take effect immediately regardless of the controller notified about the change through #onAllowedCommandsChanged(MediaController, SessionCommandGroup)

Parameters
controller: MediaSession.ControllerInfo	controller to change allowed commands
commands: SessionCommandGroup	new allowed commands

setCustomLayout

Added in 1.0.0

Deprecated in 1.3.0

fun setCustomLayout(
    controller: MediaSession.ControllerInfo,
    layout: (Mutable)List<MediaSession.CommandButton!>
): ListenableFuture<SessionResult!>

Sets ordered list of CommandButton for controllers to build UI with it.

It's up to controller's decision how to represent the layout in its own UI. Here are some examples.

Note: layout[i] means a CommandButton at index i in the given list

Controller UX layout	Layout example
Row with 3 icons	layout[1]layout[0]layout[2]
Row with 5 icons	layout[3]layout[1]layout[0]layout[2]layout[4]
Row with 5 icons and an overflow icon, and another expandable row with 5 extra icons	layout[3]layout[1]layout[0]layout[2]layout[4]
layout[3]layout[1]layout[0]layout[2]layout[4]

This API can be called in the onConnect.

Parameters
controller: MediaSession.ControllerInfo	controller to specify layout.
layout: (Mutable)List<MediaSession.CommandButton!>	ordered list of layout.

updatePlayer

Added in 1.0.0

Deprecated in 1.3.0

fun updatePlayer(player: SessionPlayer): Unit

Updates the underlying SessionPlayer for this session to dispatch incoming event to.

Parameters
player: SessionPlayer	a player that handles actual media playback in your app