Guida introduttiva

Per i casi d'uso semplici, l'utilizzo di ExoPlayer consiste nell'implementazione dei seguenti passaggi:

  1. Aggiungi ExoPlayer come dipendenza al tuo progetto.
  2. Crea un'istanza ExoPlayer.
  3. Collega il player a una visualizzazione (per l'output video e l'input utente).
  4. Prepara il player con un MediaItem da riprodurre.
  5. Rilascia il player al termine.

Questi passaggi sono descritti in dettaglio di seguito. Per un esempio completo, consulta PlayerActivity nell'app demo principale.

Aggiungi ExoPlayer come dipendenza

Aggiungi moduli ExoPlayer

Il modo più semplice per iniziare a utilizzare AndroidX Media3 è aggiungere le dipendenze gradle alle librerie necessarie nel file build.gradle del modulo dell'app.

Ad esempio, per dipendere da ExoPlayer con supporto della riproduzione DASH e componenti UI, puoi aggiungere dipendenze ai moduli in questo modo:

Kotlin

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")

Alla moda

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")

dove 1.11.1 è la versione che preferisci (puoi trovare l'ultima versione consultando le note di rilascio). Tutti i moduli devono essere della stessa versione.

AndroidX Media3 ha moduli di libreria che dipendono da librerie esterne per fornire funzionalità aggiuntive. Alcuni sono disponibili nel repository Maven, mentre altri devono essere creati manualmente. Sfoglia la directory delle librerie e consulta i singoli file README per i dettagli.

Per saperne di più sui moduli della libreria disponibili, consulta la pagina AndroidX Media di Google Maven.

Attiva il supporto di Java 8

Se non è già abilitato, devi attivare almeno il supporto di Java 8 in tutti i file build.gradle che dipendono da ExoPlayer aggiungendo quanto segue alla sezione android:

compileOptions {
  targetCompatibility JavaVersion.VERSION_1_8
}

Crea il player

Puoi creare un'istanza ExoPlayer utilizzando ExoPlayer.Builder, che offre una serie di opzioni di personalizzazione. Il seguente codice è l'esempio più semplice di creazione di un'istanza.

Kotlin

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

Java

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

Una nota sul threading

Le istanze ExoPlayer devono essere accessibili da un singolo thread dell'applicazione. Nella stragrande maggioranza dei casi, questo dovrebbe essere il thread principale dell'applicazione. L'utilizzo del thread principale dell'applicazione è un requisito quando si utilizzano i componenti dell'interfaccia utente di ExoPlayer o l'estensione IMA.

Il thread su cui deve essere eseguito l'accesso a un'istanza ExoPlayer può essere specificato esplicitamente passando un Looper durante la creazione del player. Se non viene specificato alcun Looper, viene utilizzato il Looper del thread su cui viene creato il player o, se il thread non ha un Looper, viene utilizzato il Looper del thread principale dell'applicazione. In tutti i casi, è possibile eseguire una query sul Looper del thread da cui è necessario accedere al player utilizzando Player.getApplicationLooper.

Per ulteriori informazioni sul modello di threading di ExoPlayer, consulta la sezione "Modello di threading" di ExoPlayer Javadoc.

Collega il player a una visualizzazione

La libreria media3-ui fornisce una serie di componenti UI predefiniti per la riproduzione di contenuti multimediali. Questi includono PlayerView, che incapsula un PlayerControlView, un SubtitleView e un Surface su cui viene eseguito il rendering del video. Un PlayerView può essere incluso nel file XML del layout dell'applicazione. Ad esempio, per associare il player alla visualizzazione:

Kotlin

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

Java

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

L'utilizzo dei componenti UI predefiniti di Media3 è facoltativo. Per le app video che implementano la propria UI, il target SurfaceView, TextureView, SurfaceHolder o Surface può essere impostato utilizzando rispettivamente i metodi setVideoSurfaceView, setVideoTextureView, setVideoSurfaceHolder e setVideoSurface del player. Il callback Listener.onCues può essere utilizzato per ricevere i sottotitoli codificati che devono essere visualizzati durante la riproduzione, mentre setImageOutput può essere utilizzato per ricevere le immagini decodificate.

Per un'esperienza utente più confortevole, valuta la possibilità di aggiungere l'attributo keepScreenOn. Puoi esaminare altre azioni che mantengono attivo il dispositivo nelle pagine relative al lavoro in background.

android:keepScreenOn="true"

Se la tua app utilizza Jetpack Compose per la UI, puoi utilizzare il composable Player della libreria media3-ui-compose-material3. Player mostra i video e include valori precompilati per gli slot dei controlli di riproduzione. Per collegare un oggetto androidx.media3.common.Player a un composable androidx.media3.ui.compose.material3.Player, basta passarlo come argomento:

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

Scopri di più sull'utilizzo dei componenti UI di Media3 e sulla loro personalizzazione nella pagina UI.

Compila la playlist e prepara il player

In ExoPlayer, ogni contenuto multimediale è rappresentato da un MediaItem. Per riprodurre un elemento multimediale, devi creare un MediaItem corrispondente, aggiungerlo al player, preparare il player e chiamare play per avviare la riproduzione:

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 supporta direttamente le playlist, quindi è possibile preparare il player con più elementi multimediali da riprodurre uno dopo l'altro:

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

La playlist può essere aggiornata durante la riproduzione senza dover preparare nuovamente il player. Scopri di più su come compilare e manipolare la playlist nella pagina Playlist. Scopri di più sulle diverse opzioni disponibili per la creazione di elementi multimediali, come il ritaglio e l'allegato di file di sottotitoli, nella pagina Elementi multimediali.

Controlla il player

Una volta preparato il player, la riproduzione può essere controllata chiamando i metodi sul player. Ecco alcuni dei metodi di uso comune:

  • play e pause avviano e mettono in pausa la riproduzione.
  • seekTo consente la ricerca all'interno dei contenuti multimediali.
  • hasPrevious, hasNext, previous e next consentono di navigare nella playlist.
  • setRepeatMode controlla se e come i contenuti multimediali vengono riprodotti in loop.
  • setShuffleModeEnabled controlla la riproduzione casuale della playlist.
  • setPlaybackParameters regola la velocità di riproduzione e l'altezza dell'audio.

Se il player è associato a un PlayerView o PlayerControlView, l'interazione dell'utente con questi componenti comporterà la chiamata dei metodi corrispondenti sul player.

Rilascia il giocatore

È importante rilasciare il player quando non è più necessario, in modo da liberare risorse limitate come i decoder video per l'utilizzo da parte di altre applicazioni. Questa operazione può essere eseguita chiamando ExoPlayer.release.