Added in API level 21

Summary: Nested Classes | Constants | Ctors | Methods | Inherited Methods

MediaSession

---

Kotlin |Java

public final class MediaSession
extends Object

java.lang.Object
↳	android.media.session.MediaSession

---

Allows interaction with media controllers, volume keys, media buttons, and transport controls.

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.

Once a session is created 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.

To receive commands, media keys, and other events a Callback must be set with setCallback(android.media.session.MediaSession.Callback) and setActive(true) must be called.

When an app is finished performing playback it must call release() to clean up the session and notify any controllers.

MediaSession objects are thread safe.

Summary

Nested classes
class	MediaSession.Callback Receives media buttons, transport controls, and commands from controllers and the system.
class	MediaSession.QueueItem A single item that is part of the play queue.
class	MediaSession.Token Represents an ongoing session.

Constants
int	FLAG_HANDLES_MEDIA_BUTTONS This constant was deprecated in API level 26. This flag is no longer used. All media sessions are expected to handle media button events now.
int	FLAG_HANDLES_TRANSPORT_CONTROLS This constant was deprecated in API level 26. This flag is no longer used. All media sessions are expected to handle transport controls now.

Public constructors
MediaSession(Context context, String tag) Creates a new session.
MediaSession(Context context, String tag, Bundle sessionInfo) Creates a new session.

Public methods
MediaController	getController() Get a controller for this session.
MediaSessionManager.RemoteUserInfo	getCurrentControllerInfo() Gets the controller information who sent the current request.
MediaSession.Token	getSessionToken() Retrieve a token object that can be used by apps to create a MediaController for interacting with this session.
boolean	isActive() Get the current active state of this session.
void	release() This must be called when an app has finished performing playback.
void	sendSessionEvent(String event, Bundle extras) Send a proprietary event to all MediaControllers listening to this Session.
void	setActive(boolean active) Set if this session is currently active and ready to receive commands.
void	setCallback(MediaSession.Callback callback) Set the callback to receive updates for the MediaSession.
void	setCallback(MediaSession.Callback callback, Handler handler) Set the callback to receive updates for the MediaSession.
void	setExtras(Bundle extras) Set some extras that can be associated with the MediaSession.
void	setFlags(int flags) Set any flags for the session.
void	setMediaButtonBroadcastReceiver(ComponentName broadcastReceiver) Set the component name of the manifest-declared BroadcastReceiver class that should receive media buttons.
void	setMediaButtonReceiver(PendingIntent mbr) This method was deprecated in API level 31. Use setMediaButtonBroadcastReceiver(android.content.ComponentName) instead.
void	setMetadata(MediaMetadata metadata) Update the current metadata.
void	setPlaybackState(PlaybackState state) Update the current playback state.
void	setPlaybackToLocal(AudioAttributes attributes) Set the attributes for this session's audio.
void	setPlaybackToRemote(VolumeProvider volumeProvider) Configure this session to use remote volume handling.
void	setQueue(List<MediaSession.QueueItem> queue) Update the list of items in the play queue.
void	setQueueTitle(CharSequence title) Set the title of the play queue.
void	setRatingType(int type) Set the style of rating used by this session.
void	setSessionActivity(PendingIntent pi) Set an intent for launching UI for this Session.

Inherited methods

From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Constants

FLAG_HANDLES_MEDIA_BUTTONS

Added in API level 21
Deprecated in API level 26

public static final int FLAG_HANDLES_MEDIA_BUTTONS

This constant was deprecated in API level 26.
This flag is no longer used. All media sessions are expected to handle media button events now.

Set this flag on the session to indicate that it can handle media button events.

Constant Value: 1 (0x00000001)

FLAG_HANDLES_TRANSPORT_CONTROLS

Added in API level 21
Deprecated in API level 26

public static final int FLAG_HANDLES_TRANSPORT_CONTROLS

This constant was deprecated in API level 26.
This flag is no longer used. All media sessions are expected to handle transport controls now.

Set this flag on the session to indicate that it handles transport control commands through its Callback.

Constant Value: 2 (0x00000002)

Public constructors

MediaSession

Added in API level 21

public MediaSession (Context context, 
                String tag)

Creates a new session. The session will automatically be registered with the system but will not be published until setActive(true) is called. You must call release() when finished with the session.

Note that RuntimeException will be thrown if an app creates too many sessions.

Parameters
context	Context: The context to use to create the session. This value cannot be null.
tag	String: A short name for debugging purposes. This value cannot be null.

MediaSession

Added in API level 29

public MediaSession (Context context, 
                String tag, 
                Bundle sessionInfo)

Creates a new session. The session will automatically be registered with the system but will not be published until setActive(true) is called. You must call release() when finished with the session.

The sessionInfo can include additional unchanging information about this session. For example, it can include the version of the application, or the list of the custom commands that this session supports.

Note that RuntimeException will be thrown if an app creates too many sessions.

Parameters
context	Context: The context to use to create the session. This value cannot be null.
tag	String: A short name for debugging purposes. This value cannot be null.
sessionInfo	Bundle: A bundle for additional information about this session. Controllers can get this information by calling MediaController#getSessionInfo(). An IllegalArgumentException will be thrown if this contains any non-framework Parcelable objects. This value may be null.

Public methods

getController

Added in API level 21

public MediaController getController ()

Get a controller for this session. This is a convenience method to avoid having to cache your own controller in process.

Returns
MediaController	A controller for this session. This value cannot be null.

getCurrentControllerInfo

Added in API level 28

public MediaSessionManager.RemoteUserInfo getCurrentControllerInfo ()

Gets the controller information who sent the current request.

Note: This is only valid while in a request callback, such as Callback#onPlay.

Returns
MediaSessionManager.RemoteUserInfo	This value cannot be null.

Throws
IllegalStateException	If this method is called outside of Callback methods.

See also:

• MediaSessionManager.isTrustedForMediaControl(RemoteUserInfo)

getSessionToken

Added in API level 21

public MediaSession.Token getSessionToken ()

Retrieve a token object that can be used by apps to create a MediaController for interacting with this session. The owner of the session is responsible for deciding how to distribute these tokens.

Returns
MediaSession.Token	A token that can be used to create a MediaController for this session This value cannot be null.

isActive

Added in API level 21

public boolean isActive ()

Get the current active state of this session.

Returns
boolean	True if the session is active, false otherwise.

release

Added in API level 21

public void release ()

This must be called when an app has finished performing playback. If playback is expected to start again shortly the session can be left open, but it must be released if your activity or service is being destroyed.

sendSessionEvent

Added in API level 21

public void sendSessionEvent (String event, 
                Bundle extras)

Send a proprietary event to all MediaControllers listening to this Session. It's up to the Controller/Session owner to determine the meaning of any events.

Parameters
event	String: The name of the event to send This value cannot be null.
extras	Bundle: Any extras included with the event This value may be null.

setActive

Added in API level 21

public void setActive (boolean active)

Set if this session is currently active and ready to receive commands. If set to false your session's controller may not be discoverable. You must set the session to active before it can start receiving media button events or transport commands.

Parameters
active	boolean: Whether this session is active or not.

setCallback

Added in API level 21

public void setCallback (MediaSession.Callback callback)

Set the callback to receive updates for the MediaSession. This includes media button events and transport controls. The caller's thread will be used to post updates.

Set the callback to null to stop receiving updates.

Parameters
callback	MediaSession.Callback: The callback object This value may be null.

setCallback

Added in API level 21

public void setCallback (MediaSession.Callback callback, 
                Handler handler)

Set the callback to receive updates for the MediaSession. This includes media button events and transport controls.

Set the callback to null to stop receiving updates.

Parameters
callback	MediaSession.Callback: The callback to receive updates on. This value may be null.
handler	Handler: The handler that events should be posted on. This value may be null.

setExtras

Added in API level 21

public void setExtras (Bundle extras)

Set some extras that can be associated with the MediaSession. No assumptions should be made as to how a MediaController will handle these extras. Keys should be fully qualified (e.g. com.example.MY_EXTRA) to avoid conflicts.

Parameters
extras	Bundle: The extras associated with the MediaSession. This value may be null.

setFlags

Added in API level 21

public void setFlags (int flags)

Set any flags for the session.

Parameters
flags	int: The flags to set for this session. Value is either 0 or a combination of FLAG_HANDLES_MEDIA_BUTTONS, FLAG_HANDLES_TRANSPORT_CONTROLS, and android.media.session.MediaSession.FLAG_EXCLUSIVE_GLOBAL_PRIORITY

setMediaButtonBroadcastReceiver

Added in API level 31

public void setMediaButtonBroadcastReceiver (ComponentName broadcastReceiver)

Set the component name of the manifest-declared BroadcastReceiver class that should receive media buttons. This allows restarting playback after the session has been stopped. If your app is started in this way an Intent#ACTION_MEDIA_BUTTON intent will be sent to the broadcast receiver. On apps targeting Android U and above, this will throw an IllegalArgumentException if the provided ComponentName does not resolve to an existing broadcast receiver.

Note: The given BroadcastReceiver should belong to the same package as the context that was given when creating MediaSession.

Parameters
broadcastReceiver	ComponentName: the component name of the BroadcastReceiver class This value may be null.

Throws
IllegalArgumentException	if broadcastReceiver does not exist on apps targeting Android U and above

setMediaButtonReceiver

Added in API level 21
Deprecated in API level 31

public void setMediaButtonReceiver (PendingIntent mbr)

This method was deprecated in API level 31.
Use setMediaButtonBroadcastReceiver(android.content.ComponentName) instead.

Set a pending intent for your media button receiver to allow restarting playback after the session has been stopped.

If your app is started in this way an Intent#ACTION_MEDIA_BUTTON intent will be sent via the pending intent.

The provided PendingIntent must not target an activity. On apps targeting Android V and above, passing an activity pending intent to this method causes an IllegalArgumentException. On apps targeting Android U and below, passing an activity pending intent causes the call to be ignored. Refer to this guide for more information.

The pending intent is recommended to be explicit to follow the security recommendation of PendingIntent#getService.

Parameters
mbr	PendingIntent: The PendingIntent to send the media button event to. This value may be null.

Throws
IllegalArgumentException	if the pending intent targets an activity on apps targeting Android V and above.

setMetadata

Added in API level 21

public void setMetadata (MediaMetadata metadata)

Update the current metadata. New metadata can be created using MediaMetadata.Builder. This operation may take time proportional to the size of the bitmap to replace large bitmaps with a scaled down copy.

Parameters
metadata	MediaMetadata: The new metadata This value may be null.

See also:

• MediaMetadata.Builder.putBitmap(String, Bitmap)

setPlaybackState

Added in API level 21

public void setPlaybackState (PlaybackState state)

Update the current playback state.

Parameters
state	PlaybackState: The current state of playback This value may be null.

setPlaybackToLocal

Added in API level 21

public void setPlaybackToLocal (AudioAttributes attributes)

Set the attributes for this session's audio. This will affect the system's volume handling for this session. If setPlaybackToRemote(VolumeProvider) was previously called it will stop receiving volume commands and the system will begin sending volume changes to the appropriate stream.

By default sessions use attributes for media.

Parameters
attributes	AudioAttributes: The AudioAttributes for this session's audio.

setPlaybackToRemote

Added in API level 21

public void setPlaybackToRemote (VolumeProvider volumeProvider)

Configure this session to use remote volume handling. This must be called to receive volume button events, otherwise the system will adjust the appropriate stream volume for this session. If setPlaybackToLocal(AudioAttributes) was previously called the system will stop handling volume changes for this session and pass them to the volume provider instead.

Parameters
volumeProvider	VolumeProvider: The provider that will handle volume changes. May not be null.

setQueue

Added in API level 21

public void setQueue (List<MediaSession.QueueItem> queue)

Update the list of items in the play queue. It is an ordered list and should contain the current item, and previous or upcoming items if they exist. Specify null if there is no current play queue.

The queue should be of reasonable size. If the play queue is unbounded within your app, it is better to send a reasonable amount in a sliding window instead.

Parameters
queue	List: A list of items in the play queue. This value may be null.

setQueueTitle

Added in API level 21

public void setQueueTitle (CharSequence title)

Set the title of the play queue. The UI should display this title along with the play queue itself. e.g. "Play Queue", "Now Playing", or an album name.

Parameters
title	CharSequence: The title of the play queue. This value may be null.

setRatingType

Added in API level 22

public void setRatingType (int type)

Set the style of rating used by this session. Apps trying to set the rating should use this style. Must be one of the following:

• Rating#RATING_NONE
• Rating#RATING_3_STARS
• Rating#RATING_4_STARS
• Rating#RATING_5_STARS
• Rating#RATING_HEART
• Rating#RATING_PERCENTAGE
• Rating#RATING_THUMB_UP_DOWN

Parameters
type	int: Value is Rating.RATING_NONE, Rating.RATING_HEART, Rating.RATING_THUMB_UP_DOWN, Rating.RATING_3_STARS, Rating.RATING_4_STARS, Rating.RATING_5_STARS, or Rating.RATING_PERCENTAGE

setSessionActivity

Added in API level 21

public void setSessionActivity (PendingIntent pi)

Set an intent for launching UI for this Session. This can be used as a quick link to an ongoing media screen. The intent should be for an activity that may be started using Activity#startActivity(Intent).

Parameters
pi	PendingIntent: The intent to launch to show UI for this Session. This value may be null.