Personnalisation

L'interface Player est au cœur de la bibliothèque ExoPlayer. Un Player expose les fonctionnalités traditionnelles d'un lecteur multimédia de haut niveau, telles que la mise en mémoire tampon des contenus multimédias, la lecture, la mise en pause et la recherche. L'implémentation par défaut ExoPlayer est conçue pour faire peu d'hypothèses sur le type de contenu multimédia lu (et donc imposer peu de restrictions), sur la façon et l'emplacement de son stockage, et sur la façon dont il est affiché. Plutôt que d'implémenter directement le chargement et l'affichage des contenus multimédias, les implémentations ExoPlayer délèguent ce travail aux composants injectés lors de la création d'un lecteur ou lorsque de nouvelles sources multimédias lui sont transmises. Les composants communs à toutes les implémentations de ExoPlayer sont les suivants:

• Instances MediaSource qui définissent les contenus multimédias à lire et à partir desquels ils chargent, et à partir desquels ils peuvent être lus. Une instance MediaSource est créée à partir d'un MediaItem par un MediaSource.Factory dans le lecteur. Elles peuvent également être transmises directement au lecteur à l'aide de l'API de playlist basée sur les sources multimédias.
• Instances MediaSource.Factory qui convertit un MediaItem en MediaSource. MediaSource.Factory est injecté lors de la création du lecteur.
• Instances Renderer qui affichent des composants individuels du contenu multimédia. Ils sont injectés lors de la création du lecteur.
• TrackSelector qui sélectionne les pistes fournies par le MediaSource à consommer par chaque Renderer disponible. Un TrackSelector est injecté lors de la création du lecteur.
• LoadControl qui contrôle quand MediaSource met en mémoire tampon plus de contenus multimédias et la quantité de contenus multimédias mis en mémoire tampon. Un LoadControl est injecté lors de la création du lecteur.
• Un LivePlaybackSpeedControl qui contrôle la vitesse de lecture lors des lectures en direct pour permettre au lecteur de rester proche d'un décalage en direct configuré. Un LivePlaybackSpeedControl est injecté lors de la création du lecteur.

Le concept d'injection de composants implémentant des éléments de fonctionnalité du lecteur est présent dans toute la bibliothèque. Les implémentations par défaut de certains composants délèguent le travail à d'autres composants injectés. Cela permet de remplacer individuellement de nombreux sous-composants par des implémentations configurées de manière personnalisée.

Personnalisation des joueurs

Vous trouverez ci-dessous quelques exemples courants de personnalisation du lecteur en injectant des composants.

Configurer la pile réseau

Consultez notre page sur la personnalisation de la pile réseau utilisée par ExoPlayer.

Mise en cache des données chargées à partir du réseau

Consultez les guides sur le mise en cache temporaire instantanée et le téléchargement de fichiers multimédias.

Personnaliser les interactions avec le serveur

Certaines applications peuvent vouloir intercepter les requêtes et les réponses HTTP. Vous pouvez injecter des en-têtes de requête personnalisés, lire les en-têtes de réponse du serveur, modifier les URI des requêtes, etc. Par exemple, votre application peut s'authentifier en injectant un jeton en tant qu'en-tête lors de la requête des segments multimédias.

L'exemple suivant montre comment implémenter ces comportements en injectant un DataSource.Factory personnalisé dans DefaultMediaSourceFactory:

val dataSourceFactory =
  DataSource.Factory {
    val dataSource = httpDataSourceFactory.createDataSource()
    // Set a custom authentication request header.
    dataSource.setRequestProperty("Header", "Value")
    dataSource
  }
val player =
  ExoPlayer.Builder(context)
    .setMediaSourceFactory(
      DefaultMediaSourceFactory(context).setDataSourceFactory(dataSourceFactory)
    )
    .build()

DataSource.Factory dataSourceFactory =
    () -> {
      HttpDataSource dataSource = httpDataSourceFactory.createDataSource();
      // Set a custom authentication request header.
      dataSource.setRequestProperty("Header", "Value");
      return dataSource;
    };

ExoPlayer player =
    new ExoPlayer.Builder(context)
        .setMediaSourceFactory(
            new DefaultMediaSourceFactory(context).setDataSourceFactory(dataSourceFactory))
        .build();

Dans l'extrait de code ci-dessus, l'HttpDataSource injecté inclut l'en-tête "Header: Value" dans chaque requête HTTP. Ce comportement est corrigé pour chaque interaction avec une source HTTP.

Pour une approche plus précise, vous pouvez injecter un comportement juste-à-temps à l'aide d'un ResolvingDataSource. L'extrait de code suivant montre comment injecter des en-têtes de requête juste avant d'interagir avec une source HTTP:

val dataSourceFactory: DataSource.Factory =
  ResolvingDataSource.Factory(httpDataSourceFactory) { dataSpec: DataSpec ->
    // Provide just-in-time request headers.
    dataSpec.withRequestHeaders(getCustomHeaders(dataSpec.uri))
  }

    DataSource.Factory dataSourceFactory =
        new ResolvingDataSource.Factory(
            httpDataSourceFactory,
            // Provide just-in-time request headers.
            dataSpec -> dataSpec.withRequestHeaders(getCustomHeaders(dataSpec.uri)));

Vous pouvez également utiliser un ResolvingDataSource pour effectuer des modifications juste-à-temps de l'URI, comme illustré dans l'extrait de code suivant:

val dataSourceFactory: DataSource.Factory =
  ResolvingDataSource.Factory(httpDataSourceFactory) { dataSpec: DataSpec ->
    // Provide just-in-time URI resolution logic.
    dataSpec.withUri(resolveUri(dataSpec.uri))
  }

DataSource.Factory dataSourceFactory =
    new ResolvingDataSource.Factory(
        httpDataSourceFactory,
        // Provide just-in-time URI resolution logic.
        dataSpec -> dataSpec.withUri(resolveUri(dataSpec.uri)));

Personnaliser la gestion des erreurs

L'implémentation d'un LoadErrorHandlingPolicy personnalisé permet aux applications de personnaliser la façon dont ExoPlayer réagit aux erreurs de chargement. Par exemple, une application peut vouloir échouer rapidement au lieu de réessayer plusieurs fois, ou peut vouloir personnaliser la logique de délai avant réessai qui contrôle la durée d'attente du joueur entre chaque tentative. L'extrait de code suivant montre comment implémenter une logique de délai avant expiration personnalisée:

val loadErrorHandlingPolicy: LoadErrorHandlingPolicy =
  object : DefaultLoadErrorHandlingPolicy() {
    override fun getRetryDelayMsFor(loadErrorInfo: LoadErrorInfo): Long {
      // Implement custom back-off logic here.
      return 0
    }
  }
val player =
  ExoPlayer.Builder(context)
    .setMediaSourceFactory(
      DefaultMediaSourceFactory(context).setLoadErrorHandlingPolicy(loadErrorHandlingPolicy)
    )
    .build()

LoadErrorHandlingPolicy loadErrorHandlingPolicy =
    new DefaultLoadErrorHandlingPolicy() {
      @Override
      public long getRetryDelayMsFor(LoadErrorInfo loadErrorInfo) {
        // Implement custom back-off logic here.
        return 0;
      }
    };

ExoPlayer player =
    new ExoPlayer.Builder(context)
        .setMediaSourceFactory(
            new DefaultMediaSourceFactory(context)
                .setLoadErrorHandlingPolicy(loadErrorHandlingPolicy))
        .build();

L'argument LoadErrorInfo contient plus d'informations sur le chargement ayant échoué afin de personnaliser la logique en fonction du type d'erreur ou de la requête ayant échoué.

Personnaliser les options d'extracteur

Les indicateurs d'extracteur peuvent être utilisés pour personnaliser la façon dont les formats individuels sont extraits des médias progressifs. Elles peuvent être définies sur le DefaultExtractorsFactory fourni à DefaultMediaSourceFactory. L'exemple suivant transmet un indicateur qui active la recherche basée sur l'index pour les flux MP3.

val extractorsFactory =
  DefaultExtractorsFactory().setMp3ExtractorFlags(Mp3Extractor.FLAG_ENABLE_INDEX_SEEKING)
val player =
  ExoPlayer.Builder(context)
    .setMediaSourceFactory(DefaultMediaSourceFactory(context, extractorsFactory))
    .build()

DefaultExtractorsFactory extractorsFactory =
    new DefaultExtractorsFactory().setMp3ExtractorFlags(Mp3Extractor.FLAG_ENABLE_INDEX_SEEKING);

ExoPlayer player =
    new ExoPlayer.Builder(context)
        .setMediaSourceFactory(new DefaultMediaSourceFactory(context, extractorsFactory))
        .build();

Activer la recherche de débit constante

Pour les flux MP3, ADTS et AMR, vous pouvez activer la recherche approximative en utilisant une hypothèse de débit constant avec les options FLAG_ENABLE_CONSTANT_BITRATE_SEEKING. Ces indicateurs peuvent être définis pour des extracteurs individuels à l'aide des méthodes DefaultExtractorsFactory.setXyzExtractorFlags individuelles, comme décrit ci-dessus. Pour activer la recherche de débit constant pour tous les extracteurs compatibles, utilisez DefaultExtractorsFactory.setConstantBitrateSeekingEnabled.

val extractorsFactory = DefaultExtractorsFactory().setConstantBitrateSeekingEnabled(true)

DefaultExtractorsFactory extractorsFactory =
    new DefaultExtractorsFactory().setConstantBitrateSeekingEnabled(true);

Le ExtractorsFactory peut ensuite être injecté via DefaultMediaSourceFactory, comme décrit ci-dessus pour personnaliser les indicateurs d'extraction.

Activer la mise en file d'attente de tampons asynchrones

La mise en file d'attente de tampon asynchrone est une amélioration du pipeline de rendu d'ExoPlayer, qui gère les instances MediaCodec en mode asynchrone et utilise des threads supplémentaires pour planifier le décodage et le rendu des données. L'activer peut réduire les pertes de frames et les sous-utilisations audio.

La mise en file d'attente de la mémoire tampon asynchrone est activée par défaut sur les appareils équipés d'Android 12 (niveau d'API 31) ou version ultérieure. Elle peut être activée manuellement à partir d'Android 6.0 (niveau d'API 23). Envisagez d'activer cette fonctionnalité pour des appareils spécifiques sur lesquels vous observez des images perdues ou des sous-temps audio, en particulier lorsque vous lisez du contenu protégé par DRM ou à fréquence d'images élevée.

Dans le cas le plus simple, vous devez injecter un DefaultRenderersFactory au lecteur comme suit:

val renderersFactory = 
  DefaultRenderersFactory(context).forceEnableMediaCodecAsynchronousQueueing()
val exoPlayer = ExoPlayer.Builder(context, renderersFactory).build()

DefaultRenderersFactory renderersFactory =
    new DefaultRenderersFactory(context).forceEnableMediaCodecAsynchronousQueueing();
ExoPlayer exoPlayer = new ExoPlayer.Builder(context, renderersFactory).build();

Si vous instanciez directement des moteurs de rendu, transmettez un AsynchronousMediaCodecAdapter.Factory aux constructeurs MediaCodecVideoRenderer et MediaCodecAudioRenderer.

Interception des appels de méthode avec ForwardingPlayer

Vous pouvez personnaliser certains aspects du comportement d'une instance Player en l'encapsulant dans une sous-classe de ForwardingPlayer et en remplaçant des méthodes pour effectuer l'une des opérations suivantes:

• Accédez aux paramètres avant de les transmettre au délégué Player.
• Accédez à la valeur renvoyée par le délégué Player avant de la renvoyer.
• Réimplémentez complètement la méthode.

Lorsque vous remplacez des méthodes ForwardingPlayer, il est important de vous assurer que l'implémentation reste cohérente et conforme à l'interface Player, en particulier lorsque vous traitez des méthodes destinées à avoir un comportement identique ou associé. Exemple :

• Si vous souhaitez ignorer chaque opération de lecture, vous devez remplacer ForwardingPlayer.play et ForwardingPlayer.setPlayWhenReady, car l'appelant s'attendra à ce que le comportement de ces méthodes soit identique lorsque playWhenReady = true.
• Si vous souhaitez modifier l'incrément de recherche avant, vous devez remplacer à la fois ForwardingPlayer.seekForward pour effectuer une recherche avec votre incrément personnalisé et ForwardingPlayer.getSeekForwardIncrement afin de renvoyer l'incrément personnalisé correct à l'appelant.
• Si vous souhaitez contrôler les Player.Commands annoncés par une instance de lecteur, vous devez remplacer à la fois Player.getAvailableCommands() et Player.isCommandAvailable(), et également écouter le rappel Player.Listener.onAvailableCommandsChanged() pour être informé des modifications provenant du lecteur sous-jacent.

Personnalisation de MediaSource

Les exemples ci-dessus injectent des composants personnalisés à utiliser lors de la lecture de tous les objets MediaItem transmis au lecteur. Lorsque vous avez besoin d'une personnalisation précise, vous pouvez également injecter des composants personnalisés dans des instances MediaSource individuelles, qui peuvent être transmises directement au lecteur. L'exemple ci-dessous montre comment personnaliser un ProgressiveMediaSource pour utiliser des DataSource.Factory, ExtractorsFactory et LoadErrorHandlingPolicy personnalisés:

val mediaSource =
  ProgressiveMediaSource.Factory(customDataSourceFactory, customExtractorsFactory)
    .setLoadErrorHandlingPolicy(customLoadErrorHandlingPolicy)
    .createMediaSource(MediaItem.fromUri(streamUri))

ProgressiveMediaSource mediaSource =
    new ProgressiveMediaSource.Factory(customDataSourceFactory, customExtractorsFactory)
        .setLoadErrorHandlingPolicy(customLoadErrorHandlingPolicy)
        .createMediaSource(MediaItem.fromUri(streamUri));

Créer des composants personnalisés

La bibliothèque fournit des implémentations par défaut des composants répertoriés en haut de cette page pour les cas d'utilisation courants. Un ExoPlayer peut utiliser ces composants, mais peut également être conçu pour utiliser des implémentations personnalisées si des comportements non standards sont requis. Voici quelques cas d'utilisation d'implémentations personnalisées:

• Renderer : vous pouvez implémenter un Renderer personnalisé pour gérer un type de support non compatible avec les implémentations par défaut fournies par la bibliothèque.
• TrackSelector : l'implémentation d'un TrackSelector personnalisé permet au développeur d'application de modifier la manière dont les pistes exposées par un MediaSource sont sélectionnées pour être consommées par chacun des Renderer disponibles.
• LoadControl : l'implémentation d'un LoadControl personnalisé permet à un développeur d'application de modifier la stratégie de mise en mémoire tampon du lecteur.
• Extractor : si vous devez prendre en charge un format de conteneur actuellement non pris en charge par la bibliothèque, envisagez d'implémenter une classe Extractor personnalisée.
• MediaSource : l'implémentation d'une classe MediaSource personnalisée peut être appropriée si vous souhaitez obtenir des échantillons multimédias à transmettre aux moteurs de rendu de manière personnalisée ou si vous souhaitez implémenter un comportement de composition MediaSource personnalisé.
• MediaSource.Factory : l'implémentation d'un MediaSource.Factory personnalisé permet à une application de personnaliser la manière dont un MediaSource est créé à partir d'un MediaItem.
• DataSource : le package en amont d'ExoPlayer contient déjà un certain nombre d'implémentations DataSource pour différents cas d'utilisation. Vous pouvez implémenter votre propre classe DataSource pour charger des données d'une autre manière, par exemple via un protocole personnalisé, à l'aide d'une pile HTTP personnalisée ou à partir d'un cache persistant personnalisé.

Voici quelques recommandations pour créer des composants personnalisés:

• Si un composant personnalisé doit signaler des événements à l'application, nous vous recommandons de le faire à l'aide du même modèle que les composants ExoPlayer existants, par exemple en utilisant des classes EventDispatcher ou en transmettant un Handler avec un écouteur au constructeur du composant.
• Nous vous recommandons d'utiliser le même modèle pour les composants personnalisés que pour les composants ExoPlayer existants afin de permettre à l'application de les reconfigurer pendant la lecture. Pour ce faire, les composants personnalisés doivent implémenter PlayerMessage.Target et recevoir les modifications de configuration dans la méthode handleMessage. Le code d'application doit transmettre les modifications de configuration en appelant la méthode createMessage d'ExoPlayer, en configurant le message et en l'envoyant au composant à l'aide de PlayerMessage.send. L'envoi de messages à transmettre sur le thread de lecture garantit qu'ils sont exécutés dans l'ordre avec toutes les autres opérations effectuées sur le lecteur.