Google is committed to advancing racial equity for Black communities. See how.

MediaSessionCompat

open class MediaSessionCompat
kotlin.Any
   ↳ 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 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 android.media.session.MediaSession introduced after API level 4 in a backwards compatible fashion.

Summary

Nested classes

abstract

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

abstract

A single item that is part of the play queue.

Represents an ongoing session.

Constants

static String

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

static String

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

static String

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

static String

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

static String

Argument to indicate the media attribute.

static String

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

static Int

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

static Int

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

static Int

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

static Int

The value of ARGUMENT_MEDIA_ATTRIBUTE indicating the album.

static Int

The value of ARGUMENT_MEDIA_ATTRIBUTE indicating the artist.

static Int

The value of ARGUMENT_MEDIA_ATTRIBUTE indicating the playlist.

Public constructors

<init>(@NonNull context: Context, @NonNull tag: String)

Creates a new session.

<init>(@NonNull context: Context, @NonNull tag: String, @Nullable mbrComponent: ComponentName?, @Nullable mbrIntent: PendingIntent?)

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

Public methods

open Unit

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

open static MediaSessionCompat!
fromMediaSession(context: Context!, mediaSession: Any!)

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

open MediaControllerCompat!

Gets a controller for this session.

MediaSessionManager.RemoteUserInfo

Gets the controller information who sent the current request.

open Any!

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

open Any!

Gets the underlying framework android.media.RemoteControlClient object.

open MediaSessionCompat.Token!

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

open Boolean

Gets the current active state of this session.

open Unit

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

open Unit

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

open Unit
sendSessionEvent(event: String!, extras: Bundle!)

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

open Unit
setActive(active: Boolean)

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

open Unit

Adds a callback to receive updates on for the MediaSession.

open Unit

Sets the callback to receive updates for the MediaSession.

open Unit

Enables/disables captioning for this session.

open Unit
setExtras(extras: Bundle!)

Sets some extras that can be associated with the MediaSessionCompat.

open Unit
setFlags(flags: Int)

Sets any flags for the session.

open Unit

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

open Unit

Updates the current metadata.

open Unit

Updates the current playback state.

open Unit

Sets the stream this session is playing on.

open Unit

Configures this session to use remote volume handling.

open Unit

Updates the list of items in the play queue.

open Unit

Sets the title of the play queue.

open Unit

Sets the style of rating used by this session.

open Unit
setRepeatMode(repeatMode: Int)

Sets the repeat mode for this session.

open Unit

Sets an intent for launching UI for this Session.

open Unit
setShuffleMode(shuffleMode: Int)

Sets the shuffle mode for this session.

Constants

ACTION_FLAG_AS_INAPPROPRIATE

static val ACTION_FLAG_AS_INAPPROPRIATE: String

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

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

ACTION_FOLLOW

static val 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.

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

ACTION_SKIP_AD

static val ACTION_SKIP_AD: String

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

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

ACTION_UNFOLLOW

static val 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.

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

ARGUMENT_MEDIA_ATTRIBUTE

static val ARGUMENT_MEDIA_ATTRIBUTE: String

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

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

ARGUMENT_MEDIA_ATTRIBUTE_VALUE

static val ARGUMENT_MEDIA_ATTRIBUTE_VALUE: String

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

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

FLAG_HANDLES_MEDIA_BUTTONS

static val FLAG_HANDLES_MEDIA_BUTTONS: Int

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.

Value: 1 << 0

FLAG_HANDLES_QUEUE_COMMANDS

static val FLAG_HANDLES_QUEUE_COMMANDS: Int

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

Value: 1 << 2

FLAG_HANDLES_TRANSPORT_CONTROLS

static val FLAG_HANDLES_TRANSPORT_CONTROLS: Int

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

Value: 1 << 1

MEDIA_ATTRIBUTE_ALBUM

static val MEDIA_ATTRIBUTE_ALBUM: Int

The value of ARGUMENT_MEDIA_ATTRIBUTE indicating the album.

Value: 1

MEDIA_ATTRIBUTE_ARTIST

static val MEDIA_ATTRIBUTE_ARTIST: Int

The value of ARGUMENT_MEDIA_ATTRIBUTE indicating the artist.

Value: 0

MEDIA_ATTRIBUTE_PLAYLIST

static val MEDIA_ATTRIBUTE_PLAYLIST: Int

The value of ARGUMENT_MEDIA_ATTRIBUTE indicating the playlist.

Value: 2

Public constructors

<init>

MediaSessionCompat(@NonNull context: Context, @NonNull 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 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 Context: A short name for debugging purposes.

<init>

MediaSessionCompat(@NonNull context: Context, @NonNull tag: String, @Nullable mbrComponent: ComponentName?, @Nullable 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 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 Context: A short name for debugging purposes.
mbrComponent Context: The component name for your media button receiver.
mbrIntent Context: The PendingIntent for your receiver component that handles media button events. This is optional and will be used on between android.os.Build.VERSION_CODES#JELLY_BEAN_MR2 and android.os.Build.VERSION_CODES#KITKAT_WATCH instead of the component name.

Public methods

addOnActiveChangeListener

open 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

open 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 Context!: A android.media.session.MediaSession object.
Return
MediaSessionCompat!: An equivalent MediaSessionCompat object, or null if none.

getController

open fun getController(): MediaControllerCompat!

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

Return
MediaControllerCompat!: A controller for this session.

getCurrentControllerInfo

@NonNull 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 Callback#onPlay.

Note: From API 21 to 23, this method returns a dummy 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.

getMediaSession

open fun getMediaSession(): Any!

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

This method is only supported on API 21+.

Return
Any!: The underlying android.media.session.MediaSession object, or null if none.