MediaSessionCompat

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

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

A single item that is part of the play queue.

Represents an ongoing session.

Constants
const 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.
const String!
ACTION_FOLLOW = "android.support.v4.media.session.action.FOLLOW"

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

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

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

Argument to indicate the media attribute.
const 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).
const Int

This property is deprecated.

This flag is no longer used.
const Int

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

This property is deprecated.

This flag is no longer used.
const Int

The value of ARGUMENT_MEDIA_ATTRIBUTE indicating the album.
const Int

The value of ARGUMENT_MEDIA_ATTRIBUTE indicating the artist.
const Int

The value of ARGUMENT_MEDIA_ATTRIBUTE indicating the playlist.

Public constructors
MediaSessionCompat(context: Context, tag: String)

Creates a new session.
MediaSessionCompat(
    context: Context,
    tag: String,
    mbrComponent: ComponentName?,
    mbrIntent: PendingIntent?
)

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

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

Public functions
Unit

Adds a listener to be notified when the active status of this session changes.
java-static MediaSessionCompat!
fromMediaSession(context: Context!, mediaSession: Any!)

Creates an instance from a framework android.media.session.MediaSession object.
MediaControllerCompat!

Gets a controller for this session.
MediaSessionManager.RemoteUserInfo

Gets the controller information who sent the current request.
Any!

Gets the underlying framework android.media.session.MediaSession object.
Any!

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.
Unit

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

Stops the listener from being notified when the active status of this session changes.
Unit
sendSessionEvent(event: String!, extras: Bundle!)

Sends a proprietary event to all MediaControllers listening to this Session.
Unit
setActive(active: Boolean)

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

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

Sets the callback to receive updates for the MediaSession.
Unit

Enables/disables captioning for this session.
Unit
setExtras(extras: Bundle!)

Sets some extras that can be associated with the MediaSessionCompat.
Unit
setFlags(flags: Int)

Sets any flags for the session.
Unit

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

Updates the current metadata.
Unit

Updates the current playback state.
Unit

Sets the stream this session is playing on.
Unit

Configures this session to use remote volume handling.
Unit

Updates the list of items in the play queue.
Unit

Sets the title of the play queue.
Unit

Sets the style of rating used by this session.
Unit
setRepeatMode(repeatMode: Int)

Sets the repeat mode for this session.
Unit

Sets an intent for launching UI for this Session.
Unit
setShuffleMode(shuffleMode: Int)

Sets the shuffle mode for this session.

Constants

ACTION_FLAG_AS_INAPPROPRIATE

Added in 1.1.0
const val ACTION_FLAG_AS_INAPPROPRIATE = "android.support.v4.media.session.action.FLAG_AS_INAPPROPRIATE": String!

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

See also
onCustomAction

ACTION_FOLLOW

Added in 1.1.0
const val ACTION_FOLLOW = "android.support.v4.media.session.action.FOLLOW": String!

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
const val ACTION_SKIP_AD = "android.support.v4.media.session.action.SKIP_AD": String!

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

See also
onCustomAction

ACTION_UNFOLLOW

Added in 1.1.0
const val ACTION_UNFOLLOW = "android.support.v4.media.session.action.UNFOLLOW": String!

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
const val ARGUMENT_MEDIA_ATTRIBUTE = "android.support.v4.media.session.ARGUMENT_MEDIA_ATTRIBUTE": String!

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

ARGUMENT_MEDIA_ATTRIBUTE_VALUE

Added in 1.1.0
const val ARGUMENT_MEDIA_ATTRIBUTE_VALUE = "android.support.v4.media.session.ARGUMENT_MEDIA_ATTRIBUTE_VALUE": String!

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
const val FLAG_HANDLES_MEDIA_BUTTONS = 1: Int

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

FLAG_HANDLES_QUEUE_COMMANDS

Added in 1.1.0
const val FLAG_HANDLES_QUEUE_COMMANDS = 4: Int

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
const val FLAG_HANDLES_TRANSPORT_CONTROLS = 2: Int

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
const val MEDIA_ATTRIBUTE_ALBUM = 1: Int

The value of ARGUMENT_MEDIA_ATTRIBUTE indicating the album.

See also
ARGUMENT_MEDIA_ATTRIBUTE

MEDIA_ATTRIBUTE_ARTIST

Added in 1.1.0
const val MEDIA_ATTRIBUTE_ARTIST = 0: Int

The value of ARGUMENT_MEDIA_ATTRIBUTE indicating the artist.

See also
ARGUMENT_MEDIA_ATTRIBUTE

MEDIA_ATTRIBUTE_PLAYLIST

Added in 1.1.0
const val MEDIA_ATTRIBUTE_PLAYLIST = 2: Int

The value of ARGUMENT_MEDIA_ATTRIBUTE indicating the playlist.

See also
ARGUMENT_MEDIA_ATTRIBUTE

Public constructors

MediaSessionCompat

Added in 1.1.0
MediaSessionCompat(context: Context, tag: String)

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
context: Context

The context to use to create the session.
tag: String

A short name for debugging purposes.

MediaSessionCompat

Added in 1.1.0
MediaSessionCompat(
    context: Context,
    tag: String,
    mbrComponent: ComponentName?,
    mbrIntent: PendingIntent?
)

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
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 JELLY_BEAN_MR2 and KITKAT_WATCH instead of the component name.

MediaSessionCompat

Added in 1.2.0
MediaSessionCompat(
    context: Context,
    tag: String,
    mbrComponent: ComponentName?,
    mbrIntent: PendingIntent?,
    sessionInfo: Bundle?
)

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
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 JELLY_BEAN_MR2 and KITKAT_WATCH instead of the component name.
sessionInfo: Bundle?

A bundle for additional information about this session, or EMPTY if none. Controllers can get this information by calling getSessionInfo. An IllegalArgumentException will be thrown if this contains any non-framework Parcelable objects.

Public functions

addOnActiveChangeListener

Added in 1.1.0
fun addOnActiveChangeListener(
    listener: MediaSessionCompat.OnActiveChangeListener!
): Unit

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.

Parameters
listener: MediaSessionCompat.OnActiveChangeListener!

The listener to add.

fromMediaSession

Added in 1.1.0
java-static fun fromMediaSession(context: Context!, mediaSession: Any!): MediaSessionCompat!

Creates an instance from a framework android.media.session.MediaSession object.

This method is only supported on API 21+. On API 20 and below, it returns null.

Note: A MediaSessionCompat object returned from this method may not provide the full functionality of MediaSessionCompat until setting a new MediaSessionCompat.Callback. To avoid this, when both a MediaSessionCompat and a framework android.media.session.MediaSession are needed, it is recommended to create a MediaSessionCompat first and get the framework session through getMediaSession.

Parameters
context: Context!

The context to use to create the session.
mediaSession: Any!

A android.media.session.MediaSession object.
Returns
MediaSessionCompat!

An equivalent MediaSessionCompat object, or null if none.

getController

Added in 1.1.0
fun getController(): MediaControllerCompat!

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

Returns
MediaControllerCompat!

A controller for this session.

getCurrentControllerInfo

Added in 1.1.0
fun getCurrentControllerInfo(): MediaSessionManager.RemoteUserInfo

Gets the controller information who sent the current request.

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

Note: From API 21 to 23, this method returns a fake RemoteUserInfo which has following values:

Note: From API 24 to 27, the RemoteUserInfo returned from this method will have negative uid and pid. Most of the cases it will have the correct package name, but sometimes it will fail to get the right one.

See also
LEGACY_CONTROLLER
isTrustedForMediaControl

getMediaSession

Added in 1.1.0
fun getMediaSession(): Any!

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

This method is only supported on API 21+.

Returns
Any!

The underlying android.media.session.MediaSession object, or null if none.

getRemoteControlClient

Added in 1.1.0
fun getRemoteControlClient(): Any!

Gets the underlying framework android.media.RemoteControlClient object.

This method is only supported on APIs 14-20. On API 21+ getMediaSession should be used instead.

Returns
Any!

The underlying android.media.RemoteControlClient object, or null if none.

getSessionToken

Added in 1.1.0
fun getSessionToken(): MediaSessionCompat.Token!

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

On platform versions before 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.

Returns
MediaSessionCompat.Token!

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

isActive

Added in 1.1.0
fun isActive(): Boolean

Gets the current active state of this session.

Returns
Boolean

True if the session is active, false otherwise.

release

Added in 1.1.0
fun release(): Unit

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.

removeOnActiveChangeListener

Added in 1.1.0
fun removeOnActiveChangeListener(
    listener: MediaSessionCompat.OnActiveChangeListener!
): Unit

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

Parameters
listener: MediaSessionCompat.OnActiveChangeListener!

The listener to remove.

sendSessionEvent

Added in 1.1.0
fun sendSessionEvent(event: String!, extras: Bundle!): Unit

Sends 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
extras: Bundle!

Any extras included with the event

setActive

Added in 1.1.0
fun setActive(active: Boolean): Unit

Sets 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 LOLLIPOP, a media button event receiver should be set via the constructor to receive media button events.

Parameters
active: Boolean

Whether this session is active or not.

setCallback

Added in 1.1.0
fun setCallback(callback: MediaSessionCompat.Callback!): Unit

Adds 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. Set the callback to null to stop receiving events.

Don't reuse the callback among the sessions. Callbacks keep internal reference to the session when it's set, so it may misbehave.

Parameters
callback: MediaSessionCompat.Callback!

The callback object

setCallback

Added in 1.1.0
fun setCallback(callback: MediaSessionCompat.Callback!, handler: Handler!): Unit

Sets the callback to receive updates for the MediaSession. This includes media button and volume events. Set the callback to null to stop receiving events.

Don't reuse the callback among the sessions. Callbacks keep internal reference to the session when it's set, so it may misbehave.

Parameters
callback: MediaSessionCompat.Callback!

The callback to receive updates on.
handler: Handler!

The handler that events should be posted on.

setCaptioningEnabled

Added in 1.1.0
fun setCaptioningEnabled(enabled: Boolean): Unit

Enables/disables captioning for this session.

Parameters
enabled: Boolean

true to enable captioning, false to disable.

setExtras

Added in 1.1.0
fun setExtras(extras: Bundle!): Unit

Sets some extras that can be associated with the MediaSessionCompat. No assumptions should be made as to how a MediaControllerCompat 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 session.

setFlags

Added in 1.1.0
fun setFlags(flags: Int): Unit

Sets any flags for the session.

Parameters
flags: Int

The flags to set for this session.

setMediaButtonReceiver

Added in 1.1.0
fun setMediaButtonReceiver(mbr: PendingIntent!): Unit

Sets 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.

This method will only work on LOLLIPOP and later. Earlier platform versions must include the media button receiver in the constructor.

Parameters
mbr: PendingIntent!

The PendingIntent to send the media button event to.

setMetadata

Added in 1.1.0
fun setMetadata(metadata: MediaMetadataCompat!): Unit

Updates the current metadata. New metadata can be created using android.support.v4.media.MediaMetadataCompat.Builder. This operation may take time proportional to the size of the bitmap to replace large bitmaps with a scaled down copy.

Parameters
metadata: MediaMetadataCompat!

The new metadata
See also
putBitmap

setPlaybackState

Added in 1.1.0
fun setPlaybackState(state: PlaybackStateCompat!): Unit

Updates the current playback state.

Parameters
state: PlaybackStateCompat!

The current state of playback

setPlaybackToLocal

Added in 1.1.0
fun setPlaybackToLocal(stream: Int): Unit

Sets the stream this session is playing on. This will affect the system's volume handling for this session. If 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 STREAM_MUSIC.

Parameters
stream: Int

The AudioManager stream this session is playing on.

setPlaybackToRemote

Added in 1.1.0
fun setPlaybackToRemote(volumeProvider: VolumeProviderCompat!): Unit

Configures 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 setPlaybackToLocal was previously called that stream will stop receiving volume changes for this session.

On platforms earlier than LOLLIPOP this will only allow an app to handle volume commands sent directly to the session by a MediaControllerCompat. System routing of volume keys will not use the volume provider.

Parameters
volumeProvider: VolumeProviderCompat!

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

setQueue

Added in 1.1.0
fun setQueue(queue: (Mutable)List<MediaSessionCompat.QueueItem!>!): Unit

Updates 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. The id of each item should be unique within the play queue. 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: (Mutable)List<MediaSessionCompat.QueueItem!>!

A list of items in the play queue.

setQueueTitle

Added in 1.1.0
fun setQueueTitle(title: CharSequence!): Unit

Sets 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.

setRatingType

Added in 1.1.0
fun setRatingType(type: Int): Unit

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

setRepeatMode

Added in 1.1.0
fun setRepeatMode(repeatMode: Int): Unit

Sets the repeat mode for this session.

Note that if this method is not called before, getRepeatMode will return REPEAT_MODE_NONE.

Parameters
repeatMode: Int

The repeat mode. Must be one of the followings: REPEAT_MODE_NONE, REPEAT_MODE_ONE, REPEAT_MODE_ALL, REPEAT_MODE_GROUP

setSessionActivity

Added in 1.1.0
fun setSessionActivity(pi: PendingIntent!): Unit

Sets 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.

Parameters
pi: PendingIntent!

The intent to launch to show UI for this Session.

setShuffleMode

Added in 1.1.0
fun setShuffleMode(shuffleMode: Int): Unit

Sets the shuffle mode for this session.

Note that if this method is not called before, getShuffleMode will return SHUFFLE_MODE_NONE.

Parameters
shuffleMode: Int

The shuffle mode. Must be one of the followings: SHUFFLE_MODE_NONE, SHUFFLE_MODE_ALL, SHUFFLE_MODE_GROUP