Cette page a été traduite par l'API Cloud Translation.

Activer la commande de lecture

Pour activer la lecture multimédia dans Android Auto et Android Automotive OS (AAOS), implémentez des commandes de lecture en enregistrant une session multimédia et en gérant ses méthodes de rappel. Cette page explique comment :

Enregistrez un objet MediaSessionCompat dans votre service de navigateur multimédia.
Implémentez les méthodes MediaSessionCompat.Callback pour répondre aux demandes de lecture des utilisateurs.
Configurez des actions de lecture standards et personnalisées.
Définissez l'état de lecture initial de votre session multimédia.
Ajoutez des icônes pour indiquer le format audio.
créer des liens à partir d'éléments multimédias en cours de lecture ;

Android Auto et AAOS envoient des commandes de lecture via MediaSessionCompat pour votre service. Vous devez enregistrer une session et implémenter les méthodes de rappel associées.

Enregistrer une session multimédia

Dans la méthode onCreate de votre service de navigateur multimédia, créez une instance de MediaSessionCompat, puis appelez setSessionToken pour enregistrer la session multimédia. Cet extrait de code montre comment créer et enregistrer une session multimédia :

Kotlin

override fun onCreate() {
    super.onCreate()
    ...
    // Start a new MediaSession.
    val session = MediaSessionCompat(this, "session tag").apply {
        // Set a callback object that implements MediaSession.Callback
        // to handle play control requests.
        setCallback(MyMediaSessionCallback())
    }
    sessionToken = session.sessionToken
    ...
}

Java

public void onCreate() {
    super.onCreate();
    ...
    // Start a new MediaSession.
    MediaSessionCompat session = new MediaSessionCompat(this, "session tag");
    setSessionToken(session.getSessionToken());

    // Set a callback object that implements MediaSession.Callback
    // to handle play control requests.
    session.setCallback(new MyMediaSessionCallback());
    ...
}

Lorsque vous créez l'objet de session multimédia, vous définissez un objet de rappel utilisé pour gérer les requêtes de commande de lecture. Pour créer cet objet de rappel, vous devez fournir une implémentation de la classe MediaSessionCompat.Callback pour votre application. La section suivante vous explique comment implémenter cet objet.

Implémenter des commandes de lecture

Lorsqu'un utilisateur demande de lire un élément multimédia de votre application, Android Automotive OS et Android Auto utilisent la classe MediaSessionCompat.Callback de l'objet MediaSessionCompat qu'ils ont reçu du service de navigateur multimédia de l'application. Lorsqu'un utilisateur souhaite contrôler la lecture du contenu (par exemple, en mettant en pause la lecture ou en passant au titre suivant), Android Auto et Android Automotive OS appellent l'une des méthodes de l'objet de rappel.

Pour gérer la lecture de contenu, votre application doit étendre la classe abstraite MediaSessionCompat.Callback et implémenter les méthodes compatibles avec votre application.

Implémentez chacune de ces méthodes de rappel qui sont adaptées au type de contenu proposé par votre application :

onPrepare: AAOS appelle cette méthode lorsque la source multimédia change.
onPlay: Appelée lorsque l'utilisateur lance la lecture sans choisir d'élément spécifique. Votre application doit lire son contenu par défaut ou, si la lecture a été interrompue avec onPause, l'application doit la reprendre.

Remarque : Votre application ne doit pas lancer automatiquement la lecture de musique quand Android Automotive OS ou Android Auto se connecte au service de navigateur multimédia. Pour en savoir plus, consultez Définir la classe PlaybackState initiale.
onPlayFromMediaId: Appelée lorsque l'utilisateur lance la lecture d'un élément spécifique. Cette méthode reçoit l'ID que votre service de navigateur multimédia a affecté à l'élément multimédia dans la hiérarchie de contenu.
onPlayFromSearch: Appelée lorsque l'utilisateur lance la lecture à partir d'une requête de recherche. L'application doit faire le bon choix en fonction de la chaîne de recherche qui a été transmise.
onPause: Appelée lorsque l'utilisateur décide de suspendre la lecture.
onSkipToNext: Appelée lorsque l'utilisateur décide de passer à l'élément suivant.
onSkipToPrevious: Appelée lorsque l'utilisateur décide de revenir à l'élément précédent.
onStop: Appelée lorsque l'utilisateur décide d'arrêter la lecture. Remplacez ces méthodes dans votre application pour fournir le résultat choisi. Vous n'avez pas à implémenter une méthode si sa fonctionnalité n'est pas compatible avec votre application. Par exemple, si votre application lit une diffusion en direct, telle qu'une émission sportive, vous n'avez pas besoin d'implémenter onSkipToNext. Utilisez plutôt l'implémentation par défaut de onSkipToNext.

Votre application n'a pas besoin d'une logique particulière pour lire du contenu via les haut-parleurs de la voiture. Lorsque votre application reçoit une requête de lecture de contenu, elle lit le contenu audio de la même manière que via le casque ou le haut-parleur du téléphone. Android Auto et AAOS envoient automatiquement le contenu audio au système de la voiture pour qu'il le diffuse sur ses haut-parleurs.

Pour en savoir plus sur la lecture de contenu audio, consultez Présentation de MediaPlayer, Présentation de l'application audio et Présentation d'ExoPlayer.

Définir des actions de lecture standards

Android Auto et AAOS affichent les commandes de lecture en fonction des actions activées dans l'objet PlaybackStateCompat. Par défaut, votre application doit accepter les actions suivantes :

Votre application peut, en outre, accepter les actions suivantes si elles sont pertinentes par rapport à son contenu :

Vous pouvez également créer une file d'attente de lecture que l'utilisateur peut voir (facultatif). Pour ce faire, appelez les méthodes setQueue et setQueueTitle, activez l'action ACTION_SKIP_TO_QUEUE_ITEM et définissez le rappel onSkipToQueueItem.

Vous devez également utiliser l'icône En écoute, qui indique l'élément en cours de lecture. Pour ce faire, appelez la méthode setActiveQueueItemId et transmettez l'ID de l'élément en cours de lecture dans la file d'attente. Vous devez mettre à jour setActiveQueueItemId chaque fois qu'une file d'attente est modifiée.

Android Auto et AAOS affichent des boutons pour chaque action activée, ainsi que la file d'attente de lecture. Lorsque les utilisateurs cliquent sur ces boutons, le système appelle le rappel correspondant à partir de MediaSessionCompat.Callback.

Réserver de l'espace inutilisé

Android Auto et AAOS réservent de l'espace dans l'UI pour les actions ACTION_SKIP_TO_PREVIOUS et ACTION_SKIP_TO_NEXT. Si votre application n'est pas compatible avec l'une de ces fonctions, Android Auto et AAOS utilisent cet espace pour afficher les actions personnalisées que vous créez, le cas échéant.

Si vous ne souhaitez pas renseigner des actions personnalisées dans ces espaces, vous pouvez les réserver afin qu'Android Auto et AAOS les laissent vides chaque fois que votre application n'accepte pas la fonction correspondante.

Pour ce faire, appelez la méthode setExtras avec un bundle d'extras contenant des constantes correspondant aux fonctions réservées. SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_NEXT correspond à ACTION_SKIP_TO_NEXT et SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_PREV à ACTION_SKIP_TO_PREVIOUS. Utilisez ces constantes comme clés dans le bundle et utilisez la valeur booléenne true comme valeurs.

Définir la classe PlaybackState initiale

Quand Android Auto et AAOS communiquent avec votre service de navigateur multimédia, votre session multimédia transmet l'état de lecture du contenu à l'aide de PlaybackStateCompat.

Votre application ne doit pas lancer automatiquement la lecture de musique quand AAOS ou Android Auto se connecte à votre service de navigateur multimédia. Au lieu de cela, Android Auto et AAOS doivent reprendre ou lancer la lecture en fonction de l'état de la voiture ou des actions de l'utilisateur.

Pour ce faire, définissez la classe PlaybackStateCompat initiale de votre session multimédia sur STATE_STOPPED, STATE_PAUSED, STATE_NONE ou STATE_ERROR.

La durée des sessions multimédias dans Android Auto et AAOS correspond à celle du trajet. Par conséquent, les utilisateurs lancent et arrêtent fréquemment ces sessions. Pour assurer une expérience optimale entre les lecteurs, effectuez le suivi de l'état de la session précédente. Ainsi, lorsque l'application multimédia reçoit une demande de reprise, l'utilisateur peut reprendre automatiquement là où il s'était arrêté (par exemple, le dernier élément multimédia lu, le PlaybackStateCompat et la file d'attente).

Ajouter des actions de lecture personnalisées

Vous pouvez ajouter des actions de lecture personnalisées pour afficher plus d'actions compatibles avec votre application multimédia. Si l'espace le permet (et que vous ne le réservez pas), Android ajoute les actions personnalisées aux commandes de transport. Sinon, les actions personnalisées s'affichent dans le menu Overflow. Android affiche les actions personnalisées dans l'ordre dans lequel vous les ajoutez à PlaybackStateCompat.

Les actions personnalisées permettent de fournir un comportement différent des actions standards. Ne les utilisez pas pour remplacer ou dupliquer des actions standards.

Pour ajouter des actions personnalisées, utilisez la méthode addCustomAction dans la classe PlaybackStateCompat.Builder. Cet extrait de code montre comment ajouter une action personnalisée à "Lancer une chaîne de radio" :

Kotlin

val customActionExtras = Bundle()
customActionExtras.putInt(
  androidx.media3.session.MediaConstants.EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT,
  androidx.media3.session.CommandButton.ICON_RADIO)

stateBuilder.addCustomAction(
    PlaybackStateCompat.CustomAction.Builder(
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA,
        resources.getString(R.string.start_radio_from_media),
        startRadioFromMediaIcon // or R.drawable.media3_icon_radio
    ).run {
        setExtras(customActionExtras)
        build()
    }
)

Java

Bundle customActionExtras = new Bundle();
customActionExtras.putInt(
  androidx.media3.session.MediaConstants.EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT,
  androidx.media3.session.CommandButton.ICON_RADIO);

stateBuilder.addCustomAction(
    new PlaybackStateCompat.CustomAction.Builder(
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA,
        resources.getString(R.string.start_radio_from_media),
        startRadioFromMediaIcon) // or R.drawable.media3_icon_radio
    .setExtras(customActionExtras)
    .build());

Pour obtenir un exemple plus détaillé de cette méthode, consultez la méthode setCustomAction dans l'application exemple Universal Android Music Player sur GitHub. Une fois que vous avez créé votre action personnalisée, votre session multimédia peut y répondre en remplaçant la méthode onCustomAction.

L'extrait de code suivant montre comment votre application peut répondre à une action "Lancer une chaîne de radio" :

Kotlin

override fun onCustomAction(action: String, extras: Bundle?) {
    when(action) {
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA -> {
            ...
        }
    }
}

Java

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

Pour en savoir plus, consultez la méthode onCustomAction dans l'application exemple Universal Android Music Player sur GitHub.

Créer des icônes pour les actions personnalisées

Chaque action personnalisée que vous créez a besoin d'une icône.

Si la description de cette icône correspond à l'une des constantes CommandButton.ICON_, définissez la valeur entière pour la clé EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT des extras de l'action personnalisée. Sur les systèmes compatibles, cela remplace la ressource d'icône transmise à CustomAction.Builder, ce qui permet aux composants système d'afficher de manière cohérente votre action et d'autres actions de lecture.

Vous devez également spécifier une ressource d'icône. Les applications utilisées dans les voitures peuvent être exécutées sur un large éventail de tailles et de densités d'écran. Les icônes que vous fournissez doivent donc être des drawables vectoriels. Utilisez un drawable vectoriel pour mettre à l'échelle les éléments sans perdre de détails. Un drawable vectoriel peut aligner les bords et les coins sur les limites de pixels à des résolutions inférieures.

Si une action personnalisée est avec état (si elle active ou désactive un paramètre de lecture), fournissez différentes icônes pour les différents états afin d'aider les utilisateurs à voir un changement lorsqu'ils sélectionnent l'action.

Fournir d'autres styles d'icônes pour les actions désactivées

Lorsqu'une action personnalisée n'est pas disponible pour le contexte actuel, remplacez l'icône d'action personnalisée par une autre indiquant que l'action est désactivée.

Indiquer le format audio

Pour indiquer que le contenu multimédia en cours de lecture utilise un format audio spécial, vous pouvez spécifier des icônes affichées dans les voitures compatibles avec cette fonctionnalité. Vous pouvez définir KEY_CONTENT_FORMAT_TINTABLE_LARGE_ICON_URI et KEY_CONTENT_FORMAT_TINTABLE_SMALL_ICON_URI dans le bundle d'extras de l'élément multimédia en cours de lecture (transmis à MediaSession.setMetadata). Définissez les deux extras pour vous adapter aux différentes mises en page.

De plus, vous pouvez définir l'extra KEY_IMMERSIVE_AUDIO pour indiquer aux OEM automobiles qu'il s'agit d'un son immersif. Ils doivent donc être très prudents lorsqu'ils décident d'appliquer des effets audio qui peuvent interférer avec le contenu immersif.

Ajouter les liens de l'élément en cours de lecture

Vous pouvez configurer l'élément multimédia en cours de lecture de sorte que son sous-titre, sa description ou les deux correspondent à des liens vers d'autres éléments multimédias. Cela permet à l'utilisateur de passer rapidement aux éléments connexes ; par exemple, il peut accéder à d'autres titres du même artiste ou à d'autres épisodes d'un podcast. Si la voiture est compatible avec cette fonctionnalité, les utilisateurs peuvent appuyer sur le lien pour accéder au contenu.

Pour ajouter des liens, configurez les métadonnées KEY_SUBTITLE_LINK_MEDIA_ID (pour créer un lien à partir du sous-titre) ou KEY_DESCRIPTION_LINK_MEDIA_ID (pour créer un lien à partir de la description). Pour en savoir plus, consultez le document de référence sur ces champs de métadonnées.

Activer la commande de lecture Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Enregistrer une session multimédia

Kotlin

Java

Implémenter des commandes de lecture

Définir des actions de lecture standards

Réserver de l'espace inutilisé

Définir la classe PlaybackState initiale

Ajouter des actions de lecture personnalisées

Kotlin

Java

Kotlin

Java

Créer des icônes pour les actions personnalisées

Fournir d'autres styles d'icônes pour les actions désactivées

Indiquer le format audio

Ajouter les liens de l'élément en cours de lecture

Activer la commande de lecture