added in version 22.1.0
belongs to Maven artifact com.android.support:support-media-compat:28.0.0-alpha1

MediaControllerCompat

public final class MediaControllerCompat
extends Object

java.lang.Object
   ↳ 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 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:

Developer Guides

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

Summary

Nested classes

class MediaControllerCompat.Callback

Callback for receiving updates on from the session. 

class MediaControllerCompat.PlaybackInfo

Holds information about the way volume is handled for this session. 

class MediaControllerCompat.TransportControls

Interface for controlling media playback on a session. 

Public constructors

MediaControllerCompat(Context context, MediaSessionCompat session)

Creates a media controller from a session.

MediaControllerCompat(Context context, 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 MediaController object.

static MediaControllerCompat getMediaController(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.

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.

MediaSessionCompat.Token getSessionToken()

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

int getShuffleMode()

Gets the shuffle mode for this session.

MediaControllerCompat.TransportControls getTransportControls()

Gets a MediaControllerCompat.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(MediaControllerCompat.Callback callback, Handler handler)

Adds a callback to receive updates from the session.

void registerCallback(MediaControllerCompat.Callback callback)

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 was deprecated in API level 26.1.0. Use removeQueueItem(MediaDescriptionCompat) instead.

void sendCommand(String command, Bundle params, ResultReceiver cb)

Sends a generic command to the session.

static void setMediaController(Activity activity, MediaControllerCompat mediaController)

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

void setVolumeTo(int value, int flags)

Sets the volume of the output this session is playing on.

void unregisterCallback(MediaControllerCompat.Callback callback)

Stops receiving updates on the specified callback.

Inherited methods

From class java.lang.Object

Public constructors

MediaControllerCompat

added in version 22.1.0
MediaControllerCompat (Context context,
                MediaSessionCompat session)

Creates a media controller from a session.

Parameters
context Context

session MediaSessionCompat: The session to be controlled.

MediaControllerCompat

added in version 22.1.0
MediaControllerCompat (Context context,
                MediaSessionCompat.Token sessionToken)

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

Parameters
context Context

sessionToken MediaSessionCompat.Token: The token of the session to be controlled.

Throws
RemoteException if the session is not accessible.

Public methods

addQueueItem

added in version 25.4.0
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
description MediaDescriptionCompat: The MediaDescriptionCompat for creating the MediaSessionCompat.QueueItem to be inserted.

Throws
UnsupportedOperationException If this session doesn't support this.

addQueueItem

added in version 25.4.0
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
description MediaDescriptionCompat: The MediaDescriptionCompat for creating the MediaSessionCompat.QueueItem to be inserted.

index int: The index at which the created MediaSessionCompat.QueueItem is to be inserted.

Throws
UnsupportedOperationException If this session doesn't support this.

adjustVolume

added in version 22.1.0
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
direction int: The direction to adjust the volume in.

flags int: Any flags to pass with the command.

See also:

dispatchMediaButtonEvent

added in version 22.1.0
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 version 22.1.0
Bundle getExtras ()

Gets the extras for this session.

Returns
Bundle

getFlags

added in version 22.1.0
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 version 22.1.0
Object getMediaController ()

Gets the underlying framework MediaController object.

This method is only supported on API 21+.

Returns
Object The underlying MediaController object, or null if none.

getMediaController

added in version 25.1.0
MediaControllerCompat getMediaController (Activity activity)

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

This is compatible with getMediaController().

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

Returns
MediaControllerCompat The controller which should receive events.

getMetadata

added in version 22.1.0
MediaMetadataCompat getMetadata ()

Gets the current metadata for this session.

Returns
MediaMetadataCompat<