Guide de migration AndroidX Media3

Les applications qui utilisent actuellement la bibliothèque com.google.android.exoplayer2 autonome et androidx.media doivent migrer vers androidx.media3. Utilisez le script de migration pour migrer les fichiers de compilation Gradle, les fichiers sources Java et Kotlin, ainsi que les fichiers de mise en page XML d'ExoPlayer 2.19.1 vers le 1.1.1 AndroidX Media3.

Présentation

Avant d'effectuer la migration, consultez les sections suivantes pour en savoir plus sur les avantages des nouvelles API, les API à migrer et les prérequis que le projet de votre application doit remplir.

Pourquoi migrer vers Jetpack Media3

• Il s'agit de la nouvelle interface d'ExoPlayer, tandis que com.google.android.exoplayer2 n'est plus disponible.
• Accédez à l'API Player dans tous les composants/processus avec MediaBrowser/MediaController.
• Utilisez les fonctionnalités étendues des API MediaSession et MediaController.
• Annoncez les fonctionnalités de lecture avec un contrôle des accès précis.
• Simplifiez votre application en supprimant MediaSessionConnector et PlayerNotificationManager.
• Rétrocompatibilité avec les API clientes de compatibilité multimédia (MediaBrowserCompat/MediaControllerCompat/MediaMetadataCompat)

API multimédias pour migrer vers AndroidX Media3

• ExoPlayer et ses extensions
  Cela inclut tous les modules de l'ancien projet ExoPlayer, à l'exception du module mediasession, qui a été arrêté. Les applications ou les modules qui dépendent des packages dans com.google.android.exoplayer2 peuvent être migrés avec le script de migration.
• MediaSessionConnector (en fonction des packages androidx.media.* de androidx.media:media:1.4.3+)
  Supprimez MediaSessionConnector et utilisez à la place androidx.media3.session.MediaSession.
• MediaBrowserServiceCompat (selon les packages androidx.media.* de androidx.media:media:1.4.3+)
  Migrez les sous-classes de androidx.media.MediaBrowserServiceCompat vers androidx.media3.session.MediaLibraryService et le code utilisant MediaBrowserCompat.MediaItem vers androidx.media3.common.MediaItem.
• MediaBrowserCompat (en fonction des packages android.support.v4.media.* de androidx.media:media:1.4.3+)
  Migrez le code client à l'aide de MediaBrowserCompat ou MediaControllerCompat pour utiliser androidx.media3.session.MediaBrowser avec androidx.media3.common.MediaItem.

Conditions préalables

1. S'assurer que votre projet est soumis au contrôle du code source

   Assurez-vous de pouvoir facilement annuler les modifications appliquées par les outils de migration à l'aide de scripts. Si votre projet n'est pas encore soumis au contrôle des sources, c'est le bon moment pour commencer. Si, pour une raison quelconque, vous ne souhaitez pas le faire, créez une copie de sauvegarde de votre projet avant de lancer la migration.

2. Mettre à jour votre application

   • Nous vous recommandons de mettre à jour votre projet pour utiliser la version la plus récente de la bibliothèque ExoPlayer et de supprimer tous les appels à des méthodes obsolètes. Si vous avez l'intention d'utiliser le script pour la migration, vous devez faire correspondre la version vers laquelle vous effectuez la mise à jour avec la version gérée par le script.

   • Augmentez la valeur de compileSdkVersion de votre application à au moins 32.

   • Mettez à niveau Gradle et le plug-in Android Studio Gradle vers une version récente compatible avec les dépendances mises à jour ci-dessus. Exemple:

     • Version du plug-in Android Gradle: 7.1.0
     • Version de Gradle: 7.4

   • Remplacez toutes les instructions d'importation avec caractères génériques qui utilisent un astérisque (*) et utilisez des instructions d'importation complètes: supprimez les instructions d'importation avec caractères génériques et utilisez Android Studio pour les importer (F2 - Alt/Entrée, F2 - Alt/Entrée, etc.).

   • Migrez de com.google.android.exoplayer2.PlayerView vers com.google.android.exoplayer2.StyledPlayerView. Cette opération est nécessaire, car il n'existe pas d'équivalent à com.google.android.exoplayer2.PlayerView dans AndroidX Media3.

Migrer ExoPlayer avec prise en charge des scripts

Le script facilite le passage de com.google.android.exoplayer2 à la nouvelle structure de package et de module sous androidx.media3. Le script applique des contrôles de validation à votre projet et affiche des avertissements en cas d'échec de la validation. Sinon, il applique les mappages de classes et de packages renommés dans les ressources d'un projet Gradle Android écrit en Java ou Kotlin.

usage: ./media3-migration.sh [-p|-c|-d|-v]|[-m|-l [-x <path>] [-f] PROJECT_ROOT]
 PROJECT_ROOT: path to your project root (location of 'gradlew')
 -p: list package mappings and then exit
 -c: list class mappings (precedence over package mappings) and then exit
 -d: list dependency mappings and then exit
 -l: list files that will be considered for rewrite and then exit
 -x: exclude the path from the list of file to be changed: 'app/src/test'
 -m: migrate packages, classes and dependencies to AndroidX Media3
 -f: force the action even when validation fails
 -v: print the exoplayer2/media3 version strings of this script
 -h, --help: show this help text

Utiliser le script de migration

Avertissement :Le script peut placer les fichiers de compilation Gradle dans un état inutilisable si vos déclarations de dépendance utilisent des variables ou des techniques avancées.

1. Téléchargez le script de migration à partir du tag du projet ExoPlayer sur GitHub correspondant à la version vers laquelle vous avez mis à jour votre application:

   curl -o media3-migration.sh \
     "https://raw.githubusercontent.com/google/ExoPlayer/r2.19.1/media3-migration.sh"
   

2. Rendez le script exécutable:

   chmod 744 media3-migration.sh
   

3. Exécutez le script avec --help pour en savoir plus sur les options.

4. Exécutez le script avec -l pour répertorier l'ensemble des fichiers sélectionnés pour la migration (utilisez -f pour forcer l'affichage de la liste sans avertissement):

   ./media3-migration.sh -l -f /path/to/gradle/project/root
   

5. Exécutez le script avec -m pour mapper les packages, les classes et les modules à Media3. L'exécution du script avec l'option -m applique les modifications aux fichiers sélectionnés.

   • Arrêter à l'erreur de validation sans apporter de modifications

   ./media3-migration.sh -m /path/to/gradle/project/root
   

   • Exécution forcée

   Si le script détecte un cas de non-respect des conditions préalables, la migration peut être forcée avec l'option -f:

   ./media3-migration.sh -m -f /path/to/gradle/project/root
   

Remarque :Vous pouvez utiliser le paramètre -x pour empêcher qu'un chemin soit sélectionné à des fins de modification.

 # list files selected for migration when excluding paths
 ./media3-migration.sh -l -x "app/src/test/" -x "service/" /path/to/project/root
 # migrate the selected files
 ./media3-migration.sh -m -x "app/src/test/" -x "service/" /path/to/project/root

Effectuez ces étapes manuelles après avoir exécuté le script avec l'option -m:

1. Vérifiez comment le script a modifié votre code: utilisez un outil de comparaison et corrigez les problèmes potentiels (envisagez de signaler un bug si vous pensez que le script présente un problème général qui a été introduit sans transmettre l'option -f).
2. Compilez le projet: utilisez ./gradlew clean build ou, dans Android Studio, sélectionnez File > Sync Project with Gradle Files (Fichier > Synchroniser le projet avec les fichiers Gradle), puis Build > Clean project (Compiler > Nettoyer le projet) et enfin Build > Rebuild project (Compiler > Recompiler le projet). Surveillez votre build dans l'onglet Build - Build Output' (Compilation - Sortie de compilation) d'Android Studio.

Remarque :Dans certains cas, le script doit laisser votre projet dans un état qui ne peut pas être compilé sans migrer manuellement le code. Le script vous avertit et demande l'option -f pour forcer l'exécution. C'est par exemple le cas si une application utilise MediaSessionConnector et MediaSessionCompat. Consultez la section suivante pour obtenir des conseils sur la migration de MediaSessionConnector vers Media3.

Étapes de suivi recommandées:

1. Résolvez les erreurs d'activation concernant l'utilisation d'API instables.
2. Remplacer les appels d'API obsolètes: utilisez l'API de remplacement suggérée. Maintenez le pointeur sur l'avertissement dans Android Studio et consultez le JavaDoc du symbole obsolète pour savoir quoi utiliser à la place d'un appel donné.
3. Trier les instructions d'importation: ouvrez le projet dans Android Studio, effectuez un clic droit sur un nœud de dossier de package dans la visionneuse de projet, puis sélectionnez Optimize imports (Optimiser les importations) sur les packages contenant les fichiers sources modifiés.

Remplacez MediaSessionConnector par androidx.media3.session.MediaSession.

Dans l'ancien monde MediaSessionCompat, MediaSessionConnector était chargé de synchroniser l'état du joueur avec l'état de la session et de recevoir les commandes des manettes nécessitant une délégation aux méthodes appropriées du lecteur. Avec AndroidX Media3, cette opération est effectuée directement par MediaSession sans nécessiter de connecteur.

1. Supprimez toutes les références et l'utilisation de MediaSessionConnector:si vous avez utilisé le script automatisé pour migrer les classes et les packages ExoPlayer, le script a probablement laissé votre code dans un état incompilable concernant MediaSessionConnector, qui ne peut pas être résolu. Android Studio affiche le code erroné lorsque vous essayez de compiler ou de démarrer l'application.

2. Dans le fichier build.gradle où vous gérez vos dépendances, ajoutez une dépendance d'implémentation au module de session AndroidX Media3 et supprimez l'ancienne dépendance:

   implementation "androidx.media3:media3-session:1.3.1"
   

3. Remplacez MediaSessionCompat par androidx.media3.session.MediaSession.

4. Sur le site de code où vous avez créé l'ancienne MediaSessionCompat, utilisez androidx.media3.session.MediaSession.Builder pour créer une MediaSession. Transmettez le joueur pour construire le générateur de session.

   Remarque :Si votre application utilise un lecteur différent de ExoPlayer, vous avez besoin d'une implémentation Player personnalisée que vous pouvez transmettre à MediaSession qui encapsule votre lecteur. Nous vous fournirons plus de conseils sur une implémentation Player minimale qui fonctionne avec l'implémentation de la session multimédia.

   val player = ExoPlayer.Builder(context).build()
   mediaSession = MediaSession.Builder(context, player)
       .setSessionCallback(MySessionCallback())
       .build()
   

   Remarque :Vous pouvez intercepter tout appel de méthode à Player en l'encapsulant dans un ForwardingPlayer(player).

5. Implémentez MySessionCallback selon les exigences de votre application. Cette étape est facultative. Si vous souhaitez autoriser les manettes à ajouter des éléments multimédias au lecteur, implémentez MediaSession.Callback.onAddMediaItems(). Elle utilise diverses méthodes d'API actuelles et anciennes qui permettent d'ajouter des éléments multimédias au lecteur pour une lecture rétrocompatible. Cela inclut les méthodes MediaController.set/addMediaItems() du contrôleur Media3, ainsi que les méthodes TransportControls.prepareFrom*/playFrom* de l'ancienne API. Vous trouverez un exemple d'implémentation de onAddMediaItems dans le PlaybackService de l'application de démonstration de la session.

6. Libérez la session multimédia sur le site de code où vous avez détruit votre session avant la migration:

   mediaSession?.run {
     player.release()
     release()
     mediaSession = null
   }
   

   Remarque :Il est important de libérer la session multimédia avant d'en créer une autre avec le même ID. Media3 génère une exception si une application provoque la fuite d'une instance de session.

Fonctionnalité MediaSessionConnector dans Media3

Le tableau suivant présente les API Media3 qui gèrent les fonctionnalités précédemment implémentées dans MediaSessionConnector.

MediaSessionConnector	AndroidX Media3
CustomActionProvider	MediaSession.Callback.onCustomCommand()/ MediaSession.setCustomLayout()
PlaybackPreparer	MediaSession.Callback.onAddMediaItems() (prepare() est appelé en interne)
QueueNavigator	ForwardingPlayer
QueueEditor	MediaSession.Callback.onAddMediaItems()
RatingCallback	MediaSession.Callback.onSetRating()
PlayerNotificationManager	DefaultMediaNotificationProvider/ MediaNotification.Provider

Migrer MediaBrowserService vers MediaLibraryService

AndroidX Media3 introduit MediaLibraryService qui remplace MediaBrowserServiceCompat. Le JavaDoc de MediaLibraryService et sa super-classe MediaSessionService fournissent une bonne introduction à l'API et au modèle de programmation asynchrone du service.

Le MediaLibraryService est rétrocompatible avec MediaBrowserService. Une application cliente qui utilise MediaBrowserCompat ou MediaControllerCompat continue de fonctionner sans modification de code lors de la connexion à un MediaLibraryService. Pour un client, la transparence est indiquée, que votre application utilise un MediaLibraryService ou un ancien MediaBrowserServiceCompat.

Figure 1: Présentation des composants d'application multimédia

1. Pour que la rétrocompatibilité fonctionne, vous devez enregistrer les deux interfaces de service auprès de votre service dans le AndroidManifest.xml. De cette façon, un client trouve votre service par l'interface de service requise:

   <service android:name=".MusicService" android:exported="true">
       <intent-filter>
           <action android:name="androidx.media3.session.MediaLibraryService"/>
           <action android:name="android.media.browse.MediaBrowserService" />
       </intent-filter>
   </service>
   

2. Dans le fichier build.gradle où vous gérez vos dépendances, ajoutez une dépendance d'implémentation au module de session AndroidX Media3 et supprimez l'ancienne dépendance:

   implementation "androidx.media3:media3-session:1.3.1"
   

3. Modifiez votre service pour qu'il hérite d'un MediaLibraryService au lieu d'un MediaBrowserService. Comme indiqué précédemment, MediaLibraryService est compatible avec l'ancien MediaBrowserService. Par conséquent, l'API globale que le service offre aux clients reste la même. Il est donc probable qu'une application puisse conserver la majeure partie de la logique requise pour implémenter MediaBrowserService et l'adapter au nouveau MediaLibraryService.

   Les principales différences par rapport à l'ancien MediaBrowserServiceCompat sont les suivantes:

   • Implémentez les méthodes du cycle de vie du service:les méthodes à remplacer sur le service lui-même sont onCreate/onDestroy, où une application alloue/libère la session de bibliothèque, le lecteur et d'autres ressources. En plus des méthodes standards de cycle de vie des services, une application doit ignorer onGetSession(MediaSession.ControllerInfo) pour renvoyer le MediaLibrarySession créé dans onCreate.

   • Implement MediaLibraryService.MediaLibrarySessionCallback:la création d'une session nécessite un MediaLibraryService.MediaLibrarySessionCallback qui implémente les méthodes API du domaine. Ainsi, au lieu de remplacer les méthodes API de l'ancien service, vous remplacerez les méthodes de MediaLibrarySession.Callback.

     Le rappel est ensuite utilisé pour créer MediaLibrarySession:

     mediaLibrarySession =
           MediaLibrarySession.Builder(this, player, MySessionCallback())
              .build()
     

     Retrouvez l'API complète de MediaLibrarySessionCallback dans la documentation de l'API.

   • Implémentez MediaSession.Callback.onAddMediaItems(): le rappel onAddMediaItems(MediaSession, ControllerInfo, List<MediaItem>) diffuse différentes méthodes d'API (actuelles et anciennes) qui ajoutent des éléments multimédias au lecteur pour une lecture rétrocompatible. Cela inclut les méthodes MediaController.set/addMediaItems() du contrôleur Media3, ainsi que les méthodes TransportControls.prepareFrom*/playFrom* de l'ancienne API. Vous trouverez un exemple d'implémentation du rappel dans le PlaybackService de l'application de démonstration de session.

   • AndroidX Media3 utilise androidx.media3.common.MediaItem au lieu de MediaBrowserCompat.MediaItem et MediaMetadataCompat. Les parties de votre code liées aux anciennes classes doivent être modifiées en conséquence ou mappées avec le MediaItem Media3.

   • Le modèle de programmation asynchrone général est passé à Futures, contrairement à l'approche Result détachable de MediaBrowserServiceCompat. L'implémentation de votre service peut renvoyer un ListenableFuture asynchrone au lieu de détacher un résultat ou de renvoyer un objet Future immédiat pour renvoyer directement une valeur.

Suppression de PlayerNotificationManager

MediaLibraryService prend automatiquement en charge les notifications multimédias et PlayerNotificationManager peut être supprimé lorsque vous utilisez MediaLibraryService ou MediaSessionService.

Remarque :Les applications ciblant le niveau d'API 28 ou supérieur doivent toujours demander l'autorisation FOREGROUND_SERVICE.

Une application peut personnaliser la notification en définissant un MediaNotification.Provider personnalisé dans onCreate() qui remplace le DefaultMediaNotificationProvider. MediaLibraryService se charge ensuite de démarrer le service au premier plan si nécessaire.

En remplaçant MediaLibraryService.updateNotification(), une application peut s'approprier entièrement la publication d'une notification et le démarrage/l'arrêt du service au premier plan si nécessaire.

Migrer le code client à l'aide d'un MediaBrowser

Avec AndroidX Media3, un MediaBrowser implémente les interfaces MediaController/Player et peut être utilisé pour contrôler la lecture des contenus multimédias en plus de parcourir la bibliothèque multimédia. Si vous deviez créer une MediaBrowserCompat et une MediaControllerCompat dans l'ancien monde, vous pouvez le faire en utilisant uniquement MediaBrowser dans Media3.

Remarque :Les utilisateurs de Kotlin peuvent dépendre de kotlin-coroutines-guava ou d'androidx.concurrent dans le fichier build.gradle pour ajouter la méthode d'extension await à ListenableFuture. Cela permet à l'API MediaBrowser de s'intégrer plus naturellement à une méthode suspend.

Un MediaBrowser peut être créé et attendre que la connexion au service soit établie:

scope.launch {
    val sessionToken =
        SessionToken(context, ComponentName(context, MusicService::class.java)
    browser =
        MediaBrowser.Builder(context, sessionToken))
            .setListener(BrowserListener())
            .buildAsync()
            .await()
    // Get the library root to start browsing the library.
    root = browser.getLibraryRoot(/* params= */ null).await();
    // Add a MediaController.Listener to listen to player state events.
    browser.addListener(playerListener)
    playerView.setPlayer(browser)
}

Consultez Contrôler la lecture dans la session multimédia pour découvrir comment créer un MediaController afin de contrôler la lecture en arrière-plan.

Étapes supplémentaires et nettoyage

Erreurs d'API instables

Après la migration vers Media3, vous verrez peut-être des erreurs lint concernant des utilisations d'API instables. Ces API peuvent être utilisées sans risque, et les erreurs lint sont un effet secondaire de nos nouvelles garanties de compatibilité binaire. Si vous n'avez pas besoin d'une compatibilité binaire stricte, vous pouvez supprimer ces erreurs en toute sécurité à l'aide d'une annotation @OptIn.

Arrière-plan

Ni ExoPlayer v1 ni aucune version 2 ne fournissaient de garanties strictes concernant la compatibilité binaire de la bibliothèque entre les versions ultérieures. La surface de l'API ExoPlayer est très grande par nature, ce qui permet aux applications de personnaliser presque tous les aspects de la lecture. Les versions ultérieures d'ExoPlayer introduisaient occasionnellement des changements de noms de symboles ou d'autres modifications importantes (par exemple, de nouvelles méthodes requises sur les interfaces). Dans la plupart des cas, ces défaillances ont été atténuées par l'introduction du nouveau symbole et l'abandon de l'ancien symbole pour quelques versions afin de laisser le temps aux développeurs de migrer leurs utilisations, mais cela n'a pas toujours été possible.

Ces modifications destructives ont entraîné deux problèmes pour les utilisateurs des bibliothèques ExoPlayer v1 et v2:

1. Une mise à niveau vers la version d'ExoPlayer peut entraîner l'arrêt de la compilation du code.
2. Une application qui dépendait d'ExoPlayer à la fois directement et via une bibliothèque intermédiaire devait s'assurer que les deux dépendances étaient la même version, sinon des incompatibilités binaires pourraient entraîner des plantages au moment de l'exécution.

Améliorations dans Media3

Media3 garantit la compatibilité binaire pour un sous-ensemble de la surface de l'API. Les parties qui ne garantissent pas la compatibilité binaire sont marquées avec @UnstableApi. Pour que cette distinction soit claire, l'utilisation de symboles d'API instables génère une erreur lint, sauf s'ils sont annotés avec @OptIn.

Après la migration d'ExoPlayer v2 vers Media3, vous pouvez rencontrer de nombreuses erreurs lint de l'API instables. Par conséquent, vous pouvez donner l'impression que Media3 est "moins stable" qu'ExoPlayer v2. Ce n'est pas le cas. Les parties "instables" de l'API Media3 ont le même niveau de stabilité que l'ensemble de la surface de l'API ExoPlayer v2. De plus, les garanties de la surface stable de l'API Media3 ne sont pas du tout disponibles dans ExoPlayer v2. La différence est simplement qu'une erreur lint vous alerte désormais sur les différents niveaux de stabilité.

Gérer les erreurs lint de l'API instable

Consultez la section de dépannage concernant ces erreurs lint pour découvrir comment annoter les utilisations Java et Kotlin des API instables avec @OptIn.

API obsolètes

Vous remarquerez peut-être que les appels à des API obsolètes sont barrés dans Android Studio. Nous vous recommandons de remplacer ces appels par une autre méthode appropriée. Passez la souris sur le symbole pour afficher le document JavaDoc qui indique l'API à utiliser à la place.

Figure 3: L'info-bulle JavaDoc dans Android Studio suggère une alternative à tout symbole obsolète.

Exemples de code et applications de démonstration

• Application de démonstration de la session Media3 AndroidX (mobile et Wear OS)
  • Actions personnalisées
  • Notification de l'interface utilisateur système, MediaButton/BT
  • Commande de lecture de l'Assistant Google
• UAMP: Android Media Player (branch media3) (mobile, AutomotiveOS)
  • Notification de l'interface utilisateur système, MediaButton/BT, reprise de la lecture
  • Commandes de lecture de l'Assistant Google/WearOS
  • AutomotiveOS: commande et connexion personnalisées