public class MediaSessionCompat 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 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.
Modifier and Type | Class and Description |
---|---|
static class |
MediaSessionCompat.Callback
Receives transport controls, media buttons, and commands from controllers
and the system.
|
static interface |
MediaSessionCompat.OnActiveChangeListener |
static class |
MediaSessionCompat.QueueItem
A single item that is part of the play queue.
|
static interface |
MediaSessionCompat.SessionFlags |
static class |
MediaSessionCompat.Token
Represents an ongoing session.
|
Modifier and Type | Field and Description |
---|---|
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
MediaSessionCompat.Callback . |
Constructor and Description |
---|
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).
|
Modifier and Type | Method and Description |
---|---|
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
MediaSession object. |
String |
getCallingPackage()
Returns the name of the package that sent the last media button, transport control, or
command from controllers and the system.
|
MediaControllerCompat |
getController()
Get a controller for this session.
|
Object |
getMediaSession()
Gets the underlying framework
MediaSession
object. |
Object |
getRemoteControlClient()
Gets the underlying framework
RemoteControlClient
object. |
MediaSessionCompat.Token |
getSessionToken()
Retrieve a token object that can be used by apps to create a
MediaControllerCompat for interacting with this session. |
boolean |
isActive()
Get the current active state of this session.
|
static MediaSessionCompat |
obtain(Context context,
Object mediaSession)
Deprecated.
Use
fromMediaSession(Context, Object) instead. |
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)
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(MediaSessionCompat.Callback callback)
Add a callback to receive updates on for the MediaSession.
|
void |
setCallback(MediaSessionCompat.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
MediaSessionCompat . |
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(MediaMetadataCompat metadata)
Update the current metadata.
|
void |
setPlaybackState(PlaybackStateCompat state)
Update the current playback state.
|
void |
setPlaybackToLocal(int stream)
Set the stream this session is playing on.
|
void |
setPlaybackToRemote(VolumeProviderCompat volumeProvider)
Configure this session to use remote volume handling.
|
void |
setQueue(List<MediaSessionCompat.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
MediaSessionCompat.Callback
.public MediaSessionCompat(Context context, String tag)
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.
context
- The context to use to create the session.tag
- A short name for debugging purposes.public MediaSessionCompat(Context context, String tag, ComponentName mbrComponent, PendingIntent mbrIntent)
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. Note that mbrComponent
and mrbIntent
are only used for API 20 or earlier. If you want to set a media button
receiver in API 21 or later, call setMediaButtonReceiver(android.app.PendingIntent)
.
For API 20 or earlier, the new session will use the given mbrComponent
.
If null, this will attempt to find an appropriate BroadcastReceiver
that handles
Intent.ACTION_MEDIA_BUTTON
from your manifest. See MediaButtonReceiver
for
more details.
context
- The context to use to create the session.tag
- A short name for debugging purposes.mbrComponent
- The component name for your media button receiver.mbrIntent
- 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 void setCallback(MediaSessionCompat.Callback callback)
callback
- The callback objectpublic void setCallback(MediaSessionCompat.Callback callback, Handler handler)
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.
This method will only work on
Build.VERSION_CODES.LOLLIPOP
and later. Earlier
platform versions must include the media button receiver in the
constructor.
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(int stream)
setPlaybackToRemote(android.support.v4.media.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
.
stream
- The AudioManager
stream this session is playing on.public void setPlaybackToRemote(VolumeProviderCompat volumeProvider)
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.
volumeProvider
- The provider that will handle volume changes. May
not be null.public void setActive(boolean active)
On platforms earlier than
Build.VERSION_CODES.LOLLIPOP
,
a media button event receiver should be set via the constructor to
receive media button events.
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 MediaSessionCompat.Token getSessionToken()
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.
public MediaControllerCompat getController()
public void setPlaybackState(PlaybackStateCompat state)
state
- The current state of playbackpublic void setMetadata(MediaMetadataCompat metadata)
MediaMetadataCompat.Builder
. This operation may take time
proportional to the size of the bitmap to replace large bitmaps with a scaled down copy.metadata
- The new metadataMediaMetadataCompat.Builder.putBitmap(java.lang.String, android.graphics.Bitmap)
public void setQueue(List<MediaSessionCompat.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)
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.extras
- The extras associated with the session.public Object getMediaSession()
MediaSession
object.
This method is only supported on API 21+.
MediaSession
object,
or null if none.public Object getRemoteControlClient()
RemoteControlClient
object.
This method is only supported on APIs 14-20. On API 21+
getMediaSession()
should be used instead.
RemoteControlClient
object,
or null if none.public String getCallingPackage()
MediaSessionCompat.Callback.onPlay()
. This method is not available and returns null on pre-N devices.public void addOnActiveChangeListener(MediaSessionCompat.OnActiveChangeListener listener)
listener
- The listener to add.public void removeOnActiveChangeListener(MediaSessionCompat.OnActiveChangeListener listener)
listener
- The listener to remove.@Deprecated public static MediaSessionCompat obtain(Context context, Object mediaSession)
fromMediaSession(Context, Object)
instead.MediaSession
object.
This method is only supported on API 21+. On API 20 and below, it returns null.
context
- The context to use to create the session.mediaSession
- A MediaSession
object.MediaSessionCompat
object, or null if none.public static MediaSessionCompat fromMediaSession(Context context, Object mediaSession)
MediaSession
object.
This method is only supported on API 21+. On API 20 and below, it returns null.
context
- The context to use to create the session.mediaSession
- A MediaSession
object.MediaSessionCompat
object, or null if none.