Premiers pas

Pour les cas d'utilisation simples, la prise en main de ExoPlayer consiste à suivre les étapes suivantes :

1. Ajouter ExoPlayer en tant que dépendance à votre projet.
2. Créez une instance ExoPlayer.
3. Associez le lecteur à une vue (pour la sortie vidéo et l'entrée utilisateur).
4. Préparez le lecteur avec un MediaItem à lire.
5. Libérez le lecteur une fois l'opération terminée.

Ces fichiers sont décrits plus en détail ci-dessous. Pour obtenir un exemple complet, consultez PlayerActivity dans l'application de démonstration principale.

Ajouter ExoPlayer en tant que dépendance

Ajouter des modules ExoPlayer

Le moyen le plus simple de commencer à utiliser AndroidX Media3 consiste à ajouter des dépendances Gradle aux bibliothèques dont vous avez besoin dans le fichier build.gradle de votre module d'application.

Par exemple, pour dépendre d'ExoPlayer avec la compatibilité avec la lecture DASH et les composants d'UI, vous pouvez ajouter des dépendances aux modules comme suit :

implementation("androidx.media3:media3-exoplayer:1.11.1")
implementation("androidx.media3:media3-exoplayer-dash:1.11.1")
implementation("androidx.media3:media3-ui:1.11.1")
implementation("androidx.media3:media3-ui-compose-material3:1.11.1")

implementation "androidx.media3:media3-exoplayer:1.11.1"
implementation "androidx.media3:media3-exoplayer-dash:1.11.1"
implementation "androidx.media3:media3-ui:1.11.1"
implementation("androidx.media3:media3-ui-compose-material3:1.11.1")

où 1.11.1 est votre version préférée (la dernière version est disponible dans les notes de version). Tous les modules doivent être de la même version.

AndroidX Media3 comporte des modules de bibliothèque qui dépendent de bibliothèques externes pour fournir des fonctionnalités supplémentaires. Certains sont disponibles dans le dépôt Maven, tandis que d'autres doivent être créés manuellement. Parcourez le répertoire des bibliothèques et consultez les fichiers README individuels pour en savoir plus.

Pour en savoir plus sur les modules de bibliothèque disponibles, consultez la page Google Maven AndroidX Media.

Activer la compatibilité avec Java 8

Si ce n'est pas déjà fait, vous devez activer au moins la compatibilité avec Java 8 dans tous les fichiers build.gradle qui dépendent d'ExoPlayer en ajoutant ce qui suit à la section android :

compileOptions {
  targetCompatibility JavaVersion.VERSION_1_8
}

Créer le lecteur

Vous pouvez créer une instance ExoPlayer à l'aide de ExoPlayer.Builder, qui propose différentes options de personnalisation. Le code suivant est l'exemple le plus simple de création d'une instance.

val player = ExoPlayer.Builder(context).build()
HelloWorld.kt

ExoPlayer player = new ExoPlayer.Builder(context).build();
HelloWorld.java

Remarque sur les threads

Les instances ExoPlayer doivent être accessibles à partir d'un seul thread d'application. Dans la grande majorité des cas, il doit s'agir du thread principal de l'application. L'utilisation du thread principal de l'application est obligatoire lorsque vous utilisez les composants d'UI d'ExoPlayer ou l'extension IMA.

Le thread sur lequel une instance ExoPlayer doit être accessible peut être explicitement spécifié en transmettant un Looper lors de la création du lecteur. Si aucun Looper n'est spécifié, le Looper du thread sur lequel le lecteur est créé est utilisé. Si ce thread n'a pas de Looper, le Looper du thread principal de l'application est utilisé. Dans tous les cas, le Looper du thread à partir duquel le lecteur doit être accessible peut être interrogé à l'aide de Player.getApplicationLooper.

Pour en savoir plus sur le modèle de threading d'ExoPlayer, consultez la section "Threading model" (Modèle de threading) de la documentation Javadoc d'ExoPlayer.

Associer le lecteur à une vue

La bibliothèque media3-ui fournit une gamme de composants d'interface utilisateur prédéfinis pour la lecture de contenus multimédias. Il s'agit notamment de PlayerView, qui encapsule un PlayerControlView, un SubtitleView et un Surface sur lequel la vidéo est affichée. Un PlayerView peut être inclus dans le fichier XML de mise en page de votre application. Par exemple, pour lier le lecteur à la vue :

// Bind the player to the view.
playerView.player = player
HelloWorld.kt

// Bind the player to the view.
playerView.setPlayer(player);
HelloWorld.java

L'utilisation des composants d'interface utilisateur prédéfinis de Media3 est facultative. Pour les applications vidéo qui implémentent leur propre UI, les cibles SurfaceView, TextureView, SurfaceHolder ou Surface peuvent être définies à l'aide des méthodes setVideoSurfaceView, setVideoTextureView, setVideoSurfaceHolder et setVideoSurface du lecteur, respectivement. Le rappel Listener.onCues peut être utilisé pour recevoir les sous-titres à afficher pendant la lecture, et setImageOutput peut être utilisé pour recevoir les images décodées.

Pour une expérience utilisateur plus confortable, envisagez d'ajouter l'attribut keepScreenOn. Vous pouvez examiner d'autres actions qui maintiennent l'appareil activé sur les pages de tâches en arrière-plan.

android:keepScreenOn="true"

Si votre application utilise Jetpack Compose pour son UI, vous pouvez utiliser le composable Player de la bibliothèque media3-ui-compose-material3. Player affiche la vidéo et inclut des valeurs préremplies pour les emplacements des commandes de lecture. Pour associer un objet androidx.media3.common.Player à un composable androidx.media3.ui.compose.material3.Player, transmettez-le simplement en tant qu'argument :

// Bind the player to the composable.
Player(player = player)
HelloWorld.kt

Pour en savoir plus sur l'utilisation des composants d'interface utilisateur Media3 et leur personnalisation, consultez la page UI.

Remplissage de la playlist et préparation du lecteur

Dans ExoPlayer, chaque contenu multimédia est représenté par un MediaItem. Pour lire un contenu multimédia, vous devez créer un MediaItem correspondant, l'ajouter au lecteur, préparer le lecteur et appeler play pour lancer la lecture :

// Build the media item.
val mediaItem = MediaItem.fromUri(videoUri)
// Set the media item to be played.
player.setMediaItem(mediaItem)
// Prepare the player.
player.prepare()
// Start the playback.
player.play()
HelloWorld.kt

// Build the media item.
MediaItem mediaItem = MediaItem.fromUri(videoUri);
// Set the media item to be played.
player.setMediaItem(mediaItem);
// Prepare the player.
player.prepare();
// Start the playback.
player.play();
HelloWorld.java

ExoPlayer est directement compatible avec les playlists. Il est donc possible de préparer le lecteur avec plusieurs éléments multimédias à lire les uns après les autres :

// Build the media items.
val firstItem = MediaItem.fromUri(firstVideoUri)
val secondItem = MediaItem.fromUri(secondVideoUri)
// Add the media items to be played.
player.addMediaItem(firstItem)
player.addMediaItem(secondItem)
// Prepare the player.
player.prepare()
// Start the playback.
player.play()
HelloWorld.kt

// Build the media items.
MediaItem firstItem = MediaItem.fromUri(firstVideoUri);
MediaItem secondItem = MediaItem.fromUri(secondVideoUri);
// Add the media items to be played.
player.addMediaItem(firstItem);
player.addMediaItem(secondItem);
// Prepare the player.
player.prepare();
// Start the playback.
player.play();
HelloWorld.java

La playlist peut être mise à jour pendant la lecture sans qu'il soit nécessaire de préparer à nouveau le lecteur. Pour en savoir plus sur le remplissage et la manipulation de la playlist, consultez la page Playlists. Pour en savoir plus sur les différentes options disponibles lors de la création d'éléments multimédias, comme le découpage et l'ajout de fichiers de sous-titres, consultez la page Éléments multimédias.

Contrôler le lecteur

Une fois le lecteur préparé, la lecture peut être contrôlée en appelant des méthodes sur le lecteur. Voici quelques-unes des méthodes les plus couramment utilisées :

• play et pause lancent et mettent en pause la lecture.
• seekTo permet de rechercher dans le contenu multimédia.
• hasPrevious, hasNext, previous et next permettent de parcourir la playlist.
• setRepeatMode détermine si le contenu multimédia est lu en boucle et comment.
• setShuffleModeEnabled contrôle la lecture aléatoire de la playlist.
• setPlaybackParameters ajuste la vitesse de lecture et la hauteur du son.

Si le lecteur est lié à un PlayerView ou à un PlayerControlView, l'interaction de l'utilisateur avec ces composants entraîne l'appel des méthodes correspondantes sur le lecteur.

Libérer le lecteur

Il est important de libérer le lecteur lorsqu'il n'est plus nécessaire, afin de libérer des ressources limitées telles que les décodeurs vidéo pour d'autres applications. Pour ce faire, appelez ExoPlayer.release.