Premiers pas

Conseil :Vous pouvez également commencer par suivre l'atelier de programmation ExoPlayer.

Pour les cas d'utilisation simples, vous devez suivre les étapes ci-dessous pour commencer à utiliser ExoPlayer:

1. Ajoutez 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 joueur avec une MediaItem pour pouvoir jouer.
5. Relâchez le lecteur lorsque vous avez terminé.

Ces étapes sont décrites 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 prenant en charge la lecture DASH et de composants d'interface utilisateur, vous pouvez ajouter des dépendances aux modules comme suit:

Kotlin

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

Groovy

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

où 1.3.1 est votre version préférée. Pour connaître la dernière version, consultez 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. Certaines sont disponibles dans le dépôt Maven, tandis que d'autres doivent être créées manuellement. Parcourez le répertoire des bibliothèques et consultez les fichiers README individuels pour plus de détails.

Pour en savoir plus sur les modules de bibliothèque disponibles, consultez la page des médias Google Maven pour AndroidX.

Activer la compatibilité avec Java 8

Si ce n'est pas déjà fait, vous devez activer la prise en charge de 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
}

Activer multidex

Si votre minSdkVersion Gradle est égal ou inférieur à 20, vous devez activer multidex afin d'éviter les erreurs de compilation.

Créer le lecteur

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

Kotlin

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

Java

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

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'interface utilisateur 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é, l'Looper du thread sur lequel le lecteur est créé est utilisé. Si ce thread ne possède pas de Looper, l'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.

Remarque :Si IllegalStateException est généré avec le message "Le lecteur est accédé sur le mauvais thread", du code de votre application accède à une instance ExoPlayer sur le mauvais thread (la trace de la pile de l'exception vous indique où).

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

Associer le lecteur à une vue

La bibliothèque ExoPlayer fournit un éventail de composants d'interface utilisateur prédéfinis pour la lecture de contenus multimédias. C'est le cas, par exemple, de PlayerView, qui encapsule un élément PlayerControlView, un élément SubtitleView et un élément Surface dans lequel la vidéo est affichée. Un élément PlayerView peut être inclus dans le fichier XML de mise en page de votre application. Par exemple, pour lier le lecteur à la vue:

Kotlin

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

Java

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

Vous pouvez également utiliser PlayerControlView en tant que composant autonome, ce qui est utile pour les cas d'utilisation audio uniquement.

L'utilisation des composants d'interface utilisateur prédéfinis d'ExoPlayer est facultative. Pour les applications vidéo qui implémentent leur propre interface utilisateur, les cibles SurfaceView, TextureView, SurfaceHolder ou Surface peuvent être définies à l'aide des méthodes setVideoSurfaceView, setVideoTextureView, setVideoSurfaceHolder et setVideoSurface d'ExoPlayer, respectivement. La méthode addTextOutput d'ExoPlayer peut être utilisée pour recevoir les sous-titres qui doivent être affichés pendant la lecture.

Insérer les éléments dans la playlist et préparer le lecteur

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

Kotlin

// 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()

Java

// 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();

ExoPlayer accepte directement les playlists. Il est donc possible de préparer le lecteur avec plusieurs éléments multimédias à lire l'un après l'autre:

Kotlin

// 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()

Java

// 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();

Vous pouvez modifier la playlist en cours de lecture sans qu'il soit nécessaire de préparer à nouveau le lecteur. Pour savoir comment remplir et modifier 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, telles que le découpage et l'ajout de fichiers de sous-titres, consultez la page Éléments multimédias.

Remarque :Media3 ExoPlayer convertit les éléments multimédias en instances MediaSource dont il a besoin en interne. Pour en savoir plus sur ce processus et sur sa personnalisation, consultez la page Sources multimédias. Vous pouvez fournir un MediaSource directement au joueur à l'aide de ExoPlayer.setMediaSource(s) et ExoPlayer.addMediaSource(s).

Contrôler le lecteur

Une fois le lecteur prêt, 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 démarrent et suspendent la lecture.
• seekTo autorise la recherche dans le contenu multimédia.
• hasPrevious, hasNext, previous et next permettent de naviguer dans la playlist.
• setRepeatMode contrôle si et comment les contenus multimédias sont lus en boucle.
• setShuffleModeEnabled contrôle la lecture aléatoire des playlists.
• setPlaybackParameters ajuste la vitesse de lecture et le ton de l'audio.

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

Relâchez 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 des décodeurs vidéo, pour d'autres applications. Pour ce faire, appelez ExoPlayer.release.