Utiliser une session multimédia

Les sessions multimédias fournissent un moyen universel d'interagir avec un contenu audio ou vidéo joueur. En informant Android qu'un contenu multimédia est en cours de lecture dans une application, peuvent être déléguées à l'application. L'intégration de la session multimédia permet Une application pour annoncer la lecture de contenus multimédias en externe et recevoir des commandes de lecture à partir de sources externes. Ces sources peuvent être des boutons physiques (comme le bouton de lecture bouton d'un casque ou de la télécommande d'un téléviseur) ou des commandes indirectes (comme avec l'instruction « pause » à l'Assistant Google). La session multimédia délègue ensuite ces à l'application qui les applique au lecteur multimédia transparente d'où proviennent les commandes.

Les sessions multimédias accompagnent le lecteur qu'il gère. Vous devez créer et initialiser une session multimédia dans la méthode onCreate() de l'activité qui possède la session multimédia et le lecteur associé.

Remarque :Une bonne pratique pour écrire une application multimédia consiste à utiliser la bibliothèque media-compat. Sur cette page, le terme "session multimédia" correspond à l'instance de MediaSessionCompat, et "contrôleur multimédia" correspond à Instance de MediaControllerCompat.

Initialiser la session multimédia

Une session multimédia nouvellement créée ne dispose d'aucune capacité. Vous devez initialiser la session en procédant comme suit:

• Définissez des indicateurs afin que la session multimédia puisse recevoir des rappels des contrôleurs et boutons multimédias.
• Créez et initialisez une instance de PlaybackStateCompat, puis attribuez-la à la session. L'état de la lecture change tout au long de la session. Nous vous recommandons donc de mettre le PlaybackStateCompat.Builder en cache pour le réutiliser.
• Créez une instance de MediaSessionCompat.Callback et affectez-la à la session (plus d'informations sur les rappels ci-dessous).

Vous devez créer et initialiser une session multimédia dans la méthode onCreate() du activité ou service propriétaire de la session.

Assurer le bon fonctionnement des boutons multimédias Lorsque votre application est récemment initialisée (ou arrêtée), son PlaybackState doit contiennent une action de lecture correspondant à l'intent envoyé par le bouton multimédia. C'est pourquoi ACTION_PLAY est attribué à l'état de session pendant l'initialisation. Pour en savoir plus, consultez la section Répondre aux médias Boutons :

Remarque :Si vous effectuez l'intégration avec le Extension ExoPlayer MediaSession, vous n'avez pas besoin d'implémenter votre propre MediaSessionCompat.Callback. La MediaSessionConnector se charge de mapper l'état du lecteur avec le contenu multimédia. et déléguée les événements provenant de la session multimédia.

Conserver l'état de lecture et les métadonnées

Deux classes représentent l'état d'une session multimédia.

La PlaybackStateCompat décrit l'état de fonctionnement actuel du lecteur. Par exemple :

• État de transport (lecture, mise en pause ou mise en mémoire tampon du lecteur, etc.). Consultez getState().
• Un code d'erreur et un message d'erreur facultatif, le cas échéant. (Consultez les sections getErrorCode() et États et erreurs ci-dessous.)
• La position du lecteur
• Actions valides de la manette pouvant être gérées à l'état actuel

MediaMetadataCompat décrit le contenu en cours de lecture:

• le nom de l'artiste, de l'album et du titre ;
• La durée du titre
• Pochette de l'album à afficher sur l'écran de verrouillage. L'image est un bitmap dont la taille maximale est de 320 x 320 dp (si elle est plus grande, elle est réduite).
• Une instance de ContentUris qui pointe vers une version plus grande de l'illustration

L'état et les métadonnées du lecteur 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 judicieux 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 la valeur é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 la valeur l'état de transport sur STATE_ERROR et spécifier une erreur associée à setErrorMessage(int, CharSequence). Tant que la lecture est bloquée par l'erreur, PlaybackState doit continuer pour signaler STATE_ERROR et l'erreur.

Une erreur non fatale se produit lorsque votre application ne peut pas gérer une requête, mais peut continuer à lire: Le mode de transport reste "normal" (comme STATE_PLAYING), mais PlaybackState contient un code d'erreur. Par exemple, si le dernier titre est en cours de lecture et que l'utilisateur demande à passer au titre suivant, la lecture peut continuer, mais vous devez créer une PlaybackState avec le code d'erreur ERROR_CODE_END_OF_QUEUE et Ensuite, appelez setPlaybackState(). Les contrôleurs multimédias associés à la session recevront le rappel. onPlaybackStateChanged() et expliquer à 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. Lors de la prochaine mise à jour de la session, PlaybackState ne définira plus la même erreur non fatale (sauf si l'erreur s'est produite en réponse à une nouvelle requête).

Écrans de verrouillage d'une session multimédia

À partir d'Android 4.0 (niveau d'API 14), le système peut accéder aux paramètres l'état de lecture et les métadonnées. Voici comment l'écran de verrouillage peut afficher les commandes multimédias et des illustrations. Le comportement varie en fonction du Version d'Android

Pochettes d'album

Dans 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 la session multimédia incluent un bitmap d'arrière-plan.

Commandes de transport

Dans Android 4.0 (niveau d'API 14) à Android 4.4 (niveau d'API 19), lorsqu'une session multimédia est active et que les métadonnées de la session multimédia incluent un bitmap d'arrière-plan, l'écran de verrouillage affiche automatiquement les commandes de transport.

Sur Android 5.0 (niveau d'API 21) ou version ultérieure, le système ne fournit pas de données de transport sur l'écran de verrouillage. Utilisez plutôt un MediaStyle notification pour afficher les commandes de transport.

Ajouter des actions personnalisées

Les applications multimédias peuvent définir des actions personnalisées. Exemples : "J'aime", "J'aime" ou revenir en arrière de 30 secondes. Une action personnalisée doit implémenter un comportement complètement nouveau. À faire Ne pas utiliser d'action personnalisée pour remplacer l'une des actions standards de contrôle du transport défini 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 voir un exemple complet, consultez la page consacrée au lecteur de musique Universal.

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 la page consacrée au lecteur de musique Universal.

Rappels de session multimédia

Les principales méthodes de rappel de session multimédia sont onPlay(), onPause() et onStop(). C'est ici 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 de rappel/lecteur appropriée en fonction de l'appareil et/ou du niveau du système. Vous pouvez changer de lecteur sans modifier le reste de l'application. Par exemple, vous pouvez utiliser ExoPlayer sous Android 4.1 (niveau d'API 16) ou une version ultérieure, et utiliser 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 permettent d'activer et de désactiver des fonctionnalités de votre application, et de contrôler la façon dont elle interagit avec les 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 applications audio et applications vidéo, décrire comment les rappels doivent être implémentés pour chaque type d'application.