MediaControllerCompat

Kotlin |Java

class MediaControllerCompat

kotlin.Any
↳	android.support.v4.media.session.MediaControllerCompat

Allows an app to interact with an ongoing media session. Media buttons and other commands can be sent to the session. A callback may be registered to receive updates from the session, such as metadata and play state changes.

A MediaController can be created if you have a MediaSessionCompat.Token from the session owner.

MediaController objects are thread-safe.

This is a helper for accessing features in android.media.session.MediaSession introduced after API level 4 in a backwards compatible fashion.

If MediaControllerCompat is created with a session token from another process, following methods will not work directly after the creation if the session token is not passed through a MediaBrowserCompat:

• getPlaybackState().getExtras()
• getRatingType()
• getRepeatMode()
• getShuffleMode()
• isCaptioningEnabled()

Developer Guides

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

Summary

Nested classes
abstract	Callback Callback for receiving updates on from the session.
	PlaybackInfo Holds information about the way volume is handled for this session.
abstract	TransportControls Interface for controlling media playback on a session.

Public constructors
<init>(context: Context!, @NonNull session: MediaSessionCompat) Creates a media controller from a session.
<init>(context: Context!, @NonNull sessionToken: MediaSessionCompat.Token) Creates a media controller from a session token which may have been obtained from another process.

Public methods
Unit	addQueueItem(description: MediaDescriptionCompat!) Adds a queue item from the given description at the end of the play queue of this session.
Unit	addQueueItem(description: MediaDescriptionCompat!, index: Int) Adds a queue item from the given description at the specified position in the play queue of this session.
Unit	adjustVolume(direction: Int, flags: Int) Adjusts the volume of the output this session is playing on.
Boolean	dispatchMediaButtonEvent(keyEvent: KeyEvent!) Sends the specified media button event to the session.
Bundle!	getExtras() Gets the extras for this session.
Long	getFlags() Gets the flags for this session.
Any!	getMediaController() Gets the underlying framework android.media.session.MediaController object.
static MediaControllerCompat!	getMediaController(@NonNull activity: Activity) Retrieves the MediaControllerCompat set in the activity by setMediaController(Activity, MediaControllerCompat) for sending media key and volume events.
MediaMetadataCompat!	getMetadata() Gets the current metadata for this session.
String!	getPackageName() Gets the session owner's package name.
MediaControllerCompat.PlaybackInfo!	getPlaybackInfo() Gets the current playback info for this session.
PlaybackStateCompat!	getPlaybackState() Gets the current playback state for this session.
MutableList<MediaSessionCompat.QueueItem!>!	getQueue() Gets the current play queue for this session if one is set.
CharSequence!	getQueueTitle() Gets the queue title for this session.
Int	getRatingType() Gets the rating type supported by the session.
Int	getRepeatMode() Gets the repeat mode for this session.
PendingIntent!	getSessionActivity() Gets an intent for launching UI associated with this session if one exists.
MediaSessionCompat.Token!	getSessionToken() Gets the token for the session that this controller is connected to.
Int	getShuffleMode() Gets the shuffle mode for this session.
MediaControllerCompat.TransportControls!	getTransportControls() Gets a TransportControls instance for this session.
Boolean	isCaptioningEnabled() Returns whether captioning is enabled for this session.
Boolean	isSessionReady() Returns whether the session is ready or not.
Unit	registerCallback(@NonNull callback: MediaControllerCompat.Callback) Adds a callback to receive updates from the Session.
Unit	registerCallback(@NonNull callback: MediaControllerCompat.Callback, handler: Handler!) Adds a callback to receive updates from the session.
Unit	removeQueueItem(description: MediaDescriptionCompat!) Removes the first occurrence of the specified MediaSessionCompat.QueueItem with the given description in the play queue of the associated session.
Unit	removeQueueItemAt(index: Int) Removes an queue item at the specified position in the play queue of this session.
Unit	sendCommand(@NonNull command: String, @Nullable params: Bundle?, @Nullable cb: ResultReceiver?) Sends a generic command to the session.
static Unit	setMediaController(@NonNull activity: Activity, mediaController: MediaControllerCompat!) Sets a MediaControllerCompat in the activity for later retrieval via getMediaController(Activity).
Unit	setVolumeTo(value: Int, flags: Int) Sets the volume of the output this session is playing on.
Unit	unregisterCallback(@NonNull callback: MediaControllerCompat.Callback) Stops receiving updates on the specified callback.

Public constructors

<init>

MediaControllerCompat(context: Context!, @NonNull session: MediaSessionCompat)

Creates a media controller from a session.

Parameters
session	Context!: The session to be controlled.

<init>

MediaControllerCompat(context: Context!, @NonNull sessionToken: MediaSessionCompat.Token)

Creates a media controller from a session token which may have been obtained from another process.

Parameters
sessionToken	Context!: The token of the session to be controlled.

Exceptions
RemoteException	if the session is not accessible.

Public methods

addQueueItem

fun addQueueItem(description: MediaDescriptionCompat!): Unit

Adds a queue item from the given description at the end of the play queue of this session. Not all sessions may support this. To know whether the session supports this, get the session's flags with getFlags() and check that the flag MediaSessionCompat#FLAG_HANDLES_QUEUE_COMMANDS is set.

Parameters
description	MediaDescriptionCompat!: The MediaDescriptionCompat for creating the MediaSessionCompat.QueueItem to be inserted.

Exceptions
UnsupportedOperationException	If this session doesn't support this.

See Also

• #getFlags()MediaSessionCompat#FLAG_HANDLES_QUEUE_COMMANDS

addQueueItem

fun addQueueItem(description: MediaDescriptionCompat!, index: Int): Unit

Adds a queue item from the given description at the specified position in the play queue of this session. Shifts the queue item currently at that position (if any) and any subsequent queue items to the right (adds one to their indices). Not all sessions may support this. To know whether the session supports this, get the session's flags with getFlags() and check that the flag MediaSessionCompat#FLAG_HANDLES_QUEUE_COMMANDS is set.

Parameters
description	MediaDescriptionCompat!: The MediaDescriptionCompat for creating the MediaSessionCompat.QueueItem to be inserted.
index	MediaDescriptionCompat!: The index at which the created MediaSessionCompat.QueueItem is to be inserted.

Exceptions
UnsupportedOperationException	If this session doesn't support this.

See Also

• #getFlags()MediaSessionCompat#FLAG_HANDLES_QUEUE_COMMANDS

adjustVolume

fun adjustVolume(direction: Int, flags: Int): Unit

Adjusts the volume of the output this session is playing on. The direction must be one of AudioManager#ADJUST_LOWER, AudioManager#ADJUST_RAISE, or AudioManager#ADJUST_SAME. The command will be ignored if the session does not support VolumeProviderCompat#VOLUME_CONTROL_RELATIVE or VolumeProviderCompat#VOLUME_CONTROL_ABSOLUTE. The flags in AudioManager may be used to affect the handling.

Parameters
direction	Int: The direction to adjust the volume in.
flags	Int: Any flags to pass with the command.

See Also

• #getPlaybackInfo()

dispatchMediaButtonEvent

fun dispatchMediaButtonEvent(keyEvent: KeyEvent!): Boolean

Sends the specified media button event to the session. Only media keys can be sent by this method, other keys will be ignored.

Parameters
keyEvent	KeyEvent!: The media button event to dispatch.

Return
Boolean: true if the event was sent to the session, false otherwise.

getExtras

fun getExtras(): Bundle!

Gets the extras for this session.

getFlags

fun getFlags(): Long

Gets the flags for this session. Flags are defined in MediaSessionCompat.

Return
Long: The current set of flags for the session.

getMediaController

fun getMediaController(): Any!

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

This method is only supported on API 21+.

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

getMediaController

static fun getMediaController(@NonNull activity: Activity): MediaControllerCompat!

Retrieves the MediaControllerCompat set in the activity by setMediaController(Activity, MediaControllerCompat) for sending media key and volume events.

This is compatible with Activity#getMediaController().

Parameters
activity	Activity: The activity to get the media controller from, must not be null.

Return
MediaControllerCompat!: The controller which should receive events.

See Also

• #setMediaController(Activity, MediaControllerCompat)

getMetadata

fun getMetadata(): MediaMetadataCompat!

Gets the current metadata for this session.

Return
MediaMetadataCompat!: The current MediaMetadata or null.

getPackageName

fun getPackageName(): String!

Gets the session owner's package name.

Return
String!: The package name of of the session owner.

getPlaybackInfo

fun getPlaybackInfo(): MediaControllerCompat.PlaybackInfo!

Gets the current playback info for this session.

Return
MediaControllerCompat.PlaybackInfo!: The current playback info or null.

getPlaybackState

fun getPlaybackState(): PlaybackStateCompat!

Gets the current playback state for this session.

If the session is not ready, PlaybackStateCompat#getExtras() on the result of this method may return null.

Return
PlaybackStateCompat!: The current PlaybackState or null

See Also

• #isSessionReadyCallback#onSessionReady

getQueue

fun getQueue(): MutableList<MediaSessionCompat.QueueItem!>!

Gets the current play queue for this session if one is set. If you only care about the current item getMetadata() should be used.

Return
MutableList<MediaSessionCompat.QueueItem!>!: The current play queue or null.

getQueueTitle

fun getQueueTitle(): CharSequence!

Gets the queue title for this session.

getRatingType

fun getRatingType(): Int

Gets the rating type supported by the session. One of:

• RatingCompat#RATING_NONE
• RatingCompat#RATING_HEART
• RatingCompat#RATING_THUMB_UP_DOWN
• RatingCompat#RATING_3_STARS
• RatingCompat#RATING_4_STARS
• RatingCompat#RATING_5_STARS
• RatingCompat#RATING_PERCENTAGE

If the session is not ready, it will return RatingCompat#RATING_NONE.

Return
Int: The supported rating type, or RatingCompat#RATING_NONE if the value is not set or the session is not ready.

See Also

• #isSessionReadyCallback#onSessionReady

getRepeatMode

fun getRepeatMode(): Int

Gets the repeat mode for this session.

Return
Int: The latest repeat mode set to the session, PlaybackStateCompat#REPEAT_MODE_NONE if not set, or PlaybackStateCompat#REPEAT_MODE_INVALID if the session is not ready yet.

See Also

• #isSessionReadyCallback#onSessionReady

getSessionActivity

fun getSessionActivity(): PendingIntent!

Gets an intent for launching UI associated with this session if one exists.

Return
PendingIntent!: A PendingIntent to launch UI or null.

getSessionToken

fun getSessionToken(): MediaSessionCompat.Token!

Gets the token for the session that this controller is connected to.

Return
MediaSessionCompat.Token!: The session's token.

getShuffleMode

fun getShuffleMode(): Int

Gets the shuffle mode for this session.

Return
Int: The latest shuffle mode set to the session, or PlaybackStateCompat#SHUFFLE_MODE_NONE if disabled or not set, or PlaybackStateCompat#SHUFFLE_MODE_INVALID if the session is not ready yet.

See Also

• #isSessionReadyCallback#onSessionReady

getTransportControls

fun getTransportControls(): MediaControllerCompat.TransportControls!

Gets a TransportControls instance for this session.

Return
MediaControllerCompat.TransportControls!: A controls instance

isCaptioningEnabled

fun isCaptioningEnabled(): Boolean

Returns whether captioning is enabled for this session.

If the session is not ready, it will return a false.

Return
Boolean: true if captioning is enabled, false if disabled or not set.

See Also

• #isSessionReadyCallback#onSessionReady

isSessionReady

fun isSessionReady(): Boolean

Returns whether the session is ready or not.

If the session is not ready, following methods can work incorrectly.

• getPlaybackState()
• getRatingType()
• getRepeatMode()
• getShuffleMode()
• isCaptioningEnabled()

Return
Boolean: true if the session is ready, false otherwise.

See Also

• Callback#onSessionReady()

registerCallback

fun registerCallback(@NonNull callback: MediaControllerCompat.Callback): Unit

Adds a callback to receive updates from the Session. Updates will be posted on the caller's thread.

Parameters
callback	MediaControllerCompat.Callback: The callback object, must not be null.

registerCallback

fun registerCallback(@NonNull callback: MediaControllerCompat.Callback, handler: Handler!): Unit

Adds a callback to receive updates from the session. Updates will be posted on the specified handler's thread.

Parameters
callback	MediaControllerCompat.Callback: The callback object, must not be null.
handler	MediaControllerCompat.Callback: The handler to post updates on. If null the callers thread will be used.

removeQueueItem

fun removeQueueItem(description: MediaDescriptionCompat!): Unit

Removes the first occurrence of the specified MediaSessionCompat.QueueItem with the given description in the play queue of the associated session. Not all sessions may support this. To know whether the session supports this, get the session's flags with getFlags() and check that the flag MediaSessionCompat#FLAG_HANDLES_QUEUE_COMMANDS is set.

Parameters
description	MediaDescriptionCompat!: The MediaDescriptionCompat for denoting the MediaSessionCompat.QueueItem to be removed.

Exceptions
UnsupportedOperationException	If this session doesn't support this.

See Also

• #getFlags()MediaSessionCompat#FLAG_HANDLES_QUEUE_COMMANDS

removeQueueItemAt

fun removeQueueItemAt(index: Int): Unit

Deprecated: Use removeQueueItem(MediaDescriptionCompat) instead.

Removes an queue item at the specified position in the play queue of this session. Not all sessions may support this. To know whether the session supports this, get the session's flags with getFlags() and check that the flag MediaSessionCompat#FLAG_HANDLES_QUEUE_COMMANDS is set.

Parameters
index	Int: The index of the element to be removed.

Exceptions
UnsupportedOperationException	If this session doesn't support this.

See Also

• #getFlags()MediaSessionCompat#FLAG_HANDLES_QUEUE_COMMANDS

sendCommand

fun sendCommand(@NonNull command: String, @Nullable params: Bundle?, @Nullable cb: ResultReceiver?): Unit

Sends a generic command to the session. It is up to the session creator to decide what commands and parameters they will support. As such, commands should only be sent to sessions that the controller owns.

Parameters
command	String: The command to send
params	String: Any parameters to include with the command. Can be null.
cb	String: The callback to receive the result on. Can be null.

setMediaController

static fun setMediaController(@NonNull activity: Activity, mediaController: MediaControllerCompat!): Unit

Sets a MediaControllerCompat in the activity for later retrieval via getMediaController(Activity).

This is compatible with Activity#setMediaController(MediaController). If activity inherits androidx.fragment.app.FragmentActivity, the mediaController will be saved in the activity. In addition to that, on API 21 and later, Activity#setMediaController(MediaController) will be called.

Parameters
activity	Activity: The activity to set the mediaController in, must not be null.
mediaController	Activity: The controller for the session which should receive media keys and volume changes on API 21 and later.

See Also

• #getMediaController(Activity)Activity#setMediaController(android.media.session.MediaController)

setVolumeTo

fun setVolumeTo(value: Int, flags: Int): Unit

Sets the volume of the output this session is playing on. The command will be ignored if it does not support VolumeProviderCompat#VOLUME_CONTROL_ABSOLUTE. The flags in AudioManager may be used to affect the handling.

Parameters
value	Int: The value to set it to, between 0 and the reported max.
flags	Int: Flags from AudioManager to include with the volume request.

See Also

• #getPlaybackInfo()

unregisterCallback

fun unregisterCallback(@NonNull callback: MediaControllerCompat.Callback): Unit

Stops receiving updates on the specified callback. If an update has already been posted you may still receive it after calling this method.

Parameters
callback	MediaControllerCompat.Callback: The callback to remove