MediaControllerCompat

Added in 1.1.0

Kotlin |Java

public final class 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:

Summary

Nested types
`public abstract class MediaControllerCompat.Callback implements IBinder.DeathRecipient` Callback for receiving updates on from the session.
`public final class MediaControllerCompat.PlaybackInfo` Holds information about the way volume is handled for this session.
`public abstract class MediaControllerCompat.TransportControls` Interface for controlling media playback on a session.

Public constructors
`MediaControllerCompat( Context context, @NonNull MediaSessionCompat session )` Creates a media controller from a session.
`MediaControllerCompat( Context context, @NonNull MediaSessionCompat.Token sessionToken )` Creates a media controller from a session token which may have been obtained from another process.

Public methods
`void`	`addQueueItem(MediaDescriptionCompat description)` Adds a queue item from the given `description` at the end of the play queue of this session.
`void`	`addQueueItem(MediaDescriptionCompat description, int index)` Adds a queue item from the given `description` at the specified position in the play queue of this session.
`void`	`adjustVolume(int direction, int flags)` 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.
`Object`	`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` 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.
`List<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.
`@NonNull Bundle`	`getSessionInfo()` Gets the additional session information which was set when the session was created.
`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.
`void`	`registerCallback(@NonNull MediaControllerCompat.Callback callback)` Adds a callback to receive updates from the Session.
`void`	`registerCallback( @NonNull MediaControllerCompat.Callback callback, Handler handler )` Adds a callback to receive updates from the session.
`void`	`removeQueueItem(MediaDescriptionCompat description)` Removes the first occurrence of the specified `MediaSessionCompat.QueueItem` with the given `description` in the play queue of the associated session.
`void`	`removeQueueItemAt(int index)` This method is deprecated. Use `removeQueueItem` instead.
`void`	`sendCommand( @NonNull String command, @Nullable Bundle params, @Nullable ResultReceiver cb )` Sends a generic command to the session.
`static void`	`setMediaController( @NonNull Activity activity, MediaControllerCompat mediaController )` Sets a `MediaControllerCompat` in the `activity` for later retrieval via `getMediaController`.
`void`	`setVolumeTo(int value, int flags)` Sets the volume of the output this session is playing on.
`void`	`unregisterCallback(@NonNull MediaControllerCompat.Callback callback)` Stops receiving updates on the specified callback.

Public constructors

MediaControllerCompat

Added in 1.1.0

public MediaControllerCompat(
    Context context,
    @NonNull MediaSessionCompat session
)

Creates a media controller from a session.

Parameters
`@NonNull MediaSessionCompat session`	The session to be controlled.

MediaControllerCompat

Added in 1.1.0

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

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

Parameters
`@NonNull MediaSessionCompat.Token sessionToken`	The token of the session to be controlled.

Public methods

addQueueItem

Added in 1.1.0

public void addQueueItem(MediaDescriptionCompat description)

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 FLAG_HANDLES_QUEUE_COMMANDS is set.

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

Throws
`java.lang.UnsupportedOperationException`	If this session doesn't support this.

See also
`getFlags`
`FLAG_HANDLES_QUEUE_COMMANDS`

addQueueItem

Added in 1.1.0

public void addQueueItem(MediaDescriptionCompat description, int index)

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 FLAG_HANDLES_QUEUE_COMMANDS is set.

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

Throws
`java.lang.UnsupportedOperationException`	If this session doesn't support this.

See also
`getFlags`
`FLAG_HANDLES_QUEUE_COMMANDS`

adjustVolume

Added in 1.1.0

public void adjustVolume(int direction, int flags)

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

Parameters
`int direction`	The direction to adjust the volume in.
`int flags`	Any flags to pass with the command.

See also
`getPlaybackInfo`

dispatchMediaButtonEvent

Added in 1.1.0

public boolean dispatchMediaButtonEvent(KeyEvent keyEvent)

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.

Returns
`boolean`	true if the event was sent to the session, false otherwise.

getExtras

Added in 1.1.0

public Bundle getExtras()

Gets the extras for this session.

getFlags

Added in 1.1.0

public long getFlags()

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

Returns
`long`	The current set of flags for the session.

getMediaController

Added in 1.1.0

public Object getMediaController()

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

This method is only supported on API 21+.

Returns
`Object`	The underlying `android.media.session.MediaController` object, or null if none.

getMediaController

Added in 1.1.0

public static MediaControllerCompat getMediaController(@NonNull Activity activity)

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

This is compatible with getMediaController.

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

Returns
`MediaControllerCompat`	The controller which should receive events.

See also
`setMediaController`

getMetadata

Added in 1.1.0

public MediaMetadataCompat getMetadata()

Gets the current metadata for this session.

Returns
`MediaMetadataCompat`	The current MediaMetadata or null.

getPackageName

Added in 1.1.0

public String getPackageName()

Gets the session owner's package name.

Returns
`String`	The package name of of the session owner.

getPlaybackInfo

Added in 1.1.0

public MediaControllerCompat.PlaybackInfo getPlaybackInfo()

Gets the current playback info for this session.

Returns
`MediaControllerCompat.PlaybackInfo`	The current playback info or null.

getPlaybackState

Added in 1.1.0

public PlaybackStateCompat getPlaybackState()

Gets the current playback state for this session.

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

Returns
`PlaybackStateCompat`	The current PlaybackState or null

See also
`isSessionReady`
`onSessionReady`

getQueue

Added in 1.1.0

public List<MediaSessionCompat.QueueItem> getQueue()

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

Returns
`List<MediaSessionCompat.QueueItem>`	The current play queue or null.

getQueueTitle

Added in 1.1.0

public CharSequence getQueueTitle()

Gets the queue title for this session.

getRatingType

Added in 1.1.0

public int getRatingType()

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

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

Returns
`int`	The supported rating type, or `RATING_NONE` if the value is not set or the session is not ready.

See also
`isSessionReady`
`onSessionReady`

getRepeatMode

Added in 1.1.0

public int getRepeatMode()

Gets the repeat mode for this session.

Returns
`int`	The latest repeat mode set to the session, `REPEAT_MODE_NONE` if not set, or `REPEAT_MODE_INVALID` if the session is not ready yet.

See also
`isSessionReady`
`onSessionReady`

getSessionActivity

Added in 1.1.0

public PendingIntent getSessionActivity()

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

Returns
`PendingIntent`	A `PendingIntent` to launch UI or null.

getSessionInfo

Added in 1.2.0

public @NonNull Bundle getSessionInfo()

Gets the additional session information which was set when the session was created. The returned Bundle can include additional unchanging information about the session. For example, it can include the version of the session application, or other app-specific unchanging information.

Returns
`@NonNull Bundle`	The additional session information, or `EMPTY` if the session didn't set the information or if the session is not ready.

See also
`isSessionReady`
`onSessionReady`

getSessionToken

Added in 1.1.0

public MediaSessionCompat.Token getSessionToken()

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

Returns
`MediaSessionCompat.Token`	The session's token.

getShuffleMode

Added in 1.1.0

public int getShuffleMode()

Gets the shuffle mode for this session.

Returns
`int`	The latest shuffle mode set to the session, or `SHUFFLE_MODE_NONE` if disabled or not set, or `SHUFFLE_MODE_INVALID` if the session is not ready yet.

See also
`isSessionReady`
`onSessionReady`

getTransportControls

Added in 1.1.0

public MediaControllerCompat.TransportControls getTransportControls()

Gets a TransportControls instance for this session.

Returns
`MediaControllerCompat.TransportControls`	A controls instance

isCaptioningEnabled

Added in 1.1.0

public boolean isCaptioningEnabled()

Returns whether captioning is enabled for this session.

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

Returns
`boolean`	`true` if captioning is enabled, `false` if disabled or not set.

See also
`isSessionReady`
`onSessionReady`

isSessionReady

Added in 1.1.0

public boolean isSessionReady()

Returns whether the session is ready or not.

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

Returns
`boolean`	true if the session is ready, false otherwise.

See also
`onSessionReady`

registerCallback

Added in 1.1.0

public void registerCallback(@NonNull MediaControllerCompat.Callback callback)

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

Parameters
`@NonNull MediaControllerCompat.Callback callback`	The callback object, must not be null.

registerCallback

Added in 1.1.0

public void registerCallback(
    @NonNull MediaControllerCompat.Callback callback,
    Handler handler
)

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

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

removeQueueItem

Added in 1.1.0

public void removeQueueItem(MediaDescriptionCompat description)

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 FLAG_HANDLES_QUEUE_COMMANDS is set.

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

Throws
`java.lang.UnsupportedOperationException`	If this session doesn't support this.

See also
`getFlags`
`FLAG_HANDLES_QUEUE_COMMANDS`

removeQueueItemAt

Added in 1.1.0

Deprecated in 1.1.0

public void removeQueueItemAt(int index)

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 FLAG_HANDLES_QUEUE_COMMANDS is set.

Parameters
`int index`	The index of the element to be removed.

Throws
`java.lang.UnsupportedOperationException`	If this session doesn't support this.

See also
`getFlags`
`FLAG_HANDLES_QUEUE_COMMANDS`

sendCommand

Added in 1.1.0

public void sendCommand(
    @NonNull String command,
    @Nullable Bundle params,
    @Nullable ResultReceiver cb
)

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
`@NonNull String command`	The command to send
`@Nullable Bundle params`	Any parameters to include with the command. Can be `null`.
`@Nullable ResultReceiver cb`	The callback to receive the result on. Can be `null`.

setMediaController

Added in 1.1.0

public static void setMediaController(
    @NonNull Activity activity,
    MediaControllerCompat mediaController
)

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

On API 21 and later, setMediaController will also be called.

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

See also
`getMediaController`
`setMediaController`

setVolumeTo

Added in 1.1.0

public void setVolumeTo(int value, int flags)

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

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

See also
`getPlaybackInfo`

unregisterCallback

Added in 1.1.0

public void unregisterCallback(@NonNull MediaControllerCompat.Callback callback)

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

Parameters
`@NonNull MediaControllerCompat.Callback callback`	The callback to remove

MediaControllerCompat

Summary

Nested types

Public constructors

Public methods

Public constructors

MediaControllerCompat

MediaControllerCompat

Public methods

addQueueItem

addQueueItem

adjustVolume

dispatchMediaButtonEvent

getExtras

getFlags

getMediaController

getMediaController

getMetadata

getPackageName

getPlaybackInfo

getPlaybackState

getQueue

getQueueTitle

getRatingType

getRepeatMode

getSessionActivity

getSessionInfo

getSessionToken

getShuffleMode

getTransportControls

isCaptioningEnabled

isSessionReady

registerCallback

registerCallback

removeQueueItem

removeQueueItemAt

sendCommand

setMediaController

setVolumeTo

unregisterCallback