Créer et configurer un DefaultPreloadManager

Cette page explique comment créer un DefaultPreloadManager, qui précharge le contenu multimédia de votre application en fonction de la stratégie que vous choisissez.

Les gestionnaires de préchargement basés sur la classe abstraite BasePreloadManager vous permettent de classer le contenu selon les critères de votre choix. Ce document explique comment utiliser la classe dérivée DefaultPreloadManager, dans laquelle chaque élément multimédia est classé avec un entier représentant sa position dans une liste (par exemple, sa position dans un carrousel vidéo). Le gestionnaire de préchargement priorise le chargement des éléments en fonction de leur proximité avec l'élément que l'utilisateur est en train de lire. Ainsi, si un utilisateur passe à un autre élément, le nouvel élément peut se lancer immédiatement.

La création d'une instance de DefaultPreloadManager s'effectue en trois étapes :

  • Définissez un TargetPreloadStatusControl que le gestionnaire de préchargement peut interroger pour savoir si l'élément multimédia est prêt à être chargé et quelle quantité charger.
  • Créez le compilateur que vous utiliserez pour créer le gestionnaire de préchargement et les objets ExoPlayer de votre application.
  • Utilisez le compilateur pour créer le gestionnaire de préchargement en appelant la méthode build() du compilateur.

Créer un contrôle d'état de préchargement cible

Lorsque vous créez l'DefaultPreloadManager.Builder, vous lui transmettez un objet de contrôle de l'état de préchargement cible que vous définissez. Cet objet implémente l'interface TargetPreloadStatusControl. Lorsque le gestionnaire de préchargement se prépare à précharger des contenus multimédias, il appelle la méthode getTargetPreloadStatus() de votre contrôle d'état pour déterminer s'il doit préparer, charger ou mettre en cache le contenu d'un élément multimédia. Le chargement précharge les données multimédias directement dans le tampon en mémoire d'un lecteur, ce qui les rend prêtes pour une lecture instantanée, tandis que la mise en cache enregistre les données multimédias dans un cache de disque persistant pour économiser la mémoire du lecteur. Le contrôle d'état peut répondre avec l'un des codes d'état suivants :

  • STAGE_SPECIFIED_RANGE_LOADED : le gestionnaire de préchargement doit charger le contenu à partir de la position de départ spécifiée et pour la durée spécifiée (en millisecondes) dans le tampon en mémoire du lecteur.
  • STAGE_SPECIFIED_RANGE_CACHED : le gestionnaire de préchargement doit mettre en cache le contenu à partir de la position de départ spécifiée et pour la durée spécifiée (en millisecondes) dans le cache du disque.
  • STAGE_TRACKS_SELECTED : le gestionnaire de préchargement doit charger et traiter les informations de la piste de contenu, puis sélectionner les pistes. Le gestionnaire de préchargement ne doit pas encore commencer à charger le contenu.
  • STAGE_SOURCE_PREPARED : le gestionnaire de préchargement doit préparer la source de contenu. Par exemple, si les métadonnées du contenu se trouvent dans un fichier manifeste distinct, le gestionnaire de préchargement peut récupérer et analyser ce fichier manifeste.
  • null : le gestionnaire de préchargement ne doit charger aucun contenu ni aucune métadonnée pour cet élément multimédia.

Vous devez définir une stratégie pour déterminer la quantité de contenu à charger pour chaque élément multimédia. Dans cet exemple, davantage de contenu est chargé pour les éléments qui sont les plus proches de l'élément en cours de lecture. Si l'utilisateur lit du contenu avec l'index n, le contrôleur renvoie les codes suivants :

  • Index n+1 (l'élément multimédia suivant) : chargement en 3 000 ms (3 secondes) à partir de la position de départ par défaut
  • Index n-1 (l'élément multimédia précédent) : chargement en 1000 ms (1 seconde) à partir de la position de départ par défaut
  • Autres éléments multimédias de la plage n-2 à n+2 : renvoie PreloadStatus.TRACKS_SELECTED.
  • Autres éléments multimédias de la plage n-4 à n+4 : renvoie PreloadStatus.SOURCE_PREPARED.
  • Pour tous les autres éléments multimédias, renvoie null.

class MyTargetPreloadStatusControl(var currentPlayingIndex: Int = 0) :
  TargetPreloadStatusControl<Int, DefaultPreloadManager.PreloadStatus> {

  override fun getTargetPreloadStatus(index: Int): DefaultPreloadManager.PreloadStatus {
    if (index - currentPlayingIndex == 1) { // next track
      // return a PreloadStatus that is labelled by STAGE_SPECIFIED_RANGE_LOADED and
      // suggest loading 3000ms from the default start position
      return DefaultPreloadManager.PreloadStatus.specifiedRangeLoaded(3000L)
    } else if (index - currentPlayingIndex == -1) { // previous track
      // return a PreloadStatus that is labelled by STAGE_SPECIFIED_RANGE_LOADED and
      // suggest loading 3000ms from the default start position
      return DefaultPreloadManager.PreloadStatus.specifiedRangeLoaded(3000L)
    } else if (abs(index - currentPlayingIndex) == 2) {
      // return a PreloadStatus that is labelled by STAGE_TRACKS_SELECTED
      return DefaultPreloadManager.PreloadStatus.PRELOAD_STATUS_TRACKS_SELECTED
    } else if (abs(index - currentPlayingIndex) <= 4) {
      // return a PreloadStatus that is labelled by STAGE_SOURCE_PREPARED
      return DefaultPreloadManager.PreloadStatus.PRELOAD_STATUS_SOURCE_PREPARED
    }
    return DefaultPreloadManager.PreloadStatus.PRELOAD_STATUS_NOT_PRELOADED
  }
}

Points clés concernant le code

  • Vous allez transmettre une instance de MyTargetPreloadStatusControl au compilateur du gestionnaire de préchargement lorsque vous le créerez.
  • currentPlayingIndex contient l'index de l'élément multimédia en cours de lecture. C'est à l'application de maintenir cette valeur à jour.
  • Lorsque le gestionnaire de préchargement est prêt à charger du contenu, il appelle getTargetPreloadStatus et transmet les informations de classement que vous avez spécifiées pour l'élément multimédia correspondant. Dans le cas de DefaultPreloadManager, ces informations de classement correspondent à un entier qui spécifie la position de l'élément dans un carrousel. La méthode choisit le code à renvoyer en comparant cet index à celui de l'élément actuellement sélectionné.

Créer le gestionnaire de préchargement

Pour créer votre gestionnaire de préchargement, vous avez besoin d'un DefaultPreloadManager.Builder. Ce compilateur est configuré avec le contexte actuel et le contrôle de l'état de préchargement cible de l'application. Vous pouvez créer un gestionnaire de préchargement avec toutes les configurations par défaut.

val targetPreloadStatusControl = MyTargetPreloadStatusControl()
val preloadManagerBuilder = DefaultPreloadManager.Builder(context, targetPreloadStatusControl)
val preloadManager = preloadManagerBuilder.build()

Le compilateur fournit également des méthodes de setter que vous pouvez utiliser pour définir les composants personnalisés du gestionnaire de préchargement.

Par exemple, vous pouvez personnaliser le nombre total d'octets de tampon cible pour toutes les sources multimédias de préchargement dans DefaultPreloadManager, afin que les données préchargées ne dépassent pas cette limite. Vous pouvez configurer cette limite à l'aide de setPlayerTargetBufferBytes(String, int) sur un DefaultLoadControl.Builder personnalisé avec le nom du lecteur "preload" et transmettre cette instance au compilateur du gestionnaire de préchargement :

val targetPreloadStatusControl = MyTargetPreloadStatusControl()
val preloadManagerBuilder = DefaultPreloadManager.Builder(context, targetPreloadStatusControl)

preloadManagerBuilder.setLoadControl(
  DefaultLoadControl.Builder()
    .setPlayerTargetBufferBytes("preload", 128 * 1024 * 1024) // 128 MiB
    .build()
)
val preloadManager = preloadManagerBuilder.build()

Bien que les méthodes setter du compilateur soient facultatives pour la personnalisation, si vous souhaitez mettre en cache des éléments multimédias sur le disque, vous devez configurer le compilateur avec un Cache en appelant setCache(). Si aucun cache n'est configuré, la tentative de mise en cache des éléments multimédias entraînera une erreur IllegalStateException.

Créer l'instance d'ExoPlayer pour lire l'élément multimédia préchargé

En plus d'utiliser le compilateur pour créer le gestionnaire de préchargement, vous l'utiliserez également pour créer les objets ExoPlayer que votre application utilise pour lire le contenu, afin que ExoPlayer partage correctement les composants avec le gestionnaire de préchargement. Vous pouvez toujours définir les configurations spécifiques à la lecture pour ExoPlayer en transmettant une instance ExoPlayer.Builder avec ces configurations définies.

// Direct creation
val exoPlayer = preloadManagerBuilder.buildExoPlayer()

// Creation with custom playback specific configurations
val skipSilenceExoPlayerBuilder = ExoPlayer.Builder(context).setSkipSilenceEnabled(true)
val skipSilenceExoPlayer = preloadManagerBuilder.buildExoPlayer(skipSilenceExoPlayerBuilder)