MediaControllerCompat
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()
Summary
Nested classes |
|
---|---|
abstract |
Callback for receiving updates on from the session. |
Holds information about the way volume is handled for this session. |
|
abstract |
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 |
Unit |
addQueueItem(description: MediaDescriptionCompat!, index: Int) Adds a queue item from the given |
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! |
Gets the extras for this session. |
Long |
getFlags() Gets the flags for this session. |
Any! |
Gets the underlying framework |
static MediaControllerCompat! |
getMediaController(@NonNull activity: Activity) Retrieves the |
MediaMetadataCompat! |
Gets the current metadata for this session. |
String! |
Gets the session owner's package name. |
MediaControllerCompat.PlaybackInfo! |
Gets the current playback info for this session. |
PlaybackStateCompat! |
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! |
Gets the queue title for this session. |
Int |
Gets the rating type supported by the session. |
Int |
Gets the repeat mode for this session. |
PendingIntent! |
Gets an intent for launching UI associated with this session if one exists. |
MediaSessionCompat.Token! |
Gets the token for the session that this controller is connected to. |
Int |
Gets the shuffle mode for this session. |
MediaControllerCompat.TransportControls! |
Gets a |
Boolean |
Returns whether captioning is enabled for this session. |
Boolean |
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 |
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 |
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. |
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. |
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
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. |
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. |
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 |
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. |
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. |
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. |
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. |
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. |
isSessionReady
fun isSessionReady(): Boolean
Returns whether the session is ready or not.
If the session is not ready, following methods can work incorrectly.
Return | |
---|---|
Boolean: true if the session is ready, false otherwise. |
See Also
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. |
removeQueueItemAt
funremoveQueueItemAt(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. |
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. |
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
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 |