Guida introduttiva

Suggerimento: un altro modo per iniziare è seguire il codelab di ExoPlayer.

Per casi d'uso semplici, per iniziare a utilizzare ExoPlayer è necessario implementare i seguenti passaggi:

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

Questi passaggi sono descritti più dettagliatamente 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 dipendenze Gradle sulle librerie necessarie nel file build.gradle del modulo dell'app.

Ad esempio, per dipendere da ExoPlayer con il supporto della riproduzione DASH e i componenti dell'interfaccia utente, puoi aggiungere dipendenze ai moduli come segue:

Kotlin

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

Groovy

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

dove 1.4.1 è la tua versione preferita (la versione più recente è reperibile consultando le note di rilascio). Tutti i moduli devono avere la stessa versione.

AndroidX Media3 ha moduli di librerie 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 maggiori dettagli.

Puoi trovare ulteriori informazioni sui moduli della libreria disponibili nella pagina Google Maven AndroidX Media.

Attiva il supporto Java 8

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

compileOptions {
  targetCompatibility JavaVersion.VERSION_1_8
}

Attivare multidex

Se Gradle minSdkVersion è pari o inferiore a 20, devi attivare multidex per evitare errori di compilazione.

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 sull'organizzazione in thread

È necessario accedere alle istanze di ExoPlayer da un singolo thread di applicazione. Nella maggior parte dei casi, dovrebbe essere il thread principale dell'applicazione. L'utilizzo del thread principale dell'applicazione è un requisito quando utilizzi i componenti UI di ExoPlayer o l'estensione IMA.

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

Nota: se viene generato IllegalStateException con il messaggio "Il player viene acceduto sul thread sbagliato", significa che un codice nella tua app sta accedendo a un'istanza ExoPlayer sul thread sbagliato (l'analisi dello stack dell'eccezione ti mostra dove).

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

Collegare il player a una visualizzazione

La libreria ExoPlayer fornisce una serie di componenti UI predefiniti per la riproduzione di contenuti multimediali. tra cui PlayerView, che racchiude un PlayerControlView, un SubtitleView e un Surface su cui viene visualizzato il 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);

Puoi anche utilizzare PlayerControlView come componente autonomo, utile per casi d'uso solo audio.

L'utilizzo dei componenti dell'interfaccia utente predefiniti di ExoPlayer è 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 di ExoPlayer. Il metodo addTextOutput di ExoPlayer può essere utilizzato per ricevere sottotitoli da eseguire durante la riproduzione.

Compilare la playlist e preparare il player

In ExoPlayer, ogni elemento multimediale è rappresentato da un elemento MediaItem. Per riprodurre un elemento multimediale, devi creare un elemento 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 di nuovo il media player. Scopri di più su come compilare e modificare la playlist nella pagina Playlist. Scopri di più sulle diverse opzioni disponibili per la creazione di elementi multimediali, ad esempio il ritaglio e l'aggiunta di file di sottotitoli, nella pagina Elementi multimediali.

Nota: Media3 ExoPlayer converte gli elementi multimediali in MediaSource istanze di cui ha bisogno internamente. Scopri di più su questa procedura e su come può essere personalizzata nella pagina Origini multimediali. Puoi fornire un MediaSource direttamente al player utilizzando ExoPlayer.setMediaSource(s) e ExoPlayer.addMediaSource(s).

Controllare il player

Una volta preparato il player, la riproduzione può essere controllata chiamando i metodi sul player. Di seguito sono riportati alcuni dei metodi più utilizzati:

• 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 il tono dell'audio.

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

Rilascia il player

È importante rilasciare il player quando non è più necessario, in modo da liberare risorse limitate come i decodificatori video per l'utilizzo da parte di altre applicazioni. Per farlo, chiama ExoPlayer.release.