java.lang.Object | |
↳ | android.media.session.MediaSession |
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 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.
Nested Classes | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
MediaSession.Callback | Receives media buttons, transport controls, and commands from controllers and the system. | ||||||||||
MediaSession.QueueItem | A single item that is part of the play queue. | ||||||||||
MediaSession.Token | Represents an ongoing session. |
Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
int | FLAG_HANDLES_MEDIA_BUTTONS | Set this flag on the session to indicate that it can handle media button events. | |||||||||
int | FLAG_HANDLES_TRANSPORT_CONTROLS |
Set this flag on the session to indicate that it handles transport
control commands through its MediaSession.Callback .
|
Public Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Creates a new session.
|
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Get a controller for this session.
| |||||||||||
Retrieve a token object that can be used by apps to create a
MediaController for interacting with this session.
| |||||||||||
Get the current active state of this session.
| |||||||||||
This must be called when an app has finished performing playback.
| |||||||||||
Send a proprietary event to all MediaControllers listening to this
Session.
| |||||||||||
Set if this session is currently active and ready to receive commands.
| |||||||||||
Set the callback to receive updates for the MediaSession.
| |||||||||||
Set the callback to receive updates for the MediaSession.
| |||||||||||
Set some extras that can be associated with the
MediaSession .
| |||||||||||
Set any flags for the session.
| |||||||||||
Set a pending intent for your media button receiver to allow restarting
playback after the session has been stopped.
| |||||||||||
Update the current metadata.
| |||||||||||
Update the current playback state.
| |||||||||||
Set the attributes for this session's audio.
| |||||||||||
Configure this session to use remote volume handling.
| |||||||||||
Update the list of items in the play queue.
| |||||||||||
Set the title of the play queue.
| |||||||||||
Set the style of rating used by this session.
| |||||||||||
Set an intent for launching UI for this Session.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
|
Set this flag on the session to indicate that it can handle media button events.
Set this flag on the session to indicate that it handles transport
control commands through its MediaSession.Callback
.
Creates a new session. The session will automatically be registered with
the system but will not be published until 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. |
Get a controller for this session. This is a convenience method to avoid having to cache your own controller in process.
Retrieve a token object that can be used by apps to create a
MediaController
for interacting with this session. The owner of
the session is responsible for deciding how to distribute these tokens.
Get the current active state of this session.
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.
Send 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.
event | The name of the event to send |
---|---|
extras | Any extras included with the event |
Set 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.
active | Whether this session is active or not. |
---|
Set the callback to receive updates for the MediaSession. This includes media button events and transport controls. The caller's thread will be used to post updates.
Set the callback to null to stop receiving updates.
callback | The callback object |
---|
Set the callback to receive updates for the MediaSession. This includes media button events and transport controls.
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. |
Set some extras that can be associated with the 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 .
|
---|
Set any flags for the session.
flags | The flags to set for this session. |
---|
Set 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 ACTION_MEDIA_BUTTON
intent will be sent via
the pending intent.
mbr | The PendingIntent to send the media button event to.
|
---|
Update the current metadata. New metadata can be created using
MediaMetadata.Builder
.
metadata | The new metadata |
---|
Update the current playback state.
state | The current state of playback |
---|
Set the attributes for this session's audio. This will affect the
system's volume handling for this session. If
setPlaybackToRemote(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.
|
---|
Configure this session to use remote volume handling. This must be called
to receive volume button events, otherwise the system will adjust the
appropriate stream volume for this session. If
setPlaybackToLocal(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. |
---|
Update 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.
queue | A list of items in the play queue. |
---|
Set 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.
title | The title of the play queue. |
---|
Set the style of rating used by this session. Apps trying to set the rating should use this style. Must be one of the following:
Set 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 startActivity(Intent)
.
pi | The intent to launch to show UI for this Session. |
---|