MediaSessionCompat

public class 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 Callback must be set with setCallback.

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 android.media.session.MediaSession introduced after API level 4 in a backwards compatible fashion.

Summary

Nested types
public abstract class MediaSessionCompat.Callback

Receives transport controls, media buttons, and commands from controllers and the system.
public final class MediaSessionCompat.QueueItem implements Parcelable

A single item that is part of the play queue.
public final class MediaSessionCompat.Token implements Parcelable

Represents an ongoing session.

Constants
static final String
ACTION_FLAG_AS_INAPPROPRIATE = "android.support.v4.media.session.action.FLAG_AS_INAPPROPRIATE"

Predefined custom action to flag the media that is currently playing as inappropriate.
static final String
ACTION_FOLLOW = "android.support.v4.media.session.action.FOLLOW"

Predefined custom action to follow an artist, album, or playlist.
static final String
ACTION_SKIP_AD = "android.support.v4.media.session.action.SKIP_AD"

Predefined custom action to skip the advertisement that is currently playing.
static final String
ACTION_UNFOLLOW = "android.support.v4.media.session.action.UNFOLLOW"

Predefined custom action to unfollow an artist, album, or playlist.
static final String
ARGUMENT_MEDIA_ATTRIBUTE = "android.support.v4.media.session.ARGUMENT_MEDIA_ATTRIBUTE"

Argument to indicate the media attribute.
static final String
ARGUMENT_MEDIA_ATTRIBUTE_VALUE = "android.support.v4.media.session.ARGUMENT_MEDIA_ATTRIBUTE_VALUE"

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

This field is deprecated.

This flag is no longer used.
static final int

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

This field is deprecated.

This flag is no longer used.
static final int

The value of ARGUMENT_MEDIA_ATTRIBUTE indicating the album.
static final int

The value of ARGUMENT_MEDIA_ATTRIBUTE indicating the artist.
static final int

The value of ARGUMENT_MEDIA_ATTRIBUTE indicating the playlist.

Public constructors

Creates a new session.
MediaSessionCompat(
    @NonNull Context context,
    @NonNull String tag,
    @Nullable ComponentName mbrComponent,
    @Nullable PendingIntent mbrIntent
)

Creates a new session with a specified media button receiver (a component name and/or a pending intent).
MediaSessionCompat(
    @NonNull Context context,
    @NonNull String tag,
    @Nullable ComponentName mbrComponent,
    @Nullable PendingIntent mbrIntent,
    @Nullable Bundle sessionInfo
)

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

Public methods
void

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 android.media.session.MediaSession object.
MediaControllerCompat

Gets a controller for this session.
final @NonNull MediaSessionManager.RemoteUserInfo

Gets the controller information who sent the current request.
Object

Gets the underlying framework android.media.session.MediaSession object.
Object

Gets the underlying framework android.media.RemoteControlClient object.
MediaSessionCompat.Token

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

Gets the current active state of this session.
void

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

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

Adds a callback to receive updates on for the MediaSession.
void

Sets the callback to receive updates 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

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

Updates the current metadata.
void

Updates the current playback state.
void
setPlaybackToLocal(int stream)

Sets the stream this session is playing on.
void

Configures this session to use remote volume handling.
void

Updates the list of items in the play queue.
void

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

Sets an intent for launching UI for this Session.
void
setShuffleMode(int shuffleMode)

Sets the shuffle mode for this session.

Constants

ACTION_FLAG_AS_INAPPROPRIATE

Added in 1.1.0
public static final String ACTION_FLAG_AS_INAPPROPRIATE = "android.support.v4.media.session.action.FLAG_AS_INAPPROPRIATE"

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

See also
onCustomAction

ACTION_FOLLOW

Added in 1.1.0
public static final String ACTION_FOLLOW = "android.support.v4.media.session.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.

See also
ARGUMENT_MEDIA_ATTRIBUTE
ARGUMENT_MEDIA_ATTRIBUTE_VALUE
onCustomAction

ACTION_SKIP_AD

Added in 1.1.0
public static final String ACTION_SKIP_AD = "android.support.v4.media.session.action.SKIP_AD"

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

See also
onCustomAction

ACTION_UNFOLLOW

Added in 1.1.0
public static final String ACTION_UNFOLLOW = "android.support.v4.media.session.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.

See also
ARGUMENT_MEDIA_ATTRIBUTE
ARGUMENT_MEDIA_ATTRIBUTE_VALUE
onCustomAction

ARGUMENT_MEDIA_ATTRIBUTE

Added in 1.1.0
public static final String ARGUMENT_MEDIA_ATTRIBUTE = "android.support.v4.media.session.ARGUMENT_MEDIA_ATTRIBUTE"

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

ARGUMENT_MEDIA_ATTRIBUTE_VALUE

Added in 1.1.0
public static final String ARGUMENT_MEDIA_ATTRIBUTE_VALUE = "android.support.v4.media.session.ARGUMENT_MEDIA_ATTRIBUTE_VALUE"

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

FLAG_HANDLES_MEDIA_BUTTONS

Added in 1.1.0
Deprecated in 1.1.0
public static final int FLAG_HANDLES_MEDIA_BUTTONS = 1

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

FLAG_HANDLES_QUEUE_COMMANDS

Added in 1.1.0
public static final int FLAG_HANDLES_QUEUE_COMMANDS = 4

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

FLAG_HANDLES_TRANSPORT_CONTROLS

Added in 1.1.0
Deprecated in 1.1.0
public static final int FLAG_HANDLES_TRANSPORT_CONTROLS = 2

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

MEDIA_ATTRIBUTE_ALBUM

Added in 1.1.0
public static final int MEDIA_ATTRIBUTE_ALBUM = 1

The value of ARGUMENT_MEDIA_ATTRIBUTE indicating the album.

See also
ARGUMENT_MEDIA_ATTRIBUTE

MEDIA_ATTRIBUTE_ARTIST

Added in 1.1.0
public static final int MEDIA_ATTRIBUTE_ARTIST = 0

The value of ARGUMENT_MEDIA_ATTRIBUTE indicating the artist.

See also
ARGUMENT_MEDIA_ATTRIBUTE

MEDIA_ATTRIBUTE_PLAYLIST

Added in 1.1.0
public static final int MEDIA_ATTRIBUTE_PLAYLIST = 2

The value of ARGUMENT_MEDIA_ATTRIBUTE indicating the playlist.

See also
ARGUMENT_MEDIA_ATTRIBUTE

Public constructors

MediaSessionCompat

Added in 1.1.0
public MediaSessionCompat(@NonNull Context context, @NonNull 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 ACTION_MEDIA_BUTTON. This constructor will attempt to find an appropriate BroadcastReceiver from your manifest. See MediaButtonReceiver for more details.

Parameters
@NonNull Context context

The context to use to create the session.
@NonNull String tag

A short name for debugging purposes.

MediaSessionCompat

Added in 1.1.0
public MediaSessionCompat(
    @NonNull Context context,
    @NonNull String tag,
    @Nullable ComponentName mbrComponent,
    @Nullable 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 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
@NonNull Context context

The context to use to create the session.
@NonNull String tag

A short name for debugging purposes.
@Nullable ComponentName mbrComponent

The component name for your media button receiver.
@Nullable PendingIntent mbrIntent

The PendingIntent for your receiver component that handles media button events. This is optional and will be used on between JELLY_BEAN_MR2 and KITKAT_WATCH instead of the component name.

MediaSessionCompat

Added in 1.2.0
public MediaSessionCompat(
    @NonNull Context context,
    @NonNull String tag,
    @Nullable ComponentName mbrComponent,
    @Nullable PendingIntent mbrIntent,
    @Nullable 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 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
@NonNull Context context

The context to use to create the session.
@NonNull String tag

A short name for debugging purposes.
@Nullable ComponentName mbrComponent

The component name for your media button receiver.
@Nullable PendingIntent mbrIntent

The PendingIntent for your receiver component that handles media button events. This is optional and will be used on between JELLY_BEAN_MR2 and KITKAT_WATCH instead of the component name.
@Nullable Bundle sessionInfo

A bundle for additional information about this session, or EMPTY if none. Controllers can get this information by calling getSessionInfo. An IllegalArgumentException