Skip to content

Most visited

Recently visited

navigation

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.

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)

Add a queue item from the given description at the end of the play queue of this session.

void addQueueItem(MediaDescriptionCompat description, int index)

Add a queue item from the given description at the specified position in the play queue of this session.

void adjustVolume(int direction, int flags)

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

boolean dispatchMediaButtonEvent(KeyEvent keyEvent)

Send the specified media button event to the session.

Bundle getExtras()

Get the extras for this session.

long getFlags()

Get the flags for this session.

Object getMediaController()

Gets the underlying framework MediaController object.

static MediaControllerCompat getMediaController(Activity activity)

Retrieves the current MediaControllerCompat for sending media key and volume events.

MediaMetadataCompat getMetadata()

Get the current metadata for this session.

String getPackageName()

Get the session owner's package name.

MediaControllerCompat.PlaybackInfo getPlaybackInfo()

Get the current playback info for this session.

PlaybackStateCompat getPlaybackState()

Get the current playback state for this session.

List<MediaSessionCompat.QueueItem> getQueue()

Get the current play queue for this session if one is set.

CharSequence getQueueTitle()

Get the queue title for this session.

int getRatingType()

Get the rating type supported by the session.

int getRepeatMode()

Get the repeat mode for this session.

PendingIntent getSessionActivity()

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

MediaSessionCompat.Token getSessionToken()

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

MediaControllerCompat.TransportControls getTransportControls()

Get a MediaControllerCompat.TransportControls instance for this session.

boolean isShuffleModeEnabled()

Return whether the shuffle mode is enabled for this session.

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)

Remove the first occurrence of the specified MediaSessionCompat.QueueItem with the given description in the play queue of the associated session.

void removeQueueItemAt(int index)

Remove an queue item at the specified position in the play queue of this session.

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 for later retrieval via getMediaController().

void setVolumeTo(int value, int flags)

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

void unregisterCallback(MediaControllerCompat.Callback callback)

Stop receiving updates on the specified callback.

Inherited methods

From class java.lang.Object

Public constructors

MediaControllerCompat

MediaControllerCompat (Context context, 
                MediaSessionCompat session)

Creates a media controller from a session.

Parameters
context Context
session MediaSessionCompat: The session to be controlled.

MediaControllerCompat

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

void addQueueItem (MediaDescriptionCompat description)

Add a queue item from the given description at the end of the play queue of this session. Not all sessions may support this.

Parameters
description MediaDescriptionCompat: The MediaDescriptionCompat for creating the MediaSessionCompat.QueueItem to be inserted.
Throws
UnsupportedOperationException If this session doesn't support this.

See also:

addQueueItem

void addQueueItem (MediaDescriptionCompat description, 
                int index)

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

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.

See also:

adjustVolume

void adjustVolume (int direction, 
                int flags)

Adjust 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

boolean dispatchMediaButtonEvent (KeyEvent keyEvent)

Send 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

Bundle getExtras ()

Get the extras for this session.

Returns
Bundle

getFlags

long getFlags ()

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

Returns
long The current set of flags for the session.

getMediaController

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

MediaControllerCompat getMediaController (Activity activity)

Retrieves the current MediaControllerCompat for sending media key and volume events.

Parameters
activity Activity
Returns
MediaControllerCompat The controller which should receive events.

See also:

getMetadata

MediaMetadataCompat getMetadata ()

Get the current metadata for this session.

Returns
MediaMetadataCompat The current MediaMetadata or null.

getPackageName

String getPackageName ()

Get the session owner's package name.

Returns
String The package name of of the session owner.

getPlaybackInfo

MediaControllerCompat.PlaybackInfo getPlaybackInfo ()

Get the current playback info for this session.

Returns
MediaControllerCompat.PlaybackInfo The current playback info or null.

getPlaybackState

PlaybackStateCompat getPlaybackState ()

Get the current playback state for this session.

Returns
PlaybackStateCompat The current PlaybackState or null

getQueue

List<MediaSessionCompat.QueueItem> getQueue ()

Get 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

CharSequence getQueueTitle ()

Get the queue title for this session.

Returns
CharSequence

getRatingType

int getRatingType ()

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

Returns
int The supported rating type

getRepeatMode

int getRepeatMode ()

Get the repeat mode for this session.

Returns
int The latest repeat mode set to the session, or REPEAT_MODE_NONE if not set.

getSessionActivity

PendingIntent getSessionActivity ()

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

Returns
PendingIntent A PendingIntent to launch UI or null.

getSessionToken

MediaSessionCompat.Token getSessionToken ()

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

Returns
MediaSessionCompat.Token The session's token.

getTransportControls

MediaControllerCompat.TransportControls getTransportControls ()

Get a MediaControllerCompat.TransportControls instance for this session.

Returns
MediaControllerCompat.TransportControls A controls instance

isShuffleModeEnabled

boolean isShuffleModeEnabled ()

Return whether the shuffle mode is enabled for this session.

Returns
boolean true if the shuffle mode is enabled, false if disabled or not set.

registerCallback

void registerCallback (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
callback MediaControllerCompat.Callback: The callback object, must not be null.
handler Handler: The handler to post updates on. If null the callers thread will be used.

registerCallback

void registerCallback (MediaControllerCompat.Callback callback)

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.

removeQueueItem

void removeQueueItem (MediaDescriptionCompat description)

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

Parameters
description MediaDescriptionCompat: The MediaDescriptionCompat for denoting the MediaSessionCompat.QueueItem to be removed.
Throws
UnsupportedOperationException If this session doesn't support this.

See also:

removeQueueItemAt

void removeQueueItemAt (int index)

Remove an queue item at the specified position in the play queue of this session. Not all sessions may support this.

Parameters
index int: The index of the element to be removed.
Throws
UnsupportedOperationException If this session doesn't support this.

See also:

sendCommand

void sendCommand (String command, 
                Bundle params, 
                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
command String: The command to send
params Bundle: Any parameters to include with the command
cb ResultReceiver: The callback to receive the result on

setMediaController

void setMediaController (Activity activity, 
                MediaControllerCompat mediaController)

Sets a MediaControllerCompat for later retrieval via getMediaController().

On API 21 and later, this controller will be tied to the window of the activity and media key and volume events which are received while the Activity is in the foreground will be forwarded to the controller and used to invoke transport controls or adjust the volume. Prior to API 21, the global handling of media key and volume events through an active MediaSessionCompat and media button receiver will still be respected.

Parameters
activity Activity
mediaController MediaControllerCompat: The controller for the session which should receive media keys and volume changes on API 21 and later.

See also:

setVolumeTo

void setVolumeTo (int value, 
                int flags)

Set 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
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:

unregisterCallback

void unregisterCallback (MediaControllerCompat.Callback callback)

Stop 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
This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a one-minute survey?
Help us improve Android tools and documentation.