Interface de lecteur

Un lecteur est le composant de votre application qui facilite la lecture des éléments multimédias. L'interface Player de Media3 présente les fonctionnalités généralement gérées par un lecteur. Par exemple:

  • Modifier les commandes de lecture, comme la lecture, la mise en pause et la recherche
  • Propriétés d'interrogation du contenu multimédia en cours de lecture, telles que la position de lecture
  • Gérer une playlist/une file d'attente d'éléments multimédias
  • Configurer les propriétés de la lecture, telles que la lecture en mode aléatoire, la répétition, la vitesse et le volume
  • Rendu de la vidéo à l'écran

Media3 propose également une implémentation de l'interface Player, appelée ExoPlayer.

Une interface commune entre les composants

Plusieurs composants de Media3 implémentent l'interface du lecteur, par exemple:

Component Remarques sur la description et le comportement
ExoPlayer Une API du lecteur multimédia et l'implémentation par défaut de l'interface Player.
MediaController Interagit avec un MediaSession pour envoyer des commandes de lecture. Si votre Player et votre MediaSession se trouvent dans un Service distinct du Activity ou du Fragment où se trouve l'interface utilisateur de votre joueur, vous pouvez définir MediaController comme lecteur pour l'UI PlayerView. Les appels de méthode de lecture et de playlist sont envoyés à votre Player via votre MediaSession.
MediaBrowser En plus de la fonctionnalité offerte par un MediaController, interagit avec un MediaLibrarySession pour parcourir le contenu multimédia disponible.
ForwardingPlayer Une implémentation de Player qui transfère les appels de méthode à un autre Player. Utilisez cette classe pour supprimer ou modifier des opérations spécifiques en remplaçant les méthodes respectives.
SimpleBasePlayer Une implémentation de Player qui réduit au minimum le nombre de méthodes à implémenter. Cette fonctionnalité est utile lorsque vous utilisez un lecteur personnalisé que vous souhaitez connecter à un MediaSession.
CastPlayer Implémentation de Player qui communique avec une application réceptrice Cast. Le comportement dépend de la session Cast sous-jacente.

Bien qu'un MediaSession n'implémente pas l'interface Player, il nécessite un Player lors de sa création. Son objectif est de fournir un accès au Player à partir d'autres processus ou threads.

Architecture de lecture de Media3

Si vous avez accès à un Player, vous devez appeler ses méthodes directement pour émettre des commandes de lecture. Vous pouvez annoncer votre lecture et accorder une commande de lecture aux sources externes en implémentant un MediaSession. Ces sources externes implémentent un MediaController, qui facilite la connexion à une session multimédia et l'émission de requêtes de commande de lecture.

Lorsque vous lisez des contenus multimédias en arrière-plan, vous devez héberger votre session multimédia et votre lecteur dans un MediaSessionService ou un MediaLibraryService qui s'exécute en tant que service de premier plan. Dans ce cas, vous pouvez séparer votre lecteur de l'activité dans votre application qui contient l'interface utilisateur pour la commande de lecture. Vous devrez peut-être utiliser un contrôleur multimédia.

Schéma illustrant la façon dont les composants de lecture Media3 s'intègrent à l'architecture d'une application multimédia
Figure 1: L'interface Player joue un rôle clé dans l'architecture de Media3.

État du lecteur

L'état d'un lecteur multimédia implémentant l'interface Player comprend principalement quatre catégories d'informations:

  1. État de la lecture
  2. Playlist d'éléments multimédias
  3. Propriétés de lecture/pause, telles que :
    • playWhenReady : indique si l'utilisateur souhaite que le contenu multimédia soit lu lorsque cela est possible ou reste en pause.
    • Motif de suppression de la lecture : indication de la raison pour laquelle la lecture est supprimée, le cas échéant, même si playWhenReady est true.
    • isPlaying : indique si le lecteur est en cours de lecture, ce qui n'est true que si l'état de la lecture est STATE_READY, playWhenReady est true et que la lecture n'est pas supprimée
  4. Position de lecture, y compris :

En outre, l'interface Player permet d'accéder aux pistes disponibles, aux métadonnées multimédias, à la vitesse de lecture, au volume et à d'autres propriétés auxiliaires de la lecture.

Écouter les modifications

Utilisez un Player.Listener pour écouter les modifications d'un Player. Consultez la documentation d'ExoPlayer sur les événements de joueur pour savoir comment créer et utiliser un écouteur.

Notez que l'interface d'écouteur n'inclut aucun rappel permettant de suivre la progression de lecture normale. Pour surveiller en permanence la progression de la lecture, par exemple pour configurer une interface utilisateur de barre de progression, vous devez interroger la position actuelle à des intervalles appropriés.

Kotlin

val handler = Handler(Looper.getMainLooper())
fun checkPlaybackPosition(delayMs: Long): Boolean =
  handler.postDelayed(
    {
      val currentPosition = player.currentPosition
      // Update UI based on currentPosition
      checkPlaybackPosition(delayMs)
    },
    delayMs)

Java

Handler handler = new Handler(Looper.getMainLooper());
boolean checkPlaybackPosition(long delayMs) {
    return handler.postDelayed(() -> {
        long currentPosition = player.getCurrentPosition();
        // Update UI based on currentPosition
        checkPlaybackPosition(delayMs);
    }, delayMs);
}

Contrôler la lecture

L'interface Player permet de manipuler l'état et de contrôler la lecture de plusieurs façons:

Implémentations personnalisées de Player

Pour créer un lecteur personnalisé, vous pouvez étendre le SimpleBasePlayer inclus dans Media3. Cette classe fournit une implémentation de base de l'interface Player afin de réduire au minimum le nombre de méthodes à implémenter.

Commencez par remplacer la méthode getState(). Cette méthode doit renseigner l'état actuel du lecteur lorsqu'elle est appelée, y compris:

  • Ensemble des commandes disponibles
  • Propriétés de lecture, par exemple si le lecteur doit lancer la lecture lorsque l'état de lecture est STATE_READY, l'index de l'élément multimédia en cours de lecture et la position de lecture dans l'élément actuel

Kotlin

class CustomPlayer : SimpleBasePlayer(looper) {
  override fun getState(): State {
    return State.Builder()
      .setAvailableCommands(...) // Set which playback commands the player can handle
      // Configure additional playback properties
      .setPlayWhenReady(true, PLAY_WHEN_READY_CHANGE_REASON_USER_REQUEST)
      .setCurrentMediaItemIndex(0)
      .setContentPositionMs(0)
      .build()
  }
}

Java

public class CustomPlayer extends SimpleBasePlayer {
  public CustomPlayer(Looper looper) {
    super(looper);
  }

  @Override
  protected State getState() {
    return new State.Builder()
      .setAvailableCommands(...) // Set which playback commands the player can handle
      // Configure additional playback properties
      .setPlayWhenReady(true, PLAY_WHEN_READY_CHANGE_REASON_USER_REQUEST)
      .setCurrentMediaItemIndex(0)
      .setContentPositionMs(0)
      .build();
  }
}

SimpleBasePlayer s'assurera que State est créé avec une combinaison valide de valeurs d'état. Il gère également les écouteurs et les informe des changements d'état. Si vous devez déclencher manuellement une mise à jour de l'état, appelez invalidateState().

Au-delà de la méthode getState(), il vous suffit d'implémenter les méthodes utilisées pour les commandes que votre lecteur déclare être disponibles. Recherchez la méthode de gestionnaire qui peut être ignorée et correspond à la fonctionnalité que vous souhaitez implémenter. Par exemple, remplacez la méthode handleSeek() pour prendre en charge des opérations telles que COMMAND_SEEK_IN_CURRENT_MEDIA_ITEM et COMMAND_SEEK_TO_NEXT_MEDIA_ITEM.