MediaSessionCompat

public class MediaSessionCompat
extends Object

java.lang.Object
   ↳ android.support.v4.media.session.MediaSessionCompat

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 MediaControllerCompat to interact with the session.

To receive commands, media keys, and other events a MediaSessionCompat.Callback must be set with setCallback(Callback).

When an app is finished performing playback it must call 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 MediaSession introduced after API level 4 in a backwards compatible fashion.

Developer Guides

For information about building your media application, read the Media Apps developer guide.

Summary

Nested classes

class MediaSessionCompat.Callback

Receives transport controls, media buttons, and commands from controllers and the system. 

interface MediaSessionCompat.OnActiveChangeListener

 

class MediaSessionCompat.QueueItem

A single item that is part of the play queue. 

class MediaSessionCompat.Token

Represents an ongoing session. 

Constants

String ACTION_FLAG_AS_INAPPROPRIATE

Predefined custom action to flag the media that is currently playing as inappropriate.

String ACTION_FOLLOW

Predefined custom action to follow an artist, album, or playlist.

String ACTION_SKIP_AD

Predefined custom action to skip the advertisement that is currently playing.

String ACTION_UNFOLLOW

Predefined custom action to unfollow an artist, album, or playlist.

String ARGUMENT_MEDIA_ATTRIBUTE

Argument to indicate the media attribute.

String ARGUMENT_MEDIA_ATTRIBUTE_VALUE

String argument to indicate the value of the media attribute (e.g., the name of the artist).

int FLAG_HANDLES_MEDIA_BUTTONS

This constant is deprecated. This flag is no longer used. All media sessions are expected to handle media button events now. For backward compatibility, this flag will be always set.

int FLAG_HANDLES_QUEUE_COMMANDS

Sets this flag on the session to indicate that it handles queue management commands through its MediaSessionCompat.Callback.

int FLAG_HANDLES_TRANSPORT_CONTROLS

This constant is deprecated. This flag is no longer used. All media sessions are expected to handle transport controls now. For backward compatibility, this flag will be always set.

int MEDIA_ATTRIBUTE_ALBUM

The value of ARGUMENT_MEDIA_ATTRIBUTE indicating the album.

int MEDIA_ATTRIBUTE_ARTIST

The value of ARGUMENT_MEDIA_ATTRIBUTE indicating the artist.

int MEDIA_ATTRIBUTE_PLAYLIST

The value of ARGUMENT_MEDIA_ATTRIBUTE indicating the playlist.

Public constructors

MediaSessionCompat(Context context, String tag)

Creates a new session.

MediaSessionCompat(Context context, String tag, ComponentName mbrComponent, PendingIntent mbrIntent)

Creates a new session with a specified media button receiver (a component name and/or a pending intent).

MediaSessionCompat(Context context, String tag, ComponentName mbrComponent, PendingIntent mbrIntent, Bundle sessionInfo)

Creates a new session with a specified media button receiver (a component name and/or a pending intent).

Public methods

void addOnActiveChangeListener(MediaSessionCompat.OnActiveChangeListener listener)

Adds a listener to be notified when the active status of this session changes.

static MediaSessionCompat fromMediaSession(Context context, Object mediaSession)

Creates an instance from a framework MediaSession object.

MediaControllerCompat getController()

Gets a controller for this session.

final MediaSessionManager.RemoteUserInfo getCurrentControllerInfo()

Gets the controller information who sent the current request.

Object getMediaSession()

Gets the underlying framework MediaSession object.

Object getRemoteControlClient()

Gets the underlying framework RemoteControlClient object.

MediaSessionCompat.Token getSessionToken()

Retrieves a token object that can be used by apps to create a MediaControllerCompat for interacting with this session.

boolean isActive()

Gets the current active state of this session.

void release()

This must be called when an app has finished performing playback.

void removeOnActiveChangeListener(MediaSessionCompat.OnActiveChangeListener listener)

Stops the listener from being notified when the active status of this session changes.

void sendSessionEvent(String event, Bundle extras)

Sends a proprietary event to all MediaControllers listening to this Session.

void setActive(boolean active)

Sets if this session is currently active and ready to receive commands.

void setCallback(MediaSessionCompat.Callback callback, Handler handler)

Sets the callback to receive updates for the MediaSession.

void setCallback(MediaSessionCompat.Callback callback)

Adds a callback to receive updates on for the MediaSession.

void setCaptioningEnabled(boolean enabled)

Enables/disables captioning for this session.

void setExtras(Bundle extras)

Sets some extras that can be associated with the MediaSessionCompat.

void setFlags(int flags)

Sets any flags for the session.

void setMediaButtonReceiver(PendingIntent mbr)

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

void setMetadata(MediaMetadataCompat metadata)

Updates the current metadata.

void setPlaybackState(PlaybackStateCompat state)

Updates the current playback state.

void setPlaybackToLocal(int stream)

Sets the stream this session is playing on.

void setPlaybackToRemote(VolumeProviderCompat volumeProvider)

Configures this session to use remote volume handling.

void setQueue(List<MediaSessionCompat.QueueItem> queue)

Updates the list of items in the play queue.

void setQueueTitle(CharSequence title)

Sets the title of the play queue.

void setRatingType(int type)

Sets the style of rating used by this session.

void setRepeatMode(int repeatMode)

Sets the repeat mode for this session.

void setSessionActivity(PendingIntent pi)

Sets an intent for launching UI for this Session.

void setShuffleMode(int shuffleMode)

Sets the shuffle mode for this session.

Inherited methods

Constants

ACTION_FLAG_AS_INAPPROPRIATE

public static final String ACTION_FLAG_AS_INAPPROPRIATE

Predefined custom action to flag the media that is currently playing as inappropriate.

Constant Value: "android.support.v4.media.session.action.FLAG_AS_INAPPROPRIATE"

ACTION_FOLLOW

public static final String ACTION_FOLLOW

Predefined custom action to follow an artist, album, or playlist. The extra bundle must have ARGUMENT_MEDIA_ATTRIBUTE to indicate the type of the follow action. The bundle can also have an optional string argument, ARGUMENT_MEDIA_ATTRIBUTE_VALUE, to specify the target to follow (e.g., the name of the artist to follow). If this argument is omitted, the currently playing media will be the target of the action. Thus, the session must perform the follow action with the current metadata. If there's no specified attribute in the current metadata, the controller must not omit this argument.

Constant Value: "android.support.v4.media.session.action.FOLLOW"

ACTION_SKIP_AD

public static final String ACTION_SKIP_AD

Predefined custom action to skip the advertisement that is currently playing.

Constant Value: "android.support.v4.media.session.action.SKIP_AD"

ACTION_UNFOLLOW

public static final String ACTION_UNFOLLOW

Predefined custom action to unfollow an artist, album, or playlist. The extra bundle must have ARGUMENT_MEDIA_ATTRIBUTE to indicate the type of the unfollow action. The bundle can also have an optional string argument, ARGUMENT_MEDIA_ATTRIBUTE_VALUE, to specify the target to unfollow (e.g., the name of the artist to unfollow). If this argument is omitted, the currently playing media will be the target of the action. Thus, the session must perform the unfollow action with the current metadata. If there's no specified attribute in the current metadata, the controller must not omit this argument.

Constant Value: "android.support.v4.media.session.action.UNFOLLOW"

ARGUMENT_MEDIA_ATTRIBUTE

public static final String ARGUMENT_MEDIA_ATTRIBUTE

Argument to indicate the media attribute. It should be one of the following:

Constant Value: "android.support.v4.media.session.ARGUMENT_MEDIA_ATTRIBUTE"

ARGUMENT_MEDIA_ATTRIBUTE_VALUE

public static final String ARGUMENT_MEDIA_ATTRIBUTE_VALUE

String argument to indicate the value of the media attribute (e.g., the name of the artist).

Constant Value: "android.support.v4.media.session.ARGUMENT_MEDIA_ATTRIBUTE_VALUE"

FLAG_HANDLES_MEDIA_BUTTONS

public static final int FLAG_HANDLES_MEDIA_BUTTONS

This constant is deprecated.
This flag is no longer used. All media sessions are expected to handle media button events now. For backward compatibility, this flag will be always set.

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

Constant Value: 1 (0x00000001)

FLAG_HANDLES_QUEUE_COMMANDS

public static final int FLAG_HANDLES_QUEUE_COMMANDS

Sets this flag on the session to indicate that it handles queue management commands through its MediaSessionCompat.Callback.

Constant Value: 4 (0x00000004)

FLAG_HANDLES_TRANSPORT_CONTROLS

public static final int FLAG_HANDLES_TRANSPORT_CONTROLS

This constant is deprecated.
This flag is no longer used. All media sessions are expected to handle transport controls now. For backward compatibility, this flag will be always set.

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

Constant Value: 2 (0x00000002)

MEDIA_ATTRIBUTE_ALBUM

public static final int MEDIA_ATTRIBUTE_ALBUM

The value of ARGUMENT_MEDIA_ATTRIBUTE indicating the album.

Constant Value: 1 (0x00000001)

MEDIA_ATTRIBUTE_ARTIST

public static final int MEDIA_ATTRIBUTE_ARTIST

The value of ARGUMENT_MEDIA_ATTRIBUTE indicating the artist.

Constant Value: 0 (0x00000000)

MEDIA_ATTRIBUTE_PLAYLIST

public static final int MEDIA_ATTRIBUTE_PLAYLIST

The value of ARGUMENT_MEDIA_ATTRIBUTE indicating the playlist.

Constant Value: 2 (0x00000002)

Public constructors

MediaSessionCompat

public MediaSessionCompat (Context context, 
                String tag)

Creates a new session. You must call release() when finished with the session.

The session will automatically be registered with the system but will not be published until setActive(true) is called.

For API 20 or earlier, note that a media button receiver is required for handling Intent.ACTION_MEDIA_BUTTON. This constructor will attempt to find an appropriate BroadcastReceiver from your manifest. See MediaButtonReceiver for more details.

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

MediaSessionCompat

public MediaSessionCompat (Context context, 
                String tag, 
                ComponentName mbrComponent, 
                PendingIntent mbrIntent)

Creates a new session with a specified media button receiver (a component name and/or a pending intent). You must call release() when finished with the session.

The session will automatically be registered with the system but will not be published until setActive(true) is called.

For API 20 or earlier, note that a media button receiver is required for handling Intent.ACTION_MEDIA_BUTTON. This constructor will attempt to find an appropriate BroadcastReceiver from your manifest if it's not specified. See MediaButtonReceiver for more details.

Parameters
context Context: The context to use to create the session.
tag String: A short name for debugging purposes.
mbrComponent ComponentName: The component name for your media button receiver.
mbrIntent PendingIntent: The PendingIntent for your receiver component that handles media button events. This is optional and will be used on between Build.VERSION_CODES.JELLY_BEAN_MR2 and Build.VERSION_CODES.KITKAT_WATCH instead of the component name.

MediaSessionCompat

public MediaSessionCompat (Context context, 
                String tag, 
                ComponentName mbrComponent, 
                PendingIntent mbrIntent, 
                Bundle sessionInfo)

Creates a new session with a specified media button receiver (a component name and/or a pending intent). You must call release() when finished with the session.

The session will automatically be registered with the system but will not be published until setActive(true) is called.

For API 20 or earlier, note that a media button receiver is required for handling Intent.ACTION_MEDIA_BUTTON. This constructor will attempt to find an appropriate BroadcastReceiver from your manifest if it's not specified. See MediaButtonReceiver for more details.

The sessionInfo can include additional unchanging information about this session. For example, it can include the version of the application, or other app-specific unchanging information.

Parameters
context Context: The context to use to create the session.
tag String: A short name for debugging purposes.
mbrComponent ComponentName: The component name for your media button receiver.