Ajouter des commandes de lecture à votre application

Une application qui lit un contenu multimédia nécessite des composants d'interface utilisateur permettant d'afficher ce type de contenu et de contrôler la lecture. La bibliothèque Media3 comprend un module d'UI contenant un certain nombre de composants d'UI. Pour dépendre du module d'UI, ajoutez la dépendance suivante:

Kotlin

implementation("androidx.media3:media3-ui:1.3.1")

Groovy

implementation "androidx.media3:media3-ui:1.3.1"

Le composant le plus important est PlayerView, une vue pour les lectures de contenus multimédias. PlayerView affiche la vidéo, les sous-titres et la pochette de l'album pendant la lecture, ainsi que les commandes de lecture.

PlayerView comporte une méthode setPlayer pour associer et dissocier (en transmettant null) les instances de joueur.

PlayerView

PlayerView peut être utilisé à la fois pour les lectures vidéo et audio. Il effectue le rendu de la vidéo et des sous-titres lors de la lecture de vidéos, et peut afficher des illustrations incluses en tant que métadonnées dans les fichiers audio. Vous pouvez l'inclure dans vos fichiers de mise en page comme n'importe quel autre composant d'interface utilisateur. Par exemple, un PlayerView peut être inclus avec le code XML suivant:

<androidx.media3.ui.PlayerView
    android:id="@+id/player_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:show_buffering="when_playing"
    app:show_shuffle_button="true"/>

L'extrait ci-dessus montre que PlayerView fournit plusieurs attributs. Ces attributs peuvent être utilisés pour personnaliser le comportement de la vue, ainsi que son apparence. La plupart de ces attributs ont des méthodes setter correspondantes, qui peuvent être utilisées pour personnaliser la vue au moment de l'exécution. Le Javadoc PlayerView répertorie ces attributs et méthodes setter plus en détail.

Une fois la vue déclarée dans le fichier de mise en page, vous pouvez la rechercher dans la méthode onCreate de l'activité:

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  // ...
  playerView = findViewById(R.id.player_view)
}

Java

@Override
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  // ...
  playerView = findViewById(R.id.player_view);
}

Lorsqu'un lecteur a été initialisé, il peut être associé à la vue en appelant setPlayer:

Kotlin

// Instantiate the player.
val player = ExoPlayer.Builder(context).build()
// Attach player to the view.
playerView.player = player
// Set the media item to be played.
player.setMediaItem(mediaItem)
// Prepare the player.
player.prepare()

Java

// Instantiate the player.
player = new ExoPlayer.Builder(context).build();
// Attach player to the view.
playerView.setPlayer(player);
// Set the media item to be played.
player.setMediaItem(mediaItem);
// Prepare the player.
player.prepare();

Choisir un type de surface

L'attribut surface_type de PlayerView vous permet de définir le type de surface utilisé pour la lecture des vidéos. Outre les valeurs spherical_gl_surface_view (qui est une valeur spéciale pour la lecture de vidéos sphériques) et video_decoder_gl_surface_view (qui est pour le rendu vidéo à l'aide de moteurs de rendu d'extension), les valeurs autorisées sont surface_view, texture_view et none. Si la vue est destinée uniquement à la lecture audio, utilisez none pour éviter d'avoir à créer une surface, car cela peut s'avérer coûteux.

Si la vue est destinée à une lecture vidéo standard, utilisez surface_view ou texture_view. SurfaceView présente un certain nombre d'avantages par rapport à TextureView pour la lecture des vidéos:

• Vous réduisez considérablement la consommation d'énergie sur de nombreux appareils.
• Des temps de rendu plus précis, pour une lecture vidéo plus fluide.
• Sortie vidéo HDR de meilleure qualité possible sur les appareils compatibles.
• Prise en charge d'une sortie sécurisée lors de la lecture de contenu protégé par DRM.
• Possibilité d'afficher le contenu vidéo en pleine résolution sur les appareils Android TV qui améliorent la couche d'interface utilisateur.

Par conséquent, SurfaceView doit être privilégié par rapport à TextureView dans la mesure du possible. N'utilisez TextureView que si SurfaceView ne répond pas à vos besoins. C'est par exemple le cas lorsque des animations ou un défilement fluides de la surface de la vidéo sont requis avant Android 7.0 (niveau d'API 24), comme décrit dans les notes suivantes. Dans ce cas, il est préférable d'utiliser TextureView uniquement lorsque SDK_INT est inférieur à 24 (Android 7.0) et SurfaceView dans le cas contraire.

Remarque :Le rendu SurfaceView n'était pas correctement synchronisé avec les animations de vues jusqu'à Android 7.0 (niveau d'API 24). Dans les versions précédentes, cela pouvait entraîner des effets indésirables lorsqu'un SurfaceView était placé dans un conteneur à défilement ou qu'il était animé. Ces effets incluaient le contenu de la vue qui semble être légèrement en retard sur l'emplacement d'affichage, et la vue devient noire lorsqu'elle est soumise à une animation. Pour obtenir une animation ou un défilement fluide de la vidéo avant Android 7.0, il est donc nécessaire d'utiliser TextureView plutôt que SurfaceView.

Remarque :Le cycle de vie de la surface d'un SurfaceView est lié à la visibilité de la vue, tandis que le cycle de vie de la surface d'un TextureView est lié à l'association et à la dissociation de fenêtres. Par conséquent, dans les interfaces utilisateur défilantes qui utilisent SurfaceView, le démarrage de la lecture peut prendre plus de temps, car la surface de sortie devient disponible un peu plus tard. À partir d'Android 14, PlayerView utilise SurfaceView.setSurfaceLifecycle(SURFACE_LIFECYCLE_FOLLOWS_ATTACHMENT) pour éviter ce comportement. Si votre application utilise directement SurfaceView (sans PlayerView), vous pouvez activer ce mode. Avant Android 14, il était possible de contourner la surface détruite en traduisant les vues hors écran lors de leur recyclage.

Remarque :Certains appareils Android TV exécutent leur couche d'interface utilisateur à une résolution inférieure à la résolution maximale de l'écran, ce qui l'augmente pour qu'elle soit présentée à l'utilisateur. Par exemple, la couche d'interface utilisateur peut être exécutée en 1080p sur un téléviseur Android TV doté d'un écran 4K. Sur ces appareils, SurfaceView doit être utilisé pour afficher le contenu en pleine résolution. La résolution maximale de l'écran (dans son mode d'affichage actuel) peut être interrogée à l'aide de Util.getCurrentDisplayModeSize. La résolution de la couche de l'interface utilisateur peut être interrogée à l'aide de l'API Display.getSize d'Android.

Navigation à l'aide du pavé directionnel sur Android TV

La télécommande d'Android TV est dotée d'un pavé directionnel qui envoie des commandes arrivant en tant qu'événement clé au niveau de dispatchKeyEvent(KeyEvent) de votre Activity. Ces éléments doivent être délégués à la vue du lecteur:

Kotlin

override fun dispatchKeyEvent(event: KeyEvent?): Boolean{
  return playerView.dispatchKeyEvent(event!!) || super.dispatchKeyEvent(event)
}

Java

@Override
public boolean dispatchKeyEvent(KeyEvent event) {
  return playerView.dispatchKeyEvent(event) || super.dispatchKeyEvent(event);
}

Il est important de sélectionner le lecteur pour parcourir les commandes de lecture et ignorer les annonces. Pensez à demander le focus dans onCreate de Activity:

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  // ...
  playerView.requestFocus()
  // ...
}

Java

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    // ...
    playerView.requestFocus();
    // ...
}

Si vous utilisez Compose sur Android TV, vous devez rendre AndroidView sélectionnable et déléguer l'événement en transmettant le paramètre de modificateur à AndroidView en conséquence:

AndroidView(
  modifier = modifier
    .focusable()
    .onKeyEvent { playerView.dispatchKeyEvent(it.nativeKeyEvent) },
  factory = { playerView }
)

Remplacer des drawables

Attention :Nous ne garantissons pas que les personnalisations décrites dans la section suivante continueront de fonctionner dans les futures versions de la bibliothèque. Les ID de ressources peuvent changer de nom, ou certains peuvent être entièrement supprimés. Cela est indiqué par les ID de ressources marqués comme "privés".

PlayerView utilise PlayerControlView pour afficher les commandes de lecture et la barre de progression. Les drawables utilisés par PlayerControlView peuvent être remplacés par des drawables portant les mêmes noms que ceux définis dans votre application. Consultez la documentation Javadoc sur PlayerControlView pour obtenir la liste des drawables de contrôle pouvant être remplacés.

Personnalisation plus poussée

Lorsque la personnalisation au-delà de ce qui est décrit ci-dessus, nous nous attendons à ce que les développeurs d'applications implémentent leurs propres composants d'interface utilisateur plutôt que d'utiliser ceux fournis par le module d'interface utilisateur de Media3.