Android APIs
public final class

MediaSession

extends Object
java.lang.Object
   ↳ android.media.session.MediaSession

Class Overview

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.

A MediaSession is created by calling createSession(String). Once a session is created the owner of the session may use getSessionToken() to allow apps to create a MediaController to interact with this session.

To receive commands, media keys, and other events a MediaSession.Callback must be set with addCallback(Callback). To receive transport control commands a MediaSession.TransportControlsCallback must be set with addTransportControlsCallback(MediaSession.TransportControlsCallback).

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

Summary

Nested Classes
class MediaSession.Callback Receives generic commands or updates from controllers and the system. 
class MediaSession.TransportControlsCallback Receives transport control commands. 
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 a MediaSession.TransportControlsCallback.
Public Methods
void addCallback(MediaSession.Callback callback)
Add a callback to receive updates on for the MediaSession.
void addCallback(MediaSession.Callback callback, Handler handler)
Add a callback to receive updates for the MediaSession.
void addTransportControlsCallback(MediaSession.TransportControlsCallback callback)
Add a callback to receive transport controls on, such as play, rewind, or fast forward.
void addTransportControlsCallback(MediaSession.TransportControlsCallback callback, Handler handler)
Add a callback to receive transport controls on, such as play, rewind, or fast forward.
MediaSessionToken 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.
void release()
This must be called when an app has finished performing playback.
void removeCallback(MediaSession.Callback callback)
Remove a callback.
void removeTransportControlsCallback(MediaSession.TransportControlsCallback callback)
Stop receiving transport controls on the specified callback.
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 setFlags(int flags)
Set any flags for the session.
void setLaunchPendingIntent(PendingIntent pi)
Set an intent for launching UI for this Session.
void setMetadata(MediaMetadata metadata)
Update the current metadata.
void setPlaybackState(PlaybackState state)
Update the current playback state.
void setPlaybackToLocal(int stream)
Set the stream this session is playing on.
void setPlaybackToRemote(RemoteVolumeProvider volumeProvider)
Configure this session to use remote volume handling.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int FLAG_HANDLES_MEDIA_BUTTONS

Set this flag on the session to indicate that it can handle media button events.

Constant Value: 1 (0x00000001)

public static final int FLAG_HANDLES_TRANSPORT_CONTROLS

Set this flag on the session to indicate that it handles transport control commands through a MediaSession.TransportControlsCallback. The callback can be retrieved by calling addTransportControlsCallback(MediaSession.TransportControlsCallback).

Constant Value: 2 (0x00000002)

Public Methods

public void addCallback (MediaSession.Callback callback)

Add 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 The callback object

public void addCallback (MediaSession.Callback callback, Handler handler)

Add a callback to receive updates for the MediaSession. This includes media button and volume events.

Parameters
callback The callback to receive updates on.
handler The handler that events should be posted on.

public void addTransportControlsCallback (MediaSession.TransportControlsCallback callback)

Add a callback to receive transport controls on, such as play, rewind, or fast forward.

Parameters
callback The callback object

public void addTransportControlsCallback (MediaSession.TransportControlsCallback callback, Handler handler)

Add a callback to receive transport controls on, such as play, rewind, or fast forward. The updates will be posted to the specified handler. If no handler is provided they will be posted to the caller's thread.

Parameters
callback The callback to receive updates on
handler The handler to post the updates on

public MediaSessionToken getSessionToken ()

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.

Returns
  • A token that can be used to create a MediaController for this session

public boolean isActive ()

Get the current active state of this session.

Returns
  • True if the session is active, false otherwise.

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.

public void removeCallback (MediaSession.Callback callback)

Remove a callback. It will no longer receive updates.

Parameters
callback The callback to remove.

public void removeTransportControlsCallback (MediaSession.TransportControlsCallback callback)

Stop receiving transport controls on the specified callback. If an update has already been posted you may still receive it after this call returns.

Parameters
callback The callback to stop receiving updates on

public void sendSessionEvent (String event, Bundle extras)

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.

Parameters
event The name of the event to send
extras Any extras included with the event

public void setActive (boolean active)

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.

Parameters
active Whether this session is active or not.

public void setFlags (int flags)

Set any flags for the session.

Parameters
flags The flags to set for this session.

public void setLaunchPendingIntent (PendingIntent pi)

Set an intent for launching UI for this Session. This can be used as a quick link to an ongoing media screen.

Parameters
pi The intent to launch to show UI for this Session.

public void setMetadata (MediaMetadata metadata)

Update the current metadata. New metadata can be created using MediaMetadata.Builder.

Parameters
metadata The new metadata

public void setPlaybackState (PlaybackState state)

Update the current playback state.

Parameters
state The current state of playback

public void setPlaybackToLocal (int stream)

Set the stream this session is playing on. This will affect the system's volume handling for this session. If setPlaybackToRemote(RemoteVolumeProvider) 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 STREAM_MUSIC.

Parameters
stream The AudioManager stream this session is playing on.

public void setPlaybackToRemote (RemoteVolumeProvider volumeProvider)

Configure 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.

Parameters
volumeProvider The provider that will handle volume changes. May not be null.