Ajouter des commandes de lecture à votre application

Une application qui lit un contenu multimédia nécessite des composants d'interface utilisateur pour afficher les contenus multimédias et contrôler la lecture. La bibliothèque Media3 comprend un module d'interface utilisateur qui contient un certain nombre de composants d'interface utilisateur. Pour dépendre du module d'UI, ajoutez les éléments suivants : la dépendance:

Kotlin

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

Groovy

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

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

PlayerView dispose d'une méthode setPlayer pour associer et dissocier (par (null) instances de joueur.

PlayerView

PlayerView peut être utilisé pour les lectures de vidéos, d'images et audio. Il affiche la vidéo et les sous-titres en cas de lecture de la vidéo, les bitmaps pour la lecture des images ; et peut afficher des illustrations incluses en tant que métadonnées dans des fichiers audio. Vous pouvez l'inclure dans vos fichiers de mise en page, comme tout 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 . Ces attributs peuvent être utilisés pour personnaliser le comportement de la vue, ainsi que son apparence. La plupart de ces attributs ont un setter correspondant qui permettent de personnaliser la vue au moment de l'exécution. La Javadoc PlayerView répertorie ces attributs et méthodes setter dans 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ée 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). video_decoder_gl_surface_view (pour le rendu vidéo à l'aide de l'extension les valeurs autorisées sont surface_view, texture_view et none. Si la vue est destinée à la lecture audio uniquement, utilisez none pour éviter d'avoir à créer une surface, car cela peut s'avérer coûteux.

Si la vue correspond à une lecture vidéo standard, surface_view ou texture_view doit être utilisée. SurfaceView présente un certain nombre d'avantages par rapport à TextureView pour Lecture de la vidéo:

• Beaucoup faiblement moins de puissance leur consommation 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 résolution maximale 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. Un C'est par exemple le cas lorsqu'il est nécessaire de faire défiler des animations fluides ou de faire défiler la surface de la vidéo. antérieures à Android 7.0 (niveau d'API 24), comme décrit dans les notes suivantes. Pour dans ce cas, il est préférable d'utiliser TextureView uniquement lorsque SDK_INT est inférieur que 24 (Android 7.0) et SurfaceView dans les autres cas.

Remarque :Le rendu SurfaceView n'a pas été correctement synchronisé avec les animations des vues jusqu'à Android 7.0 (niveau d'API 24). Sur les versions antérieures, cela peut avoir des effets indésirables lorsqu'un SurfaceView a été placé dans le conteneur défilant ou lorsqu'il a été soumis à de l'animation. Par exemple, le contenu de la vue semble légèrement décalé derrière l'endroit où elle doit être affichée, et la vue devient noire lorsque l'objet est soumis à l'animation. Pour obtenir une animation ou un défilement fluide de la vidéo sous 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'une TextureView est lié à l'association de fenêtres et détachement. Par conséquent, dans les interfaces utilisateur défilantes qui utilisent SurfaceView, la lecture peut prendre plus de temps, car la surface de sortie devient légèrement disponible plus tard. À partir d'Android 14, PlayerView utilise De SurfaceView.setSurfaceLifecycle(SURFACE_LIFECYCLE_FOLLOWS_ATTACHMENT) à pour éviter ce comportement. Si votre application utilise directement SurfaceView (sans PlayerView), vous pouvez alors activer ce mode. Avant Android 14, de contourner la surface détruite en traduisant les vues hors de l'écran lors du recyclage.

Remarque :Certains appareils Android TV exécutent leur couche d'interface utilisateur avec une résolution inférieure à celle en haute résolution, en l'agrandissant pour qu'il soit présenté à l'utilisateur. Pour Par exemple, la couche d'interface utilisateur peut s'exécuter en 1080p sur un téléviseur Android TV l'écran. Sur ces appareils, SurfaceView doit être utilisé pour afficher le contenu au niveau la pleine résolution de l'écran. La résolution maximale de l'écran (dans sa mode d'affichage actuel) peut être interrogé à 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 arrivera en tant qu'événement clé à dispatchKeyEvent(KeyEvent) de votre Activity. Ces doivent être déléguées à 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 naviguer dans la lecture et ignorer les annonces. Pensez à demander la mise au point dans onCreate des 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 définir AndroidView sélectionnable et déléguez l'événement en transmettant le paramètre de modificateur au 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 continuera de fonctionner dans les futures versions de la bibliothèque. Les ID de ressource changer de nom, ou certaines d'entre elles risquent d'être entièrement supprimées. Ceci est indiqué par ID de ressources marqués comme "privés".

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

Personnalisation plus poussée

Si une personnalisation supérieure à celle décrite ci-dessus est nécessaire, nous nous attendons à ce que l'application les développeurs implémenteront leurs propres composants d'interface utilisateur plutôt que d'utiliser ceux fournis par le module d'UI de Media3.