MediaSessionCompat.javaAPI DocAndroid 5.1 API68915Thu Mar 12 22:22:56 GMT


public class MediaSessionCompat extends Object
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 {@link #getSessionToken() session token} to other processes to allow them to create a {@link MediaControllerCompat} to interact with the session.

To receive commands, media keys, and other events a {@link Callback} must be set with {@link #setCallback(Callback)}.

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

MediaSessionCompat objects are not thread safe and all calls should be made from the same thread.

This is a helper for accessing features in {@link} introduced after API level 4 in a backwards compatible fashion.

Fields Summary
private final MediaSessionImpl
private final MediaControllerCompat
private final ArrayList
public static final int
Set this flag on the session to indicate that it can handle media button events.
public static final int
Set this flag on the session to indicate that it handles transport control commands through its {@link Callback}.
Constructors Summary
public MediaSessionCompat(android.content.Context context, String tag, android.content.ComponentName mediaButtonEventReceiver, mbrIntent)
Creates a new session.

context The context.
tag A short name for debugging purposes.
mediaButtonEventReceiver The component name for your receiver. This must be non-null to support platform versions earlier than {@link android.os.Build.VERSION_CODES#LOLLIPOP}.
mbrIntent The PendingIntent for your receiver component that handles media button events. This is optional and will be used on {@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR2} and later instead of the component name.

        if (context == null) {
            throw new IllegalArgumentException("context must not be null");
        if (TextUtils.isEmpty(tag)) {
            throw new IllegalArgumentException("tag must not be null or empty");

        if (android.os.Build.VERSION.SDK_INT >= 21) {
            mImpl = new MediaSessionImplApi21(context, tag);
        } else {
            mImpl = new MediaSessionImplBase(context, tag, mediaButtonEventReceiver, mbrIntent);
        mController = new MediaControllerCompat(context, this);
private MediaSessionCompat(android.content.Context context, MediaSessionImpl impl)

        mImpl = impl;
        mController = new MediaControllerCompat(context, this);
Methods Summary
public voidaddOnActiveChangeListener($OnActiveChangeListener listener)
Adds a listener to be notified when the active status of this session changes. This is primarily used by the support library and should not be needed by apps.

listener The listener to add.

        if (listener == null) {
            throw new IllegalArgumentException("Listener may not be null");
public MediaControllerCompatgetController()
Get a controller for this session. This is a convenience method to avoid having to cache your own controller in process.

A controller for this session.

        return mController;
public java.lang.ObjectgetMediaSession()
Gets the underlying framework {@link} object.

This method is only supported on API 21+.

The underlying {@link} object, or null if none.

        return mImpl.getMediaSession();
public java.lang.ObjectgetRemoteControlClient()
Gets the underlying framework {@link} object.

This method is only supported on APIs 14-20. On API 21+ {@link #getMediaSession()} should be used instead.

The underlying {@link} object, or null if none.

        return mImpl.getRemoteControlClient();
Retrieve a token object that can be used by apps to create a {@link MediaControllerCompat} for interacting with this session. The owner of the session is responsible for deciding how to distribute these tokens.

On platform versions before {@link android.os.Build.VERSION_CODES#LOLLIPOP} this token may only be used within your app as there is no way to guarantee other apps are using the same version of the support library.

A token that can be used to create a media controller for this session.

        return mImpl.getSessionToken();
public booleanisActive()
Get the current active state of this session.

True if the session is active, false otherwise.

        return mImpl.isActive();
public static context, java.lang.Object mediaSession)
Obtain a compat wrapper for an existing MediaSession.

mediaSession The {@link} to wrap.
A compat wrapper for the provided session.

        return new MediaSessionCompat(context, new MediaSessionImplApi21(mediaSession));
public voidrelease()
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 voidremoveOnActiveChangeListener($OnActiveChangeListener listener)
Stops the listener from being notified when the active status of this session changes.

listener The listener to remove.

        if (listener == null) {
            throw new IllegalArgumentException("Listener may not be null");
public voidsendSessionEvent(java.lang.String event, android.os.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.

event The name of the event to send
extras Any extras included with the event

        if (TextUtils.isEmpty(event)) {
            throw new IllegalArgumentException("event cannot be null or empty");
        mImpl.sendSessionEvent(event, extras);
public voidsetActive(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.

On platforms earlier than {@link android.os.Build.VERSION_CODES#LOLLIPOP}, {@link #setMediaButtonReceiver(PendingIntent)} must be called before setting this to true.

active Whether this session is active or not.

        for (OnActiveChangeListener listener : mActiveListeners) {
public voidsetCallback($Callback callback)
Add a callback to receive updates on for the MediaSession. This includes media button and volume events. The caller's thread will be used to post events.

callback The callback object

        setCallback(callback, null);
public voidsetCallback($Callback callback, android.os.Handler handler)
Set the callback to receive updates for the MediaSession. This includes media button and volume events. Set the callback to null to stop receiving events.

callback The callback to receive updates on.
handler The handler that events should be posted on.

        mImpl.setCallback(callback, handler != null ? handler : new Handler());
public voidsetExtras(android.os.Bundle extras)
Set some extras that can be associated with the {@link MediaSessionCompat}. No assumptions should be made as to how a {@link MediaControllerCompat} will handle these extras. Keys should be fully qualified (e.g. com.example.MY_EXTRA) to avoid conflicts.

extras The extras associated with the session.

public voidsetFlags(int flags)
Set any flags for the session.

flags The flags to set for this session.

public voidsetMediaButtonReceiver( mbr)
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 {@link Intent#ACTION_MEDIA_BUTTON} intent will be sent via the pending intent.

This method will only work on {@link android.os.Build.VERSION_CODES#LOLLIPOP} and later. Earlier platform versions must include the media button receiver in the constructor.

mbr The {@link PendingIntent} to send the media button event to.

public voidsetMetadata( metadata)
Update the current metadata. New metadata can be created using {@link}.

metadata The new metadata

public voidsetPlaybackState(PlaybackStateCompat state)
Update the current playback state.

state The current state of playback

public voidsetPlaybackToLocal(int stream)
Set the stream this session is playing on. This will affect the system's volume handling for this session. If {@link #setPlaybackToRemote} was previously called it will stop receiving volume commands and the system will begin sending volume changes to the appropriate stream.

By default sessions are on {@link AudioManager#STREAM_MUSIC}.

stream The {@link AudioManager} stream this session is playing on.

public voidsetPlaybackToRemote( volumeProvider)
Configure this session to use remote volume handling. This must be called to receive volume button events, otherwise the system will adjust the current stream volume for this session. If {@link #setPlaybackToLocal} was previously called that stream will stop receiving volume changes for this session.

On platforms earlier than {@link android.os.Build.VERSION_CODES#LOLLIPOP} this will only allow an app to handle volume commands sent directly to the session by a {@link MediaControllerCompat}. System routing of volume keys will not use the volume provider.

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

        if (volumeProvider == null) {
            throw new IllegalArgumentException("volumeProvider may not be null!");
public voidsetQueue(java.util.List 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.

queue A list of items in the play queue.

public voidsetQueueTitle(java.lang.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.

title The title of the play queue.

public voidsetRatingType(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:
  • {@link RatingCompat#RATING_NONE}
  • {@link RatingCompat#RATING_3_STARS}
  • {@link RatingCompat#RATING_4_STARS}
  • {@link RatingCompat#RATING_5_STARS}
  • {@link RatingCompat#RATING_HEART}
  • {@link RatingCompat#RATING_PERCENTAGE}
  • {@link RatingCompat#RATING_THUMB_UP_DOWN}

public voidsetSessionActivity( 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 {@link Activity#startActivity(Intent)}.

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