Gérer et lire des contenus

Cette page explique comment utiliser un gestionnaire de préchargement pour gérer le contenu vidéo. En utilisant un gestionnaire de préchargement, vous pouvez offrir une meilleure expérience à l'utilisateur. Lorsqu'il passe d'un élément multimédia à un autre, la lecture démarre plus rapidement, car le gestionnaire a déjà chargé une partie du contenu.

Cette page aborde les sujets suivants :

Ajouter des éléments multimédias au gestionnaire de préchargement

Vous devez informer le gestionnaire de préchargement de chaque élément multimédia qu'il suivra. Par exemple, si votre application comporte un carrousel de vidéos, vous devez ajouter ces vidéos au gestionnaire de préchargement. Selon votre cas d'utilisation, vous pouvez ajouter toutes les vidéos ou uniquement celles qui se trouvent à proximité de la vidéo en cours de lecture. Vous pouvez également ajouter de nouveaux éléments au gestionnaire de préchargement ultérieurement.

L'ajout d'éléments multimédias ne déclenche pas en soi le chargement du contenu par le gestionnaire de préchargement. Pour déclencher le préchargement, vous devez invalider les priorités dans le gestionnaire de préchargement.

val initialMediaItems = pullMediaItemsFromService(/* count= */ 20);
for (index in 0 until initialMediaItems.size) {
  preloadManager.add(initialMediaItems.get(index), /* rankingData= */ index)
}
// items aren't actually loaded yet! need to call invalidate() after this

Points clés concernant le code

  • Cet extrait montre comment remplir initialement le gestionnaire de préchargement après l'avoir créé. Vous pouvez également appeler add() pour ajouter des éléments à un gestionnaire de préchargement existant et déjà rempli.
  • Dans cet extrait, pullMediaItemsFromService() correspond à la logique de l'application pour récupérer la liste des contenus à lire. Le code appelle cette méthode pour récupérer une liste de 20 éléments maximum.
  • preloadManager est la DefaultPreloadManager créée dans Créer une DefaultPreloadManager. Le code appelle la méthode add() de ce gestionnaire pour ajouter chaque élément du carrousel.
  • rankingData est une valeur utilisée par le gestionnaire de préchargement pour déterminer la priorité de chaque élément multimédia. Pour DefaultPreloadManager, rankingData est un entier représentant la position de l'élément dans le carrousel. Le gestionnaire de préchargement détermine la priorité en fonction de la distance entre chaque élément et l'élément en cours de lecture.

Invalider les priorités dans le gestionnaire de préchargement

Pour déclencher le préchargement du contenu par le gestionnaire de préchargement, vous devez appeler invalidate() pour indiquer au gestionnaire de préchargement que les priorités des éléments ne sont plus à jour. Vous devez le faire dans les cas suivants :

  • Lorsque vous ajoutez ou supprimez des éléments multimédias dans le gestionnaire de préchargement. Si vous ajoutez ou supprimez plusieurs éléments, vous devez tous les ajouter, puis appeler invalidate().
  • Lorsque l'utilisateur passe d'un élément multimédia à un autre. Dans ce cas, vous devez vous assurer de mettre à jour l'index de lecture actuel avant d'appeler invalidate(), comme décrit dans Récupérer et lire du contenu.

Lorsque vous invalidez le gestionnaire de préchargement, il appelle le TargetPreloadStatusControl que vous avez créé pour déterminer la quantité de contenu à charger à partir de chaque élément. Il charge ensuite le contenu de chaque élément en fonction de son niveau de priorité (du plus élevé au plus faible).

preloadManager.invalidate()

Points clés concernant le code

  • L'appel de invalidate() déclenche la réévaluation de la priorité de chaque élément multimédia connu par le gestionnaire de préchargement. C'est pourquoi, si vous apportez de nombreuses modifications au gestionnaire de préchargement, vous devez les terminer avant d'appeler invalidate().

Récupérer et lire des contenus multimédias

Lorsque l'utilisateur passe à un nouvel élément multimédia, vous devez l'obtenir auprès du gestionnaire de préchargement. Si le gestionnaire de préchargement a chargé du contenu, celui-ci est lu plus rapidement que si vous ne l'aviez pas utilisé. Si le gestionnaire de préchargement n'a pas encore chargé le contenu de cet élément, il est lu normalement.

// When a media item is about to display on the screen
val mediaSource = preloadManager.getMediaSource(mediaItem)
if (mediaSource != null) {
    player.setMediaSource(mediaSource)
}
player.prepare()

// When the media item is displaying at the center of the screen
player.play()
preloadManager.setCurrentPlayingIndex(currentIndex)

// Need to call invalidate() to update the priorities
preloadManager.invalidate()

Points clés concernant le code

  • player est le ExoPlayer Media3 que l'application utilise pour lire le contenu. Vous devez créer ce lecteur en appelant DefaultPreloadManager.Builder.buildExoPlayer() sur le même générateur que celui utilisé pour créer le gestionnaire de préchargement.
  • Lorsque l'utilisateur passe à un nouvel élément multimédia, l'application appelle getMediaSource() pour obtenir la source multimédia du gestionnaire de préchargement. Il doit s'agir d'un mediaItem que vous avez déjà ajouté au gestionnaire de préchargement. Ce n'est pas un problème si le gestionnaire de préchargement n'a pas encore commencé à charger le contenu. Dans ce cas, il renvoie un MediaSource qui ne contient pas de données préchargées. Par exemple, cela peut se produire si l'utilisateur passe soudainement loin en avant dans le carrousel.
  • Une fois que l'utilisateur a lu le nouvel élément multimédia, appelez setCurrentPlayingIndex pour indiquer au gestionnaire de préchargement où se trouve le nouvel élément dans le carrousel. Le gestionnaire de préchargement a besoin de ces informations pour donner la priorité au chargement de l'élément suivant. Après avoir mis à jour l'index actuel, appelez invalidate() pour que le gestionnaire de préchargement redétermine la priorité de chaque élément.

Supprimer des éléments du gestionnaire de préchargement

Pour que le gestionnaire de préchargement reste efficace, vous devez supprimer les éléments qu'il n'a plus besoin de suivre. Vous pouvez également supprimer les éléments qui se trouvent toujours dans le carrousel, mais qui sont loin de la position actuelle de l'utilisateur. Par exemple, vous pouvez décider qu'un élément n'a pas besoin d'être préchargé s'il se trouve à plus de 15 éléments de ce que l'utilisateur regarde. Dans ce cas, vous supprimeriez les éléments lorsqu'ils seraient aussi éloignés. Si l'utilisateur revient vers les éléments supprimés, vous pouvez toujours les rajouter.

preloadManager.remove(mediaItem)

Points clés concernant le code

Libérer le gestionnaire de préchargement lorsque vous n'en avez plus besoin

Lorsque vous n'avez plus besoin du gestionnaire de préchargement, vous devez le libérer pour libérer ses ressources. Veillez en particulier à le libérer lorsque votre activité est détruite.

preloadManager.release()

Points clés concernant le code

  • Vous ne devez pas appeler les méthodes de l'objet après l'avoir libéré.
  • Si vous devez créer un autre gestionnaire de préchargement, créez un DefaultPreloadManager.Builder et utilisez-le pour créer le DefaultPreloadManager. N'essayez pas de réutiliser l'ancien outil de création.