public final class MediaSession extends Object
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 MediaController
to interact with the session.
To receive commands, media keys, and other events a MediaSession.Callback
must be
set with setCallback(Callback)
and setActive(true)
must be called.
When an app is finished performing playback it must call release()
to clean up the session and notify any controllers.
MediaSession objects are thread safe.
Modifier and Type | Class and Description |
---|---|
static class |
MediaSession.Callback
Receives media buttons, transport controls, and commands from controllers
and the system.
|
static class |
MediaSession.CallbackStub |
static class |
MediaSession.QueueItem
A single item that is part of the play queue.
|
static interface |
MediaSession.SessionFlags |
static class |
MediaSession.Token
Represents an ongoing session.
|
Modifier and Type | Field and Description |
---|---|
static int |
FLAG_EXCLUSIVE_GLOBAL_PRIORITY
System only flag for a session that needs to have priority over all other
sessions.
|
static int |
FLAG_HANDLES_MEDIA_BUTTONS
Set this flag on the session to indicate that it can handle media button
events.
|
static int |
FLAG_HANDLES_TRANSPORT_CONTROLS
Set this flag on the session to indicate that it handles transport
control commands through its
MediaSession.Callback . |
Constructor and Description |
---|
MediaSession(Context context,
String tag)
Creates a new session.
|
MediaSession(Context context,
String tag,
int userId)
Creates a new session as the specified user.
|
Modifier and Type | Method and Description |
---|---|
String |
getCallingPackage()
Returns the name of the package that sent the last media button, transport control, or
command from controllers and the system.
|
MediaController |
getController()
Get a controller for this session.
|
MediaSession.Token |
getSessionToken()
Retrieve a token object that can be used by apps to create a
MediaController for interacting with this session. |
boolean |
isActive()
Get the current active state of this session.
|
static boolean |
isActiveState(int state)
Return true if this is considered an active playback state.
|
void |
notifyRemoteVolumeChanged(VolumeProvider provider)
Notify the system that the remote volume changed.
|
void |
release()
This must be called when an app has finished performing playback.
|
void |
sendSessionEvent(String event,
Bundle extras)
Send a proprietary event to all MediaControllers listening to this
Session.
|
void |
setActive(boolean active)
Set if this session is currently active and ready to receive commands.
|
void |
setCallback(MediaSession.Callback callback)
Set the callback to receive updates for the MediaSession.
|
void |
setCallback(MediaSession.Callback callback,
Handler handler)
Set the callback to receive updates for the MediaSession.
|
void |
setExtras(Bundle extras)
Set some extras that can be associated with the
MediaSession . |
void |
setFlags(int flags)
Set any flags for the session.
|
void |
setMediaButtonReceiver(PendingIntent mbr)
Set a pending intent for your media button receiver to allow restarting
playback after the session has been stopped.
|
void |
setMetadata(MediaMetadata metadata)
Update the current metadata.
|
void |
setPlaybackState(PlaybackState state)
Update the current playback state.
|
void |
setPlaybackToLocal(AudioAttributes attributes)
Set the attributes for this session's audio.
|
void |
setPlaybackToRemote(VolumeProvider volumeProvider)
Configure this session to use remote volume handling.
|
void |
setQueue(List<MediaSession.QueueItem> queue)
Update the list of items in the play queue.
|
void |
setQueueTitle(CharSequence title)
Set the title of the play queue.
|
void |
setRatingType(int type)
Set the style of rating used by this session.
|
void |
setSessionActivity(PendingIntent pi)
Set an intent for launching UI for this Session.
|
public static final int FLAG_HANDLES_MEDIA_BUTTONS
public static final int FLAG_HANDLES_TRANSPORT_CONTROLS
MediaSession.Callback
.public static final int FLAG_EXCLUSIVE_GLOBAL_PRIORITY
public MediaSession(Context context, String tag)
setActive(true)
is called. You must call release()
when
finished with the session.context
- The context to use to create the session.tag
- A short name for debugging purposes.public MediaSession(Context context, String tag, int userId)
android.Manifest.permission#INTERACT_ACROSS_USERS_FULL
permission.context
- The context to use to create the session.tag
- A short name for debugging purposes.userId
- The user id to create the session as.public void setCallback(MediaSession.Callback callback)
Set the callback to null to stop receiving updates.
callback
- The callback objectpublic void setCallback(MediaSession.Callback callback, Handler handler)
Set the callback to null to stop receiving updates.
callback
- The callback to receive updates on.handler
- The handler that events should be posted on.public void setSessionActivity(PendingIntent pi)
Activity.startActivity(Intent)
.pi
- The intent to launch to show UI for this Session.public void setMediaButtonReceiver(PendingIntent mbr)
Intent.ACTION_MEDIA_BUTTON
intent will be sent via
the pending intent.mbr
- The PendingIntent
to send the media button event to.public void setFlags(int flags)
flags
- The flags to set for this session.public void setPlaybackToLocal(AudioAttributes attributes)
setPlaybackToRemote(android.media.VolumeProvider)
was previously called it will stop receiving
volume commands and the system will begin sending volume changes to the
appropriate stream.
By default sessions use attributes for media.
attributes
- The AudioAttributes
for this session's audio.public void setPlaybackToRemote(VolumeProvider volumeProvider)
setPlaybackToLocal(android.media.AudioAttributes)
was previously called the system will stop
handling volume changes for this session and pass them to the volume
provider instead.volumeProvider
- The provider that will handle volume changes. May
not be null.public void setActive(boolean active)
active
- Whether this session is active or not.public boolean isActive()
public void sendSessionEvent(String event, Bundle extras)
event
- The name of the event to sendextras
- Any extras included with the eventpublic void release()
public MediaSession.Token getSessionToken()
MediaController
for interacting with this session. The owner of
the session is responsible for deciding how to distribute these tokens.public MediaController getController()
public void setPlaybackState(PlaybackState state)
state
- The current state of playbackpublic void setMetadata(MediaMetadata metadata)
MediaMetadata.Builder
.metadata
- The new metadatapublic void setQueue(List<MediaSession.QueueItem> 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.
queue
- A list of items in the play queue.public void setQueueTitle(CharSequence title)
title
- The title of the play queue.public void setRatingType(int type)
public void setExtras(Bundle extras)
MediaSession
. No assumptions should
be made as to how a MediaController
will handle these extras.
Keys should be fully qualified (e.g. com.example.MY_EXTRA) to avoid conflicts.extras
- The extras associated with the MediaSession
.public void notifyRemoteVolumeChanged(VolumeProvider provider)
provider
- The provider that is handling volume changes.public String getCallingPackage()
MediaSession.Callback.onPlay()
.public static boolean isActiveState(int state)