Android APIs
public final class

MediaSession

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

Class Overview

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 MediaSession.Callback must be set with setCallback(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 Set this flag on the session to indicate that it can handle media button events.
int FLAG_HANDLES_TRANSPORT_CONTROLS Set this flag on the session to indicate that it handles transport control commands through its MediaSession.Callback.
Public Constructors
MediaSession(Context context, String tag)
Creates a new session.
Public Methods
MediaController getController()
Get a controller for this session.
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 setMediaButtonReceiver(PendingIntent mbr)
Set a pending intent for your media button receiver to allow restarting playback after the session has been stopped.
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 setSessionActivity(PendingIntent pi)
Set an intent for launching UI for this Session.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int FLAG_HANDLES_MEDIA_BUTTONS

Added in API level 21

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

Constant Value: 1 (0x00000001)

public static final int FLAG_HANDLES_TRANSPORT_CONTROLS

Added in API level 21

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

Constant Value: 2 (0x00000002)

Public Constructors

public MediaSession (Context context, String tag)

Added in API level 21

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.

Parameters
context The context to use to create the session.
tag A short name for debugging purposes.

Public Methods

public MediaController getController ()

Added in API level 21

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

Returns
  • A controller for this session.

public MediaSession.Token getSessionToken ()

Added in API level 21

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
  • A token that can be used to create a MediaController for this session

public boolean isActive ()

Added in API level 21

Get the current active state of this session.

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

public void release ()

Added in API level 21

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.

public void sendSessionEvent (String event, Bundle extras)

Added in API level 21

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 The name of the event to send
extras Any extras included with the event

public void setActive (boolean active)

Added in API level 21

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 Whether this session is active or not.

public void setCallback (MediaSession.Callback callback)

Added in API level 21

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 The callback object

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

Added in API level 21

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 The callback to receive updates on.
handler The handler that events should be posted on.

public void setExtras (Bundle extras)

Added in API level 21

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 The extras associated with the MediaSession.

public void setFlags (int flags)

Added in API level 21

Set any flags for the session.

Parameters
flags The flags to set for this session.

public void setMediaButtonReceiver (PendingIntent mbr)

Added in API level 21

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 ACTION_MEDIA_BUTTON intent will be sent via the pending intent.

Parameters
mbr The PendingIntent to send the media button event to.

public void setMetadata (MediaMetadata metadata)

Added in API level 21

Update the current metadata. New metadata can be created using MediaMetadata.Builder.

Parameters
metadata The new metadata

public void setPlaybackState (PlaybackState state)

Added in API level 21

Update the current playback state.

Parameters
state The current state of playback

public void setPlaybackToLocal (AudioAttributes attributes)

Added in API level 21

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 The AudioAttributes for this session's audio.

public void setPlaybackToRemote (VolumeProvider volumeProvider)

Added in API level 21

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 The provider that will handle volume changes. May not be null.

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

Added in API level 21

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 A list of items in the play queue.

public void setQueueTitle (CharSequence title)

Added in API level 21

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 The title of the play queue.

public void setSessionActivity (PendingIntent pi)

Added in API level 21

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 startActivity(Intent).

Parameters
pi The intent to launch to show UI for this Session.