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.

Pour créer une instance de DefaultPreloadManager, vous devez suivre 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 générateur pour créer le gestionnaire de préchargement en appelant la méthode build() du générateur.

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

Lorsque vous créez DefaultPreloadManager.Builder, vous lui transmettez un objet 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 s'apprête à précharger un contenu multimédia, 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 à être lues instantanément, 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 de l'é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ébut 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ébut 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, et 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
  }
}
PreloadManagerCreate.kt

Points clés concernant le code

• Vous transmettez une instance de MyTargetPreloadStatusControl au générateur du gestionnaire de préchargement lorsque vous le créez.
• 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 générateur 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()
PreloadManagerCreate.kt

Le générateur fournit également des méthodes 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 du 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 générateur 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()
PreloadManagerCreate.kt

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

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

En plus d'utiliser le générateur 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)
PreloadManagerCreate.kt