Les sessions multimédias offrent un moyen universel d'interagir avec un lecteur audio ou vidéo. En informant Android qu'un contenu multimédia est en cours de lecture dans une application, les commandes de lecture peuvent être déléguées à l'application. L'intégration à la session multimédia permet à une application d'annoncer la lecture multimédia en externe et de recevoir des commandes de lecture de sources externes. Ces sources peuvent être des boutons physiques (comme le bouton de lecture d'un casque ou d'une télécommande TV) ou des commandes indirectes (comme l'instruction "pause" de l'Assistant Google). La session multimédia délègue ensuite ces commandes à l'application, qui les applique au lecteur multimédia pour lequel l'origine des commandes est transparente.
Une session multimédia coexiste avec le lecteur qu'elle gère. Vous devez créer et initialiser une session multimédia dans la méthode onCreate() de l'activité ou du service qui possède la session multimédia et le lecteur associé.
Initialiser la session multimédia
Une session multimédia nouvellement créée ne dispose d'aucune fonctionnalité. Vous devez initialiser la session en procédant comme suit :
- Définissez des indicateurs pour que la session multimédia puisse recevoir des rappels des contrôleurs et des boutons multimédias.
- Créez et initialisez une instance de
PlaybackStateCompat, puis attribuez-la à la session. L'état de lecture change tout au long de la session. Nous vous recommandons donc de mettre en cache l'objetPlaybackStateCompat.Builderpour le réutiliser. - Créez une instance de
MediaSessionCompat.Callbacket attribuez-la à la session (pour en savoir plus sur les rappels, consultez la section ci-dessous).
Vous devez créer et initialiser une session multimédia dans la méthode onCreate() de l'activité ou du service propriétaire de la session.
Pour que les boutons multimédias fonctionnent lorsque votre application est initialisée (ou arrêtée), son PlaybackState doit contenir une action de lecture correspondant à l'intent envoyé par le bouton multimédia. C'est pourquoi ACTION_PLAY est attribué à l'état de la session lors de l'initialisation. Pour en savoir plus, consultez Répondre aux boutons multimédias.
Conserver l'état de lecture et les métadonnées
Deux classes représentent l'état d'une session multimédia.
La classe PlaybackStateCompat décrit l'état opérationnel actuel du lecteur. Par exemple :
- L'état de transport (si le lecteur est en cours de lecture, en pause, en cours de mise en mémoire tampon, etc. Voir
getState()) - Un code d'erreur et un message d'erreur facultatif, le cas échéant. (voir
getErrorCode()et lire États et erreurs ci-dessous). - La position du joueur
- Actions de contrôleur valides pouvant être gérées dans l'état actuel
La classe MediaMetadataCompat décrit le contenu en cours de lecture :
- Le nom de l'artiste, de l'album et du titre
- La durée de la piste
- Pochette d'album à afficher sur l'écran de verrouillage. L'image est un bitmap d'une taille maximale de 320 x 320 dp (si elle est plus grande, elle est réduite).
- Une instance de
ContentUrisqui pointe vers une version plus grande de l'image
L'état du lecteur et les métadonnées peuvent changer au cours d'une session multimédia. Chaque fois que l'état ou les métadonnées changent, vous devez utiliser le compilateur correspondant pour chaque classe, PlaybackStateCompat.Builder() ou MediaMetadataCompat.Builder(), puis transmettre la nouvelle instance à la session multimédia en appelant setPlaybackState() ou setMetaData(). Pour réduire la consommation globale de mémoire liée à ces opérations fréquentes, il est recommandé de créer les compilateurs une seule fois et de les réutiliser tout au long de la session.
États et erreurs
Notez que PlaybackState est un objet qui contient des valeurs distinctes pour l'état de lecture de la session (getState()) et, si nécessaire, un code d'erreur associé (getErrorCode()). Les erreurs peuvent être fatales ou non :
Chaque fois que la lecture est interrompue, vous devez générer une erreur fatale : définissez l'état de transport sur STATE_ERROR et spécifiez une erreur associée avec setErrorMessage(int, CharSequence). Tant que la lecture est bloquée par l'erreur, le PlaybackState doit continuer à signaler STATE_ERROR et l'erreur.
Une erreur non fatale se produit lorsque votre application ne peut pas traiter une requête, mais peut continuer à lire le contenu : le transport reste dans un état "normal" (tel que STATE_PLAYING), mais PlaybackState contient un code d'erreur. Par exemple, si la dernière chanson est en cours de lecture et que l'utilisateur demande à passer à la chanson suivante, la lecture peut continuer, mais vous devez créer un PlaybackState avec le code d'erreur ERROR_CODE_END_OF_QUEUE, puis appeler setPlaybackState(). Les contrôleurs multimédias associés à la session recevront le rappel onPlaybackStateChanged() et expliqueront à l'utilisateur ce qui s'est passé. Une erreur non fatale ne doit être signalée qu'une seule fois, au moment où elle se produit. La prochaine fois que la session met à jour PlaybackState, ne définissez pas à nouveau la même erreur non fatale (sauf si l'erreur s'est produite en réponse à une nouvelle requête).
Écrans de verrouillage de session multimédia
À partir d'Android 4.0 (niveau d'API 14), le système peut accéder à l'état de lecture et aux métadonnées d'une session multimédia. Voici comment l'écran de verrouillage peut afficher les commandes multimédias et l'illustration. Le comportement varie en fonction de la version d'Android.
Pochettes d'album
D'Android 4.0 (niveau d'API 14) à Android 10 (niveau d'API 29), l'arrière-plan de l'écran de verrouillage affiche la pochette de votre album, mais uniquement si les métadonnées de la session multimédia incluent un bitmap d'arrière-plan.
Commandes de transport
Sur Android 4.0 (niveau d'API 14) à Android 4.4 (niveau d'API 19), lorsqu'une session multimédia est active et que ses métadonnées incluent un bitmap d'arrière-plan, l'écran de verrouillage affiche automatiquement les commandes de transport.
Sous Android 5.0 (niveau d'API 21) ou version ultérieure, le système ne fournit pas de commandes de transport sur l'écran de verrouillage. Utilisez plutôt une notification MediaStyle pour afficher les commandes de transport.
Ajouter des actions personnalisées
Les applications multimédias peuvent définir des actions personnalisées, par exemple : "J'aime", "J'aime" ou "Revenir en arrière de 30 secondes". Une action personnalisée doit implémenter un comportement complètement nouveau. N'utilisez pas d'action personnalisée pour remplacer l'une des actions de contrôle de transport standards définies dans PlaybackStateCompat.
Ajoutez des actions personnalisées avec addCustomAction(). L'exemple suivant montre comment ajouter une commande pour une action "J'aime" :
Kotlin
stateBuilder.addCustomAction(
PlaybackStateCompat.CustomAction.Builder(
CUSTOM_ACTION_THUMBS_UP,
resources.getString(R.string.thumbs_up),
thumbsUpIcon
).run {
setExtras(customActionExtras)
build()
}
)
Java
stateBuilder.addCustomAction(new PlaybackStateCompat.CustomAction.Builder(
CUSTOM_ACTION_THUMBS_UP, resources.getString(R.string.thumbs_up), thumbsUpIcon)
.setExtras(customActionExtras)
.build());
Pour obtenir un exemple complet, consultez Universal Music Player.
Vous répondez à l'action avec onCustomAction().
Kotlin
override fun onCustomAction(action: String, extras: Bundle?) {
when(action) {
CUSTOM_ACTION_THUMBS_UP -> {
...
}
}
}
Java
@Override
public void onCustomAction(@NonNull String action, Bundle extras) {
if (CUSTOM_ACTION_THUMBS_UP.equals(action)) {
...
}
}
Consultez également Universal Music Player.
Rappels de session multimédia
Les principales méthodes de rappel de session multimédia sont onPlay(), onPause() et onStop(). C'est là que vous ajoutez le code qui contrôle votre lecteur.
Étant donné que vous instanciez et définissez le rappel de la session au moment de l'exécution (dans onCreate()), votre application peut définir d'autres rappels qui utilisent différents lecteurs et choisir la combinaison appropriée de rappel et de lecteur en fonction de l'appareil et du niveau du système. Vous pouvez modifier le lecteur sans modifier le reste de l'application. Par exemple, vous pouvez utiliser ExoPlayer sur Android 4.1 (niveau d'API 16) ou version ultérieure, et MediaPlayer sur les systèmes antérieurs.
En plus de contrôler le lecteur et de gérer les transitions d'état de la session multimédia, les rappels activent et désactivent les fonctionnalités de votre application, et contrôlent la façon dont elle interagit avec d'autres applications et le matériel de l'appareil. (Voir Contrôler la sortie audio).
L'implémentation des méthodes de rappel de session multimédia dépend de la structure de votre application. Consultez les pages distinctes qui décrivent comment utiliser les rappels dans les applications audio et les applications vidéo, et comment les rappels doivent être implémentés pour chaque type d'application.