Vamos começar

Para casos de uso simples, começar a usar o ExoPlayer consiste em implementar as seguintes etapas:

  1. Adicione o ExoPlayer como uma dependência ao seu projeto.
  2. Crie uma instância ExoPlayer.
  3. Anexe o player a uma visualização (para saída de vídeo e entrada do usuário).
  4. Prepare o player com um MediaItem para reproduzir.
  5. Libere o player quando terminar.

Essas etapas são descritas com mais detalhes abaixo. Para um exemplo completo, consulte PlayerActivity no app de demonstração principal.

Adicionar o ExoPlayer como uma dependência

Adicionar módulos do ExoPlayer

A maneira mais fácil de começar a usar o AndroidX Media3 é adicionar dependências do Gradle às bibliotecas necessárias no arquivo build.gradle do módulo do app.

Por exemplo, para depender do ExoPlayer com suporte à reprodução de DASH e componentes de interface, adicione dependências aos módulos desta forma:

Kotlin

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

Groovy

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

em que 1.9.3 é a versão preferida (a versão mais recente pode ser encontrada consultando as notas da versão). Todos os módulos precisam ser da mesma versão.

O AndroidX Media3 tem módulos de biblioteca que dependem de bibliotecas externas para oferecer funcionalidades extras. Alguns estão disponíveis no repositório Maven, enquanto outros precisam ser criados manualmente. Navegue pelo diretão de bibliotecas e consulte os arquivos LEIAME individuais para mais detalhes.

Mais informações sobre os módulos de biblioteca disponíveis podem ser encontradas na página do Google Maven AndroidX Media.

Ativar o suporte ao Java 8

Se ainda não estiver ativado, você precisará ativar pelo menos o suporte ao Java 8 em todos os arquivos build.gradle que dependem do ExoPlayer, adicionando o seguinte à seção android:

compileOptions {
  targetCompatibility JavaVersion.VERSION_1_8
}

Criar o player

Você pode criar uma instância ExoPlayer usando ExoPlayer.Builder, que oferece uma variedade de opções de personalização. O código a seguir é o exemplo mais simples de criação de uma instância.

Kotlin

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

Java

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

Observação sobre linhas de execução

As instâncias do ExoPlayer precisam ser acessadas de uma única linha de execução do aplicativo. Na maioria dos casos, essa precisa ser a linha de execução principal do aplicativo. O uso da linha de execução principal do aplicativo é um requisito ao usar os componentes de interface do ExoPlayer ou a extensão IMA.

A linha de execução em que uma instância do ExoPlayer precisa ser acessada pode ser especificada explicitamente transmitindo um Looper ao criar o player. Se nenhum Looper for especificado, o Looper da linha de execução em que o player é criado será usado ou, se essa linha de execução não tiver um Looper, o Looper da linha de execução principal do aplicativo será usado. Em todos os casos, o Looper da linha de execução em que o player precisa ser acessado pode ser consultado usando Player.getApplicationLooper.

Para mais informações sobre o modelo de linhas de execução do ExoPlayer, consulte a "Modelo de linhas de execução" seção do Javadoc do ExoPlayer.

Anexar o player a uma visualização

A biblioteca do ExoPlayer oferece uma variedade de componentes de interface pré-criados para reprodução de mídia. Eles incluem PlayerView, que encapsula um PlayerControlView, um SubtitleView e uma Surface em que o vídeo é renderizado. Um PlayerView pode ser incluído no XML de layout do aplicativo. Por exemplo, para vincular o player à visualização:

Kotlin

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

Java

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

O uso de componentes de interface pré-criados do ExoPlayer é opcional. Para apps de vídeo que implementam a própria interface, o SurfaceView, TextureView, SurfaceHolder ou Surface de destino podem ser definidos usando os métodos setVideoSurfaceView, setVideoTextureView, setVideoSurfaceHolder e setVideoSurface do ExoPlayer, respectivamente. O callback Listener.onCues pode ser usado para receber legendas que precisam ser renderizadas durante a reprodução, e setImageOutput pode ser usado para receber imagens decodificadas.

Para uma experiência do usuário mais confortável, considere adicionar o atributo keepScreenOn. Você pode investigar outras ações que mantêm o dispositivo ativado nas páginas de trabalho em segundo plano.

android:keepScreenOn="true"

Leia mais sobre como usar os componentes de interface do Media3 e a personalização deles na página da interface.

Preencher a playlist e preparar o player

No ExoPlayer, cada parte da mídia é representada por um MediaItem. Para reproduzir uma parte da mídia, é necessário criar um MediaItem correspondente, adicioná-lo ao player, preparar o player e chamar play para iniciar a reprodução:

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()
HelloWorld.kt

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();
HelloWorld.java

O ExoPlayer oferece suporte a playlists diretamente. Portanto, é possível preparar o player com vários itens de mídia para serem reproduzidos um após o outro:

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()
HelloWorld.kt

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();
HelloWorld.java

A playlist pode ser atualizada durante a reprodução sem a necessidade de preparar o player novamente. Leia mais sobre como preencher e manipular a playlist na página Playlists. Leia mais sobre as diferentes opções disponíveis ao criar itens de mídia, como cortar e anexar arquivos de legenda, na página Itens de mídia.

Controlar o player

Depois que o player for preparado, a reprodução poderá ser controlada chamando métodos no player. Estes são alguns dos métodos mais usados com frequência:

  • play e pause iniciam e pausam a reprodução.
  • seekTo permite a busca na mídia.
  • hasPrevious, hasNext, previous e next permitem navegar pela playlist.
  • setRepeatMode controla se e como a mídia é repetida.
  • setShuffleModeEnabled controla a reprodução aleatória da playlist.
  • setPlaybackParameters ajusta a velocidade do vídeo e o tom do áudio.

Se o player estiver vinculado a um PlayerView ou PlayerControlView, a interação do usuário com esses componentes fará com que os métodos correspondentes no player sejam invocados.

Liberar o player

É importante liberar o player quando ele não for mais necessário para liberar recursos limitados, como decodificadores de vídeo, para uso por outros aplicativos. Isso pode ser feito chamando ExoPlayer.release.