MediaSessionCompat
public
class
MediaSessionCompat
extends Object
java.lang.Object | |
↳ | android.support.v4.media.session.MediaSessionCompat |
Allows interaction with media controllers, volume keys, media buttons, and transport controls.
A MediaSession should be created when an app wants to publish media playback information or handle media keys. In general an app only needs one session for all playback, though multiple sessions can be created to provide finer grain controls of media.
Once a session is created the owner of the session may pass its
session token
to other processes to allow them to
create a MediaControllerCompat
to interact with the session.
To receive commands, media keys, and other events a MediaSessionCompat.Callback
must be
set with setCallback(Callback)
.
When an app is finished performing playback it must call release()
to clean up the session and notify any controllers.
MediaSessionCompat objects are not thread safe and all calls should be made from the same thread.
This is a helper for accessing features in
MediaSession
introduced after API level 4 in a
backwards compatible fashion.
Developer Guides
For information about building your media application, read the Media Apps developer guide.
Summary
Nested classes | |
---|---|
class |
MediaSessionCompat.Callback
Receives transport controls, media buttons, and commands from controllers and the system. |
interface |
MediaSessionCompat.OnActiveChangeListener
|
class |
MediaSessionCompat.QueueItem
A single item that is part of the play queue. |
class |
MediaSessionCompat.Token
Represents an ongoing session. |
Constants | |
---|---|
String |
ACTION_FLAG_AS_INAPPROPRIATE
Predefined custom action to flag the media that is currently playing as inappropriate. |
String |
ACTION_FOLLOW
Predefined custom action to follow an artist, album, or playlist. |
String |
ACTION_SKIP_AD
Predefined custom action to skip the advertisement that is currently playing. |
String |
ACTION_UNFOLLOW
Predefined custom action to unfollow an artist, album, or playlist. |
String |
ARGUMENT_MEDIA_ATTRIBUTE
Argument to indicate the media attribute. |
String |
ARGUMENT_MEDIA_ATTRIBUTE_VALUE
String argument to indicate the value of the media attribute (e.g., the name of the artist). |
int |
FLAG_HANDLES_MEDIA_BUTTONS
This constant is deprecated. This flag is no longer used. All media sessions are expected to handle media button events now. For backward compatibility, this flag will be always set. |
int |
FLAG_HANDLES_QUEUE_COMMANDS
Sets this flag on the session to indicate that it handles queue
management commands through its |
int |
FLAG_HANDLES_TRANSPORT_CONTROLS
This constant is deprecated. This flag is no longer used. All media sessions are expected to handle transport controls now. For backward compatibility, this flag will be always set. |
int |
MEDIA_ATTRIBUTE_ALBUM
The value of |
int |
MEDIA_ATTRIBUTE_ARTIST
The value of |
int |
MEDIA_ATTRIBUTE_PLAYLIST
The value of |
Public constructors | |
---|---|
MediaSessionCompat(Context context, String tag)
Creates a new session. |
|
MediaSessionCompat(Context context, String tag, ComponentName mbrComponent, PendingIntent mbrIntent)
Creates a new session with a specified media button receiver (a component name and/or a pending intent). |
Public methods | |
---|---|
void
|
addOnActiveChangeListener(MediaSessionCompat.OnActiveChangeListener listener)
Adds a listener to be notified when the active status of this session changes. |
static
MediaSessionCompat
|
fromMediaSession(Context context, Object mediaSession)
Creates an instance from a framework |
MediaControllerCompat
|
getController()
Gets a controller for this session. |
final
MediaSessionManager.RemoteUserInfo
|
getCurrentControllerInfo()
Gets the controller information who sent the current request. |
Object
|
getMediaSession()
Gets the underlying framework |
Object
|
getRemoteControlClient()
Gets the underlying framework |
MediaSessionCompat.Token
|
getSessionToken()
Retrieves a token object that can be used by apps to create a
|
boolean
|
isActive()
Gets the current active state of this session. |
void
|
release()
This must be called when an app has finished performing playback. |
void
|
removeOnActiveChangeListener(MediaSessionCompat.OnActiveChangeListener listener)
Stops the listener from being notified when the active status of this session changes. |
void
|
sendSessionEvent(String event, Bundle extras)
Sends a proprietary event to all MediaControllers listening to this Session. |
void
|
setActive(boolean active)
Sets if this session is currently active and ready to receive commands. |
void
|
setCallback(MediaSessionCompat.Callback callback, Handler handler)
Sets the callback to receive updates for the MediaSession. |
void
|
setCallback(MediaSessionCompat.Callback callback)
Adds a callback to receive updates on for the MediaSession. |
void
|
setCaptioningEnabled(boolean enabled)
Enables/disables captioning for this session. |
void
|
setExtras(Bundle extras)
Sets some extras that can be associated with the
|
void
|
setFlags(int flags)
Sets any flags for the session. |
void
|
setMediaButtonReceiver(PendingIntent mbr)
Sets a pending intent for your media button receiver to allow restarting playback after the session has been stopped. |
void
|
setMetadata(MediaMetadataCompat metadata)
Updates the current metadata. |
void
|
setPlaybackState(PlaybackStateCompat state)
Updates the current playback state. |
void
|
setPlaybackToLocal(int stream)
Sets the stream this session is playing on. |
void
|
setPlaybackToRemote(VolumeProviderCompat volumeProvider)
Configures this session to use remote volume handling. |
void
|
setQueue(List<MediaSessionCompat.QueueItem> queue)
Updates the list of items in the play queue. |
void
|
setQueueTitle(CharSequence title)
Sets the title of the play queue. |
void
|
setRatingType(int type)
Sets the style of rating used by this session. |
void
|
setRepeatMode(int repeatMode)
Sets the repeat mode for this session. |
void
|
setSessionActivity(PendingIntent pi)
Sets an intent for launching UI for this Session. |
void
|
setShuffleMode(int shuffleMode)
Sets the shuffle mode for this session. |
Inherited methods | |
---|---|
Constants
ACTION_FLAG_AS_INAPPROPRIATE
public static final String ACTION_FLAG_AS_INAPPROPRIATE
Predefined custom action to flag the media that is currently playing as inappropriate.
Constant Value: "android.support.v4.media.session.action.FLAG_AS_INAPPROPRIATE"
ACTION_FOLLOW
public static final String ACTION_FOLLOW
Predefined custom action to follow an artist, album, or playlist. The extra bundle must have
ARGUMENT_MEDIA_ATTRIBUTE
to indicate the type of the follow action. The
bundle can also have an optional string argument,
ARGUMENT_MEDIA_ATTRIBUTE_VALUE
, to specify the target to follow (e.g., the
name of the artist to follow). If this argument is omitted, the currently playing media will
be the target of the action. Thus, the session must perform the follow action with the
current metadata. If there's no specified attribute in the current metadata, the controller
must not omit this argument.
See also:
Constant Value: "android.support.v4.media.session.action.FOLLOW"
ACTION_SKIP_AD
public static final String ACTION_SKIP_AD
Predefined custom action to skip the advertisement that is currently playing.
Constant Value: "android.support.v4.media.session.action.SKIP_AD"
ACTION_UNFOLLOW
public static final String ACTION_UNFOLLOW
Predefined custom action to unfollow an artist, album, or playlist. The extra bundle must
have ARGUMENT_MEDIA_ATTRIBUTE
to indicate the type of the unfollow action.
The bundle can also have an optional string argument,
ARGUMENT_MEDIA_ATTRIBUTE_VALUE
, to specify the target to unfollow (e.g., the
name of the artist to unfollow). If this argument is omitted, the currently playing media
will be the target of the action. Thus, the session must perform the unfollow action with the
current metadata. If there's no specified attribute in the current metadata, the controller
must not omit this argument.
See also:
Constant Value: "android.support.v4.media.session.action.UNFOLLOW"
ARGUMENT_MEDIA_ATTRIBUTE
public static final String ARGUMENT_MEDIA_ATTRIBUTE
Argument to indicate the media attribute. It should be one of the following:
Constant Value: "android.support.v4.media.session.ARGUMENT_MEDIA_ATTRIBUTE"
ARGUMENT_MEDIA_ATTRIBUTE_VALUE
public static final String ARGUMENT_MEDIA_ATTRIBUTE_VALUE
String argument to indicate the value of the media attribute (e.g., the name of the artist).
Constant Value: "android.support.v4.media.session.ARGUMENT_MEDIA_ATTRIBUTE_VALUE"
FLAG_HANDLES_MEDIA_BUTTONS
public static final int FLAG_HANDLES_MEDIA_BUTTONS
This constant is deprecated.
This flag is no longer used. All media sessions are expected to handle media
button events now. For backward compatibility, this flag will be always set.
Sets this flag on the session to indicate that it can handle media button events.
Constant Value: 1 (0x00000001)
FLAG_HANDLES_QUEUE_COMMANDS
public static final int FLAG_HANDLES_QUEUE_COMMANDS
Sets this flag on the session to indicate that it handles queue
management commands through its MediaSessionCompat.Callback
.
Constant Value: 4 (0x00000004)
FLAG_HANDLES_TRANSPORT_CONTROLS
public static final int FLAG_HANDLES_TRANSPORT_CONTROLS
This constant is deprecated.
This flag is no longer used. All media sessions are expected to handle transport
controls now. For backward compatibility, this flag will be always set.
Sets this flag on the session to indicate that it handles transport
control commands through its MediaSessionCompat.Callback
.
Constant Value: 2 (0x00000002)
MEDIA_ATTRIBUTE_ALBUM
public static final int MEDIA_ATTRIBUTE_ALBUM
The value of ARGUMENT_MEDIA_ATTRIBUTE
indicating the album.
See also:
Constant Value: 1 (0x00000001)
MEDIA_ATTRIBUTE_ARTIST
public static final int MEDIA_ATTRIBUTE_ARTIST
The value of ARGUMENT_MEDIA_ATTRIBUTE
indicating the artist.
See also:
Constant Value: 0 (0x00000000)
MEDIA_ATTRIBUTE_PLAYLIST
public static final int MEDIA_ATTRIBUTE_PLAYLIST
The value of ARGUMENT_MEDIA_ATTRIBUTE
indicating the playlist.
See also:
Constant Value: 2 (0x00000002)
Public constructors
MediaSessionCompat
public MediaSessionCompat (Context context, String tag)
Creates a new session. You must call release()
when finished with the session.
The session will automatically be registered with the system but will not be published
until setActive(true)
is called.
For API 20 or earlier, note that a media button receiver is required for handling
Intent.ACTION_MEDIA_BUTTON
. This constructor will attempt to find an appropriate
BroadcastReceiver
from your manifest. See MediaButtonReceiver
for more
details.
Parameters | |
---|---|
context |
Context : The context to use to create the session. |
tag |
String : A short name for debugging purposes.
|
MediaSessionCompat
public MediaSessionCompat (Context context, String tag, ComponentName mbrComponent, PendingIntent mbrIntent)
Creates a new session with a specified media button receiver (a component name and/or
a pending intent). You must call release()
when finished with the session.
The session will automatically be registered with the system but will not be published
until setActive(true)
is called.
For API 20 or earlier, note that a media button receiver is required for handling
Intent.ACTION_MEDIA_BUTTON
. This constructor will attempt to find an appropriate
BroadcastReceiver
from your manifest if it's not specified. See
MediaButtonReceiver
for more details.
Parameters | |
---|---|
context |
Context : The context to use to create the session. |
tag |
String : A short name for debugging purposes. |
mbrComponent |
ComponentName : The component name for your media button receiver. |
mbrIntent |
PendingIntent : The PendingIntent for your receiver component that handles
media button events. This is optional and will be used on between
Build.VERSION_CODES.JELLY_BEAN_MR2 and
Build.VERSION_CODES.KITKAT_WATCH instead of the
component name.
|
Public methods
addOnActiveChangeListener
public void addOnActiveChangeListener (MediaSessionCompat.OnActiveChangeListener listener)
Adds a listener to be notified when the active status of this session changes. This is primarily used by the support library and should not be needed by apps.
Parameters | |
---|---|
listener |
MediaSessionCompat.OnActiveChangeListener : The listener to add.
|
fromMediaSession
public static MediaSessionCompat fromMediaSession (Context context, Object mediaSession)
Creates an instance from a framework MediaSession
object.
This method is only supported on API 21+. On API 20 and below, it returns null.
Note: A MediaSessionCompat
object returned from this method may not provide the full
functionality of MediaSessionCompat
until setting a new
MediaSessionCompat.Callback
. To avoid this, when both a MediaSessionCompat
and a framework MediaSession
are needed, it is recommended
to create a MediaSessionCompat
first and get the framework session through
getMediaSession()
.
Parameters | |
---|---|
context |
Context : The context to use to create the session. |
mediaSession |
Object : A MediaSession object. |
Returns | |
---|---|
MediaSessionCompat |
An equivalent MediaSessionCompat object, or null if none.
|
getController
public MediaControllerCompat getController ()
Gets a controller for this session. This is a convenience method to avoid having to cache your own controller in process.
Returns | |
---|---|
MediaControllerCompat |
A controller for this session. |
getCurrentControllerInfo
public final MediaSessionManager.RemoteUserInfo getCurrentControllerInfo ()
Gets the controller information who sent the current request.
Note: This is only valid while in a request callback, such as MediaSessionCompat.Callback.onPlay()
.
Note: From API 21 to 23, this method returns a dummy MediaSessionManager.RemoteUserInfo
which has
following values:
- Package name is
MediaSessionManager.RemoteUserInfo.LEGACY_CONTROLLER
. - PID and UID will have negative values.
Note: From API 24 to 27, the MediaSessionManager.RemoteUserInfo
returned from this method will have
negative uid and pid. Most of the cases it will have the correct package name, but sometimes
it will fail to get the right one.
Returns | |
---|---|
MediaSessionManager.RemoteUserInfo |
getMediaSession
public Object getMediaSession ()
Gets the underlying framework MediaSession
object.
This method is only supported on API 21+.
Returns | |
---|---|
Object |
The underlying MediaSession object,
or null if none.
|
getRemoteControlClient
public Object getRemoteControlClient ()
Gets the underlying framework RemoteControlClient
object.
This method is only supported on APIs 14-20. On API 21+
getMediaSession()
should be used instead.
Returns | |
---|---|
Object |
The underlying RemoteControlClient object,
or null if none.
|
getSessionToken
public MediaSessionCompat.Token getSessionToken ()
Retrieves a token object that can be used by apps to create a
MediaControllerCompat
for interacting with this session. The
owner of the session is responsible for deciding how to distribute these
tokens.
On platform versions before
Build.VERSION_CODES.LOLLIPOP
this token may only be
used within your app as there is no way to guarantee other apps are using
the same version of the support library.
Returns | |
---|---|
MediaSessionCompat.Token |
A token that can be used to create a media controller for this session. |
isActive
public boolean isActive ()
Gets the current active state of this session.
Returns | |
---|---|
boolean |
True if the session is active, false otherwise. |
release
public void release ()
This must be called when an app has finished performing playback. If playback is expected to start again shortly the session can be left open, but it must be released if your activity or service is being destroyed.
removeOnActiveChangeListener
public void removeOnActiveChangeListener (MediaSessionCompat.OnActiveChangeListener listener)
Stops the listener from being notified when the active status of this session changes.
Parameters | |
---|---|
listener |
MediaSessionCompat.OnActiveChangeListener : The listener to remove.
|
sendSessionEvent
public void sendSessionEvent (String event, Bundle extras)
Sends a proprietary event to all MediaControllers listening to this Session. It's up to the Controller/Session owner to determine the meaning of any events.
Parameters | |
---|---|
event |
String : The name of the event to send |
extras |
Bundle : Any extras included with the event
|
setActive
public void setActive (boolean active)
Sets if this session is currently active and ready to receive commands. If set to false your session's controller may not be discoverable. You must set the session to active before it can start receiving media button events or transport commands.
On platforms earlier than
Build.VERSION_CODES.LOLLIPOP
,
a media button event receiver should be set via the constructor to
receive media button events.
Parameters | |
---|---|
active |
boolean : Whether this session is active or not.
|
setCallback
public void setCallback (MediaSessionCompat.Callback callback, Handler handler)
Sets the callback to receive updates for the MediaSession. This includes media button and volume events. Set the callback to null to stop receiving events.
Parameters | |
---|---|
callback |
MediaSessionCompat.Callback : The callback to receive updates on. |
handler |
Handler : The handler that events should be posted on.
|
setCallback
public void setCallback (MediaSessionCompat.Callback callback)
Adds a callback to receive updates on for the MediaSession. This includes media button and volume events. The caller's thread will be used to post events.
Parameters | |
---|---|
callback |
MediaSessionCompat.Callback : The callback object
|
setCaptioningEnabled
public void setCaptioningEnabled (boolean enabled)
Enables/disables captioning for this session.
Parameters | |
---|---|
enabled |
boolean : true to enable captioning, false to disable.
|
setExtras
public void setExtras (Bundle extras)
Sets some extras that can be associated with the
MediaSessionCompat
. No assumptions should be made as to how a
MediaControllerCompat
will handle these extras. Keys should be
fully qualified (e.g. com.example.MY_EXTRA) to avoid conflicts.
Parameters | |
---|---|
extras |
Bundle : The extras associated with the session.
|
setFlags
public void setFlags (int flags)
Sets any flags for the session.
Parameters | |
---|---|
flags |
int : The flags to set for this session.
|
setMediaButtonReceiver
public void setMediaButtonReceiver (PendingIntent mbr)
Sets a pending intent for your media button receiver to allow restarting
playback after the session has been stopped. If your app is started in
this way an Intent.ACTION_MEDIA_BUTTON
intent will be sent via
the pending intent.
This method will only work on
Build.VERSION_CODES.LOLLIPOP
and later. Earlier
platform versions must include the media button receiver in the
constructor.
Parameters | |
---|---|
mbr |
PendingIntent : The PendingIntent to send the media button event to.
|
setMetadata
public void setMetadata (MediaMetadataCompat metadata)
Updates the current metadata. New metadata can be created using
MediaMetadataCompat.Builder
. This operation may take time
proportional to the size of the bitmap to replace large bitmaps with a scaled down copy.
Parameters | |
---|---|
metadata |
MediaMetadataCompat : The new metadata |
setPlaybackState
public void setPlaybackState (PlaybackStateCompat state)
Updates the current playback state.
Parameters | |
---|---|
state |
PlaybackStateCompat : The current state of playback
|
setPlaybackToLocal
public void setPlaybackToLocal (int stream)
Sets the stream this session is playing on. This will affect the system's
volume handling for this session. If setPlaybackToRemote(VolumeProviderCompat)
was
previously called it will stop receiving volume commands and the system
will begin sending volume changes to the appropriate stream.
By default sessions are on AudioManager.STREAM_MUSIC
.
Parameters | |
---|---|
stream |
int : The AudioManager stream this session is playing on.
|
setPlaybackToRemote
public void setPlaybackToRemote (VolumeProviderCompat volumeProvider)
Configures this session to use remote volume handling. This must be called
to receive volume button events, otherwise the system will adjust the
current stream volume for this session. If setPlaybackToLocal(int)
was previously called that stream will stop receiving volume changes for
this session.
On platforms earlier than Build.VERSION_CODES.LOLLIPOP
this will only allow an app to handle volume commands sent directly to
the session by a MediaControllerCompat
. System routing of volume
keys will not use the volume provider.
Parameters | |
---|---|
volumeProvider |
VolumeProviderCompat : The provider that will handle volume changes. May
not be null.
|
setQueue
public void setQueue (List<MediaSessionCompat.QueueItem> queue)
Updates the list of items in the play queue. It is an ordered list and should contain the current item, and previous or upcoming items if they exist. Specify null if there is no current play queue.
The queue should be of reasonable size. If the play queue is unbounded within your app, it is better to send a reasonable amount in a sliding window instead.
Parameters | |
---|---|
queue |
List : A list of items in the play queue.
|
setQueueTitle
public void setQueueTitle (CharSequence title)
Sets the title of the play queue. The UI should display this title along with the play queue itself. e.g. "Play Queue", "Now Playing", or an album name.
Parameters | |
---|---|
title |
CharSequence : The title of the play queue.
|
setRatingType
public void setRatingType (int type)
Sets the style of rating used by this session. Apps trying to set the rating should use this style. Must be one of the following:
RatingCompat.RATING_NONE
RatingCompat.RATING_3_STARS
RatingCompat.RATING_4_STARS
RatingCompat.RATING_5_STARS
RatingCompat.RATING_HEART
RatingCompat.RATING_PERCENTAGE
RatingCompat.RATING_THUMB_UP_DOWN
Parameters | |
---|---|
type |
int |
setRepeatMode
public void setRepeatMode (int repeatMode)
Sets the repeat mode for this session.
Note that if this method is not called before, MediaControllerCompat.getRepeatMode()
will return PlaybackStateCompat.REPEAT_MODE_NONE
.
Parameters | |
---|---|
repeatMode |
int : The repeat mode. Must be one of the followings:
PlaybackStateCompat.REPEAT_MODE_NONE ,
PlaybackStateCompat.REPEAT_MODE_ONE ,
PlaybackStateCompat.REPEAT_MODE_ALL ,
PlaybackStateCompat.REPEAT_MODE_GROUP
|
setSessionActivity
public void setSessionActivity (PendingIntent pi)
Sets an intent for launching UI for this Session. This can be used as a
quick link to an ongoing media screen. The intent should be for an
activity that may be started using
Activity.startActivity(Intent)
.
Parameters | |
---|---|
pi |
PendingIntent : The intent to launch to show UI for this Session.
|
setShuffleMode
public void setShuffleMode (int shuffleMode)
Sets the shuffle mode for this session.
Note that if this method is not called before, MediaControllerCompat.getShuffleMode()
will return PlaybackStateCompat.SHUFFLE_MODE_NONE
.
Parameters | |
---|---|
shuffleMode |
int : The shuffle mode. Must be one of the followings:
PlaybackStateCompat.SHUFFLE_MODE_NONE ,
PlaybackStateCompat.SHUFFLE_MODE_ALL ,
PlaybackStateCompat.SHUFFLE_MODE_GROUP
|
Interfaces
Classes
- MediaControllerCompat
- MediaControllerCompat.Callback
- MediaControllerCompat.PlaybackInfo
- MediaControllerCompat.TransportControls
- MediaSessionCompat
- MediaSessionCompat.Callback
- MediaSessionCompat.QueueItem
- MediaSessionCompat.Token
- ParcelableVolumeInfo
- PlaybackStateCompat
- PlaybackStateCompat.Builder
- PlaybackStateCompat.CustomAction
- PlaybackStateCompat.CustomAction.Builder
Content and code samples on this page are subject to the licenses described in the Content License. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2020-09-30 UTC.