Passer directement au contenu

Les plus consultés

Consultés récemment


Working with a Media Session

A media session lives alongside the player that it manages. You should create and initialize a media session in the onCreate() method of the activity or service that owns the media session and its associated player.

Initialize the media session

A newly-created media session has no capabilities. You must initialize the session by performing these steps:

You should create and initialize a media session in the onCreate() method of the activity or service that owns the session.

In order for media buttons to work when your app is newly initialized (or stopped), its PlaybackState must contain a play action matching the intent that the media button sends. This is why ACTION_PLAY is assigned to the session state during initialization. For more information, see Responding to Media Buttons.

Maintain the playback state and metadata

There are two classes that represent the state of a media session.

The PlaybackStateCompat class describes the current operational state of the player. This includes:

The MediaMetadataCompat class describes the material that is playing:

The player state and metadata can change over the life of a media session. Every time the state or metadata changes, you must use the corresponding builder for each class, PlaybackStateCompat.Builder() or MediaMetadataCompat.Builder(), and then pass the new instance to the media session by calling setPlaybackState() or setMetaData(). To reduce overall memory consumption from these frequent operations, it's a good idea to create the builders once and to reuse them throughout the life of the session.

States and errors

Note that PlaybackState is an object that contains separate values for the playback state of the session (getState()) and, when necessary, an associated error code (getErrorCode()). Errors can be fatal or non-fatal:

Whenever playback is interrupted, you should generate a fatal error: Set the transport state to STATE_ERROR and specify an associated error with setErrorMessage(int, CharSequence). As long as playback is blocked by the error, the PlaybackState should continue to report STATE_ERROR and the error.

A non-fatal error occurs when your app cannot handle a request, but can continue to play: The transport remains in a "normal" state (such as STATE_PLAYING) but the PlaybackState holds an error code. For example, if the last song is playing and the user requests a skip to next song, playback can continue, but you should create a new PlaybackState with the error code ERROR_CODE_END_OF_QUEUE and then call setPlaybackState(). Media Controllers attached to the session will receive the callback onPlaybackStateChanged() and explain to the user what happened. A non-fatal error should only be reported once, at the time it occurs. The next time the session updates the PlaybackState do not set the same non-fatal error again (unless the error occurred in response to a new request).

Media session lock screens

Starting with Android 4.0 (API level 14) the system can access a media session's playback state and metadata. This is how the lock screen can display media controls and artwork. The behavior varies depending on the Android version.

Album artwork

In Android 4.0 (API level 14) and greater, the background of the lock screen displays your album artwork - but only if the media session metadata includes a background bitmap.

Transport controls

In Android 4.0 (API level 14) through Android 4.4 (API level 19), when a media session is active and the media session metadata includes a background bitmap the lock screen automatically displays transport controls.

In Android 5.0 (API level 21) or greater the system does not provide transport controls on the lock screen. Instead, you should use a MediaStyle notification to display transport controls.

Add custom actions

You can add custom actions with addCustomAction(). For example, to add a control to implement a thumbs-up action:

stateBuilder.addCustomAction(new PlaybackStateCompat.CustomAction.Builder(
    CUSTOM_ACTION_THUMBS_UP, mResources.getString(R.string.thumbs_up), thumbsUpIcon)

See the Universal Music Player for a complete example.

You respond to the action with onCustomAction().

public void onCustomAction(@NonNull String action, Bundle extras) {
    if (CUSTOM_ACTION_THUMBS_UP.equals(action)) {

Also see the Universal Music Player.

Media session callbacks

The main media session callback methods are onPlay(), onPause(), and onStop(). This is where you add the code that controls your player.

Since you instantiate and set the session's callback at runtime (in onCreate()), your app can define alternative callbacks that use different players and choose the appropriate callback/player combination depending on the device and/or system level. You can change the player without changing the rest of the app. For example, you could use ExoPlayer when running on Android 4.1 (API level 16) or greater and use MediaPlayer on earlier systems.

Besides controlling the player and managing the media session state transitions, callbacks also enable and disable features of your app and control the way it interacts with other apps and the device hardware. (See Controlling Audio Output).

The implementation of the media session callback methods depends on the structure of your app. See the separate pages that describe how to use callbacks in audio apps and video apps, describe how the callbacks should be implemented for each kind of app.

Ce site Web utilise des cookies pour enregistrer vos préférences relatives à la langue du site et aux options d'affichage.

Recevez les dernières actualités destinées aux développeurs Android, ainsi que des conseils qui vous mèneront vers le succès sur Google Play.

* Champs obligatoires

Super !

Suivez Google Developers sur WeChat

Consulter ce site en  ?

Vous avez demandé une page en , mais la langue indiquée dans vos préférences linguistiques pour ce site est la suivante : .

Souhaitez-vous modifier vos préférences linguistiques et parcourir ce site en  ? Pour modifier ultérieurement vos préférences linguistiques, utilisez le menu "Langue" au bas de chaque page.

Cette classe nécessite le niveau d'API  ou supérieur

Ce document est masqué, car vous avez sélectionné le niveau d'API  pour la documentation. Vous pouvez modifier le niveau d'API pour la documentation avec le sélecteur situé au-dessus du menu de navigation de gauche.

Pour découvrir comment déterminer le niveau d'API nécessaire pour votre application, consultez le guide sur la prise en charge des différentes versions de plate-forme (en anglais).

Take a short survey?
Help us improve the Android developer experience. (April 2018 — Developer Survey)